agents-md: one AGENTS.md that changes how coding agents behave

A prompt file, not a plugin, and that is the whole design

The repository contains three files: AGENTS.md, LICENSE and README.md. There is no binary, no package to install and no configuration schema. The project calls itself a drop-in AGENTS.md and states that one file makes every coding agent behave like a senior engineer instead of an eager intern, with no plugins, no config and no setup rituals.

That framing explains both the appeal and the ceiling. Because the artefact is plain Markdown placed at a project root, every tool that reads such a file picks it up with no integration work. The README lists Codex, Cursor, Aider, Windsurf, Copilot, Devin, Amp, opencode and RooCode as readers of AGENTS.md, and explains that Claude Code reads CLAUDE.md while Gemini CLI reads GEMINI.md. The proposed fix is to symlink the other two names to the same file so a single source governs all of them.

What you are actually adopting is a behavioural contract written in prose. The README's before-and-after table gives the intent: an agent that says you are absolutely right and then reverts working code should instead push back, 200 lines of change where 50 would do should become the simplest diff that solves the problem, and a claim that the work is done on code that does not run should become writing the verification first, running it, and then reporting.

None of that is enforced by anything. It works to the extent the model follows the instructions, which is a different guarantee from a linter or a CI check.

Eleven numbered sections, and the ten you do not touch

The file is organised as numbered sections, and the README explains the split clearly. Sections 0 through 9 are described as the behavioural scaffold, and the guidance is not to touch them unless there is a specific reason. The two sections meant for editing are section 10, Project context, and section 11, Project Learnings.

Section 10 is the part you fill in once. The install instructions tell the agent to gather the stack, the build, test and lint commands from package.json, pyproject.toml, Cargo.toml or Makefile, and the source and test directory layout, and to record only what it can verify by reading the codebase. Anything that cannot be confirmed is left as a TODO. Forbidden areas belong here too. The README estimates the effort at five minutes.

Section 11 starts empty on purpose. The stated mechanism is that the agent appends one line each time it gets something wrong, so you do not have to babysit the file. The README frames this as the compounding part, and cites Boris Cherny, the creator of Claude Code, as running a team version with roughly 100 learnings accumulated over months, describing such a file as a trained reflex rather than a manifesto.

Size is treated as a design constraint rather than an accident. The before-and-after table notes that a file that is too long causes agents to ignore half the rules, and the file is described as tight by design at around 200 lines so that the rules stay loaded.

Installing with curl, and the symlinks that make it portable

The manual install is a single fetch of the raw file from the default branch:

curl -o AGENTS.md https://raw.githubusercontent.com/FerroxLabs/agents-md/main/AGENTS.md

That gives you AGENTS.md in the current directory. Every agent that reads the standard finds it on its own, which the README describes as the only step required. The remaining work is the two names that do not follow the standard.

On macOS and Linux, the symlinks are:

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

The README covers the failure modes rather than assuming the happy path. If symlinks are not available, copy the file instead, with the stated cost that you then have to re-copy whenever AGENTS.md changes. If CLAUDE.md or GEMINI.md already contain content, the instruction is not to overwrite them but to prepend @AGENTS.md as the first line and leave the rest intact, so existing project instructions survive.

There is also an agent-driven path. The README suggests opening Claude Code, Codex, Cursor or any coding agent in the project root and pasting an install prompt, which asks the agent to fetch the raw URL, save it as ./AGENTS.md, stop and show a diff if a file already exists, create the symlinks with the right command for the operating system, fill in section 10 with only what it can verify, leave section 11 empty, and then tell you to restart the session so the file loads.

That prompt encodes the safety rules the manual path leaves to you, and the restart step is not a formality. A file copied in after a session starts is not picked up by a running agent.

Why AGENTS.md rather than CLAUDE.md

The choice of filename is the substance of the project, and the README argues it directly. AGENTS.md is described as an open cross-tool standard stewarded by the Linux Foundation's Agentic AI Foundation, and the list of tools that read it natively is long. Claude Code reads CLAUDE.md and Gemini CLI reads GEMINI.md, so a team running all three would otherwise maintain three files describing the same rules, and those files drift.

