Drupal Core AGENTS.md Proposal Triggers Broader Debate on AI Guardrails

The issue, titled “Embrace the chaos, add a couple of AGENTS.md files to core”, was opened on 22 January 2026 by Theodore Biadala. The proposal suggested introducing machine-readable AGENTS.md files in Drupal core to provide baseline instructions for AI coding agents, covering tooling such as DDEV, Composer workflows, and conventions for patches and modern JavaScript.

The technical premise was straightforward: if contributors are already using AI tools to prepare merge requests, structured guidance could reduce noise by encoding project expectations directly in the repository. Similar approaches were cited elsewhere in the ecosystem, including Amazee.io’s Drupal AGENTS.md guide, referenced by Ronald te Brake, as well as experiments discussed in community blogs and conference sessions.

In a related reflection, J. Rockowitz described experimenting with Amazee.io’s AGENTS.md file in PHPStorm’s Junie agent. He reported that providing structured Drupal-specific context improved generated controller code, including DDEV commands, Drush usage, and SQL patterns. However, he also noted that generated code still required line-by-line review and correction. His experiments extended to pairing AGENTS.md with a README.md file aimed at guiding both AI agents and new developers.

Several contributors supported the concept in principle. Lauri Timmanee argued that structured AI guidance could function as executable documentation, benefiting both machines and human contributors. Dries Buytaert endorsed the idea of establishing a default reference environment to anchor such guidance. Christoph Breidert and Scott Falconer emphasised keeping any implementation concise and standards-focused. Supporters consistently framed AGENTS.md as guardrails rather than endorsements.

Scepticism emerged just as quickly. Nathaniel Catchpole noted that recent AI-related issues were not primarily caused by missing documentation but by contributors submitting large, poorly reviewed AI-generated merge requests. Others questioned whether formalising AGENTS.md in core would meaningfully reduce reviewer fatigue or simply legitimise practices that shift responsibility from contributor to maintainer. Similar concerns have surfaced across the wider open-source ecosystem, where maintainers have publicly described being overwhelmed by low-quality AI-generated pull requests and considering restrictions on unsolicited contributions.

Additional participants expanded the discussion beyond file formats. Kristen Pol referenced work within the Drupal AI Initiative to add AI usage disclosure to issue templates. Adam G-H described both frustration with low-signal AI contributions and practical productivity gains from careful use. The discussion reflected a spectrum: structured enablement on one side, cultural caution on the other.

Governance threads surfaced explicitly as participants linked the proposal to ongoing policy work, including the Proposed guidelines for AI contribution and the Proposal for a Drupal Code of Care. The AGENTS.md question was no longer just technical. It intersected with disclosure expectations, contributor accountability, and community health.

The debate also revealed a deeper unease about the cultural and psychological effects of AI tooling. In closing the issue on 29 January 2026, Theodore Biadala wrote that his own view had shifted during the public exploration. While initially curious about structured guidance, he expressed concern about the personal impact of AI usage and the broader consequences for community dynamics, suggesting that organisations adopting such tools should consider guardrails beyond technical documentation.

External examples were cited to illustrate possible approaches. Angie Jones’ post, “How I Taught GitHub Copilot Code Review to Think Like a Maintainer”, demonstrated how explicit instruction files can reduce review noise. Her published Copilot instruction file details confidence thresholds, skip lists, and formatting constraints. A contrasting academic model—AI Agent Guidelines—showed how institutions may deliberately restrict agent autonomy rather than expand it.

The conversation was also informed by experiments presented at community events. At NedCamp 2025, Brian Perry demonstrated how rule-based instruction files could constrain AI coding agents and improve predictability. His session, “Unlocking the Power of Agent-Driven Development with Rules,” framed markdown-based instruction files as lightweight guardrails rather than automation shortcuts, reinforcing the idea that agent behaviour can be shaped through structured context.

The issue was ultimately closed as “works as designed,” adding no AGENTS.md file to core and imposing no new policy. The discussion did not resolve whether AI tools are beneficial or harmful to Drupal. Instead, it clarified competing assumptions: whether structured files represent pragmatic guardrails, incremental normalisation, or a distraction from deeper governance and cultural questions.

The issue is closed. The governance questions it surfaced are not.