Problem/Motivation

LLM use in Drupal is not slowing down, it's picking up in Drupal core too. Drupal.org requires disclosure of LLM use when contributing. They can't do that if they're afraid of the response from the community. It means more "hidden" use of LLM, more time wondering if a contribution is LLM generated or not. Shaming people into changing their behavior doesn't work, what it does is make people hide their use, leave, or lash out, none of which is helpful.

To keep things manageable I think having an AI policy turned towards harm reduction would be a good thing. In some cases harm reduction methods can be counter productive, it's up to us to monitor the effects and adjust accordingly. LLMs are not going to solve the issues they cause, but we can make the problem less bad to deal with. Critically other humans should not be cleaning up unreviewed LLM output, as Dries puts it, never submit code you don't understand and I would add, never submit text you didn't review.

I've written a bit more details in a blog post with links to references and discussions about some of the problems raised in the previous AGENTS.md issue.

Examples

What would it change? From the recent post https://www.hojtsy.hu/blog/2026-apr-10/solving-small-drupal-issue-plenty... we have a sample of LLM generated comment on a real issue. This is not a core issue, but it's a good example of what the guidelines would change #3570518-8: Core language list parsing is not Drupal 11 compatible anymore.

Original Rewritten with new guidelines
I have a local setup of potx and I asked Claude this for demo purposes:

why would _potx_find_language_names not be able to parse LanguageManager.php in Drupal 11?

Answer from Claude is spot on:

The _potx_find_language_names() function fails to parse LanguageManager.php in Drupal 11 due to a PHP syntax change.

The Problem

Drupal 11's LanguageManager.php uses modern short array syntax:

public static function getStandardLanguageList() {
    return [
      'af' => ['Afrikaans', 'Afrikaans'],
      // ...
    ];
  }

But potx's parsing logic expects old array syntax:

public static function getStandardLanguageList() {
    return array(
      'af' => array('Afrikaans', 'Afrikaans'),
      // ...
    );
  }

Technical Issue

In _potx_find_language_names() at line 1662:

