superior-docs

优质文档

编写文档，让未来的维护者无需依赖聊天记录，也能了解项目当前的状态、重要决策和安全操作规程。文档是对证据的持续维护视图，而不是凭空编造的第二套事实来源。

选择模式

• 引导搭建： 在尚无 docs/ 系统的项目中，建立一套实用的文档体系。
• 记录： 在实施时间线中记录经验证的实现、修复、重构、配置变更或功能结果。
• 同步： 在项目变更经验证后，更新受影响的文档。
• 重建： 根据仓库证据梳理架构演进、版本发布或维护历史。
• 交接： 在一项重要工作结束时，记录当前实现、边界、风险和后续工作。

如果用户的请求已经明确了模式，就不要再让用户选择。

默认记录实现工作

对代码、配置、架构、API 行为、安全控制、构建行为或用户可见功能进行重大变更并验证后，应创建或更新实现记录，除非用户明确要求不要创建或更新文档。

每当其他实现技能完成重大工作时，都要阅读 references/automatic-change-recording.md。该文件定义了默认流程、最低限度的引导搭建要求、条目结构、退出方式和排除项。

不要等待用户另行提出文档请求，也不要对常规操作请求许可。将“跳过文档”“不要记录此事”或等效项目指令等明确退出要求视为权威指示。除非用户明确说明，否则针对单项任务的退出要求不代表永久偏好。

建立证据

检查相关代码路径、配置、测试、脚本、部署文件、现有文档和仓库指引。若涉及历史顺序或版本发布，应查看 Git 历史。

检查仓库状态和任务的实际差异，然后再归因变更。在有未提交更改的工作区中，应保留无关的用户编辑，不要把任务开始前就存在的变更描述为本次任务的成果。

将陈述分类为：

• 当前事实： 有当前仓库或运行时证据支持；
• 已接受的决策： 记录在权威决策来源中，或由用户明确确认；
• 历史事实： 有提交、标签、版本发布、迁移或注明日期的材料支持；
• 计划工作： 已明确提出但尚未实现；
• 未知： 尚未解决，并明确说明为未知。

未经佐证，不要把提交消息、过时文档、未使用文件或看似合理的架构说成当前事实。

构建精简实用的文档地图

在初始化或重组 docs/ 时，阅读 references/documentation-map.md。用户要求建立完整的连续性文档体系时，始终创建索引和三个核心文档。只有在仓库有相应证据且确有维护价值时，才添加专门章节。

自动变更记录所需的初始化工作更少：如果项目尚无文档体系，只创建 docs/README.md、docs/implementation-timeline/README.md、带有索引的稳定功能域子文件夹，以及第一份经验证的变更记录。不要为了满足记录默认要求而凭空创建三个核心文档。

不要创建空目录、占位指南，也不要为想象中的子系统各建一个文件。精简且彼此关联、始终准确的一组文档，胜过一棵看似庞大、却无人能信任的目录树。

面向检索编写

• 每份文档只聚焦一个持久主题，并为其设置稳定路径。
• 每份文档开头都应说明用途、范围，以及最后核实的修订版本或日期。
• 链接到权威代码、配置、命令、决策和相关文档。
• 记录所有权和边界，而不是记录很快就会过时的详尽文件清单。
• 只有在仓库源代码中核实过或通过安全执行验证过之后，才使用准确命令。
• 将当前状态与历史和未来工作分开。
• 对映射、决策、接口或命令，优先使用简洁的表格；用散文说明理由和限制。
• 为易变的契约注明权威来源，避免手动重复生成的架构、命令输出或配置清单。
• 保留所有权信息和更新触发条件：文档应明确说明什么事件会使其过时，以及维护者应在哪里核实。

编写文档索引、项目背景、架构或决策记录时，请阅读 references/core-files.md。

谨慎还原历史

使用提交、发布、迁移或早期文档来构建时间线和交接记录时，请阅读 references/history-and-handoff.md。

按结果和架构影响总结变更。不要罗列每个提交、把提交顺序视为因果关系，也不要仅因某个分支曾包含相关代码，就声称某项功能已经发布。有稳定标识符时，请将事实链接到对应提交或标签。

同步时避免重写所有内容

变更后，只更新其陈述已变得不完整或不再正确的文档。保留有价值的历史；如果仓库采用追加式记录，则追加决策。现实情况改变时，应替换对当前状态的描述；不要把新旧两个版本都保留为仍然有效的内容。

如果文档与可运行的代码或配置冲突：

1. 核实相关代码路径是否处于启用状态；
2. 检查是否存在已接受、待执行的迁移或例外；
3. 在获得授权的情况下更新过时文档；
4. 报告尚未解决的冲突，不要自行选择更倾向的说法。

记录与同步彼此相关，但并不相同。默认情况下，重要实现应有简洁的时间线记录。只有在当前状态架构、决策、指南或构建文档中的陈述或流程确实发生变化时，才更新这些文档。

验证

• 重新打开每份已更改的文档，并检查其中的相对链接。
• 对照当前来源确认命令、路径、名称、版本和所有权。
• 检查根索引是否能指向每份维护中的文档，且不指向占位内容。
• 检查差异，确认其中没有秘密、凭据、私有基础设施细节、个人数据或复制的日志。
• 确认文档只归因于当前任务的证据所支持的工作，且未纳入无关的工作区未提交变更。
• 报告已检查的证据、已更改的文档、历史记录的局限，以及尚未解决的未知事项。