Code To Guide

---
name: code-to-guide
description: |
  读陌生项目代码，自动组建 agent team，产出 AI 友好的项目导览文档（AI-friendly project guide）。
  触发词：理解陌生项目、生成项目导览文档、代码到说明书、AI 友好项目文档、摸清一个代码库、
  分析这个项目、给这个项目做文档、项目说明书、项目调研文档。
  定位：只读调研 + 一次性产出，轻量级。
  不是七层文档体系（code-to-7layer / doc-layer-system），不改代码，不需要人工逐步指导。
---

## §0 角色定位与边界

**做什么**：读一个已有项目的代码，理解它的模块结构、数据模型、接口设计和业务逻辑，产出一套 AI 友好的项目导览文档（`docs/<项目名>/`）。

**不做什么**：不改项目代码；不建七层文档体系；不产出需求文档（L1）；不跟随项目生命周期演进。

**与其他 skill 的区别**：
- `docs-from-code`：从代码反推 L1 需求，用于七层体系。本 skill 产出的是"项目说明书"，不是需求。
- `code-to-7layer`：七层冷启动，重型架构治理。本 skill 产出物极其轻量，只是导览。
- `doc-layer-system`：七层文档治理规范本体。本 skill 与之完全无关。

---

## §1 何时触发

**触发**：
- 接手陌生或遗留代码库，需要快速建立整体认知
- 向团队其他成员（或 AI）介绍一个项目
- 需要"让 AI 读一遍就能理解这个项目"的结构化文档

**不触发**：
- 要建七层文档体系 → 用 `code-to-7layer`
- 要补 L1 需求文档 → 用 `docs-from-code`
- 要修改/扩展项目代码 → 不适用本 skill

---

## §2 五阶段工作流总览

```
Phase 1: 项目扫描
  └─ 主 agent 亲自做：find/ls 摸结构 → 产出模块地图

Phase 2: 模块拆分 + Agent Team 并行派发
  └─ 按内聚模块拆任务 → 并行 Explore+sonnet 子 agent（≤6~8 个）

Phase 3: 汇总两层文档
  ├─ 参考层（是什么）：按模块并行整理，字段表/接口表/枚举
  └─ 理解层（为什么/怎么用）：跨模块综合或专门追踪业务流程

Phase 4: 建 README 索引 + 阅读路径
  └─ README = AI 唯一入口，含文档地图、推荐阅读路径、术语速查

Phase 5: 新鲜视角自检
  └─ 单独 agent 只读文档（禁读代码），复述项目 → 列出看不懂的点
```

---

## §3 Phase 1 — 项目扫描

主 agent 亲自执行，**不派发子 agent**。

### 扫描步骤

1. 读项目根目录（`ls`、`find . -maxdepth 3 -type f -name "*.java|*.go|*.ts|*.py" | head -50`）
2. 读 README/AGENTS.md（若有）
3. 统计文件规模：`find . -name "*.java" | wc -l`（按语言调整后缀）
4. 识别模块边界：Maven 多模块 → 看 pom.xml；Go → 看目录名；JS/TS → 看 package.json/目录结构

### 产出：模块地图

一份 Markdown 表格，包含：

| 模块名 | 目录路径 | 核心职责（一句话） | 代表文件（2~3 个） |
|---|---|---|---|

**模块地图用途**：
- 指导 Phase 2 的 agent 派发（每行 = 一个 agent 任务）
- 成为 Phase 4 README 文档地图的基础

### 语言约定

优先读项目 AGENTS.md，默认跟随用户对话语言（通常中文）。

---

## §4 Phase 2 — 模块拆分 + Agent Team 派发

### 拆分原则

- 按**内聚领域/模块**拆，不按文件数
- 每个 agent 一个 bounded context（一个模块的全部层：entity/service/api/dto）
- 模块过大（>60 个文件）则按子领域再拆
- 模块过小（<5 个文件）则与相邻模块合并
- **数量上限**：6~8 个 agent，防主 agent 调度过载与上下文爆炸

### 子 agent 规约

每个子 agent 必须：
- `subagent_type: Explore`（只读，不写文件）
- `model: sonnet`
- prompt 里给**明确文件清单**（路径列表，不是"自己去找"）
- 要求返回**结构化中文报告**，包含：
  - 实体/POJO 字段表（字段名、类型、说明）
  - 核心接口/方法清单
  - 关键枚举值
  - 模块间依赖关系（调用了哪些其他模块的什么接口）
  - 一句话模块职责总结
- 声明"只调研，不写任何文件"

### 并行派发

**单条消息**中包含所有 Agent 工具调用，使它们并行运行。

### 模板 prompt（子 agent）

```
你是一个只读代码调研 agent。任务：调研 <模块名> 模块，整理结构化中文报告。

目标文件清单（只读这些，不要扩展搜索）：
- <文件路径1>
- <文件路径2>
...

请报告：
1. 实体/POJO 字段表（字段名 | 类型 | 说明）
2. 核心接口/服务方法清单（方法签名 + 一句话说明）
3. 关键枚举值（枚举名 + 各值含义）
4. 跨模块依赖（调用了哪些模块的哪些接口）
5. 一句话模块职责总结

不要写文件，只返回报告文本。
```

---

## §5 Phase 3 — 汇总两层文档

两层文档**必须分离**，不能混写。

### 参考层（"是什么"，查字典用）

- 对应文件：`NN-<模块名>.md`（如 `01-data-model.md`、`03-write-api.md`）
- 内容：字段表、接口表、枚举值、数据结构关系
- **可并行**：每个模块 agent 报告直接整理成一个参考层文档
- 参考模板：`assets/reference.template.md`
- 每份文件头部加导读行：`> **参考手册**：查 X 时使用。设计动机见 [design.md](00-design.md)，文档导航见 [README.md](README.md)。`

