docs/ Agent 指引

本文件适用于 docs/ 下的文档工作，并补充仓库根 AGENTS.md。目标是让 docs/ 保持可导航、可追溯的系统记录，而不是堆积互相冲突的说明。

从哪里开始

任何文档任务先读 docs/README.md，再进入对应 topics/ 主题页确认当前权威口径、文档关系和已被取代的材料。

业务域存在自己的 accepted ADR/spec 时，遵守领域文档。

文档职责与权威性

• topics/：当前主题的导航与权威文档索引，负责说明取代关系和未决事项；
• decisions/：已接受的单点稳定决策（ADR）；
• architecture/：长期系统边界、依赖方向、数据所有权和信任区；
• specs/：可测试的规范性要求和协议定义；
• plans/：实施顺序、阶段门禁、回滚点和交付拆分；
• migration/：迁移映射、兼容损耗、生产切换与状态记录；
• reports/、references/：分析、调研、外部依据和历史推演；
• logs/：实施证据与过程留痕（可选，通常任务不必新建日志）。

reports/、旧 plans/、references/ 和 logs/ 不得覆盖 accepted ADR/spec。计划描述“何时、按什么顺序做”，不能静默改变已接受的系统语义。

若当前代码、运行事实与目标文档不同，应明确写成“当前状态 / 目标状态 / 迁移差距”，不要通过改写历史文档把两者伪装成一致。

修改文档的规则

• 默认使用中文；代码、路径、协议字段、标准名和固定产品名保持其 canonical 写法。
• 先判断是在更新既有权威文档、补充新的决策/规格，还是只记录调研/实施证据；不要把讨论稿或一次性结论写成 accepted 事实。
• 改变 accepted 决策或规范性要求时，同步检查相关 topic、ADR、architecture、spec 和 plan 的一致性；需要改变 MUST / MUST NOT 时，不得只改实现或日志。
• 在正式规范中使用 MUST / MUST NOT / SHOULD / MAY 等规范性语言时，沿用项目既有 RFC 2119 / RFC 8174 解释；不要在普通说明里滥用大写规范词制造虚假强制性。
• 文档被替代时保留历史价值并显式标注 superseded/历史背景与新入口；除非用户明确要求，不要删除能够解释设计演进的重要记录。
• 新文档名称、状态字段和目录选择优先遵循同目录现有惯例及对应 topic；不要为了统一外观批量重命名历史文件。

控制易腐化信息

• 不在设计/Agent 指引中复制可由 package.json、workspace manifest、配置、schema、CI 或代码直接读取的完整版本表、命令表、路由表、供应商/模型清单。
• 需要说明这些事实时，链接或指出机器可读的 source of truth，并只记录对设计有长期意义的约束。
• 外部技术、法规、标准或服务行为可能变化时，优先引用官方/一手来源；若时效性影响决策，记录核验日期或适用版本。
• 明确区分“仓库已接受的决定”“外部最佳实践”“作者建议/待决问题”，不得把调研建议直接写成既定规范。

一致性与验收

文档修改完成后至少检查：

• 所有引用的仓库路径、文档链接、规格编号和状态真实存在；
• 新增或取代权威文档时，相关 docs/README.md / topic 导航是否需要同步；
• 当前状态、目标状态、非目标和未决事项是否被清楚区分；
• 文档是否与适用的 accepted ADR/spec 冲突；若冲突是任务目的，应显式说明决策变化和影响范围；
• 纯文档改动通常不要求全仓 build，但若文档驱动生成、协议、发布或校验流程，则执行对应的相关验证。