AGENTS.md 工具：人工智能如何真正加速 Drupal 工作

周五下午 2 点，一名新开发人员昨天刚接手项目，客户就报告了一个生产漏洞，自定义队列工作器出了问题。以往遇到这种情况，就得找到了解代码的前开发人员，进行咨询、解释背景，很浪费时间，而且这一切还发生在周五。

现在呢？开发人员打开 Cursor，向人工智能询问关于队列工作器的问题，人工智能能给出有用的答案，因为它了解这个项目。它知道你在用 DDEV，知道缓存是如何配置的，也知道你有自定义模块前缀。这是怎么做到的呢？只需要你项目中的一个文件：AGENTS.md。

一、问题：人工智能不了解你的项目

你可能对这种情况很熟悉：你向人工智能（Cursor、Copilot、Claude）寻求 Drupal 开发方面的帮助，得到的代码却不适用。

人工智能不知道你在使用段落模块（Paragraphs），不知道你的主题名称与它假设的不同，不知道你特定的目录结构，也不知道你的编码标准。

你每次对话都得从头开始解释背景。人工智能会产生幻觉，因为它没有信息来源，也不了解你的项目情况。

二、解决方案：AGENTS.md

AGENTS.md 是你项目根目录中的一个文件，人工智能在每次会话开始时会自动读取它。它包含了人工智能了解项目所需的一切信息。

它包括以下信息： - Drupal 和 PHP 版本； - 目录结构（web/、docroot/ 或其他）； - 自定义模块及其前缀； - 主题及其组织方式； - 编码标准（PHPStan、PHPCS）； - 工作流程（DDEV、Git、Composer）； - 内容类型、实体、Drupal 集成。

听起来工作量很大？为了避免这种情况，成都长风云Drupal开发团队开发了一个简单的工具，可以自动生成这个文件。

三、我们的 AGENTS.md 工具在实际中是如何工作的

整个过程大约需要 5 分钟：

1. 从仓库中下载 AGENTS-TEMPLATE.md（README 中有一个 curl 命令）。
2. 将 README 中的提示复制到你的人工智能工具中。
3. 人工智能扫描你的项目——检查 composer.json、配置、模块、主题。
4. 你会得到一个针对你项目定制的现成的 AGENTS.md。

你只需做一次，就能在每次人工智能会话中受益。

该工具适用于以下助手：Cursor、Copilot、Claude Code、Codex、Aider、Gemini CLI、Roo Code、Zed、Devin——可能还有其他我们尚未测试的工具。

四、添加 AGENTS.md 后会有什么变化？

我不会声称“生产力提高了 47%”，因为我没有进行测量。但在使用 AGENTS.md 的项目中，我注意到了以下情况：

新员工入职速度提高了好几倍。新开发人员不必再问“有哪些约定？”“主题叫什么？”“你们用什么来做缓存？”人工智能已经了解这些信息，并会根据项目情况提供建议。

有上下文的调试。当你报告问题时，你不需要详细描述架构。人工智能知道你在使用段落模块，知道你使用特定的模块来处理队列，知道缓存的工作方式。

少解释，多编码。你不必每次对话都以“我们使用 DDEV，根目录是 web/，模块前缀是 xyz_”开头，只需说明你想做什么。这提升了 Drupal开发体验，就像更好的工具可以改善内容编辑工作流程一样。

减少幻觉。人工智能不会编造项目中不存在的内容。它知道安装了什么、存在哪些实体、有哪些依赖关系，就像 Drupal 中的人工智能模块利用项目上下文来生成内容一样。

五、我们仍在完善的 AGENTS.md 的三个要素

需要说明的是，AGENTS.md 并非十全十美。成都长风云Drupal开发团队仍在努力解决以下几个问题：

1. 大型项目会生成大文件。如果你有 50 个自定义模块和复杂的架构，AGENTS.md 可能会很长。我们正在努力让人工智能只提取特定上下文中所需的信息。
2. 文件需要随着重大更改进行更新。如果你添加了新模块、更改了结构，最好重新生成文件。（目前）这还不是自动完成的。
3. 它取决于你项目的组织方式。如果你的代码混乱，AGENTS.md 会记录这种混乱。人工智能会知道存在混乱，但它本身不会解决这个问题。

六、现成的 AGENTS.md 模板包含哪些内容？

该模板涵盖了 Drupal 项目中大多数重要的方面：

• 环境： DDEV、Git 工作流程、Composer。
• 代码标准： PHPStan、PHPCS、PHPUnit、Codeception、Xdebug。
• 开发： 编码标准、实体、模块、表单、数据库。
• 现代 Drupal： 无头/API、SEO、多语言。
• 前端： 主题、SCSS、JS/CSS 优化、缓存。
• 运维： 配置管理、性能和网站安全、故障排除、自动化审计。

如果你的项目有缺失的内容，你可以添加自己的部分。它只是一个普通的 Markdown 文件。

七、AGENTS.md 工具总结

你可以在几分钟内将 AGENTS.md 添加到你的 Drupal 项目中，并立即看到人工智能建议准确性的变化。

如果你正在寻找一家使用最新技术处理 Drupal开发项目的机构，欢迎与成都长风云Drupal开发团队联系。