### 理解层（"为什么/怎么用"，叙述性）

- 对应文件：`00-design.md`（设计动机）+ `NN-scenarios.md`（业务场景与数据流）
- **关键**：理解层是**跨模块**的，模块级报告给不出来，需要主 agent 综合
- 何时追加专门 agent：当有复杂的跨模块业务流程（如支付链路、商品创建链路），可追加一轮**流程追踪 agent**，给它明确的"从 A 调用 B，B 调用 C"这样的调查任务
- 参考模板：`assets/design.template.md`、`assets/scenarios.template.md`

### 设计动机文档（`00-design.md`）要回答的问题

- 为什么这样分层/拆模块？（不是"什么是XX"，而是"为什么这样设计"）
- 关键数据结构为什么这样建？有什么历史背景或迁移现状？
- 核心机制（流程引擎、幂等键、引用计数……）为什么存在？解决了什么问题？

### 业务场景文档要包含的内容

- 核心业务链路（端到端）：触发 → 调用哪些模块 → 数据如何流转 → 结果
- 数据在各模块间如何流转（追踪 ID/对象在调用链中的变化）
- 边界场景（可选）：特殊权限、状态机转换

---

## §6 Phase 4 — 建 README 索引

README 是 **AI 读文档的唯一入口**，必须在所有其他文档写完后生成。

### README 必须包含

1. **项目一句话定位**（是什么、做什么、在整体架构中的位置）
2. **文档地图**（表格）：
   - 理解层（`00-design.md`、`NN-scenarios.md`）：一句话说"读懂设计动机用"
   - 参考层（其余文档）：一句话说"查X时用"
3. **推荐阅读路径**（按任务）：
   - 新人快速入门 → 读哪几个文档、顺序
   - 要调用写接口 → 直接跳 `03-write-api.md`
   - 要理解数据模型 → ...
   - 要理解迁移现状 → ...
4. **关键术语速查**（5~10 个项目特有术语，一句话解释）
5. **AI 阅读指引**（可选）：提示 AI "先读 README，再按需跳转，不要一次性全读"

参考模板：`assets/README.template.md`

---

## §7 Phase 5 — 新鲜视角自检

**目的**：用一个没有调研上下文的 agent 来检验文档质量。

### 执行方式

另起一个独立 agent（不是复用调研 agent），prompt：

```
你是一个没有这个项目任何背景知识的新工程师。
请只阅读以下文档目录中的文件（禁止读项目代码）：
<docs 目录路径>

读完后，请：
1. 用 3~5 句话复述：这个项目是什么，核心数据模型是什么，主要接口有哪些
2. 列出你"看不懂"或"文档没有解释清楚"的地方（缺失的上下文、含糊的术语、断裂的逻辑）
3. 给文档清晰度打分（1~5 分）并说明理由
```

### 根据反馈修补

主 agent 根据自检报告，针对性补充：
- 术语没解释 → 在 README 术语速查里补
- 设计动机缺失 → 在 `design.md` 里补
- 某个链路讲不清 → 在 `scenarios.md` 里补
- 某个文档太密 → 考虑拆分

---

## §8 文档规范

### 文件大小

- **单文件 ≤ 500 行**（硬规则）
- 超限则按模块边界拆成子目录 + 子索引（如 `query/README.md` + `query/01-xxx.md`）

### 命名约定

- `NN-名称.md`（两位数编号 + kebab-case 名称）
- `00-design.md` 保留给设计动机
- `README.md` 保留给顶层索引

### AI 导航三原则

1. **README 是唯一入口**：AI 永远从 README 开始，不直接跳某个文档
2. **按需加载**：每个文档头部导读行说明"什么情况下读这个"，避免全量加载
3. **双向交叉链接**：参考层文档 → 链回 README/design/scenarios；design/scenarios → 链出到参考层具体章节

---

## §9 模板引用

| 模板文件 | 用途 | 何时使用 |
|---|---|---|
| `assets/README.template.md` | 顶层 README 骨架 | Phase 4 生成 README |
| `assets/design.template.md` | 设计动机文档骨架 | Phase 3 生成 `00-design.md` |
| `assets/scenarios.template.md` | 业务场景文档骨架 | Phase 3 生成 `NN-scenarios.md` |
| `assets/reference.template.md` | 参考层字段/接口手册骨架 | Phase 3 生成各 `NN-模块.md` |

使用方式：读模板，将 `{{占位符}}` 替换为实际内容，删除不适用的章节。

---

## §10 已知坑点

1. **上下文稀释**：子 agent scope 一定要小；不要让一个 agent 负责 "整个项目"；文件清单宁可拆多也不要合并太多。

2. **模块报告覆盖不了业务场景**：理解层（design + scenarios）必须单独投入，不能指望从模块报告里拼出来。跨模块业务流程需要专门追踪。

3. **字段手册与叙述混写**：参考层和理解层必须物理分离成不同文件，混写会导致 AI 每次加载都带来大量无关信息。

4. **忘记反链**：每份参考文档必须有头部导读行（含 README 和 design 的链接），否则 AI 在文档间迷路。

5. **README 最后写**：README 依赖所有其他文档已写完，才能准确地做索引和阅读路径推荐。不要最先写 README。

6. **子 agent 不要写文件**：子 agent 只返回报告文本，由主 agent 汇总后统一写文件，否则多个 agent 并发写同一目录会产生冲突或重复内容。