# 工程文档体系

工程文档的作用是让下一次改动能找到当前事实、关键约束和已验证证据，不是为每次任务生成一套设计报告。Study Buddy 的有效做法是将可执行约定、当前契约、决策与历史证据分层，并由一个短索引组织入口。

## 四类事实来源

| 位置／类型 | 负责回答的问题 | 维护规则 |
| --- | --- | --- |
| `AGENTS.md` | 此仓库中 Agent／开发者能做什么、如何提交、如何验证、数据库如何迁移、哪些范围和授权边界不可越过 | 每个项目根目录必须存在，且按仓库实际情况编写；在项目规则变化时同步修改。它不是完整产品手册。 |
| `docs/README.md` | 当前应从哪里开始读、哪些是开发入口、当前产品、待办和历史证据 | 只作导航，链接唯一事实来源；新增长期文档时更新。 |
| 当前契约文档 | 系统目前如何工作、架构边界、接口、身份、部署、数据与设计规则 | 以已实现代码和已验证行为为准，明确已知限制。 |
| 决策／验证／迁移记录 | 某一时间的取舍、实施范围、实际检查、失败和未完成事项 | 标题或正文带日期，标注历史性；不能被误当作当前事实。 |

常见的当前契约文档可按实际需要建立：`development.md`、`architecture.md`、`software-design.md`、`deployment.md`、`identity.md`、`agent-and-data.md`、`ui-foundation.md`。不是每个新项目都需要全部文件；只在某类规则已多次影响决策或需要跨任务稳定复用时才拆出文档。

当文档已经多到顶层索引不再易读时，再按读者问题建立子目录和子索引，例如 `docs/architecture/`、`docs/capabilities/`、`docs/engineering/`、`docs/data/`。可增加一份带核验日期的“当前实现快照”，列出实际应用、路由、服务、公开资源、数据边界、代码位置和已知差异；它用于发现文档与实现脱节，不替代各领域契约，也不应在每次小改动机械重写。

## 新项目的最小文档落地

一开始通常只需要：

```text
AGENTS.md              当前仓库的操作、授权、开发与验证约定
docs/README.md         文档导航
docs/development.md    本地启动、分支／提交、验证和迁移约定
docs/architecture.md   当前拓扑、权威边界和已选依赖
```

根目录文件使用标准名称 `AGENTS.md`。它至少明确：当前技术栈与应用边界、任务范围和外部动作授权、禁止过度设计与无关重构、不得用前端假实现冒充完整功能、数据库迁移产物与执行规则、Git 初始化与原子本地提交、`.gitignore`、二进制资源与 OSS、本地 JSON／SQL 数据边界、配置和密钥边界、按风险验证方式，以及文档何时同步更新。涉及数据库的项目必须要求提交生成的迁移 SQL 和 ORM 所需元数据，禁止改写已应用迁移；没有数据库的项目应明确当前不适用，而不是创建空迁移目录。

具体内容、审阅清单和可改写模板见 [`AGENTS.md` 项目规范](agents-md-standard.md)。只有某个子目录确实存在不同命令、所有权或安全约束时才增加嵌套 `AGENTS.md`；不得把根规则复制到每个目录。

当相关事实真的出现后，再增加：

- `deployment.md`：有明确的测试／生产或发布机制时；
- `identity.md`：存在账号、Cookie、第三方身份服务或登录生命周期时；
- `agent-and-data.md`：有 Agent、Tool、资料引用或模型成本规则时；
- `software-design.md`：多次改动需要共同的模块、事务、并发或失败语义约束时；
- `ui-foundation.md`：已有跨页面复用的布局、token 和交互规则时；
- `decisions.md` 或单独带日期的记录：需要保留非显而易见取舍时；
- `verification.md` 或带日期的验收记录：检查范围、实际结果或限制需要被后续交付引用时。

没有发生的能力不建空文档，更不创建看似已完工的接口说明、发布流程或运行手册。

## 写作与更新规则

1. 将“已实现”“计划”“决策假设”“历史记录”“待真实验收”明确分开。规划文档不能被写成能力声明；测试替身通过也不能写成真实服务商或生产验收。
2. 每条规则只保留一个首选事实来源。例如详细发布顺序写在 `deployment.md`，`development.md` 只链接该处；根目录约定只保留项目范围的短摘要和执行边界。
3. 行为、接口、配置所有权、部署步骤或验证要求变化时，同一次改动更新受影响契约和文档索引。纯重命名或探索草稿不需要制造记录。
4. 验证记录写实际命令／场景、结果、日期和限制；保留首轮失败及修正后的结果，不能用一次重跑覆盖历史。
5. 文档不得包含真实密钥、用户资料、数据库导出、运行日志、私有文件地址或可绕过权限的内部细节。用变量名、受控示例和行为说明代替。
6. `AGENTS.md` 中的强制规则要能由实际仓库验证。不得保留错误命令、虚构目录、已经不用的分支流程，或将某个参考项目的服务商和部署约定当成通用规范。

## 建议的阅读顺序

开始改动时先读 `AGENTS.md`，再经 `docs/README.md` 找到与任务对应的当前契约；需要知道过去为什么这样做时才读决策和验收记录。不要一次性把历史研究、过期规划和所有领域文档当作当前要求。

交付时简短说明：修改了什么、相应的文档位置、实际验证结果和刻意未做的事项。这样文档成为下一次开发的起点，而非项目的负担。

产品达到多端、公开 API 或长期运维规模时，补充阅读[IELTS Buddy 的扩展工程经验](../extensions/ieltsbuddy-development-experience.md)。