while ($_potx_tokens[$ti][0] != T_ARRAY) {

The function looks for T_ARRAY tokens, which are only generated by the old array() syntax. The modern short array syntax [] uses different tokens ([ and ] characters), so the parser never finds what it's looking for and can't extract the language names.

The Fix

The function needs to be updated to handle both syntaxes:

Old syntax: Look for T_ARRAY tokens
New syntax: Look for [ bracket characters

The parsing logic would need to:

Detect which array syntax is being used
Handle the different token sequences appropriately
Extract language names from both array(...) and[...] structures

This explains why potx works fine with older Drupal versions but fails with Drupal 11's modernized syntax in the core LanguageManager.php file.

_potx_find_language_names() at line 1662 loops until it finds a T_ARRAY token. T_ARRAY is only emitted for the array() call syntax. Drupal 11's LanguageManager.php uses the short [] syntax instead, which emits bracket tokens. The loop never finds T_ARRAY, so language names are not extracted.

The fix needs to handle both token sequences: T_ARRAY followed by ( for the long syntax, and [ for the short syntax.

Generated with the help of an LLM.

I think it's better. A nice side effect is that shorter means cheaper, it's less tokens to generate overall.

Proposed resolution

For a 3 months trial period: Add an AGENTS.md file enforcing a few necessary rules, that are aimed at reducing the negative impact of LLM use on human contributors.

This prompt has been tested with the following models to make sure they would apply the guidelines. Some are better than others obviously.

Sonnet
Qwen3 8B
Qwen3.6 35B-a3b
Granite 4 h-small
Mistral Nemo 12B
GPT-OSS 20B
Gemma 4 31B

Remaining tasks

Agree/Commit.

CommentFileSizeAuthor
#43 AGENTS.md3.55 KBwebchick
#16 do-3585894-attachment-tiered-context-convention.md1.57 KBalex ua

Issue fork drupal-3585894

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

nod_ created an issue. See original summary.

nod_ opened merge request !15508

nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes
Status: Active » Needs review
nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes
smustgrave’s picture

smustgrave commented

Any cross points needed from #3574093: Ban slop issue summaries and comments ?

nod_’s picture

nod_
Primary language French
Location Lille
commented

Looks like it'll complement it, in the other issue there is "If a more specific `AGENTS.md` exists in a subdirectory you are working in, its guidance supplements these instructions." And here the agent file is scoped to core/

smustgrave’s picture

smustgrave commented

As someone who deals with users using AI almost daily at this point +1 to making the problem less. If this is the path forward for it I'm for it as I don't have any other solutions. Has almost become a game of whack a mole.

I have had the scenario where a user responded to every comment with AI, every feedback with AI, but I know they didn't know what the code was doing. I think this would of helped maybe?

Another scenario that I've hit that may not have been caught is that a user used AI to scan Drupal issue queue and start to mass post MRs.

All this to say yes to helping alleviate the pain as it does become demoralizing.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

LLM use in Drupal is not slowing down, it's picking up in Drupal core too. Drupal.org requires disclosure of LLM use when contributing. They can't do that if they're afraid of the response from the community. It means more "hidden" use of LLM, more time wondering if a contribution is LLM generated or not. Shaming people into changing their behavior doesn't work, what it does is make people hide their use, leave, or lash out, none of which is helpful.

10,000% true. Thank you for saying it. 🙏

Post-DrupalCon, several of us have been working on a project called Drupal AI Best Practices which is attempting to attack this from a “filter on output” POV: meaning, help the coding agents write far less stupid Drupal code (or, more accurately, train them on all of our peculiar Drupalisms that go against the other millions of PHP + software projects they’ve been trained on ;)).

That project is still VERY early days, but the “proof of concept” is there:

1) Drupal best practice advice is covered in “skills” (example), which are Markdown files that can be consumed by either humans or robots.

2) To tell if adjustments to skills are making things better or worse, we also have an “evals” framework (example), analogous to automated tests for Drupal. Now when LLMs make *new* bone-headed mistakes writing Drupal code, we can capture those as evals and make sure we don’t regress even as guidance in markdown evolves over time.

3) Now that the basic skeleton is there, what we are hoping to do is take the comparative analysis we did (or, rather, 3 different AI models did :)) in #3585379: Perform analysis on similar repos looking deep into a litany of existing projects that have gone their own way, and pull in the “best of the best” of these in a DrupalCMS-like starter kit for developers (and hopefully eventually site builders) to give them a strong foundation of basics.

Here’s our path to MVP release: #3585542: [meta] Roadmap to MVP Release

None of this is arguing against the introduction of AGENTS.md in core, just pointing out that this effort exists in case it makes sense to borrow from one another.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

Out of curiosity… Why:

“Do not add a model name, vendor, or tool name.”

I would think this would be desired, in the interest of transparency, and so that we could see community adoption trends over time.

See Linux’s guidelines as an example: https://github.com/torvalds/linux/blob/master/Documentation/process/codi...

bramdriesen’s picture

bramdriesen
he/him
Primary language Dutch
Location Belgium 🇧🇪🇪🇺
commented

I also would not mind seeing the model/tool name used. It can be a great insight into quality of the answers generated as well.

nod_’s picture

nod_
Primary language French
Location Lille
commented

In my tests smaller local models just hallucinate their model name. This is intended to be automated, it's the minimum acceptable so vague is better than straight up wrong. I'm all for more precision but that's not where we are now with local models yet.

We should make sure local LLM options are not excluded. Not everyone can pay for so called frontier models

nod_’s picture

nod_
Primary language French
Location Lille
commented

I also would not mind seeing the model/tool name used. It can be a great insight into quality of the answers generated as well.

How would that be relevant? people should make sure the code and content they send is of adequate quality. We're not going to externalize quality check of LLM output to other people. The Agent.md file is for limiting harm, not make a case for more LLM.

If you want to benchmark how well a model does, the core queue is not the place to do that kind of experiments. This issue is about harm reduction, benchmarking models in the core queue is pretty much harm maximalization and possibly against the Policy on the use of AI when contributing to Drupal as an example of what does not meet the standard is: "Posting issue comments, MR descriptions, or forum posts that are unreviewed AI output, not your own words." and that exactly what would be useful to do to actually evaluate model output.

