[wp-trac] [WordPress Trac] #63901: Add `AGENTS.md` for the project

[WordPress Trac]

#63901: Add `AGENTS.md` for the project
------------------------------+---------------------
 Reporter:  flixos90          |       Owner:  (none)
     Type:  task (blessed)    |      Status:  new
 Priority:  normal            |   Milestone:  7.0
Component:  Build/Test Tools  |     Version:
 Severity:  normal            |  Resolution:
 Keywords:                    |     Focuses:
------------------------------+---------------------

Comment (by justlevine):

 > whenever it's ready to go.

 To move the discussion forward in the meantime, here's
 [https://arxiv.org/abs/2602.11988 | yet another preprint] that doesn't
 just cast doubt on the efficacy of AGENTS.md but tries to quantify the
 measurable negative impacts. From the abstract:

 > Across multiple coding agents and LLMs, we find that context files tend
 to reduce task success rates compared to providing no repository context,
 while also increasing inference cost by over 20%.

 And that's before taking into account that different LLMs treat
 instructions differently. We recently found out that even many on the Core
 AI team aren't up-to-date on model particularities like how
 [https://wordpress.slack.com/archives/C08TJ8BPULS/p1770395934195279 | you
 should avoid ALL CAPs GPT-5 model], so I don't know how other folks are
 supposed to keep up.

 Case in point: it took almost half a year before Gutenberg noticed that
 Claude Code wasn't even reading their `AGENTS.md` file.
 Unsurprisingly, the [https://github.com/WordPress/gutenberg/pull/75507 |
 vibe-coded update] includes ALL CAPS and other anecdotally problematic
 antipatterns. (I've asked for clarification there whether anyone tested
 efficacy before committing).

 We wouldn't commit any other build tool that we didn't have the
 availability to review or maintain. And yet, unlike other build tools, its
 behavior changes wildly by external changes (harnesses, llms themselves),
 even if we could commit today's "best practices", let alone in a way where
 it didn't hurt contributors who aren't using a particular proprietary
 model/harness.

 I recommend we immediately remove any existing AGENTS.md files from all
 public `WordPress/*` repos that are intended for community contribution,
 and only restore them when:
 1. We've done basic tests to demonstrate the specific contents in the file
 helps, not hurts, contributors (and across more than just 1 proprietary
 model+harness).
 2. We have some plan for how folks can sustainably maintain and keep the
 files updated for as long as it remains relevant as a context hack.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/63901#comment:15>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform