文档索引

August 14, 2026 · View on GitHub

本目录是项目的唯一文档根。文档按类型分层，每类有明确的生命周期与更新规则。

目录结构

docs/
├── README.md          # 本文件：文档索引 + 文档管理规范
├── design/            # 设计文档（描述"是什么、为什么这样设计"，随实现演进）
│   └── design.md      # v1 总体设计（架构、seam 接口、认证、UI）
├── plans/             # 执行计划（描述"怎么做、做到哪了"，里程碑驱动）
│   └── execution-plan.md  # v1 执行计划（M1–M7 里程碑 + DoD + 风险）
└── adr/               # 架构决策记录（不可变快照，只追加不修改）
    ├── README.md      # ADR 索引与流程
    └── NNNN-*.md      # 单条决策记录

各类文档的职责边界

类型回答的问题生命周期更新方式
design/系统是什么样、接口长什么样活文档，随实现演进直接修改，重大变更先出 ADR
plans/按什么顺序做、验收标准是什么活文档，里程碑勾选推进勾 DoD、调整任务；范围变更先出 ADR
adr/为什么当时这样决定不可变，记录决策时点只新增；推翻旧决策时新增一条并标记旧条 Superseded

文档管理规范

  1. 单一事实源：接口定义以 design/design.md 为准；进度以 plans/execution-plan.md 的 DoD 勾选为准；决策理由以 adr/ 为准。三者不重复展开对方内容，只互相链接。
  2. 决策先行：任何推翻既有设计决策的改动（换认证方式、改包结构、调 seam 接口语义等），先提 ADR PR 讨论，合并后再改 design / plans / 代码。
  3. 语言约定：docs/ 内文档使用中文；根目录 README.md 面向外部用户，中文为主，英文版在 README.en.md；未来各包 README 双语（见工程门槛）。
  4. 状态标注：design 与 plan 文件头部维护 > 状态：… 行（如"设计定稿，未开工" / "M2 进行中"），改动实质内容时同步更新。
  5. 新文档落位：先判断类型（设计 / 计划 / 决策），放入对应子目录并登记到本索引；不确定归属的内容不新建文件，先并入最接近的现有文档。
  6. Agent 协作：仓库根的 AGENTS.md 是 coding agent 的入口上下文，其中的文档规则以本文件为准（AGENTS.md 只做摘要 + 链接，避免漂移）。

快速链接