drupal / ai_best_practices
A canonical place to put opinionated Drupal best practice guidance for AI agents
Maintainers
Requires (Dev)
This package is auto-updated.
Last update: 2026-04-18 21:19:30 UTC
README
A canonical, composer-installable package of opinionated Drupal guidance for AI coding agents and their humans.
AI agents are powerful but often get Drupal wrong — reaching for unit tests instead of functional ones, mishandling the service container, generating code that ignores Drupal's conventions. This package gives agents the context they need to generate correct Drupal code from the start, in a format that also serves as readable documentation for developers.
Scope
Universal guidance that applies across Drupal projects: core, contrib, and custom code. Not project-specific configuration.
Who is this for?
- Drupal developers using AI coding tools
- Site builders who want AI assistance grounded in Drupal conventions
- Contributors who want to add or improve guidance (see CONTRIBUTING.md)
How it works
Installing this package uses drupal-scaffold to copy context files (CLAUDE.md, AGENTS.md, GEMINI.md) to your project root. Those files point agents to skill files under vendor/drupal/ai_best_practices/skills/, which are loaded on demand.
Browse the skills/ folder to see what guidance is currently available.
Installation
From the root of an existing Drupal project (the directory that contains your composer.json):
composer config extra.drupal-scaffold.allowed-packages --json --merge '["drupal/ai_best_practices"]'
composer require --dev drupal/ai_best_practices:@dev
Agent setup
In most cases, start your agent from your Drupal project root and it will pick up the context files automatically.
Some tools need a one-line config hint — see .agents/SETUP.md for tool-specific instructions.