如何创建AI Agent友好的项目

最近，用Codex修改了一个PHP项目的模板，出乎我意料之外，没有原本想象的三五下就弄好，反而折腾了好几天。

有那么一瞬间，我都在怀疑我的基于GPT5.5和GPT5.6的Codex是不是倒退回了2023年的Web上的ChatGPT。

很多细节，比如字体大小、CSS效果都要单独让Codex修改，甚至有时候，改一个细节，还要多轮对话。

相比修改这个PHP项目的模板，最近做的几个基于Nextjs的网站简直是太顺利了，从零开始，几乎一句换就把主要的功能全部完成，然后再做个首页、做一下多语言，就上线了，前后就没用几个小时。

这就是AI Agent友好的项目和AI Agent不友好的项目的区别。

我总结了一下。如何让自己的项目AI Agent友好。

1、结构化而不要碎片化

相对于Nextjs这类的前端框架，PHP的项目普遍比较碎片化，尤其是以前的老项目。

碎片化，对于AI推理来说是一件很麻烦的事，AI很容易漏掉很多东西，所以，得到的结果往往出现各种小问题。比如零散的CSS的定义，AI在做一个页面的时候，很难全面顾及。

而结构化程度高的项目，AI在推理时，会比较集中，不会有很多零碎的东西干扰，所以，最后得到的结果，质量会比较高，且很少有问题。比如，Nextjs的CSS可以只定义一个全局的，所有的页面、组件全部依赖这个全局的样式。如果不用这种全局的样式，也碎片化的写在各个页面和组件中，也很容易出现很多细节要反复调整的情况。

2、语义化而不要随便定义

随便定义参数、文件名，很容易出现AI理解错误的情况，一旦AI理解错误，就会出现一系列的问题。还有很多人习惯用拼音定义文件名和参数名，也很容易出现这种情况。

3、目录结构要浅而不要深

目录结构越深，对AI来说，文件和目录之间的关系越复杂，处理起来也越麻烦，所以很多时候，目录深的文件往往会被忽略。

4、用AGENT.md定义规范

用AGENT.md（Claude Code中是Claude.md）定义规范，可以从很大程度上提高AI Agent的能力，更容易得到更好的结果。

比如现在的GPT5.6写SQL的时候，很喜欢用外键、CHECK语句等这些限制性的语句。而我很不喜欢把这些业务上的限制放在数据层，数据表，简单存取数据就行了，限制性的东西放在控制层。所以，我在AGENT.md中专门写了一个数据库设计的规范，这样Codex再写SQL的时候就写成了我喜欢的样子。