# 文档索引

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

## 目录结构

```
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`](../AGENTS.md) 是 coding agent 的入口上下文，其中的文档规则以本文件为准（AGENTS.md 只做摘要 + 链接，避免漂移）。

## 快速链接

- 总体设计：[design/design.md](design/design.md)
- 执行计划：[plans/execution-plan.md](plans/execution-plan.md)
- 决策记录：[adr/README.md](adr/README.md)