BackToCimaCoppi §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。
扫描步骤
- 读项目根目录（
ls、find . -maxdepth 3 -type f -name "*.java|*.go|*.ts|*.py" | head -50） - 读 README/CLAUDE.md（若有）
- 统计文件规模：
find . -name "*.java" | wc -l（按语言调整后缀） - 识别模块边界：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"，而是"为什么这样设计"）
- 关键数据结构为什么这样建？有什么历史背景或迁移现状？
- 核心机制（流程引擎、幂等键、引用计数……）为什么存在？解决了什么问题？
业务场景文档要包含的内容
- 核心业务链路（端到端）：触发 → 调用哪些模块 → 数据如何流转 → 结果
- 数据在各模块间如何流转（追踪 ID/对象在调用链中的变化）
- 边界场景（可选）：特殊权限、状态机转换
§6 Phase 4 — 建 README 索引
README 是 AI 读文档的唯一入口，必须在所有其他文档写完后生成。
README 必须包含
- 项目一句话定位（是什么、做什么、在整体架构中的位置）
- 文档地图（表格）：
- 理解层（
00-design.md、NN-scenarios.md）：一句话说"读懂设计动机用" - 参考层（其余文档）：一句话说"查X时用"
- 理解层（
- 推荐阅读路径（按任务）：
- 新人快速入门 → 读哪几个文档、顺序
- 要调用写接口 → 直接跳
03-write-api.md - 要理解数据模型 → ...
- 要理解迁移现状 → ...
- 关键术语速查（5~10 个项目特有术语，一句话解释）
- 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 导航三原则
- README 是唯一入口：AI 永远从 README 开始，不直接跳某个文档
- 按需加载：每个文档头部导读行说明"什么情况下读这个"，避免全量加载
- 双向交叉链接：参考层文档 → 链回 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 已知坑点
上下文稀释：子 agent scope 一定要小；不要让一个 agent 负责 "整个项目"；文件清单宁可拆多也不要合并太多。
模块报告覆盖不了业务场景：理解层（design + scenarios）必须单独投入，不能指望从模块报告里拼出来。跨模块业务流程需要专门追踪。
字段手册与叙述混写：参考层和理解层必须物理分离成不同文件，混写会导致 AI 每次加载都带来大量无关信息。
忘记反链：每份参考文档必须有头部导读行（含 README 和 design 的链接），否则 AI 在文档间迷路。
README 最后写：README 依赖所有其他文档已写完，才能准确地做索引和阅读路径推荐。不要最先写 README。
子 agent 不要写文件：子 agent 只返回报告文本，由主 agent 汇总后统一写文件，否则多个 agent 并发写同一目录会产生冲突或重复内容。