AGENTS.md Is Programming for Your AI Agent, Not Documentation for Humans

Build Loops — Wed, 05 Aug 2026 13:15:07 +0000

If you use a coding agent for any real length of time, you hit the same wall: the agent keeps making mistakes you already corrected. Wrong package manager. Banned patterns. Edits to files that shouldn't be touched. You fix it, it happens again, you fix it, and eventually you're supervising the tool more than it's saving you time.

The standard advice is "write better prompts" — which treats a memory problem as a wording problem. The actual fix is architectural: give the agent a permanent, project-level context file it reads at the start of every session. It's called AGENTS.md, and it's the closest thing your agent has to a memory.

But here's the catch: most people create one and see no change, because they filled it with prose. They wrote a document, and the agent ignored it — because a document isn't what it's supposed to be. Prose is ambiguous, and it gives the agent nothing it doesn't already assume about a generic project. AGENTS.md is programming for an AI agent, not documentation for humans. This article explains why that distinction is everything — and what the file looks like when you write it as code.

Why your agent forgets everything

Coding agents are stateless. Between sessions, they retain nothing. Every conversation starts from scratch: a blank context, plus a set of guesses derived from code the agent saw in training — which is other people's code, not yours.

That's the entire reason you repeat yourself. It's not that the model is bad, and it's not that you're bad at prompting. The agent genuinely does not know that your project uses pnpm, that your tests need a running database, or that dist/ is generated and must never be edited. It has to guess, it guesses wrong, you correct it, and the correction evaporates the moment the session ends.

Anthropic's numbers confirm how wide this gap is: engineers use AI in roughly 60% of their work but fully delegate only 0–20% of tasks. The missing piece isn't model capability — it's setup. A well-configured agent can run autonomously; a stateless one requires constant babysitting.

The file fixes this because of a mechanism that almost no guide explains: the agent re-reads it at the start of every session. Instructions you type in a chat get buried under newer tokens and drift out of attention — that's context drift, and it happens in every long conversation. Instructions in a file don't decay, because they're re-read, not remembered. The agent doesn't recall your rules from a previous session; it loads them fresh, every single time.

Think of it as onboarding documentation for an AI employee. A README tells humans what the project is. AGENTS.md tells the agent how to work here: the exact commands, the conventions, the "don't touch" zones, and the traps that have already hurt someone.

AGENTS.md is code, not prose

Here's the mental shift that changes everything. Documentation describes a system. Code causes behavior. When you write AGENTS.md like a README — descriptive, warm, comprehensive — you're writing prose the agent reads and mostly ignores, because prose is ambiguous and the agent already has a default behavior baked in.

When you write it like code, every line has a job. A line that doesn't change an edit, doesn't earn its place. The rules for writing it well are the same rules you'd apply to good code:

Token cost is real. Every word in this file is loaded into context at the start of every single session, for every single task. A 500-word backstory about your team's engineering philosophy displaces 500 words of actual task context. And context bloat isn't free — Chroma's 2025 study found that all 18 frontier models tested degrade in accuracy as input grows, some dropping from 95% to 60% past a threshold. A bloated file isn't neutral; it's actively making the agent worse. Keep it under ~200 lines. If removing a line wouldn't change the agent's output, delete it.

Specificity beats aspiration. "Write clean, maintainable code" does nothing — the agent already tries to do that. Only include rules that are specific to your project and that the agent couldn't figure out from reading the code. "Use pnpm, not npm" changes behavior. "Follow best practices" doesn't.

Every "never" needs an "instead." Pure prohibitions create dead ends. "Never use any" leaves the agent guessing what to do. "Never use any — use unknown and narrow it with type guards" gives it an escape route. The same rule in miniature: "Use pnpm" is a fact the agent will forget; "Never use npm — install and run everything with pnpm" changes a behavior and names the alternative in one line.

Structure aids parsing. Headers, bullets, and exact commands are easier to prioritize than paragraphs. The same content, organized, is ten times more useful.

One more thing worth being honest about: this is leverage, not magic. As Martin Fowler puts it, context engineering raises the probability of useful results — it can never guarantee them. No matter how good your file is, an LLM is still an LLM. When a rule absolutely must hold, don't write it in Markdown; enforce it deterministically with a hook. Treat the file as your agent's guidance, and hooks as its guardrails.

The drop-in template

Here's the skeleton. It deliberately mixes two kinds of content. The lean core — sections 1, 5, 6, 7, 9 — is the part that changes edits: exact commands, conventions, guardrails. The workflow contract — sections 2, 3, 4, and the "when in doubt" checklist in section 8 — tells the agent how to operate: plan before code, an approval gate, a skills whitelist. That's not filler; it programs how the agent works with you. It reflects one popular workflow — supervised "vibe engineering," where the agent writes its own implementation prompts and you approve them. Run that workflow and it pays off; work more autonomously or manually and drop it — the lean core works everywhere. Either way, this is a template, not a finished file: anything that isn't true for your project gets deleted, not kept.

# AGENTS.md

You are a principal-level <role> engineer and AI implementation agent working on <PROJECT>, <one-line description>.

