doc: add AGENTS.md pointing coding agents to CONTRIBUTING.md and AI_POLICY.md #36881

pull erickcestari wants to merge 1 commits into bitcoin:master from erickcestari:doc-agents-md changing 2 files +7 −0
  1. erickcestari commented at 2:05 PM on November 15, 2026: none

    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:

    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.

  2. doc: add AGENTS.md and CLAUDE.md
    AI coding agents do not see the pull request template, so CONTRIBUTING.md
    and doc/AI_POLICY.md do not reach them. Point agents at both.
    
    CLAUDE.md only imports AGENTS.md, since Claude Code skips AGENTS.md when a
    CLAUDE.md exists.
    
    Co-authored-by: Vinicius Cestari <viniciuscestari01@gmail.com>
    8d390174f6
  3. DrahtBot added the label Docs on Nov 15, 2026
  4. DrahtBot commented at 2:05 PM on November 15, 2026: contributor

    ♻️ Automatically closing for now based on heuristics. Please leave a comment, if this was erroneous. Generally, please focus on creating high-quality, original content that demonstrates a clear understanding of the project's requirements and goals.

    📝 Moderators: If this is spam, please replace the title with ., so that the thread does not appear in search results.

  5. DrahtBot closed this on Nov 15, 2026

  6. DrahtBot commented at 2:06 PM on November 15, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    <!--006a51241073e994b41acfe9ec718e94-->

    External sites

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline and AI policy for information on the review process. A summary of reviews will appear here.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-16 00:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me