gábor hojtsy’s picture

gábor hojtsy
he/him
Primary language Hungarian
Location Hungary
commented

I think the LLM instructions included make sense. We should aim to reduce harm done by LLMs absolutely.

I don't have a strong opinion on whether to disclose LLM models, I can see the use for it, but if this improvement is held up with that I don't think its worth holding it up.

I like the example nod gave in the issue summary based on my post :)

The main thing I don't understand is to primarily suggest to rewrite LLM prose. That sounds like could be for the sake of rewriting. I can easily see that those that are extensively exposed to LLM output, conversing in their dayjobs with LLMs heavily will not necessarily improve the quality or clarity by rewriting the text?

The current d.o rules are very vague on this BTW they both say you should rewrite the text and also that validating the text is enough: https://www.drupal.org/docs/develop/issues/issue-procedures-and-etiquett...

Posting issue comments, MR descriptions, or forum posts that are unreviewed AI output, not your own words.

Unreviewed AI output vs your own words are two ends of a spectrum, reviewed AI output satisfies the first part of the sentence but not the second part.

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented

Thanks for taking the time to create this issue and the research/post that went with it

The proposed text looks good to me - this should be a living document - we should get it in and evolve from there

nod_’s picture

nod_
Primary language French
Location Lille
commented

The main thing I don't understand is to primarily suggest to rewrite LLM prose. That sounds like could be for the sake of rewriting. I can easily see that those that are extensively exposed to LLM output, conversing in their dayjobs with LLMs heavily will not necessarily improve the quality or clarity by rewriting the text?

If I spend time working on an issue and someone post a LLM response, more often that not I feel it's disrespectful.

If you check the text the primary suggestion is to not use LLM for prose. The "rewrite in your own word" is a reminder in case the first suggestion is ignored (that might also trigger a specific user skill if they trained the LLM on their writing style). Same for the writing rules, it's a security if the person ignores the second suggestion. The writing rules are not best practice on using LLM to communicate, they're the equivalent of a grayscale filter on a smartphone. We don't know people circumstances so we try to account for various level of LLM use while keeping the impact on others contained at the very least.

alex ua’s picture

alex ua commented
StatusFileSize
new do-3585894-attachment-tiered-context-convention.md1.57 KB

Shorter issue descriptions are a win for every reviewer type. Human skimmers read less. Human deep reviewers find detail faster. LLMs with small context windows waste less capacity. LLMs with large context windows spend tokens on signal instead of noise.

The layered design in this proposal works well. Discourage first, constrain second, filter third. A natural extension: keep issue bodies short per these rules, put code-level detail in the MR description, and attach deeper technical context as a file when needed. Attachment contents do not appear in the email body. The reviewer knows more context exists but is not asked to read it until they decide it is necessary. The ai_best_practices project #3585542: [meta] Roadmap to MVP Release seems like the right place to develop a convention for structuring issue context.

I attached a short outline of that idea as a starting point.

Generated with the help of an LLM.

nod_’s picture

nod_
Primary language French
Location Lille
commented
Title: LLM use in Drupal core contribution, AGENTS.md guidelines » LLM harm reduction in Drupal core contribution, AGENTS.md guidelines

Not judging people for their LLM use is a prerequisite to apply the harm reduction framework, that doesn't mean we can't say anything about the outputs.

@alex ui: I don't understand what you tried to convey and how it relates to this issue of LLM harm reduction in the core issue queue. I'm not quite sure you reviewed the comment you posted, we do not use emails to communicate in the issue queue for example and spending 1.5 paragraphs restating the point and try to summarize the issue is not helpful unless the issue summary is updated if it wasn't clear enough.

To be honest I didn't expect this issue itself to be a test ground for the Agents.md file, but here we are. Refining the AGENTS.md file.

Feel free to propose this to the ai best practice initiative, the core queue is not the right place for it.

nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes

