code-to-guide

§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/CLAUDE.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 文档地图的基础

语言约定

优先读项目 CLAUDE.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. 一句话模块职责总结

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