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.

[andriiryzhkov]

@masterpiga Several agents do support per-project personal instructions – Claude Code reads .claude/CLAUDE.md, for one – but each expects its own path, which is exactly the N-files problem you described. A single AGENTS.local.md that every agent is told to read collapses that to one file, so I've implemented your idea, with two changes.

No @. A final section in AGENTS.md says that if AGENTS.local.md exists, read and follow it alongside. @ is Claude Code and Cursor prompt syntax; Codex and Copilot read it as text, and in Copilot Chat @ means a chat participant. As an instruction it works everywhere.

.gitignore, not .git/info/exclude – one committed line, so nobody sets it up per clone. That's the part that actually answers your complaint.

@victoryforce – no placeholder needed, the wording is conditional on the file existing.

One thing I didn't carry over: you asked for "override, amend or complement", and I've written it as amends, with project conventions still governing – otherwise a local file can switch off the commit rules and a reviewer pays for it. If you have a case where overriding matters, please say so.

[masterpiga]

Thanks a lot, @andriiryzhkov, LGTM. The only instruction that I override is how to build and run. I have my own branch-aware local scripts for that, but it's no biggie.

[andriiryzhkov]

The only instruction that I override is how to build and run.

We can add in build section to look to developer's instructions for building and running specific to his setup. Updated

[masterpiga]

@andriiryzhkov A couple of additions that I have in my AGENTS.md and that are not currently covered in this one (wording should be improved so that it is more aligned with the current style):

Spacing and sizing should be done in CSS whenever possible rather than hardcoded
in C. To simplify CSS styling, always assign meaningful IDs or widget names
(gtk_widget_set_name) to new panels and widgets.

And in the "Comments" section:

Describe the current state and why it is in a certain way; do not describe how
the code used to be before a fix. Comments can, on the other hand, warn about
pitfalls and traps to avoid.

Both are based on actual review comments from previous PRs.

Actually, it could make sense to collect a rubric of "do"s and "don't"s by asking an agent to go through a bunch of recent PRs and distill general principles from reviewer comments.

I am not requesting any change, I am just thinking out loud :)

Thanks a lot for your efforts to tidy up agentic work in the repo 👍

[victoryforce]

Right now I'm reading an article that concludes: "Codebase overviews are useless" in AGENTS.md. Also: "Less content, better results". I'll try to understand more and post a link to the research here soon.

[TurboGit]

Right now I'm reading an article that concludes: "Codebase overviews are useless" in AGENTS.md. Also: "Less content, better results". I'll try to understand more and post a link to the research here soon.

Ok, I'll wait for your feedback, I was about to merge :)

[victoryforce]

I'm definitely not an expert on this topic (quite the opposite, a newbie), but in trying to figure out how to instruct agents I came across several interesting articles and studies:

• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
• On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
• What Goes in AGENTS.md (and What Doesn't)
• How to Build Your AGENTS.md (2026): The Context File That Makes AI Coding Agents Actually Work

I'll quote a few important conclusions from what I read right here:

---

The findings challenged the assumption that more context is always better:

• Human-written files help modestly. Success improved by about 4% across all agents.
• Codebase overviews are useless. They didn’t help agents find relevant files faster. In many cases agents took more steps with overviews present.
• Curated, minimal AGENTS.md files with only three content categories (coding conventions, architecture, project description) reduced median wall-clock time by 28% and output tokens by 16%. Less content, better results.
• The study concludes that human-written files should describe only minimal requirements, custom-built commands, and specific tooling choices, while avoiding content that agents can already discover independently.
• Architectural overviews "do not provide effective overviews," per the study: removing an "Architecture" section while keeping only commands, constraints, and non-standard patterns produces the same agent behavior at a lower token budget.

[andriiryzhkov]

Reduced instructions size. It should look better now. I'd propose to move on and merge this. I am sure this is not the final version, but we need more testing and feedback. Especially with different AI platforms.