Build with AI Agents

AI coding agents such as Claude Code, Cursor, Codex, and GitHub Copilot read your repository, edit files, and run commands until a task is done. How good their Drupal code is depends on how much of your project they can see and check. This page sets up a Drupal project so an agent writes current Drupal 11 code and proves it works.

This section covers agents that build Drupal. To build AI features into a Drupal site, such as chatbots or content generation, see the AI module.

Why Drupal works well with agents

Drupal is built on conventions an agent can follow. A block plugin lives in src/Plugin/Block/ and is declared with a #[Block] attribute. Services are declared in *.services.yml and injected through the constructor. Routes live in *.routing.yml, and configuration has a schema. When you ask an agent for a new block, a route, or a settings form, it knows where the file goes and what shape it takes.

Drupal also has strong tooling an agent can run: Drush to look inside the site, and PHP_CodeSniffer, PHPStan, and PHPUnit to check the code. An agent that uses both stops guessing and starts checking.

Add the Drupal conventions file

Agents read an instructions file from the project root at the start of every session. These docs publish one for Drupal 11: AGENTS.md. It states the patterns current Drupal requires, the commands that verify a change, and links to the pages behind each rule. Download it into your project root:

curl -o AGENTS.md https://docs.drupal.org/AGENTS.md

Then add the details only your project knows, such as the custom modules that exist and the commands your team runs. If your agent reads a different file, such as CLAUDE.md or .cursor/rules/, make that file one line that points at AGENTS.md:

See AGENTS.md in the repository root for all project conventions.

For deeper context, point the agent at llms.txt. It indexes these docs in topic sets, so an agent working on a theme loads the theming pages instead of the whole site.

Install Drupal skills

Skills are task-specific instructions an agent loads only when it needs them, so they add detail without crowding the instructions file. Install them with the skills CLI, which places them where your agent looks:

# Drupal Canvas code components (official)
npx skills add drupal-canvas/skills

# Configuration management, DDEV, testing, Views, Search API, deploy safety
npx skills add grasmash/drupal-claude-skills

The Drupal Canvas skills teach an agent to build Canvas code components. The Drupal Claude skills collection covers day-to-day site work. The community is collecting shared guidance for agents in AI Best Practices for Drupal.

When your team repeats a task, write a skill for it: a SKILL.md file with a name and description in its frontmatter, saved under .agents/skills/<name>/, or .claude/skills/<name>/ for Claude Code.

Let the agent use Drush

Drush already answers the questions an agent asks about a running site. Tell the agent to use it instead of guessing from the code:

Task	Command
Check the Drupal and PHP versions and the database	drush status
Read a configuration object	drush config:get system.site
List the fields on a bundle	drush field:info node article
Find the controller and access rules for a path	drush core:route --path=/node/1
Read recent log messages after an error	drush watchdog:show
Test a hypothesis against the bootstrapped site	drush php:eval '<code>'
Scaffold a module, plugin, or service	drush generate

drush generate matters most. Generated scaffolding follows the current patterns, so the agent fills in the logic instead of writing boilerplate from memory. The full list is in the Drush reference.

Allow the agent to run the read-only and verification commands without asking. Require approval for anything that changes content, users, or the database, such as drush sql:* and drush user:*. Run the agent against a local copy of the site with its own database, such as a DDEV project, never production.

Connect the agent to your site with MCP

The MCP Server module exposes a Drupal site to agents over the Model Context Protocol. Install it on your local site:

composer require 'drupal/mcp_server:^2.0@beta'
drush pm:enable mcp_server

Register vendor/bin/drush mcp:server <user> as a stdio server in your agent’s MCP configuration. Every tool call runs with that user’s permissions, so use a dedicated local account. The agent gets the tools you add: write your own as plugins with the #[Tool] attribute, or expose existing Tool API plugins with MCP Server Tool Bridge.

Make the agent verify its work

An agent’s code reads as correct whether or not it is. Coding standards, static analysis, and tests decide the difference, and AGENTS.md tells the agent to run them before it calls a task done:

vendor/bin/phpcs --standard=Drupal,DrupalPractice web/modules/custom
vendor/bin/phpstan analyse web/modules/custom
vendor/bin/phpunit -c web/core web/modules/custom/your_module
drush cr

PHPStan with phpstan-drupal catches invented APIs and deprecated calls. The DrupalPractice standard catches static \Drupal:: calls where dependency injection belongs. Verify agent-generated Drupal code sets up the tools and explains what each check catches.

Review what the checks miss

Passing checks prove the code is well formed and does what the test asks. They do not prove it is right for Drupal. Read every agent diff for:

• Cache metadata. A render array that varies by user or content declares its tags and contexts. See Caching.
• Access. Every access check matches who should actually be allowed. See Access.
• Entity API. Content goes through entity storage, not raw SQL. See Entities.
• Config schema. New configuration has a matching schema.
• Architecture. The feature has the right shape: a listing is a view, not a controller. See Choose your path.

When the same finding comes up twice, add a rule for it to AGENTS.md. Where AI agents get Drupal wrong lists the recurring mistakes and the check that catches each one.