代码生成文档

文档为什么会比代码先坏

代码有 CI、lint 和编译错误当反馈回路；文档没有等价机制，一旦写完就只在「有人记得去改」时才会更新。结果是 PRD、HLD、运营手册和实现慢慢分叉——不是谁偷懒，而是流程上缺少以代码为真相源的生成与校准步骤。

技能怎么跑

本技能分两条路径，入口由你的表述决定，不能混用：

• 生成模式（A）：文档缺失或要从零建立时，从仓库逆向提炼后落稿。必须先由你明确文档类型（如 PRD、HLD、LLD、运营手册、测试文档、SLI/SLO、CI/CD 等）；未说明类型时只会提问，不会擅自开读代码。
• 反向同步模式（B）：已有文档但与代码对不上时，以代码校准文档。出现「更新文档」「文档漂移」「反向同步」等表述时，走独立流程（references/reverse-sync.md），不再执行生成模式的五轮骨架。

生成模式的大致节奏是：识别技术栈与入口 → 按文档类型扫描路由、模型、接口、业务规则等高信息密度位置 → 逐模块深度分析 → 按类型模板出稿 → 对复杂模块做第五轮复审（多规则、多层依赖或全量范围时尤其必要）。输出会区分 〔FACT｜文件:行号〕 与 〔INFER〕，并避免把 @Deprecated、无调用方或被开关关掉的逻辑写进正文。完成后写入 docs/[项目名]/ 并做同目录文档的同步检查，禁止留「待后续更新」。

适用边界

• 强烈建议按模块/功能点分批生成，而不是默认一次性覆盖整个仓库。
• 运营类文档会按受众去掉过多技术术语；架构与 LLD 则保留接口与异常路径精度。
• 推断不出且无法从调用方验证的细节会标注推断，需要你确认后再当作事实写入。