How to Write a CLAUDE.md File (and AGENTS.md) That Actually Works (2026)

What is a CLAUDE.md file?

A CLAUDE.md is a plain-markdown file of standing instructions that Claude Code reads at the start of every session — the persistent memory a stateless model otherwise lacks. Put it in your project root and Claude loads it automatically; mechanically, its contents are added to your prompt as context on every request. Anthropic documents the full system in the Claude Code memory docs.

Think of it as an onboarding script for your codebase. Without one, Claude starts fresh each session — re-exploring your code, guessing your conventions, and making assumptions you then have to correct. With a good one, it already knows your stack, your commands, and your rules. That difference is most of what separates a frustrating Claude Code session from a productive one.

Why shorter is better (the instruction budget)

Here's the part most guides miss: a bigger CLAUDE.md is not a better one. The whole file loads into context on every single prompt, and models reliably follow only a finite number of instructions — practitioners put it around 150–250 before adherence falls apart. Claude Code's own system prompt already spends some of that budget.

And the failure mode isn't graceful. When you go over budget, the model doesn't cleanly obey the first 200 instructions and ignore the rest — quality degrades across all of them (the effect researchers call "context rot"). A single vague or wrong line doesn't just get ignored; it can quietly worsen every response. That's why experienced users treat CLAUDE.md as a liability to minimize: target under ~200 lines, and the real skill on each model upgrade is deciding what to remove, not what to add.

What to put in a CLAUDE.md (and what to leave out)

The filter that works: would a competent senior developer joining your team already know this? If yes, leave it out. Only write down the context they'd actually need. In practice that's five kinds of thing — kept as short, headed, bulleted sections, not prose:

What to leave out

Three things bloat a CLAUDE.md without helping. Code-style rules ("use 2-space indentation") belong in your linter and formatter, enforced by a PostToolUse hook — a formatter is deterministic; a CLAUDE.md instruction is an expensive, less reliable version of the same thing. Step-by-step procedures belong in a skill or a slash command, which load only when needed. And anything that only matters for one corner of the codebase belongs in a path-scoped rule under .claude/rules/, not in the always-loaded file.

Be specific or don't bother. "Write clean code" and "be careful with the database" change nothing — the model can't act on them. "TypeScript strict mode, no any types" and "never delete rows in the audit table" do. Every line should produce a measurable difference in the output; if it wouldn't, cut it.

A full CLAUDE.md you can copy into any project

The most-copied CLAUDE.md in the world isn't tied to any stack — it's a set of universal behavior rules that fix the mistakes every coding agent makes. This one, from Forrest Chang, distills Andrej Karpathy's observations on where LLM coding agents go wrong; it has passed 100,000 GitHub stars and works with any agent — Claude Code, Codex, Cursor, or Gemini CLI. Drop it into any repo as-is, and, as the file itself notes, merge your project-specific sections (the stack, commands, and conventions from above) on top. Grab the current version from the andrej-karpathy-skills repo.

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Where CLAUDE.md lives: the memory hierarchy

CLAUDE.md files load in a hierarchy, from broad to specific, and all of them are concatenated into context. You'll mostly use the project and user levels.

Keep it lean: imports, rules, and skills

The way to stay under budget without losing detail is to push detail out of the always-loaded file. CLAUDE.md can import another file with @path syntax — for example, a single line pointing at docs/conventions.md keeps a long style guide out of the main file (note: imported files still load at launch, so they're for organization, not for hiding a huge document). Path-scoped rules in .claude/rules/ load only when Claude touches matching files. Skills and slash commands hold procedures and load only when invoked.

It helps to picture the layers: CLAUDE.md is always in context, path-scoped rules load when relevant, skills load on demand, and hooks run deterministically no matter what the model decides. Put each instruction where it belongs, and CLAUDE.md stays short. Our guide to Claude Code memory goes deeper on the automatic-memory side, and the best Claude Code prompts include the "add a rule to CLAUDE.md so this stops happening" habit that grows the file the right way.

Should you use /init to generate it?

This is where practitioners split. Running /init has Claude analyze your codebase and write a starter CLAUDE.md — Anthropic recommends it, and it's a genuinely useful bootstrap. The counter-argument, from developers who've maintained these files at scale, is that AI-generated instructions come out verbose and vague, exactly the bloat that hurts adherence.

The reconciliation: use /init to get a first draft fast, then curate it down hard — cut the generic lines, keep the few that capture something Claude wouldn't discover on its own. A good final file usually looks nothing like the generated one. And a strong habit for growing it over time: when you correct Claude on something twice, tell it to "add a rule to CLAUDE.md so this stops happening" — the file then only ever grows by things that actually tripped you up.

Tips for writing instructions that stick

Beyond keeping it short, a few habits measurably improve how reliably Claude follows the file:

1. 01Be specific and verifiable: "use named exports, not default exports" beats "keep the code clean." If you can't check whether Claude obeyed it, rewrite it.
2. 02Exploit position: models pay most attention to the top and bottom of a document and least to the middle — put your most important rules first, and your hard "do nots" last.
3. 03Emphasize the critical few: IMPORTANT, MUST, or caps on the handful of rules that really matter helps them land.
4. 04Give it the test command so it can check its own work — self-validation is worth more than another paragraph of instruction.
5. 05Remove, don't just add. On every model upgrade, open your busiest project's CLAUDE.md and ask what you can delete — merge near-duplicates, cut anything that no longer changes the output.
6. 06Resolve contradictions: if two lines disagree, Claude picks one at random. Review the file (and any nested ones) periodically and delete conflicts.

What is AGENTS.md, and how does it relate to CLAUDE.md?

AGENTS.md is the tool-agnostic version of the same idea: "a README for agents," a predictable place at the repo root for the context and rules an AI coding agent needs. It's an open standard stewarded under the Linux Foundation, adopted by 60,000+ projects and read by 20+ tools — OpenAI Codex, Cursor, GitHub Copilot, Google's Jules and Gemini CLI, Devin, Zed, Aider, Windsurf, and more (the full list is at agents.md). Because it's not locked to one vendor, it's the better choice when you want portability across tools instead of a Claude-only or Gemini-only file.

The content principles are identical — short, specific, sectioned — with a few AGENTS.md-flavored habits from people who use it heavily: put the commands near the top (the agent needs to know how to run things first), show a right-vs-wrong code example instead of describing your style in prose, pin exact stack versions, and paste a two-level file tree so the agent knows the layout. In a monorepo, a nested AGENTS.md per directory can add local rules and point back to the root file.

The catch for Claude Code users: Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already has an AGENTS.md, don't duplicate it — create a CLAUDE.md whose first line is @AGENTS.md (which imports it), then add any Claude-specific notes below. A symlink works too (ln -s AGENTS.md CLAUDE.md). Either way, both tools read one source of truth. Running /init in a repo that already has an AGENTS.md will fold it in for you.

The bottom line

Whether you call it CLAUDE.md or AGENTS.md, the file is the highest-leverage thing you control after your choice of model — and the discipline is the same: write down only what the agent couldn't figure out on its own, say it specifically, and keep it short enough that every line still counts. Start small, add a rule only when a real mistake earns it, and prune on every upgrade. If you're still choosing an agent, our best AI coding tools guide compares the field, and Claude Code is in our directory.