文档驱动：AI 软件工程的第一秘籍
内容提要
文章主张AI软件工程应“文档驱动”：文档是写代码前的输入、开发中的工作记忆和验收标准。核心四条为文档驱动、对抗审查、暴力测试、复杂度惩罚。作者强调先写PRD明确需求，用文档保存Agent思考过程，验收不可外包，并建议为项目配文档站，将文档视为与代码同等重要的交付物。
延伸解读
文档驱动为何成为AI工程的地基
文章将文档驱动列为四条实践之首，并视其为对抗审查、暴力测试、复杂度惩罚的基础。原因在于Coding Agent如同“失忆的天才”，每天遗忘项目背景，只能依赖代码、测试和文档。文档从代码完成后的补充，变为写代码前的输入和开发中的工作记忆。若文档缺失，Agent可能重复已被否定的方案，造成大量无效工作。因此，文档质量直接决定AI工程的方向正确性。
验收不可外包：人类签字的关键环节
文章强调验收测试无法交给AI代劳，因为“做出来的东西是不是你真正想要的”只有人类能判断。作者建议让AI生成验收方案，并交付与代码同等质量的使用手册，人类照着手册走通核心流程。验收等于用自己的信誉背书，偷懒会导致交付物大概率是垃圾。这一环节要求人类扮演资深架构师角色，对宏观路线和架构品味负责，而非逐行审查代码。
工作记忆管理：避免Agent随地大小便
针对Agent在项目中散落PLAN.md、NOTES.md等零散文件的问题，文章提出两层工作记忆管理：完整保存思考过程，按时间或议题记录原始过程；定期总结索引，更新到AGENTS.md或CLAUDE.md。两层缺一不可，既不能全部堆在一起，也不能只留索引。这样Agent遇到类似问题时可回溯之前的架构决策，避免重蹈覆辙。Session Log被视为项目真正沉淀的资产，记录了代码无法体现的Why。
文档站：从内部笔记到交付物
文章主张为每个项目配一个伴生文档站，将文档视为与代码同等地位的交付物。作者以OINK Hugo主题为例，说明文档站应具备交付简单、功能齐全、最小化摩擦的特点，并支持每页纯Markdown版本和llms.txt，方便人类和Agent使用同一份源。文档站不是随手记的云笔记，而应从第一天就写好并管理起来。没有合格文档的项目，作者认为完全不行，并举了朋友蒋老板的数据库项目为例。
Q&A
什么是文档驱动开发？它在AI软件工程中扮演什么角色？
文档驱动开发是指将文档视为写代码之前的输入、开发过程中的工作记忆以及交付时的验收标准。在AI软件工程中，文档是上下文管理的核心，与代码同等重要，甚至更重要。
为什么在AI编程中，文档比传统开发更重要？
因为Coding Agent像失忆的天才，没有人类团队的部落知识，只能依靠代码、测试和文档。文档写得差，Agent可能从方向上做错，重新实现已被否定的方案，浪费大量精力。
如何为AI Agent管理开发过程中的工作记忆？
将工作记忆作为文档管理，做两件事：完整保存思考过程（原始记录存工作目录，按时间或议题顺序），以及定期总结索引（更新到AGENTS.md或CLAUDE.md，记录过往Thread和Session）。两层缺一不可。
在AI软件工程中，哪些测试可以交给AI，哪些必须人工验收？
单元测试和集成测试可以交给AI自测，通常不用人工看。但验收测试必须人工介入，因为验收等于拿自己的信誉背书，不能外包。你可以让AI出验收方案，但最终签字必须自己来。
为什么建议为每个项目配一个文档站？
文档是交付物的一部分，必须方便交付。文档站能实现自动CI/CD、提供代码块、搜索、多语言等完整功能，每页有纯Markdown版本和llms.txt，方便人和Agent使用，且构建简单快速。
在AI软件工程中，Token应该主要花在哪些环节？
如果追求工程质量，至少70%～80%的Token应该用在QC和测试上，而不是写代码。写代码很快且不耗Token，真正耗Token的是穷举各种测试，这是提升质量的关键。
Silo项目是如何实践文档驱动开发的？
Silo为每个Issue创建设计文档，沉淀完整设计思路和决策过程。所有变更必须通过CI和人工审核，Agent的完整工作记录和取舍归档留存。Session Log被视为项目真正沉淀的资产，记录了Why而不仅是What和How。