Made the file shorter. Used the existing AI posts in the core queue to find new rules to stop, hence the expanded "writing" section.
Updated IS example with new rules.

Confirmed that the shorter text is as good as the previous one across all the models tested initially.

alex ua’s picture

alex ua commented

My point connects directly to your proposal: the optimization you're recommending seems great, but it raises the question of where other information that doesn't fit within the shorter comments/descriptions goes.

I'm also saying that there are three types of reviewers that this should be aimed at:

  1. Those not using any system: more information is available but not pushed at the reviewer. Scan and ignore if you want.
  2. Those using local LLMs who have a smaller context window (I've started working with Qwen and Gemma personally): progressive disclosure allows them to only load what fits.
  3. Those using frontier models: the savings on a progressive disclosure system are dramatic. ~240-token vs a ~2,000-token description is a huge difference that grows with every turn.

I don't know how many core reviewers will use a frontier model (seems like very few right now), but I'm suggesting that you structure this to at least allow for that possibility. I'm pointing to a risk: that if you shorten the comments too much, and there's no convention for where the additional context goes, you might remove too much signal. A convention for where the deeper context lives keeps the top layer succinct without info loss. That seems relevant to harm reduction.

This was mostly written by me, though an LLM helped with the token math, spelling, and grammar checks.

alex ua’s picture

alex ua commented

...also, regarding the "email" comment, that was really just a me using own oddball method I useto make sure I keep up with issues (I have a label in my email applied to d.o. issues and I scan for replies). That oddity aside, I think it still stands when you are scanning the issue pages. The question is: in a scenario where you aren't adding an MR, then where should additional context could go? It seems like an attachment is the natural spot

nod_’s picture

nod_
Primary language French
Location Lille
commented

@alex ua: please open a follow-up in the ai best practice queue. The goal here is to make LLM use less negatively impactful to other contributors in the queue. Spending time talking about how to optimize LLM use is pretty much against the spirit of this issue. You're absolutely free to try and optimize things, don't make other contributors in this queue part of it. Work it out outside core where people are willing to spend time and help you with it. We want to reduce the time taken by LLM discussions in the core queue, not have more of it.

alex ua’s picture

alex ua commented

@_nod: sure, I will do that. I am hearing that you don't want to hear from the LLM users in figuring out how to deal with LLM users, and I'll not make the obvious mistake of engaging in the conversation again.

Thanks for all you do.

Edit: the issue is now at #3587092: Skill: progressive context convention for issue descriptions and reviews.

nod_’s picture

nod_
Primary language French
Location Lille
commented

I'm open to discussion, this is simply not the right place as I said back in #17. Scope creep is still something that needs to be managed.

penyaskito’s picture

penyaskito
he/him
Primary language Spanish
Location 🧑🏽‍🌾 Seville 💃 Andalusia, UTC+2 🇪🇺
commented

A nit about headers in html.

I have opinions on disclosing tools + models too, and even using Assisted-by. But I'm +1 to merging as is as plumber's tape, and moving forward in follow-ups if needed.
alex ua’s picture

alex ua commented

@_nod- understood and totally understandable. I can't blame the LLM for my own challenges with both attention and hyperactivity, and I'll try to do better to avoid the scope creep. Again, thanks for all you do!

nod_’s picture

nod_
Primary language French
Location Lille
commented
Issue summary: View changes
Related issues: +#3587092: Skill: progressive context convention for issue descriptions and reviews

Going for a trial period with metrics monitoring to implement: "In some cases harm reduction methods can be counter productive, it's up to us to monitor the effects and adjust accordingly."

Proposing we go with a 3 months experiment. We add the file to core, and see what happens. if it's better, great. if it's not we analyse what happened, and discuss how to move forward.

I have a whole data pipeline setup to monitor the core queue, I'll make a public dashboard that tracks (in aggregate, never individual users/comments) some metrics. I'll propose some metrics to look at.

smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

From dealing with users who push AI solutions and worst AI summaries it would be good to finally get something in place so marking this

xjm’s picture

xjm
she/her
Primary language English
commented
Issue tags: +Needs release manager review, +Needs framework manager review, +Needs product manager review

I think this probably needs all the signoffs since it's as much governance as technology.

xjm’s picture

xjm
she/her
Primary language English
commented
Issue tags: +DrupalSouth 2026

With regard to disclosing the tool used or not. I would love to have that information as human-written steps to reproduce, so that others can try to replicate the results.

If the LLMs themselves are hallucinating false information in response to "what and how this was made", I agree that's worse than nothing.

Is there maybe a way we can encourage people to document human STR for what they've done?

catch’s picture

catch
he/him
Primary language English
commented
Status: Reviewed & tested by the community » Needs review
alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
commented

@nod_ doesn't Claude ignore agents.md - I'm seeing stuff like https://github.com/woocommerce/woocommerce-gateway-stripe/blob/develop/C... in other projects.

nod_’s picture

nod_
Primary language French
Location Lille
commented

It doesn't read it automatically, I wondered if we should add it or not, still on the fence no strong feelings either way.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
commented

If we want this to be read the LLMs that people are using then I think we should add a CLAUDE.md pointing to AGENTS.md. Afaik this is the LLM that quite a few developers are using; I include myself in that list. And also there's https://dalia-drupal.com/ which is built on top of Claude.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

Many developers right now are switching back and forth between Claude and Codex as one exceeds the other in capabilities or pricing.

You could add a CLAUDE.md file with one line that's just:

@AGENTS.md

That will do the trick. (reference)

nod_’s picture

nod_
Primary language French
Location Lille
commented

Added the claude.md file, addressed the rest of the comments.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

There are more of these “special snowflake” LLMs that use their own variation of AGENTS.md but I think we can handle the remainder in AI Best Practices. Linking related issue.

It makes sense for Drupal core to only support tools with “critical mass” behind them, particularly within the Drupal community, which would make CLAUDE.md a no-brainer but GEMINI.md more of a squint.

poker10’s picture

poker10 commented

Even though Claude is currently one of the most widely used tools, I am not sure if it is a good idea to add MD files specific to a particular tool, especially when looking ahead to the future. What if other tools emerge in the coming months or years and users switch from Claude to something else (and it will not support agents.md)? Will we add another 2, 3, or 5 MD files for these new tools? That does not seem right to me (especially considering that these tool-specific files are not any industry standards, only the own custom designs by these companies). Do we need this to work out of the box?It seems like that a simple symlink is enough, so it can be easily set-up if needed.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

There’s a bit of detail in https://github.com/anthropics/claude-code/issues/6235 but basically, if you symlink you can’t then _also_ put Claude-specific guidance in there. Then again neither can you here without “hacking core.”

The approach AI Best Practices uses is based on Surge https://www.drupal.org/project/surge and it assembles the default AGENTS.md and then also accounts for project-specific guidance. It’s a whole ball of wax, so it’s reasonable to punt how to deal with CLAUDE.md et al to a follow-up issue.

However, given the goals of this issue are to “minimize harm” and given the prevalence of Claude as a tool, I’d recommend committing the CLAUDE.md file as-is and then talk about a better / less vendor-prone approach separately. Otherwise this MR as-is won’t really do anything to stop the worst of the problems.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Issue tags: +#AX (Agent Experience)
smustgrave’s picture

smustgrave commented

Is this something we could maybe merge and continue to fine tune after? Think getting something would be helpful.

quietone’s picture

quietone commented
Issue tags: -Needs release manager review

The rm's discussed this, except xjm but she has been helping on the wording here, so, for now, I am assuming she agrees. Concerns included

  1. That simply having an AGENTS.md file implies that core encourages the use of AI.
  2. That LLM output will be harder to detect and will still be undisclosed.
  3. That issues would be opened in the core queue to develop agent 'skills'.

For 3) any issues about 'skills' and similar can be moved to AI Best Practices for Drupal. That is the project for providing "a CANONICAL place to put opinionated Drupal best practice guidance for AI agents (and their humans!)". So, those wanting to improve the AI experience can work over there and keep the core queue about core itself.

