Friday, 2:00 PM. A new developer took over the project yesterday. The client reports a production bug - something’s broken with a custom queue worker. In the past, this scenario meant tracking down the previous developer who knows the code. Consultations, explaining context, wasting time. All on a Friday.
Now? The developer opens Cursor, asks AI about the queue worker, and AI responds with useful answers because it knows the project. It knows you’re using DDEV, that cache is configured a specific way, that you have custom module prefixes. How is this possible? Just one file in your project: AGENTS.md.
Problem: AI doesn’t know your project
You probably recognize this scenario: you ask AI (Cursor, Copilot, Claude) for help with Drupal and get code that… doesn’t fit.
AI doesn’t know you’re using Paragraphs. It doesn’t know your theme has a different name than it assumes. It doesn’t know your specific directory structure. It doesn’t know your coding standards.
You have to explain the context. With every conversation, from scratch. AI hallucinates because it has no source of information and doesn’t know what your project looks like.
Solution: AGENTS.md
AGENTS.md is a file in your project’s root directory that AI reads automatically at the start of each session. It contains everything AI needs to know about the project.
It includes information such as: - Drupal and PHP versions, - directory structure (web/, docroot/, or something else), - custom modules and their prefixes, - theme and its organization, - coding standards (PHPStan, PHPCS), - workflow (DDEV, Git, Composer), - content types, entities, Drupal integrations.
Sounds like a lot of work? To avoid that, we built a simple tool that generates this file automatically.
How our AGENTS.md tool works in practice
The entire process takes about 5 minutes:
- Download
AGENTS-TEMPLATE.mdfrom the repository (one curl command in README). - Copy the prompt from README into your AI tool.
- AI scans your project - checks composer.json, configuration, modules, theme.
- You get a ready-made
AGENTS.mdcustomized to your project.
You do this once and benefit from it in every AI session.
The tool works with assistants like: Cursor, Copilot, Claude Code, Codex, Aider, Gemini CLI, Roo Code, Zed, Devin - and probably others we haven’t tested yet.
Repository: github.com/droptica/drupal-agents-md
What changes after adding AGENTS.md?
I won’t claim “productivity increased by 47%” because I didn’t measure it. But here’s what I noticed on projects with AGENTS.md:
Onboarding new people is several times faster. New developers don’t have to ask “what are the conventions?”, “what’s the theme called?”, “what do you use for cache?”. AI already knows and suggests according to the project.
Debugging with context. When you report an issue, you don’t need to write an elaborate description of the architecture. AI knows you have Paragraphs, that you’re using a specific module for queues, that cache works a certain way.
Less explaining, more coding. Instead of starting every conversation with “we use DDEV, we have web/ as root, module prefixes are xyz_” - you simply write what you want to do. This enhances the development experience similar to how better tooling improves content editing workflows.
Fewer hallucinations. AI doesn’t make up things that aren’t in the project. It knows what’s installed, what entities exist, what dependencies are there – similar to how AI modules in Drupal use project context to generate content.
3 elements of AGENTS.md we’re still refining
To be clear, AGENTS.md isn’t all superlatives. There are a few things we’re still working on:
- Large projects generate large files. If you have 50 custom modules and a complex architecture, AGENTS.md can be lengthy. We’re working on having AI take only what’s needed in a given context.
- The file needs updates with major changes. You add a new module, change the structure - it’s worth regenerating the file. It’s not automatic (yet).
- It depends on your project’s organization. If your code is chaotic, AGENTS.md will document that chaos. AI will know there’s a mess, but it won’t fix the mess itself.
What does the ready-made AGENTS.md template include?
The template covers most things that matter in a Drupal project:
- Environment: DDEV, Git workflow, Composer.
- Code standards: PHPStan, PHPCS, PHPUnit, Codeception, Xdebug.
- Development: coding standards, entities, modules, forms, database.
- Modern Drupal: headless/API, SEO, multilingual.
- Frontend: themes, SCSS, JS/CSS optimization, caching.
- Operations: config management, performance and website security, troubleshooting, automated audits.
If something’s missing for your project, you can add your own sections. It’s just a regular markdown file.
AGENTS.md tool - summary
In a few minutes, you can add AGENTS.md to your Drupal project and immediately see the difference in AI suggestion accuracy.
Repository: github.com/droptica/drupal-agents-md
And if you’re looking for a Drupal agency that will handle your project development using the latest technologies, get in touch with us.
