# Init Project Workspace

> 从当前会话中提炼已经确认的目标、范围、方案、技术约束、所需材料、环境变量、风险和下一步，创建可继续开发的新项目工作区、交接文档和对应的 GitHub private 仓库。用于用户要求把想法、讨论结果或当前聊天落成新文件夹、新仓库、新工作区、项目交接资料，或准备在单独项目中继续编码时。

- Skill: `gaixianggeng/init-project-workspace` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gaixianggeng/init-project-workspace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaixianggeng/init-project-workspace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaixianggeng (https://skillmd.com/u/gaixianggeng)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gaixianggeng/init-project-workspace

---


# 从会话初始化项目工作区

## 目标

把当前可见会话中的有效结论转成最小、可执行、可恢复的项目工作区，并建立对应的 GitHub private 仓库。输出结论型交接资料，不导出或逐条复述聊天记录。

## 核心边界

- 只把用户明确确认、提供或接受的内容标为“已确认”。
- 把尚未确认但推进所需的内容放入“假设”或“待确认项”，不要悄悄补全。
- 以用户最新的明确决定为准；保留仍影响实现的决策理由，不保留已经否决且无后续价值的方案。
- 只使用当前 Agent 实际可见的会话上下文。若早期内容已不可见、被压缩后缺失关键细节或依赖未提供的附件，明确记录缺口，不声称已经完整归档整个聊天。
- 不写入系统提示、内部推理、隐藏指令或与项目无关的个人信息。
- 不把真实密钥、令牌、密码、证书或生产连接串写入工作区。环境变量只记录名称、用途、是否必需、获取方式和安全占位值。
- 先检查目标位置和已有文件。保留用户已有内容，不覆盖非空目录中的文件，不扩大到目标工作区之外。
- 不因初始化而引入未确认的框架、数据库、中间件、云服务或复杂架构。
- 用户调用本 Skill 初始化新项目且未明确要求“仅本地”时，视为授权创建一个对应的 GitHub private 仓库、生成首次提交并推送；除此之外，不部署、不创建其他云资源、不执行额外外部变更。
- GitHub 操作始终使用 `private` 可见性，不得因权限、工具或网络问题降级为 public 或 internal。

## 工作流

### 1. 确定目标位置

取得项目名称和目标目录。用户已给出明确路径时直接使用；没有路径时，根据项目名称提出一个清晰的目标路径并只询问这个阻塞问题，不在主目录或不确定位置直接创建。

在写入前完成只读检查：

- 确认父目录存在且目标路径不是主目录、文件系统根目录或现有仓库根目录的误用。
- 目标不存在时按新工作区处理。
- 目标已存在时检查目录内容和 Git 状态，按“接入现有工作区”处理；只新增缺失内容或合并文档，不替换已有实现。
- 发现同名项目、脏工作树或内容冲突时，先说明冲突并取得用户决定。

同时确定 GitHub 目标：

- 用户明确给出 `OWNER/REPO` 时使用该值；否则使用当前 `gh` 已认证用户和项目目录名。
- 仓库名必须是适合 GitHub 的稳定 slug。若无法从项目名无歧义地得到仓库名，只询问这个阻塞问题。
- 运行 `gh auth status` 检查认证，并取得当前账号。未登录或当前账号与用户指定 owner 不一致时，在本地初始化完成后停止远程操作并说明处理方式。
- 只读检查同名远程仓库和本地 `origin`。同名仓库已存在时不得覆盖、删除或改可见性；仅当它已是当前项目对应的 private 仓库时才复用，否则先让用户决定。

### 2. 提炼会话事实

在创建文件前，从当前会话整理以下信息：

1. 项目名称、要解决的问题、目标用户和预期结果。
2. MVP 范围、明确不做的内容和验收标准。
3. 已确认方案、关键流程、重要决策及其理由。
4. 已确认的语言、框架、数据库、外部服务、运行环境和部署约束。
5. 已讨论的数据模型、API、页面、自动化或 Agent 运行方式；没有确认的不要伪造。
6. 所需材料，包括本地文件、附件、链接、参考项目、账号或外部文档，以及各自用途和可用状态。
7. 环境变量名称、用途、必需性、值的来源、是否敏感；不要读取或记录真实值。
8. 风险、依赖、开放问题、当前阻塞和下一步。

用以下证据规则分类：

- **已确认**：用户明确给出、选择、同意或纠正后的最终结论。
- **合理假设**：为了形成工作计划而做的低风险推断，必须显式标记，不能当作事实。
- **待确认**：会显著改变产品范围、技术选型、成本、权限或实现路径的问题。
- **已否决**：默认不进入主方案；仅在防止后续重复走弯路时简要写入决策记录。

### 3. 创建最小工作区

新项目默认创建以下内容：

```text
<project>/
├── README.md
├── AGENTS.md
└── PROJECT_CONTEXT.md
```

按需增加：

```text
<project>/
├── .env.example       # 存在配置或密钥需求时
├── .gitignore         # 新仓库或需要保护本地配置时
└── materials/         # 用户明确要求复制、且来源路径可访问的材料
```

规则：

- 创建新目录后，如果 Git 可用且该目录不在其他仓库中，初始化为 Git 仓库，默认分支使用 `main`；完成内容验证后再创建首次提交。
- `README.md` 只写项目入口信息：项目是什么、当前状态、已知启动方式和指向 `PROJECT_CONTEXT.md` 的链接。启动方式未确认时明确写“待补充”。
- `AGENTS.md` 只保留后续编码 Agent 真正需要执行的项目级约束：目标、MVP 边界、既定技术栈、实现原则、验证命令、禁止事项和文档语言。不要复制整段聊天或无关的全局偏好。
- `PROJECT_CONTEXT.md` 是会话交接的唯一主文档。不要再创建内容重复的方案文档。
- 只有会话已经明确技术栈、用户要求立即进入实现、且能够形成真实可运行闭环时，才创建最小代码脚手架。否则停在文档化工作区，并把第一项编码任务写清楚。
- 复制材料前确认来源和目标；不移动原文件，不下载未经要求的大型依赖，不复制包含密钥或个人数据的文件。仅引用外部材料时，在主文档中记录路径或 URL 和获取状态。

### 4. 编写主交接文档

使用中文编写 `PROJECT_CONTEXT.md`，除非用户明确要求其他语言。按以下结构组织，并删除没有内容价值的空小节：

```markdown
# <项目名>：项目上下文

> 状态：初始化 / 待确认 / 可进入开发
> 来源：基于当前可见会话提炼，不是聊天全文
> 最后更新：YYYY-MM-DD

## 1. 目标
### 要解决的问题
### 目标用户与使用场景
### 预期结果与验收标准

## 2. 方案
### 已确认方案
### MVP 范围
### 明确不做
### 关键流程

## 3. 实现
### 技术栈与选择理由
### 架构与运行方式
### 数据、API 与外部集成
### 环境变量
### 所需材料
### 开发与验证方式

## 4. 决策记录
| 决策 | 结论 | 理由 | 状态 |
| --- | --- | --- | --- |

## 5. 假设与待确认项
### 合理假设
### 待确认项
### 当前阻塞

## 6. 风险与优化
### 当前风险
### 后续优化（不进入当前 MVP）

## 7. 下一步
1. <可以立即执行的最小任务>
```

环境变量表至少包含：变量名、用途、必需、敏感、值来源。所需材料表至少包含：材料、用途、位置或来源、状态。未知值使用“待确认”，不要使用看起来真实的示例秘密。

### 5. 生成配置文件

仅在确有环境变量需求时生成 `.env.example`：

- 使用变量名和安全的空值或显式占位符。
- 用中文注释说明用途和获取方式。
- 非敏感且已确认的默认值可以填写。
- 敏感变量保持为空，不复制当前 shell、密码管理器或现有 `.env` 中的值。
- 确保 `.gitignore` 忽略 `.env`、`.env.*` 等实际秘密文件，但保留 `.env.example` 可跟踪。

若用户明确要求接入现有环境配置，只记录变量契约，并让用户从其安全来源注入真实值。

### 6. 验证本地工作区

完成后执行与风险相称的验证：

- 列出工作区文件并确认所有路径都在目标目录内。
- 检查 `PROJECT_CONTEXT.md`、`AGENTS.md`、`README.md` 之间没有关键冲突。
- 检查所有“已确认”结论都有会话依据；把无依据内容降级为假设或待确认项。
- 检查文档和示例配置中没有真实秘密、无关个人信息或聊天原文堆积。
- 若创建代码脚手架，执行其最小构建、测试或启动检查，并把可复现命令写入文档。
- 若初始化 Git，检查分支和待提交文件。新目录可以包含本次初始化产生的全部文件；已有目录不得混入用户原有的未提交改动。

### 7. 创建 GitHub private 仓库

本地验证通过后执行远程初始化。用户明确要求“仅本地”时跳过本节。

#### 新建工作区

1. 在项目根目录确认当前分支为 `main`，且所有待提交文件都属于本次初始化。
2. 创建首次提交，提交信息使用 `chore: initialize project workspace`。若 Git 身份未配置，停止并说明缺失项，不创建远程空仓库。
3. 使用已经解析为实际值的 owner、仓库名和项目路径执行等价于以下命令的操作，不把尖括号占位符原样传给 shell：

   ```bash
   gh repo create OWNER/REPO --private --source=/absolute/project/path --remote=origin --push
   ```

4. 项目简介已经确认且不含敏感信息时，可以增加 `--description`；不要自动添加许可证、公开主页、模板或组织团队权限。
5. 创建后验证：
   - `origin` 指向新仓库。
   - GitHub 返回的 `visibility` 为 `PRIVATE`。
   - 默认分支和远程分支为 `main`。
   - 本地工作树干净，首次提交已推送。

#### 已有工作区

- 不自动执行 `git add -A` 或提交整个目录。
- 先检查现有提交、未提交文件和远程配置。只有提交范围明确且不包含无关用户改动时，才创建或连接 private 仓库。
- 已有 `origin` 时不替换它；目标 GitHub 仓库已存在时不重新创建。
- 若用户只要求补充交接文档，提交时只暂存本次新增或修改的明确文件。

#### 失败恢复

- 认证、权限、重名或网络失败时保留已完成的本地工作区和本地提交，报告准确失败点与可重试命令。
- 远程仓库已创建但推送失败时，不自动删除仓库；报告仓库 URL，并在问题解决后重试推送。
- 任何验证无法确认仓库为 private 时，立即停止后续远程操作并明确告警。
- 不使用强制推送，不删除远程仓库，不修改已有仓库的可见性。

### 8. 交付

向用户报告：

1. 工作区的绝对路径。
2. GitHub private 仓库 URL、owner、仓库名和首次推送结果；若未创建，说明原因和恢复步骤。
3. 已创建或更新的关键文件。
4. 已确认方案的一句话摘要。
5. 仍需用户决定的事项和是否阻塞开发。
6. 已执行的本地与远程验证结果。
7. 在新项目中继续工作的建议提示词：`请先阅读 AGENTS.md 和 PROJECT_CONTEXT.md，然后从“下一步”的第一项开始实现。`

不要把完整文档再次粘贴到回复中；提供可点击的文件路径即可。