The first two are more difficult to know what to do about. And, it we agreed that the best thing to do is to commit this for a trial period. Of the two the first one is a point that catch has brought up in each of the previous issues that got us to this point. The MR tries to discourage AI use for prose but really, who knows what will happen.

So, in the end we agree to this for a trial period only. A period of three months was suggested but we did not formally agree to that.

znerol’s picture

znerol commented

I think my mental model for AGENTS.md is somewhat the same as for robots.txt. It contains instructions for machines (at least those which are designed to be compliant). From that point of view, having an AGENTS.md file in the source tree doesn't mean that LLMs are endorsed by the project, in the same way that having a robots.txt file doesn't mean that a website endorses big tech search engines.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
StatusFileSize
new AGENTS.md3.55 KB

Heads up: This is an issue comment that could've been a blog post. 😅

Concerns included:

  1. That simply having an AGENTS.md file implies that core encourages the use of AI.
  2. That LLM output will be harder to detect and will still be undisclosed.
  3. That issues would be opened in the core queue to develop agent 'skills'.

There are multiple things wrapped up in these concerns, and it's important IMO to separate them.

To AGENTS.md, or not to AGENTS.md? That is the question.

Simply having an AGENTS.md file in the project root really does nothing other than signal that Drupal is aware of and keeping in step with emerging developer trends and industry standards. It is acknowledgement that there are lots of developers using coding agents in 2026 as part of their developer workflows.

