How to Write an AGENTS.md File in 2026 (Short, Hand-Written, Data-Backed)

An AGENTS.md file is a plain-Markdown "README for your coding agent" that lives at the root of your repo and tells tools like Claude Code, Codex, and Cursor how to build, test, and behave in your project. The best ones are short, specific, and hand-written: they list your exact commands, name your stack with versions, and draw hard lines around what the agent must never touch. The worst ones are long, vague, and auto-generated — and there's now measured evidence they make agents slower and less accurate.

We build TechRiseUps with Claude Code, and the single file that most changed how reliably it ships correct work was the agent-instructions file. This is the practical guide we wish we'd had: what to write, what to cut, and why less is more.

What is an AGENTS.md file?

AGENTS.md is an open, tool-agnostic format for guiding coding agents — "a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." Think of it as the counterpart to your human-facing README: build steps, test commands, and conventions that would clutter the README but that an agent genuinely needs.

The format was pioneered by OpenAI for Codex, and in December 2025 it was donated to the Agentic AI Foundation under the Linux Foundation, so it's no longer a single vendor's convention. It's now recognized by 60,000+ open-source projects and supported across 28+ tools including Codex, Cursor, Aider, Devin, Google Jules, and VS Code. Claude Code reads its own CLAUDE.md and increasingly honors AGENTS.md too; the content advice below applies to both. One file, many agents — that's the whole point.

What to put in an AGENTS.md file

GitHub analyzed more than 2,500 real agents.md files (published November 19, 2025) and found a clean divide between files that help and files that get ignored. The failing ones share one trait: they're too vague. "Helpful coding assistant" personas did nothing; exact commands and hard boundaries did the work.

Here's what earns its place — and what to leave out:

Include (earns its tokens)	Cut (wastes them)
Exact commands with flags: pnpm test, pytest -v	"Run the tests" with no command
Stack with versions: "React 18, TS 5, Vite, Tailwind"	"Modern web stack"
A real code snippet showing your style	Paragraphs describing your style
Three-tier boundaries: Always / Ask first / Never	A generic "be careful" line
Non-obvious gotchas (monorepo quirks, env setup)	A full directory tree the agent can read itself
"Never commit secrets" and protected paths	Restating language docs the model already knows

The most common genuinely useful constraint across the 2,500 repos was blunt: "Never commit secrets." That single line is the cheapest insurance you can write, and it ties directly into the wider supply-chain lessons from the npm Shai-Hulud crisis — agents with shell access can leak credentials just as fast as a compromised package.

Why a shorter AGENTS.md beats a longer one

This is the part most guides skip, and it's the most important. Every line in your AGENTS.md is injected into every agent session, so each line competes for the model's limited attention budget. Padding it out doesn't help the agent — it actively hurts.

A 2026 ETH Zurich study put numbers on it. Auto-generated, bloated context files reduced task success in 5 of 8 tested settings, made agents take 2.45 to 3.92 additional steps per task, and pushed inference costs up 20–23% — all while adding no measurable quality. Human-curated files, by contrast, outperformed LLM-generated ones for every agent tested, by roughly 4 percentage points on the AGENTbench benchmark. When researchers deleted redundant docs entirely, auto-generated files' performance actually improved, confirming they were mostly duplicating things the model already knew.

The practical rule from practitioners matches the data: keep it short. The general consensus is under 300 lines, and teams like HumanLayer keep theirs under 60. Write it yourself, deliberately, because "a bad line in AGENTS.md cascades into bad plans, bad code, and bad results across every session."

How to write your AGENTS.md, step by step

You can have a working file in ten minutes. Do it in this order:

