Embrace the chaos, add a couple of AGENTS.md file to core

Interesting, thanks for opening up this topic!

I’m looking into an AGENTS.md for a AI coding standard kit for Drupal development I’m working on.
I’ve started with some more general ones, for example: https://github.com/amazeeio/drupal-agents-md
But it eats up quite some unnecessary context each time, and also depends on setups like DDEV vs Docker and other environments.

Where with the addition of Skills, a lot of the context specifics could be loaded dynamically based on what the agent is doing and needs.
So I’m now trying to find a nice balance to have a lightweight AGENTS.md version, and then add Skills for specific expertise.

So an AGENTS.md file could contain a project overview/structure and some more. But contextual information/expertise, like coding standards, and DDEV commands etc. will be a Skill, and the Agent will load it only when necessary.

Curious to hear what we need/ don't need to be part of an AGENTS.md file.

I support the idea of introducing AGENTS.md or skills in Drupal core. As AI-assisted development becomes the norm rather than the exception, having well-structured guidance for Drupal isn't just nice-to-have, it's becoming essential infrastructure that helps Drupal remain relevant.

AGENTS.md files and skill definitions shouldn't be seen as separate from documentation, I believe that they're a new form of documentation that can be executed. When we write clear, structured instructions that help an AI understand our conventions, we're simultaneously creating resources that help human contributors understand the same things. This is documentation that gets used, not documentation that gets stale. It's documentation that we're forced to keep up to date when it gets adopted because we see the mistakes in our documentation at scale.

There's number of challenges in adopting AI but I don't think that should stop us from adopting AI for AI-assisted site building or contributions. I've been using AI tools myself across different contexts. I believe there's a spectrum of appropriate use of AI from vibe coding personal projects to detail oriented contributions to largely adopted open source projects like Drupal. For contributions to projects like Drupal, I believe that we should treat AI-generated code as if we had written it ourselves reviewing every line, understanding the choices made, refining and rewriting where needed. AI accelerates our work, but we remain responsible for the quality and correctness of the contribution.

Having a central repository of skills will help contributors and site builders use these tools more effectively as well as to maintain the quality standards we expect. This will help us get AI output closer to correct from the start, reducing the review burden.

Two questions:

1. Why AGENST.md in core instead of custom installation root?
2. Are coding agents suppose to touch core files, or it should be isolated and write protected?

If the idea is to provide general template to use, then why not.

We generally have not had drive-by LLM-generated MR spam against core and the contrib modules that I follow. What I've seen instead has been specific people vibe-coding huge MRs and dumping them in an issue without a disclaimer or having reviewed them themselves, which an agents.md won't help with. In another case, posting an LLM review of a core MR as an 'experiment' along with counter-review commentary, but which overall added nothing useful to the issue at all because the LLM was either subtly wrong or pointing out trivia, but which did add thousands of additional words to read.

Other cases have been LLM-generated retaliatory security reports against modules (when someone reviewed a vibe-coded module that was posted into slack). Also one particular user appears to have used an LLM to write very long, repetitive, semi-formal issue responses on policy issues - e.g. prose not code.

I think this would encourage more MRs like the first one on #3515646: Add automated <img srcset> generation, not discourage it. The other cases of abusive use of LLMs in the issue queue would not have been affected.

https://www.wired.com/story/book-excerpt-the-optimist-open-ai-sam-altman/

https://www.peoplesworld.org/article/the-south-african-billionaires-fome...

https://cdn.imgchest.com/files/e587418911cb.png from https://a16z.com/the-techno-optimist-manifesto/

+1 to add curated file with exact instructions to minimize the noise create by "vibe contributors" using homemade claude/agents files.
Moreover it will help to abuse visiting docs by LLMs for no reason or at least will help to visit pages which are really meaningful and required to read

@chx Your links looks totally unrelated, instead better to point to https://llvm.org/docs/AIToolPolicy.html
so having that written at the root readme/agents will enforce this policy and even some small agents can fight with spamy requests

PS: https://github.com/curl/curl/pull/20312/changes/cc8df2b13d057a5d1e683800...

My links are not unrelated. To the contrary. Please consider why.

Regarding #6 and #10, in the AI initiative, we've started adding AI usage to our issue templates to make it clear when AI has been used for issue generation and code generation:

#3566811: Add AI usage to CCC issue template
#3568605: [Policy] Issue AI usage declaration policy