The stated benefit is one source of truth, and the practical one is a single edit instead of three. If you change the review rules, you change AGENTS.md and the symlinks propagate it.

There is a caveat the README does not dwell on. The standard is read natively by some tools and by convention in others, and a symlink is a filesystem-level trick that only works where the agent opens the file through a path that resolves it. On Windows, the symlink step needs PowerShell with administrator rights or Developer Mode enabled, and the copy fallback is a manual re-copy each time the file changes. The portability story is good on Unix-like systems and workable with friction on Windows.

The other thing to weigh is what the project is derived from. The README credits Sean Donahoe's IJFW principles, Andrej Karpathy's four principles on LLM coding failure modes, Boris Cherny's public Claude Code workflow, Anthropic's official Claude Code best practices, and the AGENTS.md standard itself. If your house style already comes from those sources, this file is a distillation of them rather than a new idea.

Sharding for large codebases, and the tooling that already exists

The README treats sharding as the exception, saying it is rare but happens on large codebases, and advises reading the docs before splitting because most projects do not need it. The patterns it names are tool-specific.

For Claude Code, the options are @path/to/file.md imports inside CLAUDE.md, or topic-scoped rules dropped into .claude/rules/*.md with paths: frontmatter so that they load only when Claude touches matching files. The README also notes that Claude Code writes its own memory automatically, with the advice not to reinvent it, which matters because section 11 of this file is a hand-rolled version of the same idea.

For Cursor, the equivalent is .cursor/rules/*.mdc with path scoping. For every other tool listed, the answer given is that one AGENTS.md is still the right answer, so the sharding mechanisms are not portable across the ecosystem. A team that runs both Claude Code and Cursor can scope rules for each, but a single rule set that both honour at the same granularity is not on offer.

The stated goal is fewer tokens loaded per session, not more files for their own sake. That is the right framing, and it also caps how far the sharding advice goes: it addresses token budget, not conflicting instructions, and it leaves the risk of two rule sets drifting apart on the same file unaddressed.

Where this approach stops working

The first limitation is that nothing is enforced. A prompt file cannot fail a build, block a pull request or stop an agent from ignoring a section. Teams that need review rules to be non-negotiable need them expressed as tooling, and the README never claims otherwise.

The second is the maintenance loop. Section 11 only works if someone lets the agent append to it, and in a repository with strict review rules, a model editing a tracked file to record its own mistakes is a proposal to accept or reject on every change. The README's picture of a file with around 100 accumulated learnings over months assumes a team that has decided this is worth the diff churn.

The third is the drift risk of the install prompt. It instructs the agent to fill section 10 from package.json, pyproject.toml, Cargo.toml or Makefile, but those files change, and nothing in the workflow re-reads them. A stale build command in section 10 is a stale instruction that agents will keep following, and there is no marker in the file that says when it was last reconciled.

The fourth is project fit. Rules about diff minimality and verification loops are generic engineering advice, which is exactly why the file is useful. A repository with unusual constraints, a legacy language toolchain, or a monorepo where the correct scope of a change is subtle will find generic rules insufficient, and the README's own answer to that is to add topic-scoped files rather than to extend section 10 indefinitely.

Editorial conclusion

agents-md is worth an afternoon for a team that runs several coding agents across shared repositories, because it gives Claude Code, Codex, Cursor, Gemini CLI and the rest one instruction source instead of three diverging ones, and it is MIT licensed so you can fork it freely. It is the wrong tool if you need enforced rules, since a prompt file can be ignored and cannot gate a merge, and it is wasted effort if only one agent ever touches the code. Before adopting it, drop the file in one repository, fill section 10 with the build and test commands you can actually verify, run a task that tempts the agent into a wide refactor, and check whether section 11 starts accumulating corrections on its own, because the last push was on 2026-05-31 and the only release so far is v0.1.0 from 2026-04-19.

Frequently asked questions

Official sources

1. FerroxLabs/agents-md on GitHub
2. Issues
3. License: MIT
4. README
5. Releases