CLAUDE.md best practices (and AGENTS.md, GEMINI.md)

The best CLAUDE.md is short (well under 200 lines), specific and verifiable: the commands to build and test, the conventions the agent can’t guess from the code, and the mistakes it has already made once. Everything else, such as a tour of the folder tree, long procedures or general advice like “write clean code”, either belongs somewhere else or doesn’t belong at all.

This guide covers what CLAUDE.md, AGENTS.md and GEMINI.md are, where each agent looks for them, what to write and what to leave out, how imports work, and how to keep one file that every agent on the project reads.

What these files are

Coding agents start every session with no memory of your project. An instructions file is the note you leave for them: a plain Markdown file that the CLI reads at launch and adds to the model’s context window before your first message.

AGENTS.md came out of a collaboration between OpenAI Codex, Amp, Google Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. It is the closest thing to a shared standard. Claude Code kept its own name, but recent versions (v2.1.277 and later) read AGENTS.md natively when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it.

Where the files live

All three agents use the same idea: a global file for you, a project file for the team, and optional files deeper in the tree for one part of the code.

Claude Code

Files in the working directory and the directories above it load at launch and are concatenated, not overridden. Nested files in subdirectories load on demand, the first time Claude touches files in that folder. Run /context to see which memory files are actually loaded, and /memory to open one for editing.

Codex

Codex reads a global ~/.codex/AGENTS.md (or AGENTS.override.md), then walks from the git root down to the current directory and takes one file per folder: AGENTS.override.md if present, otherwise AGENTS.md. Deeper files come later in the combined text, so they win when two rules conflict. The total is capped by project_doc_max_bytes, 32 KiB by default, and the chain is built once per session. More on the CLI itself on the Codex page.

Gemini CLI

Gemini CLI loads ~/.gemini/GEMINI.md, then the files in your workspace directories and their parents, and picks up more files as its tools visit other folders. Everything is concatenated and sent with every prompt. /memory show prints the combined text and /memory reload re-reads it after you edit.

What to put in

Write for a capable new teammate who has never seen the repo and will not ask questions. Each line should be something the agent can act on and you can check.

• Commands. How to install, build, run one test, run all tests, lint and type-check. This is the single most useful section; without it, the agent guesses.
• Conventions the code doesn’t show. “Use pnpm, not npm.” “New API routes go through withAuth().” “Dates are stored in UTC.”
• Boundaries. “Never edit files under generated/.” “Don’t touch the migrations folder without asking.”
• How to finish a task. “Run pnpm test and pnpm typecheck before saying you’re done.” “Commit messages follow Conventional Commits.”
• Known traps. The mistake the agent made twice last week, stated as a rule.

A good rule is concrete. “Use 2-space indentation” works; “format code properly” doesn’t. “Run npm test before committing” works; “make sure things work” doesn’t.

A compact example

# Project notes

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- One test: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- TypeScript strict; no `any` in new code.
- Server code lives in `src/server`, UI in `src/ui`; never import server code from UI.
- Database access only through `src/server/db.ts`.

## Don’t
- Don’t edit `src/generated/` (run `pnpm codegen` instead).
- Don’t add dependencies without saying why in the summary.

## Learned the hard way
- The payments tests need `STRIPE_KEY=test`; they fail silently without it.

That is about 20 lines, and it covers most of what an agent needs on day one.

What to leave out

Keep it short

Every line in CLAUDE.md is sent at the start of every session and stays in context for the whole conversation. Anthropic’s own docs suggest staying under 200 lines per file, and note that longer files reduce how reliably Claude follows them. The pattern is familiar: the more rules there are, the more each one gets diluted.

A few habits help:

• Add a rule only when you need it. The agent made the same mistake twice, a review caught something, or you keep typing the same correction. That is the signal.
• Prune when you add. If a rule hasn’t mattered in a month, cut it.
• Prefer pointers over paste. “The release process is in docs/release.md” costs one line; pasting the process costs fifty.
• Use HTML comments for notes to humans. Claude Code strips block-level <!-- --> comments before sending the file.

If token cost is on your mind, the Claude Code token usage guide goes into what else fills the context.

Imports and path-scoped rules

Claude Code lets a CLAUDE.md pull in other files with @path:

See @README.md for the overview.
Coding rules: @docs/conventions.md
@~/.claude/my-preferences.md