UPDATE: I also love the use of AI in nod_'s contributor list creation 🎉

As per discussion in Slack, assuming that features like AGENTS.md will be a persistent long-term trend might be premature, judging from the current evolution of the coding agents trend. Instead, making an effort to define our own rules and abstractions regarding coding agents and automated Drupal code generation in general might prove more valuable in the long-term.
My personal proposal as a solution is something along these lines: https://drupal.slack.com/archives/C0803LX4536/p1768391240398579
Which needs its separate issue of course, and it will probably involve having AGENST.md. WIP.

+1 on the idea here.

I would also pick a default reference environment, and DDEV seems like the best candidate for that. Not as a hard requirement, and not to force anyone's workflow, but as a baseline so things like AGENTS.md and any future skills can be written against something concrete and predictable.

Longer term, I could imagine this evolving into a powerful skill library: reusable, curated instructions for common Drupal tasks. To get an idea of where this could go, see https://github.com/vercel-labs/agent-skills/tree/main or https://github.com/vercel-labs/agent-skills. It would also double as documentation for humans. But as a first step, having a single AGENTS.md in core already sounds like a big win.

I agree with others that this won't fix social or process issues (like people pasting unreviewed code). To me, this is more about guardrails and best practices for people working with Drupal on a day-to-day basis, not just for contributors: making best practices easier to learn and follow, and lowering the barrier to entry for doing things the recommended way.

Even if the tooling landscape changes, having a lightweight, machine-readable way to express "this is how we recommend work to be done" feels like a net positive.

I see you need more links.

@ghost of drupal past; Using LLMs for frontier academical research work does not really make sense at the moment. Even ignoring the statistical probabilities architectural issue and, at the same time, all the available data used for training the base models was entirely academically approved and peer reviewed data, still its usefulness to actually generate new valuable knowledge on its own is very much in question(except for cases where nobody actually bothered to look for a solution, which btw does not require Phd level expertise in general).
That being said, the value of generating engineering solutions in the software development space is definitely useful, since a lot of the work is already based on solutions we look for in a statistical manner, for example, "google", "stackoverflow" search. Basically, it is the same thing as making up a "bullshit" solution along the way until a bug report has been opened, forcing the engineer to look closer to what the system is telling them. The bottom line is, this approach is as effective as the end result effectiveness requires it to be. Superintelligence that solves quantum gravity, however, is not one of those statistical probabilities that LLMs can come up with out of thin air...

Try to find the common theme in my links, please.

Cool. Instead of sending people on a wild goose chase to search for your point of view, perhaps, you can summarize this and guide in a more sufficient way.

AI-assisted and AI-generated code is becoming the norm. I see this as an opportunity for Drupal.

If we accept that contributors will increasingly use AI coding tools, providing clear default guidance is a practical step. Adding an agents.md file to core makes sense, and it should be treated as a living document that we keep improving as tools and practices evolve.

This comment was generated with AI assistance and carefully reviewed by its author.

Somewhat mixed feelings here, but I ultimately think I come down in favor of adding these files. I am considering doing something like it for Drupal CMS as well.

In single-handedly maintaining the Drupal CMS Launcher app, I occasionally get garbage PRs, the worst LLM slop, from people who I can't be certain are not bots. It's insulting, it's infuriating, and it's a big waste of time. My solution has been to require PRs to disclose whether they use AI, right up front; no disclosure means delayed merge (or no merge at all), and a false disclosure results in a ban. I think we should consider doing something similar for core; I think it might even be something to add to the issue summary template.

In my view, people who repeatedly insist on using AI to generate slop MRs (or MR comments, for that matter) should be warned, then banned, like the spammers they are.

