Is It Time to Add AGENTS.md to Drupal Core?

Rockowitz situates his exploration within the broader community discussion on Drupal.org, specifically the issue titled “Embrace the chaos, add a couple of AGENTS.md files to core.”. That thread debates whether Drupal should formally adopt a machine-readable guidance file that describes conventions, workflows, and architectural expectations. Rather than focusing on policy outcomes, Rockowitz concentrates on practical experimentation.

His experiments draw on a Drupal-focused AGENTS.md example from Amazee.io’s Drupal AI Agent Development Guides and the emerging cross-tool standard documented at agents.md. By pointing AI assistants to a structured AGENTS.md file, he reports improved results when generating Drupal-specific code, including controllers, DDEV configuration steps, and SQL queries aligned with Drupal conventions.

Rockowitz extends the experiment by pairing AGENTS.md with a human-facing README.md. Using AI prompts informed by the AGENTS.md file, he generated installation guidance for a new Drupal environment built with DDEV. He then iteratively refined both files, treating AGENTS.md as a persistent instruction layer for machines and README.md as onboarding material for developers.

A key refinement involved explicitly referencing Drupal’s Examples for Developers module as a development dependency. By directing AI tools to consult working implementations of hooks, plugins, render arrays, entities, and other APIs located in web/modules/contrib/examples/, he aimed to anchor AI output in real, production-grade patterns rather than abstract guesses.

The post does not provide benchmarks or quantitative evaluation. Instead, it presents AGENTS.md as an evolving documentation layer: lightweight, version-controlled, and adaptable. Rockowitz suggests that even an imperfect initial file in core could grow alongside the codebase, potentially lowering barriers for AI-assisted development while keeping humans “in the loop.”