Unlocking AI agent-driven development
Last fall at NedCamp, Brian Perry shared his experience as a front-end developer, unlocking the power of agent-driven development with rules. In short, he walked through how he used rules and guidelines to get Cursor's coding agent to generate high-quality front-end components. Everything he showed made sense, but it was a little complicated to determine which guidelines to define and how to leverage them, because at that time, there were many standards across different platforms and coding agents. He wished that the newly created non-proprietary standard for coding agent guidelines, called AGENTS.md, would become the de facto solution. I walked out of his session feeling that one of the key things for coding Drupal with AI to succeed is that we must give them enough guidance to understand the broader context of the Drupal application being built, not just a few initial prompts with some web crawling.
Embracing AGENTS.md
Like many developers, I've used AI code completion and chat daily. Still, I felt I was falling behind the AI tidal wave. I could not wrap my head around the concept of vibe coding until I learned that Drupal-specific AGENTS.md files were being shared within the Drupal community.
Things are moving very fast, and in the last few months, Brian's hope that AGENTS.md files would become the de facto standard has been realized. My search for Drupal + AGENTS.md led me to the Embrace the chaos, add a couple of AGENTS.md files to core issue on Drupal.org. The discussion on that issue was the beginning of a debate on whether, how, and why to add an AGENTS.md file to Drupal core. From that issue, I discovered Amazee.io's Drupal AI Agent Development Guides.
Experimenting with a Drupal-specific AGENTS.md file
I am a passionate PHPStorm IDE user who pays for its AI coding agent, called Junie. I pointed Junie to Amazee.io's AGENTS.md file for context. My head exploded from the comprehensiveness of the response to my Drupal-specific prompts for creating a custom report. Junie knew how to run DDEV, use Drush, create a controller, and write advanced Drupal-specific SQL queries. Without question, I had to give the code generated by Junie a thorough, clear, and concise review, including bullet-pointed changes, renames, reorders, and refactors. Junie immediately applied my suggested changes. The final controller met my standards and was completed in a quarter of the time it would have taken me to build it manually. This experience made me wonder what tasks I typically struggle with that an AI could help manage, and of course, README.md documentation came to mind.
Creating a README.md that is a companion to AGENTS.md
Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.
As a second experiment, I wanted to see whether using Amazee.io's AGENTS.md file, attached to a simple Claude chat, could help me get started building a new Drupal environment to experiment with AI-driven development and Drupal's AI capabilities. If an AGENTS.md file is for machines to understand Drupal, could I use it to create a README.md for new Drupal developers? My theory is that AGENTS.md and README.md files could be companions that evolve over the life of a software project.
Below is the first prompt that I gave Claude.
I am building a new Drupal setup using DDEV. Use the attached AGENTS.md file for context and guidance. Please generate a README.md that provides step-by-step instructions for installing DDEV and Drupal. Keep the instructions simple and reference other resources.
The README.md file generated by Claude from AGENTS.md is a decent starting point. Of course, there is some minor feedback and best practices I would recommend, including avoiding aliases for Drush commands to ensure new Drupal developers know which command they are executing. I might even take things a step further and have Claude generate a DRUSH.md cheatsheet for common commands, including examples and aliases. For now, I want to improve the README.md by encouraging new Drupal developers to explore the Examples for Developers module and tell AGENTS.md to also look at the code examples located at /web/modules/contrib/examples/modules.
So here is my second prompt that I gave Claude.
Please add instructions to README.md for downloading the https://www.drupal.org/project/examples as a dev dependency to composer.json. Also, update the directions in the previous AGENTS.md to refer to the examples in /web/modules/contrib/examples for guidance on implementing various Drupal features and APIs, including hooks, plugins, and render arrays.
Here are the README.md and AGENT.md file updated to include the Examples for Developers module by Claude. Claude, add the following directive to AGENTS.md; it should improve code quality for most coding agents.
Reference Code: The Examples for Developers module is installed as a dev dependency. Browse web/modules/contrib/examples/ for working implementations of Drupal's core APIs including hooks, plugins, forms, render arrays, entities, caching, and more. Always consult relevant example modules before implementing a new pattern.
The README.md and AGENTS.md files are moving in the right direction. Still, the next step might be having an AI agent crawl /web/modules/contrib/examples/modules for *.info.yml files and create a single section called "Drupal Code Examples" in AGENTS.md that acts as a TOC for all the examples, which might be easier for machines and humans to understand and maintain.
Including AGENTS.md in Drupal core and contrib modules.
As a senior developer, I am inspired by the results and see an opportunity to mentor new developers who are learning to code in Drupal using AI. I am getting started with coding Drupal using AI, and that will likely be the topic of my next blog post.
For now, I am in favor of the community collaboratively and thoughtfully exploring adding AGENTS.md to core and contributed modules, with the goal that these files evolve with our code and community.
Final takeaways
Adding an AGENTS.md file is the first step toward introducing and integrating other open standards, such as MCP, into Drupal's development community.
Core's AGENTS.md file does not have to be perfect, and developers should be encouraged to take ownership of these directives and adapt them to meet their specific needs and use cases.
Our biggest challenge might not be integrating AI into our process, but inviting the next generation of junior Drupal developers to use AI effectively to join our community while building high-quality collaborative code.
AI is a tidal wave, and we need to figure out how to surf it.
Feel free to post comments here or join the large discussion happening on Drupal.org.
References
About AGENTS.md
Drupal-specific AGENTS.md examples
- Drupal AI Agent Development Guides
- Drupal-specific AGENTS.md examples on GitHub
Discussions
- Embrace the chaos, add a couple of AGENTS.md files to core [#3568936] | Drupal.org
- Add an AGENTS.md file [#3569529] | Drupal.org
- AI tools for contributors and maintainers [#3570498] | Drupal.org
Presentations
Blog posts