RFC: add AGENTS.md

[andriiryzhkov]

Related: #21881

This is a first pass at the AGENTS.md idea from the bisect RFC. It is meant as a starting point for discussion, not a finished policy – if the consensus is that we don't want this file at all, that's a fine outcome too.

Why

We're getting more AI-assisted patches, and they go wrong in the same few ways. The one that hurts most is the bisect problem from #21881: a series where only the last commit builds. The others are familiar – an API inferred from its name instead of read, a claim that something works when it was never run, a diff with half the file reformatted around the actual change.

None of that is addressed anywhere an agent will look. The Developer's guide and dev-doc/ are excellent, but nothing points an assistant at them, and AGENTS.md in the repo root is the filename most coding tools now read by default. So this is mostly a signpost with the sharp edges called out.

What's in it

The rules aren't new – they're collected from the Developer's guide, dev-doc/ and what the history already does. Where I couldn't find a written rule I measured the tree instead of inventing one, which is how the commit-message and comment sections ended up the way they did.

Two things in it contradict the wiki, and I think the wiki is wrong: .clang-format and tools/beautify_style.sh don't exist any more (removed in 46b054c and b734b01), but the guide still points people at the script.

What I'd like feedback on

• Is the root the right place, and is AGENTS.md the right name? Some tools want their own filename; a symlink or a short pointer file could cover those.
• Length. It's ~340 lines. I've cut it twice already and could cut more, but every rule in there is one I've watched an agent get wrong.
• The commit section documents Fixes #N in commit messages because the history does it, but if maintainers would rather close issues from the PR only, that should change.
• Anything I've stated as a rule that isn't actually the project's practice. That's the failure mode I'm most worried about, so please push back.

Written with AI assistance. Every rule in it was checked against the tree or the history before it went in, but that checking was done by the same assistant, so a second pair of eyes on the specifics would be welcome.

[da-phil]

Good idea and good content already, thanks for that.

Is the root the right place, and is AGENTS.md the right name? Some tools want their own filename; a symlink or a short pointer file could cover those.

I think claude code is the only tool which insists to not support the https://agents.md/ convention, it seems Google, Github Copilot, Windsurf, OpenAI Codex have implemented it.

There is even documentation around this proprietary behavior: https://code.claude.com/docs/en/memory#agents-md

Hence I suggest to also create a CLAUDE.md file with the only content @AGENTS.md, or just a symlink if this is fine with everybody.

Length. It's ~340 lines. I've cut it twice already and could cut more, but every rule in there is one I've watched an agent get wrong.

Sounds fine, even if those lines will be part of every prompt context.

The commit section documents Fixes #N in commit messages because the history does it, but if maintainers would rather close issues from the PR only, that should change.

I don't have a strong opinion on that.

Anything I've stated as a rule that isn't actually the project's practice. That's the failure mode I'm most worried about, so please push back.

I didn't find an obvious violation of our (unwritten) project pratices, hence it's such a good idea to finally agree on common accepted practices ;)

[andriiryzhkov]

Hence I suggest to also create a CLAUDE.md file with the only content @AGENTS.md,

Added.