DDAD-002：写给AI看的文档，人也能看懂
DDAD-002：写给AI看的文档，人也能看懂
有人问，DDAD 里的文档既然主要给 AI 用，是不是应该全写成 JSON，字段越多越好？
千万别。
机器味很重的文档，通常人看着费劲，AI 也未必真能用好。它缺的往往不是格式，而是项目里那些没人写下来的规矩：启动命令是什么，改完要跑哪些测试，哪个目录不能碰，需求冲突时听谁的。
这也是我说「写给 AI 看的文档，人也能看懂」的原因。不是照顾人类阅读体验这么简单，而是人看不懂的约束，通常也没人能检查 AI 到底有没有理解。
拿一个项目里的 CLAUDE.md 来说，我会先写这几类东西：
- 常用的构建、检查和测试命令；
- 核心目录分别管什么；
- 已经踩过的坑；
- 代码风格和提交规矩；
- 做完一项工作后，怎么证明它真的完成了。
Anthropic 自己给的建议也差不多，而且特意提醒 CLAUDE.md 要简短、让人能读。这个提醒很重要。很多人一看到 AI 能吃长上下文，就忍不住把公司规章、架构设计、产品需求和半年前的会议纪要全塞进去。结果和搬家时把所有杂物倒进一个纸箱差不多：东西确实都在，找的时候照样骂人。
文档要具体，但具体不等于啰嗦。
「注意代码质量」没法执行。改成「修改 Python 文件后运行 pytest 和 ruff check，失败不得提交」，人和 AI 都知道下一步做什么。
「尽快完成」也没用。改成验收条件：哪个接口能调用，哪个页面能打开，哪些测试必须通过。DDAD 真正需要的不是更会写作文，而是把团队脑子里的默认规则变成可以执行、可以检查的文字。
这类文档还有一个好处：AI 做错时比较容易追责。到底是规则没写，还是写了它没遵守，一眼能看出来。最怕的是文档写得像领导讲话，句句正确，出了问题却找不到一条能执行的东西。