{"slug": "a-claude-md-for-drupal-11-projects-that-actually-matches-your-repo", "title": "A CLAUDE.md for Drupal 11 projects that actually matches your repo", "summary": "A developer published a guide for writing CLAUDE.md and AGENTS.md instruction files for Drupal 11 projects that are derived from the actual repository rather than copied from templates. The approach inspects composer.json type, .ddev presence, and drush availability to determine whether a repo is a full site, a contrib module, or a distribution, then writes only commands that exist in that context. The guide also recommends a short list of paths agents must not touch, such as vendor/, settings.local.php, and .env.", "body_md": "Most project instructions for coding agents are copied from a template. The commands in them often don't exist in your repo, so the agent runs them, fails, and guesses. For Drupal this is worse than usual, because \"a Drupal project\" can mean three very different things: a full site, a single contrib module, or a distribution. This post shows how to write a `CLAUDE.md` (or `AGENTS.md`) by reading the repository first, using two real public repos:\n\n`2.2.x`)\n\n```\ngrep -n '\"type\"' composer.json\nls -a | head -40\n```\n\nIn `localgov_directories`, `composer.json` says `\"type\": \"drupal-module\"` and the root holds `localgov_directories.info.yml`. There is no `web/` directory, no `vendor/`, no Drush. In `drupal/cms` there is a `.ddev/` directory, a `web` docroot setting in `.ddev/config.yaml`, and `drush/drush` in `composer.json`.\n\nThat one check changes every command you write. A module repo cannot run its own tests: they need a full Drupal codebase around the module. If your instructions say `vendor/bin/phpunit -c web/core ...` for a module repo, the agent will fail on the first try.\n\nDon't assume DDEV. The `drupal/cms` `AGENTS.md` makes this explicit: check for a `.ddev/` directory *and* `ddev` on the `PATH`; otherwise fall back to local Composer, and use `vendor/bin/drush` only if it exists. Steal that idea:\n\n```\nls -d .ddev 2>/dev/null\ncommand -v ddev\ntest -x vendor/bin/drush && echo \"project drush\"\n```\n\nThen write the commands with the right prefix once, instead of leaving the agent to decide each time.\n\nEvery command in the file should come from somewhere you can name: a `composer.json` script, the DDEV config, the CI workflow, or the official docs. For Drupal the commands that matter are small in number:\n\n`drush cache:rebuild` (`drush updatedb`\n`drush config:status` (`drush config:import --diff` (`vendor/bin/phpunit -c web/core path/to/Test.php` (\nNotice what is *not* on the list: `drush config:import --yes`. The `drupal/cms` agent file lists it as a normal workflow, which is reasonable for a fresh local site. On a site with real active config, the `--yes` flag applies the import without asking, so in your own file you may want \"show the diff first\" instead.\n\nIn the module repo, CI runs the tests through a shared workflow that installs the module at `web/modules/contrib/localgov_directories` inside a full site. So the honest instruction there is one sentence: \"tests run inside a full Drupal site; the module path is `web/modules/contrib/localgov_directories`\", not a made-up local command.\n\nThe part agents most need is what *not* to touch. A short list works better than a long one:\n\n`web/modules/custom` and `web/themes/custom`.` vendor/`, `settings.local.php`, `.env`, or uploaded files under `web/sites/*/files`.\nThe `drupal/cms` file has this section too, and it is the most reusable part of it.\n\nIf a `CLAUDE.md` or `AGENTS.md` exists, add a clearly marked section instead of rewriting it. Other people (and other tools) rely on the original lines.\n\nAsk three questions of every line: where does this command come from, does it work from this directory, and what happens if it is wrong? If you can't answer the first, delete the line. A shorter file made of true statements beats a long one the agent has to second-guess.\n\n*Written with AI assistance. Every command and example here was run against the public repositories named above.*", "url": "https://wpnews.pro/news/a-claude-md-for-drupal-11-projects-that-actually-matches-your-repo", "canonical_source": "https://dev.to/beingrealfrank/a-claudemd-for-drupal-11-projects-that-actually-matches-your-repo-139j", "published_at": "2026-11-14 02:16:07+00:00", "updated_at": "2026-11-14 02:21:11.667770+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Drupal", "Claude", "localgov_directories", "drupal/cms", "DDEV", "Drush"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/a-claude-md-for-drupal-11-projects-that-actually-matches-your-repo", "markdown": "https://wpnews.pro/news/a-claude-md-for-drupal-11-projects-that-actually-matches-your-repo.md", "text": "https://wpnews.pro/news/a-claude-md-for-drupal-11-projects-that-actually-matches-your-repo.txt", "jsonld": "https://wpnews.pro/news/a-claude-md-for-drupal-11-projects-that-actually-matches-your-repo.jsonld"}}