文档驱动AI迭代开发规范

先解决的问题：AI 编程的知识断层与静默破坏

AI 编程助手的上下文窗口是有限的。会话一结束，项目知识就散落在对话历史里；下一次会话的 AI 等于"裸奔"——不知道目录约定、不知道运行命令、不知道禁区，于是重复犯错、重复探路。另一个老问题是：模型改完代码后没有测试网兜底，已有行为被静默破坏，等到上线才发现。

这套 DDAD + TDD 规范就是针对这两个痛点设计的。

核心思路：两条铁律与标准文档结构

DDAD（Document-Driven AI Development）：把项目知识持久化在文档而非对话历史里，每次会话先读文档交接，离开时把变化写回。TDD：先写失败测试，再写最小实现，最后重构，测试是 AI 与项目之间的契约。

两条铁律：没有文档不动手，没有测试不改码；文档与代码同进同出。

标准文档结构：

• AGENTS.md — 每次会话的第一入口：安装/构建/测试/运行命令、目录约定、代码风格、禁止事项
• docs/PRD.md / docs/ARCHITECTURE.md — 需求与架构
• docs/CHANGELOG.md — 迭代日志
• docs/DECISIONS.md — ADR 决策记录
• docs/tasks/ — 单轮迭代任务卡

每轮改动必走的流程：

1. 会话交接：先读文档，缺文档先补骨架，禁止"裸改"
2. 代码探查：索引工具优先（codegraph、ctags、ast-grep 等），降级顺序 Grep → Glob → Read，禁止全文扫读找符号
3. 建任务卡：验收标准、方案概述、测试计划、明确"不做什么"
4. TDD 执行：Red（按预期失败）→ Green（最小实现）→ Refactor（测试全绿前提下清理）
5. 文档同步：CHANGELOG / ARCHITECTURE / DECISIONS / AGENTS.md 与代码同一提交
6. 小步提交 + 逐条验收

适用边界与注意点

• 它约束的是 AI 在长迭代项目中的行为，单文件脚本或一次性实验项目收益有限
• 纯文档、配置、样式微调可不写测试，但需在 CHANGELOG.md 注明原因
• 任务卡超过 200 行说明需求过大，应先向用户提议拆分迭代
• 规范依赖项目自带索引工具才能发挥最大效果；长期迭代却无索引工具时，它建议引入 ast-grep 或 codegraph MCP 并记入 DECISIONS.md