[docs] Add AGENTS.md based on #1377 dev experience

[BenjaminPelletier]

This PR adds the start of an AGENTS.md, generated via prompts¹ following the completion of an agent's dev work on #1377. My hope is that future agents can help to grow and refine this document so that the capability to make effective agentic contributions to this repo grows over time. If agentic PRs are generated carelessly, this could also be a place to have agents direct their humans to a (to be written) agentic use policy :)

Of course, the start of explicit use/support of agentic development is an important and potentially impactful topic, so any concerns or comments are welcome here or other appropriate forum.

¹Prompt 1:

Looks great! That task is complete. But now that you have good context on the project, please consider how future AI agents (including yourself) can more quickly/efficiently inform themselves about how the project works (acquire context necessary for development efficiently). If appropriate, please add some documentation to the project to improve future context acquisition. Ideally, this documentation would be consumable by both humans and AI agents and therefore live in human-readable Markdown files. But, agent-specific improvements are good as well (e.g., AGENTS.md or other standard way of communication information to AI agents). When adding documentation outside AI-only contexts, please try to be as succint as practical while still conveying the necessary information as we don't want to bury humans in more information than they can handle. And/or ensure the documentation structure allows humans to easily ignore irrelevant information (e.g., but not clicking on a link for a page that they can see won't be relevant to their subject of interest) to reach relevant information quickly.

Or alternately, if there is a reason this suggested documentation approach would likely not be effective in accomplishing the intended goal, please explain why that is instead of attempting to write documentation.

Prompt 2:

That looks great as well! Please add one more item to it: a prompt/hint/suggestion for AI agents to also update AGENTS.md with things that will help future agents based on their experience performing the core work, along with the core work they are asked to do. Basically, include my request above (addressed to future AI agents), but shortened/clarified/etc as you think would most effectively elicit the kinds of improvements to AGENTS.md that you just made.

Prompt 3:

That's excellent as well. Let's make one tweak/addition to also encourage correction of AGENTS.md when necessary as well. Through a mistake or the progression of time, it could be that something written in AGENTS.md is mistaken -- if an AI agent discovers such a mistake during the course of their other work, fixing the AGENTS.md mistake in addition would generally be appreciated.

[barroco]

@BenjaminPelletier, I think it is great to help AI assistants / agents and more generally our users with providing "machine readable" context to the repository to encourage high quality contributions. As mentioned during the contributors call on March 10, 2026, there is a risk of overwhelming reviewers / committers with good looking but disfunctionning PRs which require extra careful review. There is probably nothing we can do at this point since we are definitely not there but we may want to keep it on our radar.

[BenjaminPelletier]

there is a risk of overwhelming reviewers / committers with good looking but disfunctionning PRs which require extra careful review

I think this is a good point as the effort could be asymmetric (not much effort to submit PR, a lot of effort to review). It seems like looking into the feasibility of an AI reviewer could potentially be useful. I think (hope) our main/initial mitigation can be an AI use policy if that becomes needed. In that case, I think we could modify this file to instruct the AI agent to tell its human certain things or ask them certain things (for instance, pointing out the AI use policy, perhaps having the AI agent evaluate whether it was being used correctly).