Agent 引导文档生成器

当 Agent 接手项目时发生了什么

把一个新 Agent 扔进陌生代码库，它只能靠猜。没有结构化的引导文档，Agent 需要花大量时间在海量文件里摸爬滚打，找入口、理架构、猜规范。更糟的是，当你让不同 Agent 各自生成文档时，得到的往往是几份职责重叠、内容互相复制的 README——它们各自声称"完整覆盖"，实际上谁都没有真正可用的导航能力。

agent-onboarding-docs 解决的是这个问题：为 Agent 生成一套职责清晰、可迭代维护的引导文档，而不是又一套"看起来什么都写了"的项目文档。

核心能力

这套技能产出的不是单份文档，而是一套分工明确的 canonical 文档套件：

• CLAUDE.md：总导航入口，负责文件索引、模块定位和接手 checklist
• PRD.md：产品背景、业务规则和决策记录
• DEVELOPMENT_GUIDE.md：架构约束、开发流程和陷阱
• CODE_STYLE_GUIDE.md：仅在项目有足够代表性代码时生成，记录真实代码风格

核心原则是区分"实现事实"和"产品意图"。代码和配置是实现事实，需求文档和已确认设计是产品意图。两者冲突时，技能会显式记录差异，而不是静默覆盖其中一方。

工作流程分两种模式：现有代码逆向生成（模式 A）和需求文档正向生成（模式 B）。模式 A 会扫描源码、追踪调用链、读取至少 3 个代表性文件提取风格规则；模式 B 则从 PRD 和需求出发，标注"待确认"的技术决策，避免在没有代码证据时编造规范。

500 行上限是硬约束。任何文档接近 500 行时，必须提取专题文档到 docs/agent-onboarding/ 下，原文档只保留摘要和链接，并在 CLAUDE.md 文档地图中登记。这防止了文档无限制膨胀。

适用边界

这套技能有几个明确的红线：

• 不用于生成普通 README，也不是改错别字的工具
• 迭代更新时必须在原位修改，禁止创建 -new、-v2、日期副本或第二套文档
• CODE_STYLE_GUIDE.md 不会在空脚手架或纯需求阶段生成，必须有至少 3 个真实源码文件支撑
• 不把 Repository、Factory、DTO 等通用模式当作项目规范，除非代码中有证据
• 不会以"避免过度设计"为由省略安全、权限或数据完整性保护

渐进式加载是另一个关键设计：参考文件按需读取，不一次性加载所有模板。先读 references/index.md 定位，再按当前步骤选择对应的工作流、代码风格提取或模板文件。

写完文档后必须执行质量检查清单，确认路径、命令、模块职责都有真实证据支撑，且没有丢失已有的人工内容。