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.

[masterpiga]

Thanks @andriiryzhkov, LGTM.

To allow for customization, maybe you could add @AGENT_OVERRIDES.md or something like that at the very end, commit an empty file with that name and then a second commit adding it to .gitignore. I already have my own setup and I would prefer it the two could coexist.

[victoryforce]

maybe you could add @AGENT_OVERRIDES.md or something like that at the very end, commit an empty file with that name

@masterpiga - How will agents behave if this file is mentioned but does not exist? Will they process it correctly and not consider it an error? If everything is fine, I wouldn't add an empty file to the repo because it just looks a bit sloppy.

[masterpiga]

The last line in AGENT.md could be something like:

If it exists, also follow the instructions in @AGENT_OVERRIDES.md, which may override, amend or complement this set of instructions.

[andriiryzhkov]

@masterpiga : The core idea is that AGENTS.md is a project level placed in the root. This is the common foundation for everybody. Each AI platform allows it's own setting other than AGENTS.md. For example, Claude Code looks for instructions in multiple locations: root CLAUDE.md (defined on the project level in repo), .claude/CLAUDE.md - this is were I add my own instructions on top of project one.

Is similar multi-layer approach something you can adopt?

[masterpiga]

Sure, I am adaptable. I thought that it would be nice to have a way to make it easier to integrate specific developer instructions, but if it's controversial just forget about it 👍

[andriiryzhkov]

I thought that it would be nice to have a way to make it easier to integrate specific developer instructions

I don't think it is controversial and it is a right place to discuss it. But I never saw such extensions so far and majority of AI platforms have support for instructions on different levels - project, user, etc.

I probably need to check better instructions layering on different platforms and I will come back with more educated opinion and maybe suggestions on that topic.

[masterpiga]

I don't think it is controversial and it is a right place to discuss it. But I never saw such extensions so far and majority of AI platforms have support for instructions on different levels - project, user, etc.

As I mentioned before, I don't feel strongly about it, and I wouldn't want you to waste your time on it. It's just that AGENTS.md is the only almost-standard way to instruct agents on a specific project. If I want to use different agents for the same project with a different/additional set of instructions (but the same instructions for all), I have to create N separate instruction files (or N symlinks), one for each agent/platform, and then add them one by one to .git/info/exclude (to avoid cluttering .gitignore). I am not aware of another catch-(almost)-all method, but I may very well be wrong.