Regardless of how individual core contributors feel about this fact, it is simply just that: a fact. "Most developers prefer Git" is another fact, and it's why we moved off of CVS despite this breaking some of our previously conceived tooling and workflows, because we have always (historically, anyway...?) wanted Drupal to have a great developer experience for incoming contributors.

Quoting from AGENTS.md (the specification website):

AGENTS.md
A simple, open format for guiding coding agents, used by over 60k open-source projects.

Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.

So with that definition in mind, the decision to add an AGENTS.md file to core is no more contentious than us having a robots.txt file in core (which we already do). It's a widely-adopted standard, it has downstream impacts to our users (developers in this case), and so as a "developer-forward" platform, Drupal core provides support for it. It's really as simple as that.

What goes IN the AGENTS.md file? That is the REAL question. ;)

Now, What goes IN Drupal core's AGENTS.md file ... that is where you can start to express opinions on a variety of things, including whether or not you encourage the use of AI.

Here again, I think the safest path would be to NOT be opinionated, and instead just be factual. This also has the side benefit of helping humans as well as agents.

Non-AI Example: https://www.drupal.org/docs/develop/development-tools/editors-and-ides contains a bunch of tools I could potentially use as an Editor or IDE to develop on Drupal. PHPStorm is at the top of the list (presumably because lots of people use it, and we're trying to make discoverability easier, but I'm actually not sure). I have no idea (nor do I want to know) what the CEO of JetBrains does in their spare time, whether or JetBrains has terrible employment policies, whether they donate to political causes I disagree with... it's simply a developer tool, and that page's job is to raise awareness of that tool (among others like it), so that I can read more about the options and choose the best one for me.

Here's an AGENTS.md file that Claude whipped up that simply "sticks to the facts":

- What is in this repository?
- Where are the authoritative sources for things like Coding Standards, API changes, etc.
- What tooling does Drupal use for automated testing, code linting, etc.

^ Things like that. These are completely neutral facts about Drupal core. That's the approach I would recommend, because it takes the "heat" entirely out of this conversation. The conversation instead shifts to "what are the top tips that we want all Drupal contributors (human, coding agents, or otherwise) to know when first coming to our repo?" and creates effectively a "1-pager" for those.

But we DO have opinions about AI usage in Drupal! And they're important, DANG IT!

YES, YOU DO! :) But you don't want to just shout those opinions into the void (well, maybe some of you do ;)). You want AI tools to listen (as much as they "listen" to anything :P) so that they (eventually) STOP doing stupid things that frustrate and annoy you and burn you out as maintainers. (Fully agreed with this concern, btw! And Drupal is going through this along with every,. other. open source. project. on earth. <3)

For that problem, you need to use a different widely-adopted industry standard, which is the Agent Skills specification. Again, quoting from the source:

