CLAUDE.md and AGENTS.md Templates for Claude Code and Codex CLI: What to Put In, What to Leave Out

A practical guide to project instruction files for Claude Code and Codex CLI: where they live, what belongs in them, and how to keep one file working for both tools

If you use Claude Code or OpenAI's Codex CLI for long, you start repeating yourself. "Use pnpm, not npm." "Don't touch the generated client." Every session starts with a fresh context window, so the agent forgets all of it.

Both tools solve this the same way: a Markdown file in your repository that the agent reads at the start of every session. Claude Code calls it CLAUDE.md. Codex calls it AGENTS.md. Many of these files end up nearly empty or several screens of prose the agent half-follows. Here's how to write one that earns its place.

What these files are, and where each tool looks

Claude Code: CLAUDE.md

Claude Code reads CLAUDE.md files from a few places, and it combines them instead of picking one:

• User level: ~/.claude/CLAUDE.md applies to every project on your machine. Put personal preferences here.
• Project level: ./CLAUDE.md or ./.claude/CLAUDE.md in the repo. This is the one you commit and share with your team.
• Local level: ./CLAUDE.local.md is for your own project-specific notes. Add it to .gitignore.

At launch, Claude Code loads these files from your current working directory and every directory above it, and concatenates them. The file closest to where you launched is read last. Files in subdirectories don't load at launch. Each one loads when Claude reads or edits a file in that subdirectory. That makes a packages/api/CLAUDE.md a good home for rules that only matter in that package.

Anthropic's docs are clear that CLAUDE.md is context, not enforced configuration. Claude reads it and tries to follow it, but nothing guarantees compliance. If something must never happen, use a permission rule or a hook, not a sentence in a Markdown file.

Codex CLI: AGENTS.md

Codex builds what it calls an instruction chain when it starts:

• Global: ~/.codex/AGENTS.md (or the CODEX_HOME directory if you've set it). An AGENTS.override.md in the same place takes priority if it exists.
• Project: starting at the project root (usually the Git root), Codex walks down to your current working directory and picks up at most one instruction file per directory. In each directory it checks AGENTS.override.md first, then AGENTS.md.

Files are joined from the root down, so a file in a nested directory appears later and can override broader guidance. A few details are worth knowing. Codex skips empty files, and it stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. Also, unlike Claude Code, Codex stops at your current directory. It doesn't pick up files from subdirectories below where you launched, so start Codex from the directory whose rules you want.

Both tools can draft one for you

Claude Code and Codex both have an /init command. In Claude Code, it analyzes the codebase and writes a starting CLAUDE.md with build commands and conventions it finds. In Codex, it generates an AGENTS.md scaffold in the current directory. Treat either as a first draft: the useful part is what you add that the agent couldn't work out by itself.

What to put in

A good test for every line: would a capable new teammate need to be told this, or would they figure it out by reading the code? Write down the first kind.

Commands, exactly as you run them. Install, build, test, a single test file, lint, type-check. Agents run these constantly, and guessing wrong wastes a whole loop. Write pnpm test -- path/to/file rather than "run the tests."

A short map of the repo. Not every folder, just where the important things live and anything surprising. "API handlers are in src/api/handlers/. Shared types are in packages/types, not in each app."

Conventions that differ from the defaults. If your team does something the agent wouldn't assume, say so: a specific error-handling pattern, a naming rule, a preferred library over a more popular one.

Gotchas. The things that bit you. The test suite needs a local Redis. A module is imported dynamically, so "unused" doesn't mean unused.

What not to touch. Generated files, vendored code, lockfiles you don't want rewritten, a legacy directory under a freeze. Be explicit and use paths.

How to check the work. What "done" means: tests pass, lint is clean, types check. Agents do better when they know how to verify their own changes.

Anthropic's guidance on phrasing is worth copying: make instructions concrete enough to check. "Use 2-space indentation" instead of "format code properly." "Run npm test before committing" instead of "test your changes."

What to leave out

Long prose. Paragraphs of background are harder for the model to act on. Use headings and short bullets.

Things the model can infer. Every dependency, a full directory tree, an explanation of React. The agent can read package.json and the file system. Claude Code's /doctor checkup flags this kind of content as derivable from the codebase.

Secrets. No API keys, tokens, passwords, or internal URLs you wouldn't want in Git history. The project file is committed to source control and goes straight into the model's context every session. Point to where credentials come from ("read from .env.local, which is gitignored") instead.

One-off procedures. A ten-step release checklist doesn't need to be in every session. Claude Code has skills and path-scoped rules in .claude/rules/ for instructions that should load only when relevant. In Codex, a nested AGENTS.md keeps service-specific rules out of the root file.

Contradictions. If your user-level file says one thing and the project file says another, Anthropic's docs warn that Claude may pick one arbitrarily. Review all the layers together now and then.

Keep it short, because you pay for it every session

This is the part people underestimate. Your instruction file is loaded into context at the start of every session, before you type anything. Every line is input tokens you pay for, in money on the API or usage limits on a subscription, and room your actual task could use.

Length hurts quality too. Anthropic recommends keeping each CLAUDE.md under 200 lines and notes that longer files reduce adherence. Splitting a file with @imports helps organization but doesn't reduce the cost, because imported files also load at launch. Codex enforces a hard ceiling with its 32 KiB default, and anything past it simply doesn't get added.

Two small tricks help. In Claude Code, block-level HTML comments in CLAUDE.md are stripped before the content reaches the model, so you can leave notes for human maintainers at no context cost. And before adding a line, ask whether you've actually had to correct the agent about it. Anthropic suggests adding to the file when the agent makes the same mistake twice.

A concrete example

Here's an AGENTS.md for a hypothetical TypeScript monorepo, short on purpose.

# AGENTS.md

## Commands
- Install: `pnpm install` (never npm or yarn)
- Dev server: `pnpm dev --filter web`
- All tests: `pnpm test`
- One test file: `pnpm vitest run path/to/file.test.ts`
- Lint and types: `pnpm lint && pnpm typecheck`

## Layout
- `apps/web`: Next.js frontend
- `apps/api`: Fastify server; route handlers in `src/routes/`
- `packages/types`: shared types. Import from here, don't redefine.

## Conventions
- Return errors as `Result<T, AppError>` from `packages/types`; don't throw in route handlers.
- Use `zod` schemas in `src/schemas/` for all request validation.
- New UI components go in `apps/web/components/ui/`.

## Gotchas
- API tests need Redis running locally: `docker compose up redis`.
- Run database migrations from the repo root only: `pnpm db:migrate`.

## Do not touch
- `packages/api-client/generated/` (regenerate with `pnpm codegen`)
- `pnpm-lock.yaml`, except through `pnpm install`

## Before you finish
- `pnpm lint && pnpm typecheck && pnpm test` must pass.

Notice what's missing: no project history, no explanation of Next.js, no full file tree, no credentials. Every line is a command, a location, a non-default rule, or a trap.

One file for both tools

If your team uses both tools, you don't want two files drifting apart. The official docs offer three options:

Let Claude Code read AGENTS.md directly. Recent versions of Claude Code read AGENTS.md as the project instructions when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. One catch: adding a CLAUDE.local.md counts, and by default it stops Claude from reading AGENTS.md. You can change that with the Project instructions setting in /config.

Import it. Create a CLAUDE.md next to your AGENTS.md whose first line is @AGENTS.md, then add any Claude-specific notes below it under their own heading. Claude Code expands the import at launch. This is the most predictable setup, and it works even in sessions that can't load AGENTS.md on their own. Anthropic's docs note that keeping the import never makes Claude read the file twice.

Symlink it. If you have nothing Claude-specific to add, ln -s AGENTS.md CLAUDE.md works. Anthropic recommends the import instead if anyone on the team uses Windows, where symlinks need extra setup and Git may check the link out as a plain text file.

Whichever you pick, verify it. In Claude Code, run /context and check that the file appears under Memory files. In Codex, the docs suggest running codex --ask-for-approval never "Summarize the current instructions." from the repo root and checking that it echoes your guidance.

A short checklist

• The file lives where the tool looks: project root for team rules, ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md for personal ones.
• Build, test, single-test, lint, and type-check commands are written exactly as you run them.
• The repo map covers only the important or surprising parts.
• Conventions listed are ones that differ from what the agent would assume.
• Gotchas and "do not touch" paths are explicit.
• Nothing the agent can read for itself, and no secrets.
• Bullets and headings, not paragraphs.
• Comfortably under 200 lines, with niche rules moved to nested files or path-scoped rules.
• No contradictions between user, project, and nested files.
• Hard requirements are enforced with hooks or permissions, not just written down.
• You checked that the file actually loaded.
• You prune it when the project changes.

A good instructions file is less a manual than a list of things you're tired of repeating. Start with the /init draft, cut what the agent could figure out, and add a line each time you correct the same mistake twice.

Disclosure: I built TokenBar, a $15 Mac menu bar app that shows your Claude and Codex usage and cost, partly so I could see how much a bloated instructions file was costing me. It's at https://tokenbar.site if that's useful.