The goal is to improve the output of every contributor's coding agent by having it follow the contribution guidelines, commit rules and AI policy. Agents load an AGENTS.md file from the repository root before they start working. This adds one that tells them to read CONTRIBUTING.md and doc/AI_POLICY.md.
The PR template mentions the AI policy, but an agent opening a PR through gh pr create or the API skips the template, as pointed out in #35386. Reviewers keep flagging the same guideline breaks on LLM-written PRs:
- agent co-author trailers (#36465, #36105, #36106, #34892), two of them merged after #35794 (01e3eca2d8, aa01721c89)
- agents driving the PR and replying to review comments (#36085, #34829)
- CONTRIBUTING.md items such as squashing (#35370, #36350), commit splitting (#34873),
@mentions in the description (#36740) and long descriptions that end up in the git log (#36224, #36342)
I measured the effect with Claude Code (Opus 5.5) on 12 past issues, each checked out at the parent of the merge that fixed it, with 5 runs per issue without the file and 5 with it. Compared with no file:
- no agent co-author trailer: 60/60 runs, against 0/60
- no AI footer in the PR description: 54/60, against 4/60
- the final reply tells the user to own and be able to explain the change: 60/60, against 0/60
- PR title prefix from CONTRIBUTING.md's list: 48/60, against 39/60
Agents acting as "maintainers" scored the outputs without knowing which setup produced them, and rated the runs with the file higher on all 12 issues. The fixes themselves did not change (35/60 worked either way), and most commit subjects stayed over 50 characters (14/60 within the limit, against 4/60). The harness and data are at https://github.com/erickcestari/bitcoin-agents-md-eval.
The AGENTS.md links to the existing docs, so it doesn't need updating when the policy changes. Anyone with their own agent instructions can keep them in CLAUDE.local.md or ~/.claude/CLAUDE.md, which Claude Code loads together with the project file.
Note: DrahtBot will probably close this automatically because of its heuristics. I still think this is an important discussion to have, since any improvement in what agents produce helps both maintainers and contributors.