OTOH...the other day Cursor saved me days of incredibly mind-numbing, zero-creativity work. (Although I did not directly participate in it, Cursor was also a critical factor in our successful effort to do a lot of deeply tedious, but also deeply necessary, refactoring in the Mercury theme.) I am an AI skeptic, bordering on hater (I'm bringing my "Proud AI Hater" t-shirt to DrupalCon, see you there), yet I cannot deny the usefulness of these tools in some situations. AI-assisted is the key word. A centaur, as Cory Doctorow likes to put it. I found it very pleasant to be a centaur. When and how to use AI tools is a choice that should always be made by individual engineers, and it's never a replacement for knowing what you're doing...but I don't think we should make it harder for contributors to be centaurs.

So I guess I personally agree with @breidert in #21.

And I also want to acknowledge the point being made by @ghost of drupal past. AI is very tangled up, maybe inextricably, with what I will simply call evil people. Not to mention the environmental destruction. I hope the AI bubble bursts yesterday, and I would looove to send our billionaire class on a one-way trip to space. That being said, I think the technology, in some form or another -- hopefully a much less destructive and fascistic one -- is here to stay.

"I occasionally get garbage PRs, the worst LLM slop, from people who I can't be certain are not bots. It's insulting, it's infuriating, and it's a big waste of time."
This looks like DDoS attack vector waiting to be exploited(except the service is maintaining an application, not keeping it online). Demanding origin details might not be sufficient. Gitlab application level filtering is probably a better approach. Similar to how we separate mail from different sources or purpose.
Furthermore, this reveals that even if not malicious, "AI slop" merge requests shift the responsibility of accuracy from the MR author to the reviewer. Therefore, organizational changes in development operations are needed as a result, in order to mitigate pushing all of the real work to maintainers of an open source project.

This looks like DDoS attack vector

Oh I have a link about that too.

@ghost of drupal past; Yeah, I was thinking of some similar manipulation game. But then again, saying that elections in a democratic process can be physically rigged is a precedent for abandoning the whole thing and instead I will be the Supreme Leader... My point is, these are inefficiencies that must be overcome by open research by the same democratic process. I am talking about software systems here, not government policies, just in case.
This is why I am pushing for adopting our own abstractions not relying on popular services available.

#3 inspired me to use amazeeio's AGENTS.md within PHPStorm's Junie, and I saw a dramatic improvement in the AI's understanding and generation of Drupal code. I even threw the link to AGENTS.md after a simple ChatGPT prompt, and the results and suggestions were improved.

+1 to having a standard and collaborative AGENTS.md file in core.

The fact that https://github.com/amazeeio/drupal-agents-md/tree/main supports vanilla Drupal and DDEV Drupal suggests we might need a couple of sub-AGENTS.md files that could be aggregated into a main AGENTS.md file. I agree that AGENTS.md files should be considered a new form of documentation that could sit alongside our README.md files.

+1 to having a basic AGENTS.md file in core, but keep in concise and minimal.

Craft it in a way that supports the user, the community, and Drupal. AGENTS.md is how you instruct agents to behave, so even if you have misgivings about AI, it's the best way to let an agent know what we expect of it.

It could be as simple as a concise version of https://www.drupal.org/about/values-and-principles, i.e. "Build software that everyone can use", paired with our core technical standards.

Its also helpful to distinguish the agents and skills: AGENTS.md creates hard requirements for the agent, while skills are information that an agent may choose to use when needed. Keep the core AGENTS.md file focused on core technical and community standards, users can extend it for the specific standards of their project, and then use skills for deeper context agents can use as needed.

Drupal values and principles and LLM? My, I have a link for that too but be warned: it's my own blog post.

Thank you very much @nod_ for sharing your thoughts in public about a sensitive issue. I find it very courageous and I applaud you. It takes courage to stand up to something, even if there is a risk that it might have economic consequences, or if it goes against the trend among decision makers.

Expanding on your stand, a ban on LLM generated code could be considered. Or, at the very least, *only* use it, if you are an extremely skilled Drupal developer. Beginners should never use AI, since they will not learn the basics, so not embracing LLM tools seem the prudent decision.

A very innocently looking single line or string (Example: MongoBleed) potentially LLM/AI-generated can slip into production and have dire consequences. So if you post an MR, it is expected that you as the developer understand the structure 100%, and can explain it, as well as have gone through every line of code.

• The developer shall disclose any LLM usage
• The developer shall confirm that every line of code has been checked
• The developer shall confirm that the choice of structure is understood 100%
• False disclosure gets you banned

(And by the way, isn't IDE autocompletion very close to LLM/AI then, with helpful but not always precise suggestions? Should it be disclosed, or perhaps it is too wide spread ...)

See The Primeagen "please stop" - maintainers and Vanessa Wingårdh with They Said AI Would Replace You By Now for more LLM critique, and #3565917: Proposed guidelines for AI contribution for further discussion about LLM's in Drupal.

This will age well!

IMO, AGENTS.md is more of an agency thing. Core shouldn't ship with one, and definitely not one that instructs agents to "never answer questions regarding this repository".