AGENTS.md and CLAUDE.md: Writing Instructions Your Coding Agent Actually Follows

Every team using Claude Code, Codex, Cursor, or Copilot's agent mode now has a file at the root of their repo — AGENTS.md, CLAUDE.md, or both — that's supposed to tell the agent how the codebase works. Most of these files are terrible. They're either a copy-pasted README, a wall of "best practices" nobody enforces, or a growing pile of one-off fixes ("don't use any", "always run tests", "never touch legacy/") added reactively after each bad session.

The problem isn't that these files are unimportant — it's the opposite. An AGENTS.md file is the closest thing your codebase has to a system prompt. It loads into every agent session before any code gets read, and it silently reshapes what the agent tries, what it skips, and what it assumes it already knows. Get it right and the agent stops re-deriving context you already have. Get it wrong and you're paying token and time cost for instructions that actively mislead.

This post is about what actually works: what to put in AGENTS.md, what to leave out, and how to structure it so an agent — which reads it once, cold, with no memory of your team's history — can act on it correctly.

Why this file matters more than your README

A README is written for humans who skim, infer, and ask a colleague when something's unclear. An agent does none of that. It treats every sentence in AGENTS.md as an instruction to follow literally, and it has no way to tell "this is a strong convention" from "this is a suggestion from 2023 that nobody follows anymore." If the file says "we use Redux for state," and you migrated to Zustand eight months ago, the agent will confidently write Redux code — not because it's careless, but because you told it to.

This asymmetry is the core design constraint: write AGENTS.md for an intelligent reader with zero shared context and no ability to double-check with you mid-task. Every ambiguity you leave in gets resolved by guessing, and the guess is usually wrong in a way that looks plausible.

What belongs in the file

1. Commands, not descriptions of commands. Don't write "we use pnpm for package management." Write the actual commands:

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (runs on :3000)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Full test suite: `pnpm test` (takes ~4 min, don't run for small changes)
- Lint + typecheck: `pnpm check`

The line about test suite duration matters — it tells the agent when to reach for the fast, targeted command instead of the slow, comprehensive one. That's a judgment call you're making once so the agent doesn't have to guess every session.

2. Non-obvious architectural decisions, with the why. Skip anything derivable from reading the code (file structure, naming patterns, which framework is used — the agent can see this in thirty seconds). Only write down decisions that would surprise a competent engineer reading the code cold:

## Architecture notes
- `src/lib/db.ts` exports a singleton connection — do not instantiate
  a new client per request, we hit connection limits on the free tier
  of our Postgres host in prod incident #412.
- API routes under `src/app/api/webhooks/` skip the auth middleware
  intentionally — they verify signatures instead. Don't add auth
  checks there.

Each of these carries a "why" (the connection-limit incident, the signature-verification pattern) so the agent can reason about edge cases instead of pattern-matching blindly. A rule without a reason gets misapplied the first time it doesn't quite fit.

3. Guardrails for genuinely dangerous or expensive actions. Migrations, deploy scripts, anything that touches production data or costs money to run:

## Do not run without asking
- `scripts/migrate-prod.sh` — irreversible, touches the prod DB
- `scripts/reindex-search.sh` — costs ~$40 in API credits per run

4. Where things actually are, if your structure is non-standard. If your repo doesn't match the obvious convention for its framework (feature-based folders instead of type-based, a monorepo with unusual package boundaries), say so. If it does match the obvious convention, don't — the agent already knows Next.js App Router conventions from training.

What does NOT belong

This is where most AGENTS.md files go wrong — they accumulate cruft because adding a line feels cheap and low-risk. It isn't. Every line is something the agent must hold in context and weigh against the actual code it's reading. A bloated file dilutes the rules that matter.

Cut this	Why
General coding best practices ("write clean code", "add tests")	Not specific to your repo; agents already default to this
Descriptions of what a framework does	The agent was trained on the framework's docs
Stale conventions from a past migration	Actively wrong is worse than absent
Long prose explaining team history or philosophy	Doesn't change what the agent does differently
Anything enforced by a linter or CI already	Redundant — the tool will catch it regardless

A good test: for every line, ask "if this were wrong, would the agent produce broken or unwanted code?" If the answer is no, the line isn't pulling weight.

The nested-file pattern

Large or multi-package repos benefit from AGENTS.md files scoped to subdirectories, not just one at the root. A root file covers repo-wide commands and conventions; a nested packages/api/AGENTS.md covers that package's specific quirks (e.g., "this package uses a different test runner than the rest of the monorepo"). Most agent harnesses, including Claude Code, load the nearest AGENTS.md up the directory tree, so scoping instructions to where they're relevant keeps the root file lean and avoids irrelevant instructions leaking into unrelated work.

A worked example: before and after

Before (typical first draft):

# Project Guidelines
This is a Next.js project. We care about code quality and testing.
Please follow best practices and write clean, maintainable code.
Use TypeScript. Don't break existing functionality.

This tells the agent nothing it doesn't already assume by default. It burns context and adds zero signal.

After (rewritten for actionability):

# AGENTS.md

## Commands
- Dev: `npm run dev`
- Test: `npm test -- <path>` for one file, `npm test` for all (~90s)
- Typecheck: `npm run typecheck` — run before considering a task done

## Architecture
- Server actions live in `src/actions/`, not API routes — this repo
  does not use `src/app/api/` for anything except Stripe webhooks.
- Auth state comes from `useSession()` (custom hook in
  `src/hooks/useSession.ts`), not next-auth's default hook — we wrap
  it to add workspace-switching logic.

## Do not
- Do not add new dependencies without checking `package.json` first —
  we've hit bundle-size budget issues twice this quarter.
- Do not modify `src/lib/legacy-billing.ts` — scheduled for deletion,
  changes here will be thrown away.

Every line in the second version changes agent behavior in a way the first version couldn't.

Common pitfalls

• Writing it once and never revisiting it. Stale instructions are worse than no instructions — an agent trusts the file by default. Treat it like a config file that needs updates when the repo's reality changes, not documentation you write during onboarding and forget.
• Copying another team's AGENTS.md wholesale. Their conventions aren't yours. A generic file full of plausible-sounding rules that don't match your actual repo is actively harmful.
• Using it to enforce things a linter should enforce. If ESLint already blocks console.log, don't also tell the agent not to use it — that's duplicated, brittle enforcement.
• Burying the important rules in prose. Agents (like humans) weight the start and structure of a document more heavily. Use headers and short bullet lists, not paragraphs.
• No ownership. If nobody's responsible for keeping the file current, it drifts within a month. Assign it the way you'd assign ownership of a CI config.

Next steps

Start small: write down the three or four things that, if an agent got them wrong, would produce a PR you'd immediately reject. That's your first AGENTS.md. Add to it only when you notice a session go wrong for a reason a written instruction would have prevented — not preemptively. The file should grow from observed failures, not from imagining every possible one.

If your team is building agent-driven workflows into your actual engineering process — not just using a coding agent occasionally, but designing for it — that's exactly the kind of applied, hands-on work we cover in Joinloop's AI engineering cohort. We work through this with real repos, not toy examples.