文档和决策记录
文档是帮助使用、修改、评审和运维系统的工具。先确定权威位置和维护者，再选模板；不必为了符合目录图而创建空目录。
文档责任表
| 文档 | 主要用途 | 需要更新的时机 |
|---|---|---|
| README.md | 项目用途、快速开始、命令和主要链接 | 用途、安装、启动或常用路径变化 |
| AGENTS.md | 仓库级 AI 代理工作规则、边界、命令和权威文档链接 | 命令、保护边界、评审规则变化 |
| docs/index.md | 权威文档入口、状态和所有者 | 重要文档增加、移动或退役 |
| docs/product/brief.md | 问题、用户、范围、成功标准 | 产品范围或目标变化 |
| docs/architecture/overview.md | 系统上下文、组件、责任和关键流程 | 所有权、集成或部署变化 |
| docs/development/local-development.md | 支持的开发模式、依赖、启动测试、数据生命周期 | 工具链或本地运行方式变化 |
| docs/api/ 与契约文件 | 请求、响应、权限、错误、兼容约定 | 接口、事件、架构或策略变化 |
| docs/data/ | 数据责任、迁移、保留、租户隔离 | 结构、所有权或留存变化 |
| docs/plans/ | 在做或待评审的较大变更 | 发现、切片或风险变化 |
| docs/adr/ | 难以回滚的技术/产品决定及原因 | 新决定取代旧决定时增加新 ADR |
| docs/operations/ | 部署、回退、监控、备份、事故手册 | 运行环境或故障处理变化 |
文档详略由职责、风险和真实维护需要决定，不由团队人数决定。边界简单的项目可用 README 加简洁 AGENTS 记录目的、权威上下文、代理边界和命令；服务或平台再按实际复杂度增加架构、接口、数据、安全和运维内容。已有 Docusaurus/MkDocs 站、docs/planning 或契约目录可以继续作为权威来源；导航不需要迁移文档内容。AI 工具需要在仓库内找到稳定上下文，不能依赖某个人的聊天历史。
写作要求
- 开头一两句说明目的、读者和适用范围。
- 对系统描述区分“当前已核实”“拟议”“历史”与“未知”，重要断言给出路径、命令或契约依据。
- 使用便于任务导航的 Markdown 和稳定相对链接；保持仓库主要语言一致。
- 设计文档说明目标和非目标、组件、接口/数据、权限、安全/可靠性风险、失败路径、方案取舍、验证与发布。
- Runbook 说明前置条件、影响、步骤、期望结果、健康检查、恢复与升级联系人；绝不放真实密钥。
- 低层 API/字段细节放在 OpenAPI、proto、schema 或迁移里；文档解释原因并链接到权威契约。
- 负责人、状态和复核日期只有在有人实际维护时才记录。未知的人名、日期、端点和部署不得编造。
- 未解决项标为 TODO/TBD，并尽量指出谁做决定、下一步是什么。
架构图和 ADR
默认使用可在 Git 中评审的 Mermaid Markdown 图。图注明确是当前、拟议或示例，解释边界和箭头含义，并链接实际接口/代码。图只是视图，不能替代 OpenAPI 等精确契约。
对影响长期支持、数据兼容、访问边界或独立部署的决策使用 ADR，至少记录背景、候选方案、决定和后果。不要为普通小改动写 ADR，也不要通过改写旧 ADR 来伪造历史；后续变化写新的 ADR 并标记替代关系。
文档校验
评审时检查内部和外链、图中组件名称、文档状态、命令工作目录、示例与当前契约是否一致。自动化链接检查有帮助，但不能证明文档中的系统事实或恢复过程真实可用。