Problem/Motivation
The repository had no onboarding documentation for AI coding agents (or new
contributors) explaining what the module does or how to work with its local
development environment. The project uses
ddev-drupal-contrib,
which scaffolds a full Drupal codebase around this module and provides a set
of custom ddev commands (poser, phpunit,
phpcs, phpstan, etc.), but none of this was
documented anywhere in the repo, making it harder to get productive quickly.
Proposed resolution
Added an AGENTS.md file at the project root with:
- A short overview of what the Role Audit module does (permissions
comparison and routing access comparison reports under
/admin/people/role-audit), pointing to the key files
(src/Form/,src/PermissionsComparison.php,
src/RoutingAccessComparison.php, and the
tests/src/Kernel/test suite). - An explanation that the project runs locally via
ddev-drupal-contrib, that the repo root is the module
(not a full Drupal docroot), and thatweb//vendor/
are scaffolded by the add-on rather than meant to be edited directly. - A table of the custom
ddevcommands the add-on provides
(poser,phpunit,phpcs,
phpcbf,phpstan,eslint,
stylelint,nightwatch,
symlink-project,core-version) with a one-line
purpose for each, sourced from the scripts in.ddev/commands/. - A note that
.gitlab-ci.ymlruns the same categories of
checks (coding standards, static analysis, PHPUnit) via Drupal.org's shared
GitLab CI templates.
Since Claude
Code does not read AGENTS.md automatically, a minimal
CLAUDE.md was also added containing only an
@AGENTS.md import, so Claude Code picks up the same content
without duplicating it, while other AGENTS.md-aware tools can read the file
directly.
Remaining tasks
- Keep
AGENTS.mdin sync if the DDEV Contrib add-on config
or module structure changes.
Comments
Comment #3
gedur commented