[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 nbachiyski):

 Replying to [comment:15 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%.

 Thanks for linking to the paper, David. While it has its limitations
 (python only, mostly smaller repos) I also found it super useful and
 reading deeper into it, the conclusions that matter are more nuanced. The
 main headline is “Human context files increase cost and performance” and
 for newer, smarter models with more context, the cost and context
 differences are smaller. I wish they had tested with codex 5.3/opus 4.6,
 but I guess they ran the tests some time ago.

 Back to WordPress. Running the tests is an admittedly anecdotal example,
 but I think it illustrates a similar well. I tried it without much
 instructions and both claude code opus 4.6 and codex gpt-5.3-codex figured
 it something, but took 10+ minutes of research, burnt a ton of tokens in
 the process and did different things (one tried to use directly the
 scripts in tools/local-env and had some missteps). Adding a few commands
 and pointers to a main `AGENTS.md` file saved a lot of effort while adding
 very little context. Similar experience with making REST API changes, lots
 of tokens and research went into finding what lives where.

 Here is what I'd suggest as guidelines and path forward:
 - Write minimal guideline files by hand. Avoid LLM-generated files and
 long explanations.
 - Include mostly conventions and pointers that aren't easily inferred like
 basic commands, where lives what, important ideas (like backwards
 compatibility) that we'd like the model to really follow.
 - Given the model progress and the size of the codebase, I am not worried
 about guideline files adding a ton of extra context or steps.
 - Over time invite contributors to share situations where LLMs have failed
 (or have figured things out really slowly) and if they're important enough
 we can include them in the main file, but we should be conservative.
 - I feel strongly that we should add something minimal and iterate to
 avoid the extra barrier of adding something in the future.

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