Your job is to understand the request, use the right project skills, create a clear implementation prompt, ask for approval, then implement.

---

# 1. Product

<PROJECT> <what it does>.

Build only:

- <feature>
- <feature>

Do not overbuild.

---

<!-- Optional: workflow contract. Sections 2–4 (and the "when in doubt" checklist in section 8) only pay off when you run a supervised, agent-driven workflow (plan, approve, implement). Lean-core-only users can delete them. -->

# 2. Workflow

For every implementation request:

1. Read `AGENTS.md`.
2. Read the skills explicitly mentioned by the user.
3. Read clearly needed supporting skills from the approved skill list.
4. Inspect relevant code.
5. Ask a focused question only if the task has meaningful ambiguity.
6. Create a detailed prompt file in `prompts/`.
7. Ask: "I prepared the implementation prompt at `prompts/<file-name>.md`. Is this good to execute?"
8. Implement only after user approval.
9. Run available checks.
10. Share exact steps to test or run the completed feature.

Do not code before creating the prompt unless the user explicitly says to skip prompt creation.

---

# 3. Skills

Use only these skills:

- `.agents/skills/<skill>`

Do not invent new skills.

---

# 4. Prompt files

Prompt files live in the `prompts/` directory.

Each prompt must include:

- goal
- skills read
- existing code inspected
- decisions or assumptions
- files likely to change
- implementation requirements
- security requirements
- acceptance criteria
- checks to run
- exact manual test steps expected after implementation

<!-- End of the optional workflow contract. Everything from here is lean core — keep it even without the workflow sections. -->

---

# 5. Architecture

Keep these layers separate:

- <layer>: <responsibility>
- <layer>: <responsibility>

<Boundary rule, e.g. "UI must display stored data only.">

---

# 6. Tech stack

Use:

- <stack>

Do not use:

- <stack>

---

# 7. Source of truth

<Name the authoritative source the agent should rely on — a database, a spec document, a config file, an API. It's whatever your project treats as ground truth.>

<What each record or entity stores, required fields, what must never be hardcoded or assumed.>

---

# 8. Security, code standards, and final rule

Never expose to browser code: <secrets>.
Never run from browser code: <side-effectful work>.

<Language / style rules: explicit types, no `any`, small functions.>

When in doubt:

1. Keep it small.
2. Use the relevant skill.
3. Preserve server/client boundaries.
4. Ask a focused question if needed.
5. Save a prompt before coding.
6. Ask if it is good to execute.
7. Implement after confirmation.
8. Run available checks.
9. Share exact test steps.

---

# 9. Commands and checks

"Run available checks" (sections 2 and 8) means running these from the project root and reporting the results:

- `<command>` — <what it does>
- `<command>` — <what it does>

Development and runtime:

- `<command>` — start the dev server
- `<command>` — run tests

After implementation, run the checks and report the exact output. Never claim a check passed without running it.

Now the part people skip: why each section exists. Start with the lean core — the four sections that change edits:

Product / "Build only" — the agent works best when it knows exactly who it's supposed to be and what it's allowed to build. "Do not overbuild" is the anti-hallucination guardrail: it stops the agent from expanding a small request into a rewrite of the codebase.
Architecture + tech stack — the "Do not use" list matters as much as the "Use" list. It stops the agent from reaching for the dependency you deliberately avoided.
Source of truth — one authoritative place for the facts the agent relies on, whatever it is: a database, a spec, a config file. It turns a vague feature request into concrete decisions instead of guesswork.
Commands and checks — the highest-ROI section. Exact invocations, including the flag the agent would otherwise guess wrong. And "do not claim a check passed without running it" is the evidence rule: the agent must report real output, not assume success.

Then the workflow contract — only when you run a supervised, agent-driven workflow:

Workflow — this is what turns the file from documentation into programming. The numbered steps and the approval gate are the most important piece: the agent plans, you approve, it executes. That isn't documentation; it's a control loop.
Skills + prompt files — a whitelist ("Do not invent new skills") plus a mandatory plan-before-code step with a defined list of required sections. That's what makes the approval gate real: the agent can't show you a one-line plan.
Security + final rule — the fallback checklist for situations your rules didn't cover. It tells the agent how to behave when it doesn't know what to do — which is exactly when improvisation goes wrong.

The Airflow project shows how far this can go in the real world. Its AGENTS.md instructs: "Never run pytest, python, or airflow commands directly on the host — always use breeze." One line, and the agent stops polluting the developer's machine with a wrong-versioned Python environment. That's a guardrail that saves real pain, and it only works because it names the alternative, not just the prohibition.

If you use Claude Code specifically, one practical note: Claude Code reads CLAUDE.md natively, not AGENTS.md. Bridge them with a one-line import:

# CLAUDE.md
@AGENTS.md

The @AGENTS.md import expands at session start, so you keep a single source of truth and add Claude-specific rules below it.

What changed for me

Before I started using AGENTS.md, every project began the same way: initialize the repo, then type out a long prompt covering everything I wanted built, the conventions, the things not to touch. It worked — for that one session. The next day I'd open a new session and all of it was gone. I'd repeat myself, re-correct a mistake it had already made, and watch it make a similar one anyway. It got frustrating fast.

