当接手遗留代码库、文档缺失或过时时，如何从代码重建可信文档树

在文档缺失、过时或不可信的既有代码库中，通过先勘察、再按证据层级验证、最后生成可复用文档树的方式重建系统文档。

适用场景

解决思路

1. 先勘察再动笔：枚举系统的各个面——入口点与进程（可执行文件、服务、定时任务、队列消费者、请求处理器）、命令与端点、配置（代码读取的每个键、标志、环境变量）、数据（模式、表、迁移、磁盘文件、外部存储）、集成（每个外部系统及其方向和协议）、构建与部署（产物如何产生、落在哪里）。
2. 每个计数都是一项声明，必须打印出背后的命令、在 HEAD 上运行、标注日期；命令、计数和日期记入覆盖台账，文档本身保持稳定。
3. 文档树从勘察清单推导，而不是按阅读顺序推导。
4. 契约面要详尽：HTTP 端点、消息负载、命令、文件格式、配置键等外部方绑定且无法读代码的部分，按 Reference 规则逐项覆盖每个端点、每个字段、每个键。
5. 内部机制只写要点：描述性文档说明机制及其后果（如“存储是只追加的；读取取链的末端；更新替换整条记录”），实现该机制的类、数据库键、映射和调用链留在代码里。
6. 用重构测试检验：完成的# 文档在代码重构时保持不动，只在行为变化或新功能落地时修改；任何会被重命名证伪的句子（方法名、行号、类列表）都是散文形式的实现细节，应提升为其所实现的行为或删除。
7. 散文不携带代码引用：文档在开头一次性命名所描述的模块或路径作为漂移锚点，正文中不出现路径、类名和行号；精确的 file:line 放在 findings 笔记中。
8. 边界检查：只对已经打开该文件的读者有帮助的段落是转录，删除它或缩减为其锚点；通过检查的细节通常是 quirk，而 quirk 是内容。
9. 遵守证据层级（信任度降序）：1) 在 HEAD 上阅读的代码；2) 覆盖该路径的测试；3) 运行时证据（日志、数据库内容、实时配置，需标注日期）；4) 提交历史；5) 名称、注释、现有文档和人的记忆——这些是证词，引用、验证后才可重复；当名称与行为矛盾时，记录行为并指出矛盾。
10. 证明代码是死是活：活代码由接线证明（引用搜索、注册、运行时追踪）；死代码由缺失证明，并命名缺失证据（如“没有命令、没有控制器、除自身测试外无引用”）；休眠是独立状态（已接线但禁用，或只能从死路径到达），用过去时或显式的已接线但禁用限定词描述；配置键要检查是否绑定，代码从不读取的键是死旋钮。
11. 在接地过程中保持类型纪律：描述性文档以现在时精确匹配代码行为，每篇在开头命名所描述的代码；规范性文档若发现被违反，绝不淡化——契约成立，违规记入 findings 笔记；历史被挖掘并标注，git log 显示的内容作为历史，推断的意图标注为推断并说明依据；过时文档加横幅，绝不静默删除。
12. Quirk 是内容：令人惊讶但真实的行为（如更新替换整条记录、打破模式的表）写入所属文档，平实地陈述为行为。
13. 缺陷只记录不追查：看起来坏掉的东西仍按其实际行为记录，怀疑本身在 findings 笔记中用一行加 file:line 记录，文档链接该行而不重复；不做严重性分级，不做验证流水线。
14. 故意还是损坏往往无法从代码单独判定：陈述行为，标记意图未知，让所有者分类。
15. 维护一份覆盖台账（coverage.md）：按面记录已文档化计数与勘察分母，每个都带命令和日期；每篇文档的状态（草稿或已审阅），草稿在文档自身中标注；标记已审阅需要第二位读者；工作先记入台账再被依赖；中断时台账说明已完成和未完成的内容；并行时每篇文档只有一个作者。
16. 分阶段并行推进：1) 勘察扇出——每个面一个枚举者，返回带命令的计数，用能保持输出形状的最小模型；2) 合并与规划——单一屏障，去重清单、推导文档树、写入覆盖台账，由一个中等模型完成；3) 按子系统接地再审阅——每篇计划文档一个接地代理，直接流水线到该文档的新鲜眼光审阅者，子系统间无屏障；接地用中等模型封顶，小模型常足够；仅在证据表明需要时升一级，绝不默认升级，绝不升到最大级；被弹回的接地者重新划定范围（锐化提示或拆分），第二次弹回作为未解决文档交给所有者；审阅者持判断席位，用中等模型；4) 最后组装——概览、索引和交叉引用从已接地的叶子文档推导；一次端到端追踪真实场景跨越子系统边界，追踪的流程成为 processes.md。
17. 使用默认文档树骨架：docs/README.md（索引，含置信层级 Measured/Sourced/Estimated）、overview.md（系统边界和真实依赖图，来自导入和接线）、<subsystem>.md（每个子系统一篇描述性文档）、config-reference.md（每个键含默认值、绑定证据和 Usage，死旋钮标记为死）、api-reference.md（每个端点、命令和消息负载）、integrations.md（每个外部系统、方向、协议、失败行为）、data-model.md（存储什么、谁拥有、生命周期和 quirk）、processes.md（端到端业务流程，配 diagrams/ 中的图）、diagrams/、history.md、findings.md、coverage.md、unknowns.md。
18. unknowns 文档即使为空也必需：“没有未知”是一项声明；每个条目命名检查了什么，让下一次尝试从停止处开始。
19. 整个行动对系统只读：文档、findings 笔记和台账是唯一输出；每个发现的缺陷是笔记，绝不是编辑。
20. 不写交付叙事：文档树描述系统，不描述记录它的行动；行动存在于台账和提交中。
21. 扩展所有者：遗留行动若在唯一好的活文档旁另起炉灶会让文档树更糟；应接地并扩展该文档。

适用边界 · 注意事项

• 不要用于记录你正在做的变更；核心技能和文档类型技能覆盖随变更写文档。
• 不要用于论证重写；那是 writing-design-docs 的职责，由这些文档喂养。
• 不要用于修复接地过程中发现的问题；代码修复在本插件之外，记录异常才是本技能的事。