One file. Every coding agent starts behaving like a senior engineer.
Drop it into any repo. Claude Code, Codex, Cursor, Gemini CLI, Aider, Windsurf, Copilot, and Devin all read it on their own. No plugins. No config. No setup rituals.
It just works.
This is the tool and the core operating discipline we run on every project at Ferrox Labs. One file, every agent, every repo.
Open Claude Code, Codex, Cursor, or any coding agent in your project root. Paste this:
Install https://github.com/FerroxLabs/agents-md into this project.
- Fetch
https://raw.githubusercontent.com/FerroxLabs/agents-md/main/AGENTS.mdand save it as./AGENTS.mdat the project root. IfAGENTS.mdalready exists, stop and show me the diff before overwriting.- Symlink
CLAUDE.mdandGEMINI.mdtoAGENTS.mdso Claude Code and Gemini CLI read the same file. Use the right command for my OS (ln -son macOS/Linux,New-Item -ItemType SymbolicLinkon Windows). If symlinks fail, fall back to copying the file. IfCLAUDE.mdorGEMINI.mdalready exist with content, do not overwrite — prepend@AGENTS.mdas the first line and leave the rest intact.- Open the new
AGENTS.md, find section 10 (Project context), and fill in only what you can verify by reading this codebase: stack, build/test/lint commands frompackage.json,pyproject.toml,Cargo.toml, orMakefile, and source/test directory layout. Leave anything you can't confirm asTODO.- Do not touch section 11 — it stays empty by design.
- When done, tell me to restart this session so the file loads.
Restart the session. You're done.
curl -o AGENTS.md https://raw.githubusercontent.com/FerroxLabs/agents-md/main/AGENTS.mdCodex, Cursor, Aider, Windsurf, Copilot, Devin, Amp, opencode, and RooCode read AGENTS.md on their own. Nothing else to do.
Claude Code and Gemini CLI look for their own filenames, so symlink:
macOS / Linux
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.mdWindows (PowerShell, run as admin or with Developer Mode on)
New-Item -ItemType SymbolicLink -Path CLAUDE.md -Target AGENTS.md
New-Item -ItemType SymbolicLink -Path GEMINI.md -Target AGENTS.mdIf symlinks aren't available, copy the file instead — you'll just need to re-copy when you update AGENTS.md:
Copy-Item AGENTS.md CLAUDE.md; Copy-Item AGENTS.md GEMINI.mdOpen a session. You're done.
| Before | After |
|---|---|
| "You're absolutely right!" → reverts working code | Agent pushes back when you're wrong |
| 200 lines when 50 would do | Simplest diff that solves the problem |
| Reformats your whole file while fixing a typo | Every changed line traces to your request |
| Claims "done" on code that doesn't run | Writes verification first, runs it, then reports |
| Silently guesses between two interpretations | Surfaces the ambiguity, asks once |
| Ignores half your rules because the file is too long | Tight by design. ~200 lines. Rules stay loaded. |
Section 10 — Project context. Stack, commands, layout, forbidden areas. Fill the TODOs once. Five minutes.
Section 11 — Project Learnings. Starts empty. Every time the agent gets something wrong, one line gets added. The agent itself adds the line when you correct it — you don't babysit the file.
This is the section that compounds. Boris Cherny, the creator of Claude Code, runs his team's version at around 100 learnings accumulated over months. His file is a trained reflex, not a manifesto.
Sections 0–9 are the behavioral scaffold. Don't touch them unless you have a specific reason.
Rare. But it happens on large codebases. Read the docs before you shard — most people don't need to:
- Claude Code: use
@path/to/file.mdimports insideCLAUDE.md, or drop topic-scoped rules into.claude/rules/*.mdwithpaths:frontmatter so they only load when Claude touches matching files. Claude Code also writes its own memory automatically — don't reinvent it. - Cursor: use
.cursor/rules/*.mdcwith path scoping for the same reason. - Everyone else: one
AGENTS.mdis still the right answer.
The goal is fewer tokens loaded per session, not more files for their own sake.
AGENTS.md is the open cross-tool standard stewarded by the Linux Foundation's Agentic AI Foundation. Codex, Cursor, Windsurf, Copilot, Aider, Devin, Amp, opencode, and RooCode read it natively. Claude Code reads CLAUDE.md. Gemini CLI reads GEMINI.md. Symlink all three and every agent reads the same file.
One source of truth. Stop maintaining three.
- Sean Donahoe's IJFW principles — it just f*cking works: one install, zero ceremony, working code
- Andrej Karpathy's four principles on LLM coding failure modes
- Boris Cherny's public Claude Code workflow — reactive pruning, keep it tight
- Anthropic's official Claude Code best practices
- The AGENTS.md open standard
MIT. Fork it, rewrite it, ship it with your own name on it. That's the point.
If it saved you an hour, a ⭐ on the repo is how you say thanks.