AGENTS.md for Local Coding Agents: The Cheapest Quality Upgrade You Can Make

Written by Jakub Rusinowski · Last updated 2026-08-04 · Hardware figures computed by our VRAM engine

AGENTS.md is a plain-Markdown file at your repo root telling coding agents how to build, test and change your project. It is read natively by most agents in 2026 and it helps local models more than frontier ones, because a small model cannot infer your conventions from a few files. Keep it under roughly 100 lines of commands and hard rules — on a 16–32K window, a bloated rules file costs more than it teaches.

Every coding agent needs the same handful of facts before it can be useful in your repo: how to run the tests, how to build, where things live, and what it must never touch. Without them a model guesses — and a local model guesses worse, because it has less general knowledge of your stack to fall back on and a smaller window in which to explore.

The fix is a file. AGENTS.md at the repo root has become the cross-tool convention for it: an open, Markdown-format instructions file that agents read automatically, adopted broadly across the tool ecosystem through 2026 (Codex, Cursor, Copilot, Aider, Gemini CLI, Zed and others read it natively) and stewarded as an open standard rather than any one vendor's format. Claude Code keeps its own CLAUDE.md convention, bridged with an import or a symlink.

For local setups it is the highest ratio of quality gained to effort spent — a few hundred tokens, written once, that stop the same three mistakes recurring in every session.

Why small models depend on it more

A frontier model can often reverse-engineer your conventions from the files it reads. A 8–27B model, with a fraction of the window and less latent knowledge of your framework's idioms, mostly cannot. Four concrete effects:

• It invents commands. Told to run the tests, it will try npm test in a project that uses pnpm vitest run, watch it fail, and spend three turns recovering. One line in the rules file removes the entire detour.
• It explores instead of working. Without a layout hint it reads files to find out where things are — expensive in a small window, and each irrelevant file dilutes attention.
• It defaults to the internet's average style. Class components, an ORM you removed, a logging library you never used. A local model regresses to the mean of its training data unless told otherwise.
• It repeats mistakes across sessions. No memory between runs; the rules file *is* the memory. Every recurring correction you write down is a fix you never make twice — the level-4 "meta loop" from loop engineering, done manually.

A template that fits a small window

Commands and hard rules first — they are the highest-value tokens and the ones most likely to survive a compaction. Prose last, or not at all.

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- Test (fast, use this in loops): `pnpm vitest run src/`
- Test (full): `pnpm test`
- Types: `pnpm tsc --noEmit`
- Lint: `pnpm lint`
Run types + fast tests after every change. Both must pass before you report done.

## Layout
- `src/lib/` — pure logic, unit-tested. Put new business rules here.
- `src/components/` — React components, no data fetching.
- `src/server/` — API handlers. Never import from components/.
- Tests live beside the code as `*.test.ts`.

## Conventions
- TypeScript strict. No `any`. No default exports.
- Existing patterns win over your preferences — read a neighbouring file first.
- Errors: throw typed errors from lib/, handle at the server boundary.

## Never
- Never edit files under `generated/` or `*.snap`.
- Never modify tests to make them pass. Fix the code.
- Never add a dependency without asking.
- Never touch `.env`, migrations, or CI config.

That is roughly 250 tokens and it removes most recurring failure modes. Note the two lines doing the heaviest lifting: a fast test command explicitly labelled for loops, and "never modify tests to make them pass" — the guardrail against the most common way an agent produces green, worthless output.

What to leave out

Rules files rot into README duplicates. Every token spent on background is a token not spent on your code, and on a 16K window that trade is brutal.

• No project history or rationale. The agent does not need to know why you migrated off Webpack.
• No content the agent can read faster than you can maintain. Don't paste your schema; tell it where the schema file is.
• No wishful instructions. "Write elegant, idiomatic code" changes nothing. "No default exports" changes something.
• No duplicated tool config. If .eslintrc already enforces it, the agent will get the error from lint — cheaper and more reliable than a paragraph.
• No stale commands. A wrong command is worse than no command: the agent trusts it, fails, and has to recover. Re-check the file whenever your scripts change.

A rule of thumb for local models: under 100 lines, and every line either a command, a path, or a prohibition. If you cannot say which failure a line prevents, delete it.

AGENTS.md, CLAUDE.md, and the rest

The proliferation of per-tool files — .cursorrules, CLAUDE.md, .github/copilot-instructions.md — is exactly what AGENTS.md was created to end.

The 2026 default: write AGENTS.md, and add a tool-specific file only when you hit a real limitation. Where a tool insists on its own name, symlink rather than duplicate — two rules files that disagree is a worse failure than none, because you will not notice which one the agent read.

# Bridge Claude Code to the shared file instead of maintaining two
ln -s AGENTS.md CLAUDE.md

Local-model note: whichever file your agent reads, verify it is actually in the prompt. If the assembled context exceeds the served window, the rules file — usually near the front — is the first thing silently dropped. That is the single most common reason a correct rules file appears to be ignored; see context engineering.

Scaling to a monorepo

Nested files work: an AGENTS.md in a subdirectory applies to work inside it, with the nearest file taking precedence. For a monorepo, keep the root file to what is genuinely universal (how to install, the commit convention, the global "never" list) and put package-specific commands beside the packages.

This matters more on local models than hosted ones, for the usual reason: a root file carrying every package's build commands is mostly irrelevant tokens on any given task. Nesting keeps the working window small — the same principle as curating a working set, applied to instructions.

Treat it as a living artefact

The rules file earns its keep through maintenance, not authorship. A workable habit:

1. Every time you correct the agent twice for the same thing, write the rule. That is the trigger. Not "the agent was wrong" — "the agent was wrong the same way again." 2. Re-read it monthly, delete what has gone stale. Wrong commands are actively harmful. 3. Keep it in version control, review it in PRs. It shapes generated code; it deserves the same scrutiny as a lint config. 4. Test it the cheap way. Start a fresh session and ask the agent to state the test command and the directories it must not touch. If it cannot, the file is either not being read or too long to survive compaction.

Combined with a verifier command and a sandbox, a maintained rules file is most of what separates a local agent that helps from one you abandon after a week.

Frequently asked questions

Keep going

• System prompts & personas for local models
• Coding & debugging prompting workflow
• Local coding assistant setup
• The Agent Harness: What Actually Turns a Local Model Into a Coding Agent
• Context Engineering for Local Coding Agents: Budgeting a Window You Pay For
• Run a Local Coding Agent End-to-End: Ollama + Qwen3-Coder + VS Code
• Sandboxing a Local Coding Agent: Autonomy Without the Blast Radius
• Local AI coding assistant — the full hub