dev-blueprint

---
name: dev-blueprint
description: >
  分析 GitHub 项目或本地代码库，以此为参考生成从零开发一个新项目的完整文档套件（产品手册、开发文档、架构文档、目录结构文档、设计规范文档、数据库设计文档、开发步骤计划、实施步骤文档、部署文档），并附带 AGENTS.md 指引 AI 开发工具执行开发。
  当用户提供一个参考项目（GitHub 链接或本地路径），要求生成开发计划、开发文档、项目蓝图、功能拆解、实施步骤，或要求基于某个项目从零开发类似项目时使用。
  允许用户指定技术栈替换、功能增减、聚焦特定模块。
  适用于中文请求，例如"参考这个项目生成开发计划"、"基于这个 GitHub 项目给我一套开发方案"、"生成项目蓝图"、"输出开发步骤"、"我想做一个类似 xxx 的项目"等。
---

# Dev Blueprint

分析一个参考项目（GitHub 链接或本地路径），理解其架构、功能和实现方式，然后以此为依据生成从零开发一个**新项目**所需的完整 Markdown 文档套件。新项目可以与参考项目不同：支持换技术栈、增减功能、聚焦特定模块。产出文档包含足够的架构设计和操作细节，可直接用于 Codex 等 AI 开发工具从零开发。

## 工作流程

### 第一步：获取参考项目

识别参考项目来源：

- **GitHub URL 或 `org/repo`**：浅克隆到新临时目录（`git clone --depth 1`），按本地仓库分析。克隆目录不能覆盖已有文件。
- **本地路径**：直接分析。
- **克隆失败**：降级使用远程 README、文件树，说明限制。

### 第二步：确定新项目范围

这是关键一步。明确新项目与参考项目之间的差异：

- **功能取舍**：参考项目的哪些功能要保留？哪些去掉？要新增什么功能？
- **技术栈**：是否换技术栈？如果用户没有指定，默认沿用参考项目的技术栈，但要说明这个默认选择。
- **范围限定**：是做全部功能还是只做某些模块？
- **文档范围**：用户要完整文档套件还是只要其中几份？

如果用户只提供了项目链接没有说明上述信息，主动询问。典型提问：
"你希望新项目和参考项目有哪些不同？比如：要保留/去掉哪些功能？需要换技术栈吗？是全部功能还是只做某些模块？"

如果用户明确表示"照着做就行"，则默认完全复刻参考项目，所有功能保留。

**部分生成模式**：用户只要部分文档时，按依赖关系补齐所需的上游文档：

- 要 07 或 08：必须先生成 01（功能清单来源）和 03（架构来源）。
- 要 08：必须先生成 07。
- 要 06：必须先生成 02（技术栈来源）。
- 完整套件才生成 `AGENTS.md`；部分模式改为在回复中给出已生成文档的阅读顺序。

### 第三步：分析参考项目

按 `references/analysis-guide.md` 的维度分析参考项目。重点关注：
- 功能全貌和模块划分。
- 架构模式和分层设计。
- 核心数据流和模块依赖关系。
- 数据模型与持久化。
- 设计模式和编码约定。

分析时引用源码路径和行号作为证据。读取 `references/analysis-guide.md` 获取完整分析维度清单。

**分析结果必须落盘**：写入 `{项目根}/docs/00参考项目分析.md`（结构见 `references/doc-templates.md` 的参考项目分析章节）。该文件是过程产物，不计入交付文档清单，`AGENTS.md` 不引用它。作用：跨轮次保留分析证据；第四步起以它为唯一分析依据，不再重复读参考项目源码。

### 第四步：生成文档

按 `references/doc-templates.md` 的模板生成文档。每份文档输出为独立的 `.md` 文件，文件名带两位序号前缀，描述的是**新项目**而非参考项目。

生成顺序（即阅读顺序，以文件名序号为唯一权威）：

1. `docs/00参考项目分析.md` — 第三步已生成（过程产物）
2. `docs/01产品手册.md`
3. `docs/02开发文档.md`
4. `docs/03项目架构文档.md`
5. `docs/04目录结构文档.md`
6. `docs/05设计规范文档.md`
7. `docs/06数据库设计文档.md`（仅当新项目使用数据库，否则跳过）
8. `docs/07开发步骤计划文档.md`
9. `docs/08实施步骤文档.md`
10. `docs/09部署文档.md`（库/CLI 项目输出发布变体）
11. `AGENTS.md` — AI 开发指引，**最后生成**：它需要引用全部交付文档的内容和顺序。

