Write it down for the machine

The most useful thing you can do to make AI coding agents work better isn't a better prompt or a better model. It's a plain text file at the root of your repo called AGENTS.md, and most people building with agents still haven't written one.

Here's why it matters now. A year ago every tool had its own special file — .cursorrules, CLAUDE.md, a Copilot config, whatever Devin wanted. You wrote your project's conventions five times or not at all. That's over. As of early 2026, AGENTS.md is read natively by Claude Code, OpenAI's Codex CLI, Cursor, Aider, Devin, GitHub Copilot, Gemini CLI, Windsurf, and Amazon Q — the closest thing the industry has to a universal instruction format for coding agents. One file, and almost every agent that opens your repo reads it first.

Let me make the case for actually writing it, because the leverage is lopsided.

What it is, plainly

AGENTS.md is a Markdown file you put at the root of your project. It's the note you'd leave a competent new contractor who's never seen your codebase: how to build it, how to run the tests, what the conventions are, what not to touch. The agent reads it before it starts work and treats it as standing instructions — so you write the context once, instead of re-typing it into every prompt for the rest of the project.

That's the whole trick. It's not a new framework or a clever prompt. It's writing down the things you already know about your project so the machine knows them too.

Why it works so well

Agents don't fail because they're dumb. They fail because they're working blind — they can't see the unwritten rules every human on your team absorbed by osmosis. The agent doesn't know you always run pnpm, never npm. It doesn't know the one module nobody touches without a review. It doesn't know your tests have to pass a coverage gate before anything ships. So it guesses, and a third of the guesses are wrong.

A good AGENTS.md removes the guessing. It's the same idea behind why a spec beats a prompt: the durable, reusable artifact is the written context, not the throwaway instruction. And it compounds — every agent run, across every tool, on every branch, starts from the same shared understanding instead of from zero.

What actually goes in it

Keep it short and concrete. The ones that work read like a checklist, not an essay:

• How to build and run. The exact commands — install, dev server, build. Spell out pnpm vs npm, the right Node version, any setup step that isn't obvious.
• How to test. The test command, the coverage bar, "every gate green before you commit." Agents are far more useful when they can run the tests and see the real failure themselves.
• Conventions that matter. Naming, the lint/format rules, "match the surrounding code." The stuff a reviewer would otherwise send back.
• What not to touch. Generated files, the one fragile module, secrets, anything where "helpfully refactored it" is a disaster.
• Project shape. A one-line map of where things live, so the agent doesn't have to reverse-engineer your structure on every task.

Skip the philosophy. The agent doesn't need your mission statement; it needs the commands, the constraints, and the landmines.

The bottom line

We spend a lot of energy on prompts, which are per-task and disappear, and almost none on the one artifact that's per-project and persists. AGENTS.md flipped from a per-tool gimmick into a near-universal standard precisely because the problem it solves is the real one: agents work blind, and the fix is to stop making them guess at what you already know.

So before the next time you point an agent at your repo, spend the hour. Write down how to build it, how to test it, what the rules are, and what to leave alone. It's the rare piece of AI advice that costs almost nothing, works across every tool you'll use, and pays back on every single run. Write it down for the machine — it's reading.