Agent Instructions

Written & tested for accuracy by a developer (not AI) · Updated October 2026

CLAUDE.md and AGENTS.md Best Practices

What to put in AI agent instructions and what to leave out. How to test that agent rules work. Best practices for CLAUDE.md and AGENTS.md files.

CLAUDE.md and AGENTS.md are instruction files that an AI coding agent reads at the start of every session. Claude Code reads CLAUDE.md, and Codex and most other AI coding tools read AGENTS.md. A good file saves you from repeating the same instructions in every conversation. But long or redundant files use context (the agent's working memory) in every session and can lead to poor performance.

To learn where the files go, how to create them, and how to use one file for both Claude Code and Codex, see Developer Setup for Agent Instructions. Good agent instructions are part of setting up a Mac for AI coding. See the Mac development setup guide for an overview.

Before you get started

I recommend using our free app to set up agent instructions for Claude Code and Codex. It is a FREE Mac app that installs the developer tools and AI coding agents you need, adds a note about your setup to your agent instructions, and verifies your setup is working. Here are all the details about the app before you download. Then download it:

Evidence-based research about AGENTS.md files

Two studies tested whether instruction files help an agent finish its work. Put together, they suggest an instruction file helps with what the agent can't find out for itself, such as your commands, your unusual conventions, or knowledge newer than the model, and costs context without benefit when it repeats what the agent can read in your code.

Researchers at ETH Zurich and LogicStar.ai tested coding agents on real tasks from open-source projects, with and without an AGENTS.md file ("Evaluating AGENTS.md", arXiv 2602.11988, revised September 2026). Agents followed the instructions in the files. The authors found the files useful for "non-standard coding practices", the conventions an agent can't guess. What didn't help was an overview of the project, the kind of summary many files open with, which you should skip. They found that providing an instruction file "does not generally improve task success rates", while it raises the cost of each task by "over 20% on average". That held for files written by people and for files written by an AI model.

Vercel tested a narrower case: an agent writing code for new Next.js 16 features that the AI model had never seen ("AGENTS.md outperforms skills in our agent evals", January 2026). With no documentation, the agent passed 53% of the tests. With the documentation packaged as a skill, it passed 53% when left to decide on its own, and 79% when the prompt told it to use the skill. In 56% of the tests, the agent never opened the skill. With a short index of the documentation in AGENTS.md, 8 KB in all, it passed 100%.

Put in what the agent can't work out for itself

Anthropic's and OpenAI's own advice matches the research. Include:

  • Commands - how to install, build, test, lint and run the project, especially any the agent couldn't guess.
  • Conventions that differ from the usual defaults - code style, file layout, naming, and how you write commits and pull requests.
  • Quirks of your environment, and common gotchas - such as settings the project needs, or behavior that isn't obvious from the code.
  • "Don't" rules - files never to edit, commands never to run, and anything that needs your approval first.
  • What "done" means - such as "the tests pass and the linter shows no errors". OpenAI's guide lists this alongside the commands and conventions.

Leave out what the agent can read in the code

Anthropic's best-practices page lists what to leave out:

  • What the agent can learn by reading your code, including descriptions of each file and folder.
  • Standard conventions of the language that any developer knows.
  • Long documentation, explanations or tutorials. Link to the documentation instead.
  • Information that changes often.
  • General advice, such as "write clean code".

For each line, Anthropic suggests a test: "Would removing this cause Claude to make mistakes?" If the answer is no, cut the line.

Keep CLAUDE.md and AGENTS.md short

Every line of the file is read in every session, whether the task needs it or not. Anthropic's documentation recommends keeping each CLAUDE.md under 200 lines, and its best-practices page warns: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" OpenAI's says "A short, accurate AGENTS.md is more useful than a long file full of vague rules."

Codex adds a hard limit: it reads at most 32 KiB (about 32,000 characters) of instructions in all, counting the personal file in your home folder and every project file, and stops adding files at that limit.

Write rules an agent can follow

  • Be concrete. Anthropic's example: write "Use 2-space indentation", not "Format code properly".
  • Write one rule per line, under headings that group related rules, so each rule is easy to find and change.
  • Remove rules that contradict each other. When two rules disagree, the agent has to guess which one you meant.
  • Mark only what matters most. Anthropic suggests adding a word such as "IMPORTANT" to a rule the agent keeps missing, and notes that emphasis stops working when many lines carry it.

Add a rule after a mistake, then test it

OpenAI's guide suggests adding new rules "only after you notice repeated mistakes", not in advance. You can check that a new rule helps: undo the agent's change, run the same task again with the new rule in place, and compare the result.

To check that an agent reads a file at all, put a made-up word in it, such as "The project codeword is PELICAN-42", and ask the agent for the project's codeword. Remove the line when you're done. In Claude Code, /memory also lists the instruction files loaded in the session.

Use /init as a starting point, then cut

Type /init in Claude Code or Codex, and the agent writes a first draft of CLAUDE.md or AGENTS.md from your project. In Claude Code, the draft includes a description of your code, the part the ETH Zurich study found doesn't help. Keep the commands and rules it found, cut the description, and add the conventions and "don't" rules only you know.

Move long or occasional instructions elsewhere

When a file grows, move the instructions that apply only some of the time out of it:

  • To a subfolder. In Codex, an AGENTS.md in a subfolder applies only to work in that folder. Claude Code does the same with a CLAUDE.md in the subfolder, which can hold the line @AGENTS.md to read the subfolder's AGENTS.md.
  • To a rule file for matching files. In Claude Code, a file in .claude/rules/ that starts with a paths: list, such as src/api/**/*.ts, loads only when Claude works on matching files.
  • To a skill. A procedure you use now and then, such as the steps to release your project, belongs in a skill, which the agent loads only when the task calls for it. See Developer Setup for Agent Skills.
  • To a hook. An action that must happen every time, such as formatting each file after an edit, belongs in a hook, a command Claude Code or Codex runs automatically at a set moment, not in an instruction the agent might skip.

CLAUDE.md and AGENTS.md examples

Here's a template for a project's AGENTS.md, with placeholders to replace:

# <Project name>

## Commands

- Install: `<install command>`
- Test: `<test command>`
- Lint: `<lint command>`

## Conventions

- <A rule that differs from the usual default, such as "Use tabs, not spaces">
- <Where new code goes, such as "Put API routes in src/routes/">

## Don't

- <Something the agent must never do, such as "Never edit the generated files in dist/">

## Done means

- <What must be true before a task is finished, such as "The tests pass and the linter shows no errors">

Add a CLAUDE.md holding the single line @AGENTS.md, so Claude Code reads the same instructions.

Your personal file, ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md, applies in every project, so keep it to how your Mac is set up and habits you want everywhere:

# My Mac

- Homebrew installs command-line tools (`brew install <name>`).
- Python: use uv. Run scripts with `uv run` and add packages with `uv add`.
- Ask before you change my shell files, `~/.zprofile` and `~/.zshrc`.

For a real example, read Homebrew's own instruction file. If you have Homebrew, it is already on your Mac:

$ cat "$(brew --repository)/AGENTS.md"

It runs to about 70 lines, under headings for running commands, what to do before each commit, Git, code style, tests, and the layout of the repository. Its CLAUDE.md is the single line @AGENTS.md.

Learn more about writing agent instructions

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.