AI 能写代码以后,我为什么反而开始写文档了?

👋 Hi，我是乐峰呀，一枚野生程序员，喜欢蒸馏点技术，也喜欢蒸馏点程序人生，把复杂的东西讲简单，把枯燥的东西写得有趣。🚀

上一篇，我写了怎么让 ChatGPT 直接进入 GitHub，读代码、改代码、提交 PR。以前还得一段段复制代码，现在把项目地址丢过去，再告诉它我想做什么，它就能自己进去找、自己改。

按理说，AI 都已经能直接写代码了，我应该继续疯狂给 Yakable 加功能。但最近这段时间，我干得最多的事情反而不是写代码，而是写 AGENTS.md、Java 规范、模块规范、测试规范，甚至 PRD。

为什么？因为我慢慢发现，AI 现在最大的问题已经不是“会不会写”，而是：它每次都能写，但不一定每次都按同一种方式写。

不知道大家有没有遇到过这种情况：让 AI 写一个功能，逻辑是对的，代码也能跑，可项目写着写着，ProjectAssembler、ProjectConverter、ProjectManager 之类的类就越来越多。你说它错了吗？好像也没错，但本来一眼就能看懂的逻辑，被拆散以后，读代码反而要不停往下跳。

我后来没有简单粗暴地规定“这些类统统不能出现”，而是换了一种方式：把 Service 到底应该负责什么、可以依赖谁、数据转换应该怎么做，直接写清楚。 比如 Service 只负责本领域业务，不为了形式统一补一堆无意义 CRUD；DTO、Entity、VO 的简单转换优先走已有的 Common 能力，没必要每次再造一套转换层。

这样做的好处是，我约束的不是某几个类名，而是为什么这个类需要存在。下一次 AI 再写类似功能时，它有了这些边界，大概率就不会为了“架构完整”随手再多拆几层。

这样做以后，AI 当然不会突然变成“百分之百听话”，但下一次再让它写类似代码时，大概率会顺着项目里已经存在的规则走。对我来说，这就够了：不是让 AI 每次都猜对，而是尽量减少那些本来就不该让它猜的东西。

Service 只是其中一个例子。类似的问题在 Yakable 里还有很多：模块边界不清楚，我就补模块 README；测试不知道该测到什么程度，我就补测试规范；需求容易被 AI 自己脑补，我就开始先写 PRD。  

我现在的思路其实很简单：遇到一个反复需要解释的问题，就把它变成项目里的规则。当然，这些文档首先还是给人看的，然后才是给 AI 看的。如果连自己都不愿意读，再“AI Friendly”也没什么意义。  

规范不是为了迁就 AI，而是先让人看得懂，再让 AI 跟得上。 

下一篇，我准备先从最前面的一份开始聊。

AGENTS.md 到底应该写什么，又不应该写什么？

好了，今天就蒸馏到这儿。

AI 可以负责写代码，但规则，最好还是掌握在自己手里。

我是乐峰，我们下篇见。🚀