Repo instruction files that work (AGENTS.md / CLAUDE.md)

Every new session, the agent walks into your repo like a contractor on day one. It doesn’t know how you run tests, which folder is legacy, or that you never touch the generated client by hand.

A repo instruction file is the note you tape to the door. Most coding agents look for one (names like AGENTS.md or CLAUDE.md) and load it automatically at the start of each session. Check your tool’s docs for the exact file name and whether it also reads files in subfolders.

How it reaches the agent

1. 📄You write itPlain markdown at the repo root
2. ↓→
3. 📥Session startsThe agent loads it before your brief
4. ↓→
5. 🧭Every stepIt shapes each read, edit and command
6. ↓→
7. ✏️You refine itWhen the agent repeats a mistake

↺ Each repeated mistake is a line you haven’t written yet

That last point matters. Because it loads every time, the file sits in the fixed part of your context budget from lesson 2.1. A bloated file taxes every single task.

What goes in, what stays out

Here is the shape I start from. It is short on purpose. Adapt the commands and paths to your stack.

# Agent instructions

## Commands
- Install: pnpm install
- Run one test file: pnpm test path/to/file.test.ts
- Full check before finishing: pnpm lint && pnpm typecheck && pnpm test

## Layout
- apps/web: Next.js front end
- packages/billing: pricing and invoice logic (money in integer cents)
- packages/api-client: GENERATED, never edit by hand, run pnpm gen

## Rules
- Add or update a test for every behavior change.
- Don't add dependencies without saying why in your summary.
- Database migrations live in db/migrations; never edit an applied one.

## More context
- Billing rules: docs/billing.md
- Error handling conventions: docs/errors.md

Quick check

🧠 Instruction file check

Score: 0 / 4

1. 1. Your agent keeps running the whole test suite, which takes 12 minutes. What’s the best fix?

   Tell it to hurry up in every briefAdd the command to run a single test file to the instruction fileDelete the slow testsPaste the test runner’s docs into the file

   Give it the exact, fast command once, where every session will see it.

2. 2. Why keep the instruction file short?

   Agents can’t read long filesIt loads in every session, so every line costs context on every taskMarkdown files have a size limitShort files are easier to translate

   It is part of the fixed budget. Put depth in linked docs the agent reads only when needed.

3. 3. Which line is most useful?

   Follow best practices.Write readable code.packages/api-client is generated: never edit it, run pnpm gen instead.This project is very important to the company.

   It is specific, has a reason, and prevents a real mistake.

4. 4. The agent made the same mistake twice this week. What do you do?

   Nothing, it’s randomAdd one precise line to the instruction file and see if it stopsSwitch agentsRewrite the whole file from scratch

   Repeated mistakes are the best source of new lines. Add one, observe, keep or remove it.

↺ Try again

Team-wide conventions for these files, and sharing prompts across a team, come back in Module 6.

Before you move on

✅ Key takeaways

0 / 5 completed

• My repo has an instruction file the agent loads automatically.
• It lists exact commands, including how to run a single test.
• Every rule is specific, has a reason, and isn’t already enforced by tooling.
• It points to deeper docs instead of pasting them.
• When the agent repeats a mistake, I add one precise line and check it helps.

↺ Reset