Explore alternative AGENTS.md file

[felixarntz]

I researched different AGENTS.md structures in other projects and explored a few iterations created by an LLM (I used Gemini CLI) with some guidance on the particular structure).

I'm opening this PR with one that I particularly liked, simply for consideration.

I'm not saying that this is holistically particularly better than the current one, but I think it might be helpful for us to compare the different sections. Maybe there are things we'll want to combine from both variants.

On this note, I would also highly encourage other folks that use a coding agent to explore and share their drafts.

[justlevine]

@felixarntz do you have an eval that can be used to compare the differences?

[felixarntz]

@justlevine I don't.

I agree that would probably be useful to a certain extent, but at the same time it wouldn't capture the diversity of the different coding assistant tools that different contributors use anyway.

[JasonTheAdams]

I think this new structure is simple enough. The structure I had was from /claude init and was also AI-generated. I don't think there's likely to be a significant difference in model performance based on structure, so long as it's sensible. I do understand that models tend to do better with more straightforward instructions, which I think this structure does a good job of. 👍

[jeffpaul]

The thing I still have a hard time with this sort of a file is that the content seems wholly fit for something like a CONTRIBUTING.md or DEVELOPERS.md file. There's not much if anything really in this AGENTS.md file that otherwise wouldn't be helpful context for a human onboarding to the project.

[felixarntz]

@jeffpaul Agreed. In theory, I wish there wouldn't need to be this duplication. That being said, based on my anecdotal experience, agents do better with being the relevant content passed directly instead of e.g. putting into AGENTS.md something like "You must read the CONTRIBUTING.md file." 😐

An alternative idea would be to fully combine the two and either require agents to be configured to rely on CONTRIBUTING.md (either by actually configuring it or by symlinking AGENTS.md), or the other way around by centralizing some shared information in AGENTS.md and in CONTRIBUTING.md refer contributors to that file for those respective pieces of information.

But that would also have problems. Having to look between the two files would be unnecessary mental overhead for new contributors. And maybe more importantly, there are strategies that work well with LLMs that would not go well with contributors (for example SCREAMING LANGUAGE LIKE THIS 🙃).

My 2 cents is, while I don't like duplication, I think we'll need to optimize for contributors and for LLMs separately, which will mean some duplication.

[JasonTheAdams]

I kind of like the idea of simply referring folks in the CONTRIBUTING.md doc to check out this doc for a crash course on project structure and architectural details. That reduces redundancy a bit. There isn't much of anything in the AGENTS.md doc that wouldn't be useful to a person, even if the writing style is a bit odd.

[JasonTheAdams]

I feel like we can merge this and iterate more. The discussion doesn't seem to be moving away from the importance of having this.

[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 <[email protected]>
Co-authored-by: JasonTheAdams <[email protected]>
Co-authored-by: justlevine <[email protected]>
Co-authored-by: jeffpaul <[email protected]>

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