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 that web//vendor/
    are scaffolded by the add-on rather than meant to be edited directly.
  • A table of the custom ddev commands 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.yml runs 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.md in sync if the DDEV Contrib add-on config
    or module structure changes.

Comments

gedur created an issue. See original summary.

  • gedur committed 15afed35 on 1.0.x
    Issue #3608943: Add AGENTS.md documentation covering the DDEV Contrib...
gedur’s picture

Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.