---
title: "Instruction files: AGENTS.md, CLAUDE.md and friends"
description: "Why instruction files exist Every new agent session starts with amnesia. Without guidance, the agent spends its first minutes (and your tokens)…"
url: https://optimizeall.com/learn/agentic-coding-with-ai/agent-instruction-files
updated: 2026-10-05
---

AI-Assisted Software Development: Coding Agents in Practice · Context engineering for codebases · lesson 4 of 17 · 13 min

# Instruction files: AGENTS.md, CLAUDE.md and friends

## Why instruction files exist

Every new agent session starts with amnesia. Without guidance, the agent spends its first minutes (and your tokens) rediscovering how to build, test and lint your project, and it guesses your conventions. **Instruction files** are Markdown files the agent loads automatically at the start of each session. They are the cheapest, highest-leverage context engineering you can do.

## The main formats in 2026

| File | Read by | Notes |
|---|---|---|
| `AGENTS.md` | Codex, GitHub Copilot, Cursor and many other agents | Open, tool-neutral convention; nested files in subdirectories can add local rules |
| `CLAUDE.md` | Claude Code | Project, user and directory levels; can import other files; Claude Code also keeps auto memory |
| `.github/copilot-instructions.md` and `*.instructions.md` | GitHub Copilot | Repository-wide and path-scoped instructions |
| `.cursor/rules/*.mdc` | Cursor | Rules with frontmatter controlling when they apply; Cursor also reads AGENTS.md |
| `GEMINI.md` | Gemini Code Assist / Gemini CLI | Context file at project root |

Formats and precedence rules change; check each tool's docs. A practical pattern for mixed teams: keep the substance in **AGENTS.md** and make tool-specific files short pointers (for example, a CLAUDE.md that says "See @AGENTS.md" plus Claude-only notes).

## What belongs in an instruction file

Think "onboarding note for a strong contractor who has never seen this repo".

1. **Project map in three lines.** What the system does, main directories, where not to go.
2. **Exact commands.** Install, build, run, test (all and single test), lint, type-check, format. Copy-pasteable.
3. **Conventions that are not obvious from code.** Error handling pattern, logging, naming, where new modules go, which libraries are preferred or banned.
4. **Definition of done.** "Tests added or updated; `npm run check` passes; no new lint warnings; public API unchanged unless the task says so."
5. **Boundaries.** Files never to edit (generated code, migrations already applied, vendored libraries), commands never to run, secrets policy.
6. **Gotchas.** The flaky test, the env var that must be set, the reason `utils/legacy.ts` looks wrong but must stay.

What does **not** belong: long architecture essays, whole style guides the linter already enforces, secrets, and anything that changes weekly. Every line costs context on every turn.

## Worked example: a real-world AGENTS.md

```markdown
# AGENTS.md — invoicing-service

## What this is
Node 22 + TypeScript API that generates and exports invoices (PK, UAE, UK tax rules).
Main code: src/. Tests: test/. Do not edit: src/generated/, migrations/applied/.

## Commands
- Install: npm ci
- Test all: npm test          Single file: npx vitest run test/pricing.test.ts
- Lint + types: npm run check
- Local DB: docker compose up -d db

## Conventions
- Money is integer minor units (paisa, fils, pence). Never use floats for money.
- Dates: store UTC, convert at the edge with src/lib/tz.ts. Never call new Date() in domain code; inject Clock.
- Errors: throw DomainError subclasses; never return null for failures.
- Prefer zod for validation. Do not add new dependencies without saying why in the PR.

## Definition of done
- New or changed behavior has tests. npm test and npm run check pass.
- PR description lists what changed, why, and how it was verified.

## Boundaries
- Never read or print .env* files. Never commit secrets.
- Never run migrations against anything but the local docker DB.
```

Notice how each line prevents a specific, predictable mistake.

## Hands-on: generate, then prune

