需要为代码库功能或系统编写架构文档时…

当用户要求记录某功能如何工作、创建架构概览、为新人上手或知识传递解释代码结构、或研究并描述系统设计时，通过分阶段研究代码库产出面向人类与 AI 的架构文档。

适用场景

解决思路

1. 阶段1 范围定义：先问清要记录的功能/系统/组件，明确目标读者（开发者、AI agent 或两者），若上下文不明显则确认代码库位置。
2. 阶段2 初步探索：用轻量快速的方式广泛浏览代码库建立心智模型（如在 Claude Code 中用 Haiku Explore 子代理）：扫描目录结构并识别关键入口点；阅读 README、配置文件和已有文档；找出与该功能相关的主要文件和模块；形成对代码库组织的心智模型。
3. 阶段2 向用户展示高层大纲（列出各组件及简述），并询问是否准确捕捉了研究范围，请用户回复 yes 继续或指出误解；用户确认后再进入深度研究。
4. 阶段3 深度研究：对大纲中每个组件，从入口点追踪代码路径；识别组件间的依赖与交互；记录配置项及其定义位置；找出数据存储或持久化的位置；建立代码引用索引（文件路径 + 关键函数/类名）。尽量复用初步探索的信息，按需读取更多文件；若范围变化较大可再启用第二个代码探索子代理。
5. 阶段3 停止探索的判断：能无缺口地追踪 happy path；能说清边界（范围内与外部）；能画出无占位框的架构图；能回答每个组件的输入输出（谁和谁通信）。出现“我认为它连接…”“可能调用…”的不确定、存在未检查模块的 import/调用、无法解释数据如何从组件 A 到 B 时说明还没做完；逐文件通读、追踪进外部库或框架内部、探索不影响架构的实现细节则说明做过头了。
6. 阶段4 文档草稿：按模板生成文档，交给用户审阅并根据反馈迭代；如有 AskUserQuestion 工具，用它就关键决策征求用户输入。
7. 阶段5 定稿：写入前先确认文件位置，可基于仓库惯例（如 docs/architecture/、ARCHITECTURE.md）提议路径，但未经用户明确确认位置绝不写文件（用户事先给出路径即视为确认）；将最终文档写入已确认的位置。
8. 文档模板结构：标题为 [功能/系统名] Architecture，依次包含 Overview（1-2 段说明做什么及为何存在）、Architecture Diagram（Mermaid flowchart）、Components（每个组件含 Purpose、Location、Key Functions、Interactions）、Data Flow、Configuration、Code References 表格（Component/File/Key Symbols）、Glossary 表格；按被记录功能调整，不适用的段落可省略，可增加独特方面。
9. 代码引用约定：路径用相对仓库根的相对路径（如 src/auth/login.ts）；引用函数和类名而非行号；格式为 path/to/file.ext 并单独列出关键符号；可用搜索模式作锚点（如 auth/ 中的 handleAuth 函数）。
10. 代码引用禁忌：绝不把代码粘贴进文档（代码会立刻过时，文档应是指向源码的指南，描述代码做什么再指出在哪找）；不用行号（每次编辑都会变）；不用绝对路径，只用仓库相对路径。
11. Mermaid 图：组件关系用 flowchart（如 Client --> API Gateway --> Service --> Database），请求流用 sequence diagram（Client->>API: Request 等）；图要聚焦被记录的具体功能，避免塞入无关组件。
12. 写作准则：描述而非复制，解释代码做什么及在哪找；用标题、表格、列表便于扫读；具体到真实文件路径、函数名和配置键；同时服务人类与 AI 两类读者（对人类清晰、对 AI 结构一致）；注明关于代码状态或版本的假设。
13. 输出为 Markdown 文件，含 Mermaid 图和稳定的代码引用，适合人类和 AI agent 阅读。

适用边界 · 注意事项

• 不要逐文件通读整个目录而不做代表性抽样，也不要追踪进外部库或框架内部，或探索不影响架构的实现细节。
• 不要在未经用户明确确认文件位置的情况下写入文档（用户事先给出路径除外）。
• 不要在文档中粘贴代码、使用行号或绝对路径。