工程文档体系

工程文档的作用是让下一次改动能找到当前事实、关键约束和已验证证据，不是为每次任务生成一套设计报告。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/。可增加一份带核验日期的“当前实现快照”，列出实际应用、路由、服务、公开资源、数据边界、代码位置和已知差异；它用于发现文档与实现脱节，不替代各领域契约，也不应在每次小改动机械重写。

新项目的最小文档落地

一开始通常只需要：

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

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

具体内容、审阅清单和可改写模板见 AGENTS.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 或带日期的验收记录：检查范围、实际结果或限制需要被后续交付引用时。

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

写作与更新规则

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

建议的阅读顺序

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

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

产品达到多端、公开 API 或长期运维规模时，补充阅读IELTS Buddy 的扩展工程经验。