每份文档直接写入文件，不要在回复中粘贴全文；回复中只报告文件路径和一句话摘要。

**中断恢复**：每份文档写入前先检查目标文件——已存在且非空则跳过并在回复中说明；仅当用户明确要求"重新生成"时才覆盖。

### 第五步：自检

全部文档生成后逐项核对，发现问题当场修复：

1. **功能编号一致**：01 功能清单、07 功能点表、08 实施步骤三处的功能编号（F-xx）和功能名一致。
2. **链接有效**：`AGENTS.md` 引用的每份文档都实际存在（无数据库项目不得引用 06）。
3. **条件文档正确**：未使用数据库 → 06 不存在；库/CLI 项目 → 09 为发布变体。
4. **步骤可执行**：08 每个步骤都有文件路径、操作内容和验证方式（验证命令或完成标志）。
5. **格式规范**：文件名前缀与产出清单一致、无缺号；产出文档不含零宽字符（U+200B）等不可见字符。

## 产出文档清单

| 序号 | 文档 | 文件名 | 输出位置 | 条件 |
|------|------|--------|---------|------|
| 00 | 参考项目分析 | `00参考项目分析.md` | `docs/` | 过程产物，不计入交付，`AGENTS.md` 不引用 |
| — | AI 开发指引 | `AGENTS.md` | 项目根目录 | 完整套件时最后生成 |
| 01 | 产品手册 | `01产品手册.md` | `docs/` | 总是 |
| 02 | 开发文档 | `02开发文档.md` | `docs/` | 总是 |
| 03 | 项目架构文档 | `03项目架构文档.md` | `docs/` | 总是 |
| 04 | 目录结构文档 | `04目录结构文档.md` | `docs/` | 总是 |
| 05 | 设计规范文档 | `05设计规范文档.md` | `docs/` | 总是 |
| 06 | 数据库设计文档 | `06数据库设计文档.md` | `docs/` | 仅当新项目使用数据库 |
| 07 | 开发步骤计划 | `07开发步骤计划文档.md` | `docs/` | 总是 |
| 08 | 实施步骤文档 | `08实施步骤文档.md` | `docs/` | 总是 |
| 09 | 部署文档 | `09部署文档.md` | `docs/` | 总是（库/CLI 项目输出发布变体） |

文件名序号是排列和阅读顺序的唯一权威；06 缺省时 05 之后直接是 07，其余序号不变。

## 输出规则

- 所有文档描述的是**新项目**。参考项目只允许出现在两处：`docs/00参考项目分析.md`（全量记录），以及各交付文档中明确标注"与参考项目对比/异同"的章节（如 03 架构文档的架构对比）。功能来源标注（[保留]/[新增]/[调整]）只标记出处，不属于对参考项目的描述。
- 所有文档使用中文，技术术语保留英文（如 RESTful、CRUD、middleware、ORM、SSR）。
- `AGENTS.md` 输出到新项目根目录；其余带序号文档输出到 `docs/` 目录下。
- 每份文档独立输出为 `.md` 文件，文件名按上表（含两位序号前缀）。
- 产出文档中禁止出现零宽字符（U+200B）等不可见字符。
- 技术判断需有分析依据，可引用 `docs/00参考项目分析.md` 中已记录的源码路径。
- 实施步骤文档需具体到文件路径和操作指令，使 AI 开发工具可直接执行。
- **输出目录**：用户未指定输出目录时，在当前工作目录下创建以新项目名命名的文件夹作为项目根目录。项目名未指定时，默认用 `{参考项目名}-new`（如 `myapp-new`），并在回复中说明。项目根目录已存在时：为空 → 直接使用；非空 → 列出将创建和冲突的文件，经用户确认后才能写入，默认不覆盖已有文件。

• SKILL.md 8 KB
• agents/openai.yaml 1 KB
• references/analysis-guide.md 5 KB
• references/doc-templates.md 22 KB