What are Agent Skills?
Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

Agent Skills are where you encode domain knowledge as well as opinionated guidance on how to do something. That's inclusive of things like:

  • How Drupal APIs work — Entity/Field API, caching, render system, etc.
  • Community norms (a lot of which is what's actually in the MR) — here's how to write a good issue summary, here's the standard commit message format, here's how to think about assigning contribution credit...
  • "Topical" guidance around how Drupal thinks about security, automated testing, accessibility, etc. etc.

And BEST OF ALL, because all of this guidance is just in Markdown files, once again it helps out all Drupal contributors. If you hate AI and never want to use it, no problem! You can still browse https://git.drupalcode.org/project/ai_best_practices/-/tree/1.0.x/skills... and read what's in there, and come away smarter and more well-informed.

So then, do "Agent Skills" go in core?

Originally, I thought yes... but since it was very clear from the "vibes" that this was not happening. ;) I started AI Best Practices for Drupal project in contrib to be that "canonical" place for Drupal-wide guidance.

Now that we've been maintaining that project for a few months, however, I actually think contrib is where Agent Skills belong. Not because "AI is bad" (whether AI is or isn't "bad" isn't the purview of Drupal core, just as it isn't the purview of Drupal core to recommend PHPStorm over Visual Studio Code) but because this *(@# moves way too fast for Drupal core's shipping cycles.

Non-AI Example: The GitLab migration has started happening in the past month or two, and we're "between" major Drupal core releases. That means:

  1. The Drupal Association is making changes to our GitLab deployment in response to early feedback, for example these /do:XX commands that simulate the old "click this button" workflow on Drupal.org.
  2. GitLab itself is also changing, and for example GitLab CLI (glab) now has a 1.0 release which fixes a bunch of annoying stuff we used to have to document our way around, there's now a beta of fine-grained personal access tokens which is super important from a security POV
  3. The "best practices" advice around using GitLab with Drupal are also changing week by week as we discover new ways of working and share tips and tricks and workflows with one another.

^ If this "how to contribute" guidance were held in Drupal core, tools would constantly be completely wrong because one particular contributor is getting outdated information from version X, and another contributor is getting it from version Y, etc.

Whereas if it lives in contrib, developers can git pull (or composer update or whatever you do :D) to get the latest best practice advice every time they sit down to code something.

That was TOO MANY WORDS, webchick! TL;DR it for me, SHEESH!

FAIR. :D Here's my 5 cents Canadian (tariffs! 😭) as a former Drupal core committer who understands (at least to a large extent) the competing pressures y'all are dealing with (<3):

  1. Drupal core (the software) should steer clear of expressing opinions on AI, and should treat it as a choice individual contributors make, just as they make choices about other tools that they use (e.g. IDEs)
  2. It makes sense for AGENTS.md to be provided by Drupal core, because it's a well-adopted industry standard supported by 60K+ other open source projects, and also supports the preferred workflow of a LARGE (and growing) set of developers.
  3. Drupal core's AGENTS.md content should be limited to factual information only, aimed at helping any new contributor to Drupal understand the "lay of the land." Ideally, this should be very short — AI community guidance around this is around 150–200 lines.
  4. "How to do things in Drupal" guidance should be in Agent Skills, NOT in AGENTS.md.
  5. Agent Skills should live in contrib, NOT Drupal core, due to mismatch in the pace of shipping cycles
  6. If you wish agents would do less stupid things with Drupal, please join our efforts at AI Best Practices for Drupal, where we are actively trying to do something about it :)

(For more on the "origin story" of this project and why you see @webchick in the various queues yammering on and on about AI lately :P, see Talking Drupal Podcast #555)

Thank you for coming to my TED talk. ;)

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

^ Oh THAT'S COOL I didn't know it would do that! :D

Anyway, shorter this time. ;) https://git.drupalcode.org/project/ai_best_practices/-/work_items/3588935 is an issue I've created in the AIBP project so we can take some of the "how to" guidance from this issue + MR + discussion and encode it in a "how to contribute to Drupal core" skill so all agent-using developers can benefit from it.

