documentation-guidelines

文档编写指南

记录代码本身无法说明的长期有效信息：业务意图、所有权、不变量、权限、契约和运维决策。实现细节和可执行证据应由源码和测试负责。

委派

默认在主对话中执行。委派可能增加用量：使用子 Agent 前，先就拟议的 Agent 数量和范围获得明确批准。在批准范围内可重复使用该批准；扩大已批准的数量或范围前，请再次征求批准。

查找所有者和证据

如有相关文档索引和所有者，先阅读，再根据源码、测试、架构、配置和运行时证据核实受影响的事实。阅读理解变更契约所需的链接；当继续阅读不再影响结果时，即可停止。文档缺失或过时，意味着应检查源码，而不是阻碍工作的前提条件。

针对当前范围，识别适用的参与者、触发条件、规则、状态转换、输入/输出、副作用、失败路径、所有权和兼容性要求。省略不相关的类别；记录尚未解决的重要事实，不要凭空编造。

长期有效信息变更时更新文档

变更	文档操作
内部重构、格式调整，或修复问题以恢复文档所述行为	仅在必要时更新受影响的路径或证据锚点
用户行为、业务规则或工作流	更新其现有所有者
API、架构、权限、事件或兼容性	更新契约和受影响的使用方映射
设置、迁移、部署、备份或恢复	更新对应的运维手册
实体重命名、移动或移除	修复发现路径和过时的引用
文档重复或相互矛盾	在一个所有者文档中保留有效事实，修复链接，然后在范围内删除过时副本

避免仅仅记录任务活动的文档变更。除非临时计划、命令日志和 CI 输出体现了长期有效的运维要求，否则应将它们保留在任务、PR 或现有证据载体中。

便于查找和维护

• 为每项长期有效的事实指定明确的所有者。使用方链接到该文档，只记录自身的映射或约束。
• 遵循代码库的布局。只有在确有发现或工具需求、且值得持续维护时，才添加路由器、注册表或元数据。
• 使用具体规则、稳定且便于搜索的标题、示例，以及少量源码/测试锚点。优先使用符号和路径，而非脆弱的行号。
• 区分事实、建议和未知事项。删除泛泛的教程、推测性要求、复制的实现内容，以及会过时的状态元数据。
• 如果历史记录仍有审计、迁移或运维用途，则予以保留。对于已被取代的受跟踪内容，若 Git 历史记录足够，则使用 Git 历史。

阅读 templates.md 了解文档类型，阅读 architecture.md 了解多所有者结构，或阅读 audit-cleanup.md 了解整合。

验证并汇报

从现有入口跟踪到更新后的所有者文档，检查链接、标识符、命令、证据锚点，以及受影响的使用方契约。搜索相互矛盾的副本和旧名称。运行针对性的文档或生成验证器，以及适用的必需检查；只有在变更影响可执行行为或其契约时，才需要运行应用测试。

汇报变更的长期有效事实、重要的删除或整合、验证情况，以及尚未解决的问题。