Most agents can draft an instruction file for you (for example, Claude Code's `/init` command). Use that as a starting point, then prune hard:

```text
Read the repository and draft AGENTS.md with: a 3-line project map, exact install/build/
test/lint commands (verify each by running it), non-obvious conventions you can infer
from the code, a definition of done, and boundaries (generated or vendored paths).
Keep it under 80 lines. Mark anything you are unsure of with "(verify)".
```

Then: run every command yourself, delete anything generic ("write clean code"), and add the gotchas only your team knows. Commit it and review it like code.

## Maintaining instruction files

- **Treat it as code.** Changes go through PR review.
- **Update on failure.** When an agent makes the same mistake twice, add one line that prevents it.
- **Nest when needed.** A monorepo can have a root file and short per-package files.
- **Prune quarterly.** Remove rules the linter or type system now enforces.

## Pitfalls

- **Contradictions** between AGENTS.md and a tool-specific file. Keep one source of truth.
- **Aspirational rules** the codebase does not follow. The agent copies the code, not the wish.
- **Using instructions as security.** "Never delete the database" belongs in permissions and hooks as well.

## How to measure success

Track "repeat mistakes": corrections you make that an instruction line could have prevented. A good file drives that number down within two or three sprints.

## Video lecture: Instruction files: AGENTS.md, CLAUDE.md and friends

Lecture coming soon · 14 chapters · about 9 minutes. Read the full transcript below.

1. Instruction files: onboarding for agents
2. Analogy: the laminated safety card
3. Why they matter
4. The formats
5. Six ingredients
6. Lines that earn their place
7. What stays out
8. Generate, then prune
9. Keeping it healthy
10. Before → after (two lines)
11. Scenario: 12 devs, one sprint (illustrative)
12. Deeper: five patterns → five lines
13. Watch me do it: AGENTS.md
14. Recap

## Lecture transcript

### Instruction files: onboarding for agents

Imagine hiring a brilliant contractor who forgets everything about your company every single morning. You would write them a one-page onboarding note and hand it over at the door. That is exactly what an instruction file does for a coding agent. In this lecture you will learn the formats, what to put in them, what to leave out, and how to keep them sharp over time.

### Analogy: the laminated safety card

Why should you care about a humble Markdown file? Because it is the one piece of context that is present in every single session, for every developer, for every agent that reads it. Think of it like the laminated safety card on a factory machine. It is short, it lists the few things you absolutely must know, and it is bolted to the machine so nobody has to remember to fetch it. Nobody laminates a hundred-page manual. They laminate the ten lines that prevent accidents. Your instruction file is that laminated card for your codebase.

### Why they matter

Every agent session starts from zero. Without guidance, the agent spends its first minutes, and your money, working out how to run your tests, and then guesses your conventions. Guesses are where subtle bugs come from. An instruction file is a Markdown file the agent loads automatically at the start of each session. It is the cheapest and highest-leverage improvement you can make, and it takes an afternoon.

### The formats

There are several formats. AGENTS dot M D is the open, tool-neutral convention, read by Codex, Copilot, Cursor and many others. Claude Code reads CLAUDE dot M D, at project, user and folder level. Copilot also supports a copilot instructions file and path-scoped instruction files. Cursor has project rules in a rules folder, and it reads AGENTS dot M D too. Gemini uses GEMINI dot M D. For mixed teams, a clean pattern is to keep the substance in AGENTS dot M D and make the tool-specific files short pointers to it.

### Six ingredients

So what goes inside? Six things. A project map in three lines. Exact commands for install, build, test, single test, lint and type check. Conventions that are not obvious from the code, like how you handle money or dates. A definition of done. Boundaries: files never to touch and commands never to run. And gotchas: the flaky test, the environment variable that must be set, the weird legacy file that must stay weird.

### Lines that earn their place

Look at one line from the sample file in the lesson. Money is integer minor units: paisa, fils, pence. Never use floats for money. That single line prevents a whole class of rounding bugs across Pakistani, Emirati and British invoices. Another: never call new Date in domain code, inject a clock instead. That one makes time-based logic testable. Good instruction lines are like that. Each one prevents a specific, predictable mistake.

### What stays out

And what stays out? Long architecture essays. Style rules your linter already enforces. Anything that changes every week. And never, ever, secrets. Remember, every line is sent on every turn, so every line costs attention and tokens. Also avoid aspirational rules. If the file says always use the repository pattern, but half the codebase does not, the agent will copy the code, not your wishes.

### Generate, then prune

A practical way to start: ask the agent to draft the file for you. Claude Code has an init command, and any agent can follow a prompt like the one in the lesson. Ask it to verify every command by running it and to mark uncertain items. Then prune hard. Run every command yourself, delete generic advice, and add the gotchas only your team knows. Commit it and review it like code. From then on, whenever an agent makes the same mistake twice, add one line.

### Keeping it healthy

Keeping the file healthy is a habit, not a project. Treat it as code, so every change goes through review. When an agent makes the same mistake twice, add one precise line that prevents it. In a monorepo, keep a short root file and add small nested files per package for local rules, since many agents read the nearest file to the code they are editing. And once a quarter, prune. If the linter or the type system now enforces a rule, delete it from the file. A lean file that is always true beats a long file that is half stale.

### Before → after (two lines)

Let's do a simple before and after. Before: an agent in a Python repository runs python dash m unittest, which finds nothing, then tries pytest, then installs a new testing library it thinks you are missing. Three wasted steps and an unwanted dependency. After adding two lines, test all colon pytest dash q, and never add dependencies without asking, the next session runs the right command first time and asks before installing anything. Two lines. Minutes saved every session, and one risky behavior stopped. That is the return on an instruction file.

### Scenario: 12 devs, one sprint (illustrative)

Now a realistic scenario with illustrative numbers. A twelve-developer product team in Dubai tracks corrections they make to agent pull requests for one sprint. They log thirty-four corrections. Twenty-one of them fall into five repeat categories: wrong date handling, missing tenant ID filters, wrong error type, logging personal data, and editing generated files. They add five precise lines to AGENTS dot M D, one per category. The next sprint, repeat corrections drop to six. The exact figures will differ for you, but the method is what matters: count repeat mistakes, add one line per pattern, and measure again.

### Deeper: five patterns → five lines

One level deeper on the Dubai example. Look at how each of the five repeat categories turned into exactly one line. Wrong date handling became: dates are stored in UTC and converted only in the tz helper. Missing tenant filters became: every repository query must take a tenant identifier. Wrong error type became: throw domain error subclasses. Logging personal data became: never log email, phone or address fields. And editing generated files became a boundary. Specific, checkable, short.

### Watch me do it: AGENTS.md

Watch me do it. I'm building an AGENTS dot M D for the invoicing service using the generate-then-prune method. Step one: I paste the drafting prompt from the lesson, asking for a three-line map, verified commands, conventions, a definition of done and boundaries, under eighty lines, marking anything uncertain with verify. The agent explores and returns a draft of about seventy lines. Step two: I run every command myself. npm ci works. npm test works. The single-file test command it suggested uses the wrong runner, so I correct it to npx vitest run with a file path. The lint command was marked verify, and it turns out the real one is npm run check, which also runs type checks. Step three: I delete generic lines. Write clean, readable code: gone. Follow best practices: gone. Step four: I add the lines only our team knows. Money is integer minor units, paisa, fils and pence. Inject a clock, never call new Date in domain code. Never run migrations against anything except the local docker database. Step five: boundaries. Do not edit the generated folder or applied migrations. Never read or print env files. The final file is fifty-two lines. I open a pull request so the team can review it like code, and I note one thing to track: repeat corrections over the next two sprints.

### Recap

Recap. Instruction files are onboarding notes that load every session. Keep one source of truth, usually AGENTS dot M D. Include map, commands, conventions, done, boundaries and gotchas, and keep it lean. And remember that instructions guide behavior but do not enforce it. Your next step: draft, verify and prune an instruction file for your main repository, then track how many repeat mistakes it prevents over the next two sprints.

## Key takeaways

- Instruction files load every session; they are the cheapest, highest-leverage context you can add.
- Keep substance in one source of truth (often AGENTS.md) with short tool-specific pointers.
- Include map, exact commands, non-obvious conventions, definition of done, boundaries and gotchas.
- Keep files lean, review them like code, and add a line whenever a mistake repeats.

## Try it

Draft an AGENTS.md for one repository using the generate-then-prune prompt, verify every command by running it, and open a PR for team review.

- [Previous: Choosing and setting up tools with a fair trial](https://optimizeall.com/learn/agentic-coding-with-ai/choosing-and-setting-up-tools)
- [Next: Repo maps, skills, MCP and the context budget](https://optimizeall.com/learn/agentic-coding-with-ai/repo-maps-and-context-budget)
- [All lessons of AI-Assisted Software Development: Coding Agents in Practice](https://optimizeall.com/learn/agentic-coding-with-ai)