Here's the edited version:
You merge a pull request, run your test suite, and watch it fail because the AI agent that submitted it invented a function signature that doesn't exist in your codebase. Sound familiar? As AI coding agents flood open-source repos with patches, maintainers are discovering that these tools don't know your conventions unless someone writes them down somewhere the agent will actually look.
That somewhere is increasingly a file called AGENTS.md, sitting quietly in the repo root. Even the Linux kernel, which has been fielding a steady stream of AI-generated patches, doesn't have one yet — though a patch set submitted recently would finally add it (Phoronix, https://www.phoronix.com/news/Linux-Considers-AGENTS-MD). You don't need to wait for kernel politics to sort themselves out. You can write one for your project this afternoon.
What Is AGENTS.md and Which Tools Actually Read It
AGENTS.md is a plain Markdown file that lives at the root of a repository and documents how an AI coding agent should behave in that codebase: build commands, test commands, style conventions, and PR expectations. It's not a kernel-specific idea. The convention emerged across several coding-agent ecosystems that needed a predictable place for machine-readable contribution rules — distinct from CONTRIBUTING.md, which targets humans and often contains prose that agents parse poorly.
Support varies by tool and changes frequently, so verify any specific claim about a given agent's parsing behavior yourself rather than take it on faith. Some agents look for AGENTS.md by name at the repo root. Others check tool-specific variants like a .github/copilot-instructions.md file or a CLAUDE.md.
The safest approach for a small project: write one AGENTS.md with clear, short, imperative sentences, then symlink or duplicate the content into whatever tool-specific filename your contributors' agents expect. Markdown headers and fenced code blocks matter here — agents parse structure, not just prose, so a wall of unstructured text works far less reliably than clearly labeled sections.
Step-by-Step: Building Your AGENTS.md
1. Audit what's actually going wrong
Before writing anything, pull up the last five to ten AI-submitted PRs your project received. Note the specific failures: wrong test runner invoked, missing changelog entries, commits that break your message format, or code that ignores an existing utility function and reinvents it.
Your AGENTS.md should target these exact failure modes, not generic advice. A file full of vague best practices won't fix a pattern of agents skipping your linter.
2. Decide where the file lives
Put AGENTS.md in the repository root, next to README.md and LICENSE. Agents scanning a repo for instructions typically check the top level first — the same place they'd look for a README. For more on this, see read about audit ubuntu cloud images for missing packages.
If your project is a monorepo with sub-packages that need different rules, add nested AGENTS.md files inside each subdirectory. The closest one to the edited file generally takes precedence for tools that support nesting, but confirm this in your specific agent's documentation rather than assuming it.
3. Draft the build and test section first
Agents fail most often on mechanical details: how to build the project, which command runs tests, and what a passing result looks like. Write these as exact shell commands the agent can copy and run, not descriptions.
If your project ships a Makefile, a shell script, or a Dockerfile for reproducible builds, name it explicitly. This section carries the most leverage in the whole file because it prevents PRs that were never even test-run locally.
4. Add style and structural rules
List your indentation style, naming conventions, commit message format, and any linters or formatters you run in CI — along with the exact command to invoke them (shellcheck, clang-format, black, whatever applies). If you require a specific commit message prefix, like conventional commits or a Signed-off-by line for kernel-style Developer Certificate of Origin workflows, state it here in one line rather than burying it in a separate doc.
5. Write the PR checklist
End the file with a short checklist the agent should satisfy before opening a pull request: tests pass locally, documentation updated if behavior changed, no unrelated files touched, commit message follows the format above. Agents respond well to checklists because they map cleanly onto their own internal task-completion loops.
6. Commit the template
Here's a minimal template you can copy into your repo root and adapt. Replace every bracketed placeholder with your project's real commands.
## AGENTS.md
## Project overview
This is a [language/framework] project for [one-sentence purpose].
## Build
Run `[your build command]` from the repo root. Expected result: [what success looks like].
## Test
Run `[your test command]` before opening a PR. All tests must pass. Do not open a PR with skipped or failing tests without explaining why in the description.
## Style
- Formatter: run `[formatter command]` before committing.
- Linter: run `[linter command]`; fix all warnings, not just errors.
- Commit messages: use `[format, e.g. type(scope): summary]`.
- Do not reformat unrelated code in the same commit.
## Pull request checklist
- [ ] Tests pass locally with `[test command]`
- [ ] Linter/formatter run with no new warnings
- [ ] Only files relevant to the change are modified
- [ ] Commit message follows the required format
- [ ] Docs updated if public behavior changed
## Do not
- Do not add new dependencies without opening an issue first.
- Do not touch files under `[protected path, e.g. /vendor or /generated]`.
Commit it with standard git commands:
Also read: our guide to slack code channels vs terminal agents: a decision guide
git add AGENTS.md
git commit -m "docs: add AGENTS.md with contribution rules for AI agents"
git push origin main
Verifying an Agent Is Actually Following the File
Adding the file is the easy part. Confirming it changes behavior takes a few review cycles. Run this checklist on the next several AI-submitted PRs after you commit AGENTS.md:
- Check whether the PR description or commit message references the build or test command you specified. That reference suggests the agent actually ran it rather than skipping straight to a diff.
- Compare the commit message format against your stated convention. A mismatch is the fastest signal that the agent — or the human running it — never loaded the file.
- Look for unrelated file changes, like reformatted files outside the diff's stated scope. Since AGENTS.md explicitly forbids this, violations are easy to flag in review comments.
- If a PR fails your checklist items, close it with a comment pointing to the specific line in AGENTS.md it violated. This creates a paper trail and, for agents with memory across sessions on the same repo, sometimes improves the next submission.
- Track this informally for your first ten AI PRs after adding the file. If the pattern of failures doesn't shift, the tool submitting those PRs likely isn't reading AGENTS.md at all — you may need a tool-specific filename instead of, or in addition to, the standard one.
If the convention isn't helping, or the maintenance overhead of keeping it updated outweighs the benefit, back it out cleanly:
git rm AGENTS.md
git commit -m "docs: remove AGENTS.md"
git push origin main
Or, to revert to a specific prior version instead of deleting the file outright:
git log --oneline -- AGENTS.md
git checkout <commit-hash> -- AGENTS.md
git commit -m "docs: restore previous AGENTS.md version"
Treat this as an iterative document, not a one-time task. Once you have a few AI PRs to compare against your rules, you'll likely tighten the build section, add a new "do not" line for a failure mode you hadn't anticipated, or split the file if your project grows sub-packages with different toolchains. Watch how the kernel's own AGENTS.md patch set evolves too — whatever conventions the largest and most heavily AI-patched open-source project settles on will shape what agent tooling expects by default over the next few release cycles.
