[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:  enhancement       |      Status:  new
 Priority:  normal            |   Milestone:  Awaiting Review
Component:  Build/Test Tools  |     Version:
 Severity:  normal            |  Resolution:
 Keywords:                    |     Focuses:
------------------------------+------------------------------

Comment (by justlevine):

 Using this solely for illustrative purposes (I understand the specific
 wording isn't the focus 🙇):

 > FWIW, I've found success by maintaining context in a separate directory
 (like `/docs`) and then explicitly loading it through the main agent file
 (previously, `CLAUDE.md`).
 >
 > {{{
 > # Agent context for the WordPress project
 >
 > This is the root level context file for the open source project,
 WordPress.
 >
 > ## Project overview
 >
 > Always load @CONTRIBUTING.md, @README.md, and @docs/architecture.md ....
 when starting a new session.
 > }}}
 >

 I want to
 [https://core.trac.wordpress.org/ticket/63901?replyto=9#comment:7 repeat]
 that GitHub Copilot explicitly recommends not to use absolute language
 like "always".

 From https://docs.github.com/en/copilot/how-tos/configure-custom-
 instructions/add-repository-instructions

 > You should also consider the size and complexity of your repository. The
 following types of instructions may work for a small repository with only
 a few contributors, but for a large and diverse repository, these may
 cause problems:
 >
 > - Requests to refer to external resources when formulating a response
 > - Instructions to answer in a particular style
 > - Requests to always respond with a certain level of detail
 > For example, the following instructions may not have the intended
 results:
 >
 > {{{
 > Always conform to the coding styles defined in styleguide.md in repo my-
 org/my-repo when generating code.
 >
 > Use @terminal when answering questions about Git.
 >
 > Answer all questions in the style of a friendly colleague, using
 informal language.
 >
 > Answer all questions in less than 1000 characters, and words of no more
 than 12 characters.
 > }}}

 Does Claude Code or whatever still need absolute language to prevent it
 from ignoring our AGENTS.md and falling back to the built-in instruction
 set when the context window gets too large? Is GitHub's recommendation
 just as true for when using GPT5 or only the more sycophantic 4x models
 that are used by default?

 I don't know. But I do feel that in any most other context the bulk of
 core committers and leadership (yup acutely aware of all my heros I'm
 core-splaining to right now 😅) would strongly oppose to adding such an
 opaque footgun to core. I mean we won't even `phpcbf` legacy code because
 it might cause some diff headaches on old PRs, but we're cool with
 something that can actively degrade the contributor experience - while
 costing them money on wasted tokens! - with no explicit indicator or hint
 that it's a bug with the instructions and not e.g.
 [https://techcrunch.com/2025/07/17/anthropic-tightens-usage-limits-for-
 claude-code-without-telling-users/ Anthropic secretly rate limiting and
 using a worse model]?

 ----

 More direct feedback

 Replying to [comment:9 jeremyfelt]:
 > This can then be tested with a prompt like:
 > {{{
 > What context have you loaded already? Please provide filenames.
 > }}}

 I think we need test the _results_, i.e. the effect on the ability to
 generate compliant code or accurately answer questions about/navigate the
 codebase.

 1. A positive answer here doesn't prove those files are in context. It
 doesn't even prove that `AGENTS.md` is in the context (or still
 unsupported by the IDE), just that when asked the question the LLM was
 able to discover that and parrot back what what's written there.
 2. Just because something is "in context" doesn't mean it's having a
 positive effect out the LLM output. A big part of the shift to subagents
 rn is that ability to only have the relevant info for the task.

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