Paths are relative to the file that contains the import, imports can nest up to four hops, and @ inside code spans or code blocks is ignored. The first time a project imports files from outside the repo, Claude Code asks you to approve them.

One catch: imports organise the text, but they don’t save tokens. An imported file is loaded in full at launch, just like the parent. For rules that only matter in part of the tree, use .claude/rules/*.md with a paths: glob in the frontmatter, so they load only when Claude works on matching files:

---
paths: ["src/api/**/*.ts"]
---
- Every handler validates input with zod before touching the database.

Gemini CLI supports the same @file.md import syntax in GEMINI.md.

One file for every agent

If your team uses more than one CLI, maintaining three files with the same rules is how they drift apart. The usual setup:

1. Put the shared rules in AGENTS.md. Codex, Cursor, Copilot, opencode and most others read it directly.

2. Create a CLAUDE.md that imports it and adds anything Claude-specific:

   @AGENTS.md
   
   ## Claude Code only
   - Use the project's /review skill before opening a PR.

3. In Gemini CLI, add AGENTS.md to the file names it looks for, in .gemini/settings.json:

   { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

A symlink (ln -s AGENTS.md CLAUDE.md) also works on macOS and Linux, but the import approach is clearer and doesn’t depend on how Windows handles links. Claude Code also has a “Project instructions” setting in /config if you want it to read both CLAUDE.md and AGENTS.md together.

Writing the first version

You don’t have to start from a blank page. In Claude Code, /init reads the repo and drafts a CLAUDE.md. Treat that draft as raw material: keep the commands, delete the folder tour, and cut anything you wouldn’t tell a new teammate on their first morning.

Then let the file grow from real work. Each time you correct the agent, ask yourself whether the correction would apply next week too. If yes, it is a candidate rule.

Doing it with AgentVera

AgentVera runs Claude Code, Codex, Gemini CLI and other CLIs side by side in real terminals. Each agent still reads its own CLAUDE.md, AGENTS.md or GEMINI.md exactly as described above; AgentVera doesn’t replace those files. A few features work alongside them:

• Rule suggestions from your corrections. When you send an agent’s work back from the review inbox with a note, or Verify finds a failed criterion, a small Claude model turns the correction into one short rule. It shows up under Rule suggestions; Add to instructions appends it to the project’s CLAUDE.md and AGENTS.md (whichever exist), and rules already in the files are skipped. If neither file exists, it creates AGENTS.md and a CLAUDE.md that imports it with @AGENTS.md.
• Per-agent roles instead of a bloated shared file. The “Role and instructions” field in the agent dialog is given to that one agent (Claude gets it appended to its system prompt, Codex as developer instructions). Agent-specific roles stay out of the shared file. Cursor, Gemini CLI and Amp don’t use this field and rely on the project’s AGENTS.md or rule files instead.
• A code map, so you can skip the folder tour. The project map is built locally and offered to agents as MCP tools (map_related, map_outline, map_usages and others), and new agents get a short summary of modules, entry points and the test command. That is the part people tend to paste into CLAUDE.md by hand.
• Project memory. AgentVera Brain reads your Git-tracked docs, including CLAUDE.md and AGENTS.md, along with commits, PRs and past conversations, and tracks which decisions are current or stale. An optional context pack (off by default) can be added to new agents’ instructions.
• Procedures as skills. The skill gallery manages SKILL.md folders for Claude Code and Codex, which is where long procedures belong.
• Rules that must always run. CLAUDE.md is advice; for checks that must happen every time, use Claude Code hooks, and move narrow side tasks to subagents.

Checklist

• Under 200 lines; ideally under 100.
• Build, test, lint and type-check commands are listed and correct.
• Every rule is specific enough to check.
• No folder tour, no secrets, no generic advice.
• Folder-specific rules are in nested files or path-scoped rules.
• Long procedures are in skills or docs, linked by one line.
• Hard limits are enforced with hooks or permissions, not prose.
• Shared rules live in AGENTS.md; CLAUDE.md imports it.
• Personal preferences are in ~/.claude/CLAUDE.md or CLAUDE.local.md.

Wrapping up

An instructions file is the cheapest way to make an agent behave like it has worked on your project before. Keep it short, keep it concrete, and let it grow only from mistakes you’ve actually seen. Put shared rules in AGENTS.md so every CLI reads the same thing, move procedures into skills, and enforce the things that really matter with hooks rather than sentences.