1. Create AGENTS.md at the repo root. Start empty. Resist the urge to run a "generate my AGENTS.md" command — you now know the data says hand-written wins.
2. Write the commands first. The exact lines you'd type to install, run, test, and lint. Include flags. This is the highest-value section, so it goes at the top.
3. Name the stack with versions. One line: languages, framework, package manager, key libraries and their major versions. Ambiguity here causes the most wasted agent steps.
4. Add one real code snippet that demonstrates your conventions — an actual function or component from your repo, not a description of one.
5. Set three-tier boundaries. Always (e.g. "run the linter before finishing"), Ask first (e.g. "before changing the DB schema"), Never (e.g. "never commit secrets, never touch /vendor, never git push"). This is where you encode judgment the model can't infer.
6. Note the non-obvious only. Monorepo package layout, a required env var, a flaky test to ignore. Skip anything the agent can discover by reading the tree.
7. Test it, then trim. Run a real task, watch where the agent guesses wrong, add a line to fix that, and delete any line that never earned its keep.

One counterintuitive payoff: tools you name in AGENTS.md get used about 160× more often than tools you don't. If you want the agent to use your custom script or a specific MCP server, mention it explicitly — otherwise it effectively doesn't exist. If you're still choosing which agent to standardize on, our Cursor vs Copilot vs Windsurf vs Claude Code showdown covers how each one loads project context.

AGENTS.md, CLAUDE.md, and .cursorrules — do you need all three?

No. AGENTS.md is the emerging cross-tool standard, so make it your source of truth. Claude Code still looks for CLAUDE.md and Cursor historically used .cursorrules; the low-effort move is to keep the real content in AGENTS.md and, where a tool insists on its own filename, symlink or import it rather than maintaining two drifting copies. In a monorepo, you can also nest files: agents automatically read the nearest AGENTS.md in the directory tree, so a package can override the root — OpenAI's own repo ships 88 of them. Keep the root file general and let each package hold its specifics. Which agent you pair it with still matters; see our roundup of the best AI coding tools in 2026.

Common mistakes to avoid

• Auto-generating the whole file. The fastest way to a slower agent. Generate a skeleton at most, then rewrite by hand.
• Pasting your directory tree. Agents list files themselves; a static tree just rots and burns tokens.
• Restating the obvious. The model knows how Python works. Tell it what's specific to your repo.
• One giant file for everything. Use progressive disclosure: keep task-specific notes in separate docs (e.g. agent_docs/running-tests.md) and reference them, so the root file stays lean.
• Never revisiting it. The file drifts as your project changes. Trim it whenever the agent guesses wrong.

FAQ

Where does the AGENTS.md file go? At the root of your repository. For monorepos, add additional AGENTS.md files inside individual packages; the agent reads the closest one to the file it's working on, and that nearest file takes precedence.

How long should an AGENTS.md be? Short. The working consensus is under 300 lines, and many strong examples sit under 100. Because every line is loaded into every session, length has a real cost in both accuracy and tokens — write only what changes the agent's behavior.

Should I let an AI generate my AGENTS.md? Use one to draft a rough skeleton if you must, but don't ship it as-is. The ETH Zurich research found auto-generated files reduced task success in most settings and raised costs 20–23%. Human-curated files beat generated ones across the board — the file is worth writing by hand.

Does Claude Code use AGENTS.md? Claude Code natively reads CLAUDE.md and increasingly recognizes AGENTS.md. The content principles are identical either way: exact commands, versioned stack, hard boundaries, and brevity. If you already keep a good CLAUDE.md, you're 90% of the way to a good AGENTS.md.

What's the one thing every AGENTS.md should have? A "Never" boundary that includes "never commit secrets." It was the single most common useful constraint across 2,500+ real repos, and it's the cheapest line to protect a codebase that an agent can now edit and run.

Sources

• agents.md — the open format and spec: definition, supported tools, monorepo nesting, and Agentic AI Foundation / Linux Foundation stewardship.
• GitHub Blog — How to write a great agents.md: lessons from over 2,500 repositories: the data-backed sections that work and the "too vague" failure mode (Nov 19, 2025).
• Philipp Schmid — Writing a Good AGENTS.md: the "keep it under 300 lines" consensus and the 160× tool-mention finding.
• Augment Code — How to Build Your AGENTS.md: summary of the ETH Zurich study showing auto-generated files reduce task success and raise cost.