LMK who it makes sense to partner with on this. And then, with that person's permission, I would love to add them to MAINTAINERS.md as a "Skill Maintainer" for that skill, so we don't make future changes to that guidance without their review.

nod_’s picture

nod_
Primary language French
Location Lille
commented

That's a wim-sized comment right there, been a while :D

If you wish agents would do less stupid things with Drupal, please join our efforts at AI Best Practices for Drupal, where we are actively trying to do something about it :)

I wish people would do less unhelpful things with LLMs. And that's really what the AGENTS.md file tries to do. It discourage LLM use for communication which is a big part of the pain points we have with LLM users in the queue, and make sure the code sent is tested and follows our conventions so we don't waste people and even CI's time.

Having a "factual" AGENTS.md file on the other hand is cementing the status quo, the tools are problematics in ways git and the vast majority of the other softwares are not. Agents are addictive on purpose, Claude is to devs what tiktok is for teenage girls. While there is way more evidence of tiktok harms, there is already evidence for LLM harm. Being neutral and having an AGENTS.md file really does communicate that we don't care about the effects of LLMs, and that's its OK to use it for everything, it's not. I don't want to talk with LLMs, if the communication is going through LLMs we're not a community anymore.

On the AGENTS.md or Skill, from what I said previously the opinion needs to be in core. What I want is a "grayscale" mode for LLMs working with Drupal core. There is no artificial limitation on the capabilities of the LLMs, but we're trying to reduce the built-in harmful effects of Agents/LLMs

cilefen’s picture

cilefen commented

CS courses set standards, like this CLAUDE.md from Stanford's CS336, that constrain the LLM to act more like a teaching assistant.

wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented

That's a wim-sized comment right there, been a while :D

🤣

/homerbackingaway.gif

quietone’s picture

quietone commented

The word 'maintainership' isn't in the Merriam Webster or Collins dictionary, so not American English. So, I talked with nod_ in Slack and I suggested a change which he agreed would work. I have made that change to the MR.

quietone’s picture

quietone commented
Issue tags: -Needs framework manager review

I brought this up in a committer channel and got confirmation that the framework managers are ok with this, so removing tag.

quietone’s picture

quietone commented
Status: Needs review » Reviewed & tested by the community
Issue tags: -Needs product manager review

In the committer channel lauriii expressed concern that the text is asking people to not use LLM but then gives instructions for using LLM. I think that was expressed in this issue in #13 and responded to in #15.. lauriii did say the they are not comfortable with this wording but will not block this addition. Since @gábor hojtsy has already commented here and not opposed this, so I am removing product manger review tag.

And setting to RTBC.

godotislate closed merge request !15508

  • godotislate committed eb59ce6b on main 
    task: #3585894 LLM harm reduction in Drupal core contribution, AGENTS.md...
godotislate’s picture

godotislate
he/him
commented
Status: Reviewed & tested by the community » Fixed

Committed eb59ce6 and pushed to main. Thanks to everyone for their thoughtful contributions.

The trial for these changes will run three months as of today. I consulted with @quietone, @catch, and @longwave, and we agreed to merge this to main only for now. One of the reasons being if we do decided to revert this in the future, we'd have to consider what to do with older security-only branches.

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.

nod_’s picture

nod_
Primary language French
Location Lille
commented

Thanks, created #3606814: [PP until 2026-09-30] Evaluate AGENTS.md effects

xmacinfo’s picture

xmacinfo
he/him
Primary language French
Location Canada
commented

Can we backport to 11.4.x or is this too late? An AGENTS.md file cannot break Drupal, so adding it to 11.4.x just a few days before its release should be welcome.

Let's get feedback about the AGENTS.md file soon.

bramdriesen’s picture

bramdriesen
he/him
Primary language Dutch
Location Belgium 🇧🇪🇪🇺
commented

Great! Let's see what this gets us.

nod_’s picture

nod_
Primary language French
Location Lille
commented

I don't think it makes sense to backport to 11.4.x, this is a experiment for core contribution. Development happens on main, not on the branches

Status: Fixed » Closed (fixed)

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