The turning point was writing a well-structured AGENTS.md before anything else. The agent stopped repeating those mistakes — not because I prompted better, but because it could re-read my instructions every session instead of trying to remember them. Work was easier, and there was a side effect I hadn't expected: I was burning fewer tokens. Re-explaining everything session after session is the biggest token waste there is, and when you're paying for a plan, that waste costs real money. A good AGENTS.md is cheap insurance against it.

Real-world proof that this scales

A single file might feel like a small thing. The adoption numbers say otherwise.

AGENTS.md is now an open standard, released by OpenAI in August 2025 and donated — jointly with Anthropic — to the Linux Foundation's Agentic AI Foundation in December 2025. It's used in more than 60,000 open-source repositories and read natively by every major agent: Codex, Cursor, Copilot, Claude Code (via import), Google's Jules, Gemini CLI, Windsurf, and more. One file, all tools. That's the point of a standard.

The most extreme use of it is inside OpenAI's own repository, which ships 88 nested AGENTS.md files — a root file for global conventions, and subdirectory files for each subproject. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence. That's how you scale from "one file for my side project" to "one hierarchy for a monorepo."

At the enterprise end, context configuration is part of the layer that makes the headline agent stories possible. Rakuten runs an autonomous code-repair system across 12.5 million lines of code; TELUS credits full-pipeline AI integration with half a million saved engineering hours. Systems like that have to be reliable — and reliable agents need to understand the codebase they're operating on, which is exactly what a well-written context file is for.

The message for a solo developer is simpler: if a 60,000-repo open standard and Fortune-500 engineering orgs both treat this file as infrastructure, it's worth the thirty minutes it takes to write yours properly.

The mistakes that make your file useless

Most AGENTS.md files fail for one of five reasons. Here's what they look like and how to fix them.

1. The novel. A 500-word essay about your codebase's history. It burns context on every session and buries the rules that matter. Fix: cut ruthlessly. If a sentence wouldn't change the agent's output, it's dead weight.

2. The wish list. "Write clean, well-documented code. Follow best practices." The agent already does this by default, so the file is pure noise. Fix: delete anything the agent would get right without being told.

3. Negative-only rules. "Never use any." "Don't commit to main." Without an alternative, the agent improvises — usually badly. Fix: every prohibition gets an "instead."

4. Contradictions. "Always write comprehensive tests" and "keep sessions fast, minimize token usage" are in tension. The agent oscillates between them. Fix: set explicit priorities and document the trade-offs.

5. Set and forget. This one is the silent killer. A recent study of 356 repositories found stale code references in 23% of AI configuration files — files pointing at renamed paths, deleted modules, and old commands. Stale instructions don't just waste tokens; they actively mislead. Fix: treat the file like code. Review it monthly, put a # last reviewed: YYYY-MM-DD comment at the top, and delete anything that no longer reflects reality.

The 30-minute setup

You can get the full benefit in about half an hour:

Write the file. Start with the template above and adapt it to your project: commands, conventions, guardrails. Cut anything that wouldn't change the agent's output.
Verify your commands. Run each one yourself. An AGENTS.md full of commands that don't work is worse than no file at all.
Run a real session. Give the agent a task that touches your conventions — a refactor, a new endpoint — and watch whether it follows the file.
Test a guardrail on purpose. Ask the agent to do something your file forbids (e.g., "add console.log here"). If it complies, the rule is too vague — rewrite it as a hard constraint or move it to a hook.

Then keep the freshness loop going: commit the file to git, review it monthly, and add a rule any time the agent repeats a mistake. One correction that turns into a rule is a correction you never make again.

The one-line takeaway

Your coding agent isn't limited by the model — it's limited by what it knows about your project. A short, specific, maintained AGENTS.md is the highest-leverage change you can make to your AI workflow. Not because the file is magic, but because it's the agent's only permanent memory.

Write it like documentation, and you've added a paragraph to a manual. Write it like code, and you've given a teammate a brain.

FAQ

Does AGENTS.md replace CLAUDE.md?

No. AGENTS.md is the tool-agnostic standard read by most agents. Claude Code reads CLAUDE.md natively — bridge them with a one-line @AGENTS.md import in CLAUDE.md so you keep a single source of truth.

How long should AGENTS.md be?

Under ~200 lines. Every word is loaded into context on every session, and context bloat degrades model accuracy. If removing a line wouldn't change the agent's output, delete it.

Why does my coding agent keep repeating mistakes?

Because it's stateless — it forgets everything between sessions and starts from training-data guesses about your project. AGENTS.md is re-read at the start of every session, so it acts as the agent's permanent memory.

Where should AGENTS.md live?

At the repository root. For monorepos, add one per subdirectory — agents read the nearest file, so the closest one takes precedence (OpenAI's repo ships 88 of them).

CTA: Copy the template into your repo and run one session. But before you do, think about your answer to this: what mistake does your coding agent repeat every session? That's the first line of your file. Start with just that one rule — the "instead" included — and test it. One correction that becomes a rule is a correction you never make again.

DEV Community: Build Loops