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. 一句话模块职责总结

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

---

§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"，而是"为什么这样设计"）
• 关键数据结构为什么这样建？有什么历史背景或迁移现状？
• 核心机制（流程引擎、QueryMode、引用计数……）为什么存在？解决了什么问题？

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

• 核心业务链路（端到端）：触发 → 调用哪些模块 → 数据如何流转 → 结果
• 数据在各模块间如何流转（追踪 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 并发写同一目录会产生冲突或重复内容。