Remove directory structure section in AGENTS.md as it's pointless and easily stale

[felixarntz]

No need for a directory structure in AGENTS.md:

• Unnecessary maintenance, super likely to get stale.
• Pretty much pointless because agent sees the folders anyway.
• Something super high-level like src, tests, docs would work, but that is so basic, the agent will know anyway what these are for.

In other words, I think we should remove it.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: JasonTheAdams <jason_the_adams@git.wordpress.org>
Co-authored-by: justlevine <justlevine@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[justlevine]

Pretty much pointless because agent sees the folders anyway.

My understanding and anecdotal experience is that it's the most important thing you can do in your agents.md file, (second being the list + descriptions of available NPM commands. meanwhile the coding practices are usually context waste in brownfield projects where patterns are inferred and strictly enforced by existing code)

It's not about the (sub)agent being able to see the file structure, it's to give keywords the inference models can tokenize and match against so they can lookup and disclose more efficiently.

I'll leave it to you folks to decide whether the upkeep is worth the benefit (I'm still of the opinion the file shouldn't have been committed in the first place because of the upkeep burden and how invalid context leads to worse outcomes than missing context). please don't consider this comment blocking.

[felixarntz]

[...] that it's the most important thing you can do in your agents.md file [...]

Can you clarify why you think it's helpful? Or where/how you've seen it providing value?

I'm still of the opinion the file shouldn't have been committed in the first place because of the upkeep burden and how invalid context leads to worse outcomes than missing context

This is part of why I think this should be removed. The rest of the file doesn't really have any considerable upkeep burden I think.

[justlevine]

[...] that it's the most important thing you can do in your agents.md file [...]

Can you clarify why you think it's helpful? Or where/how you've seen it providing value?

If I remember I can share the preprints later when I'm by my desk, but tl;dr is that by prepriming the context window with where things are, the agent doesn't need to waste the initial tokens or context space (storing the results of the tool/subagent) to build own keyword map. As you pointed out, common top-level patterns like src/ vs test/ and .github/ are pretty obvious, but knowing which functionality belongs in which file involves a lot of searching, grepping, and file-hopping, and it's even less efficient when a project goes "full-OOP" like this one, instead of more topical/semantic colocation (bad but illustrative e.g. inferring the difference between ProviderImplementations/{*}, and Providers... or Providers/*Implementation/ or Providers/Model/* ).

When you prime the context with a directory/namespace treemap to semantic definitions the searching is more efficient, the results have more accurate relevance scores, and with less of your context window used you get longer before compaction takes your agent off track.

(PS: this is the same way that progressive disclosure works elsewhere (to varying degress, depending on the harness), and one of the big motivators for nested AGENTS.md )..

Without real evals, easy way to see this in action would be to open two copies of this repo side by side and use opencode (or something else where you can disable the caching/"persistent memory") to ask it something requiring domain knowledge e.g. `--prompt "Scaffold out a new provider for OpenCode." and then watch the tool and token usage and relative accuracy w(/o) a domain tree. Obvs with a prompt like that we're not expecting anything functional but:

• how long and tokens wasted until it found the correct dir
• how much (if any) of the correct api (OOP classes/methods etc) was used.
• how many compactions/how far it got before saying it was "done"

(Clarifying above is how I have/would see the value. Am not suggesting that this particular PR change needs the above "burden of proof", the level of detail is just for the discussion and future need for prior art.)

The rest of the file doesn't really have any considerable upkeep burden I think.

(IMO time and the evolution of the spec are the upkeep burden. For example, that **DO**: Read the Docs: Before making any changes, thoroughly read CONTRIBUTING.md and docs/ARCHITECTURE.md. line that was probably super helpful in previous thinking models is likely destroying 4.5-haiku and others that are similarly commoditized. There's also some more ostensible "emerging best practices" beyond the natural efficiencies from deduping some of those DOs and subsection into a directory map, but without evals 🤷

The fact that you're here tweaking this file at all is a recognized counterpoint to my concern.)

[JasonTheAdams]

I think there's a tension being struck with these files. Having them is useful, making them too robust loads up tokens and becomes hard to maintain, not having them requires each person to maintain their own, which may get out of sync.

So I think removing this is a fair trade-off for maintainability, while the rest of the file remains valuable.