# CLAUDE.md guide: how to write one Claude follows

> What CLAUDE.md is, where it goes, what to put in it, a short template, how it works with AGENTS.md, and how to run Claude Code with it on an API key.

Updated: 2026-11-02

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. Put it at the root of your repository and keep it short: the exact commands, conventions and corrections Claude can't work out from the code. Run `/init` to generate a first draft, then cut every line Claude doesn't need.

## What is CLAUDE.md?

Every Claude Code session starts with a fresh context window, and `CLAUDE.md` carries what Claude should know about your project from one session to the next. Claude treats it as context, not enforced configuration, so the more specific and concise the file, the more consistently Claude follows it.

## Where does CLAUDE.md go?

The location decides who gets the instructions:

| Scope | Location | Who gets it |
| --- | --- | --- |
| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Your whole team, through source control |
| Local | `./CLAUDE.local.md`, added to `.gitignore` | Only you, in this project |
| User | `~/.claude/CLAUDE.md` | Only you, in all your projects |
| Managed | A system folder your IT team controls, such as `/etc/claude-code/CLAUDE.md` on Linux | Everyone in your organization |

Claude Code loads `CLAUDE.md` and `CLAUDE.local.md` from the directory where you start it and every directory above it, and joins them rather than letting one override another. A file in a subfolder, such as `packages/api/CLAUDE.md`, loads once Claude works on a file in that folder. Run `/context` and look under **Memory files** to see what loaded.

## How do you create a CLAUDE.md?

Run `/init` in your project. Claude reads the codebase and writes a first `CLAUDE.md` with build commands, test instructions and the conventions it finds, or suggests improvements to an existing one. It also carries over rules you wrote for other tools, such as `.cursorrules`. From there the work is mostly removing lines.

For a guided version, start Claude Code with `CLAUDE_CODE_NEW_INIT=1 claude` and run `/init`: it asks follow-up questions and shows a proposal before it writes anything.

## What should go in CLAUDE.md?

Every line takes a little of Claude's attention on every task, so keep only what Claude can't work out from the code:

- **How to check work:** the exact test, typecheck and lint commands, and how to run one test file.
- **Where the code misleads:** an old pattern that new code must not copy, or a folder that looks unused but isn't.
- **Decisions that aren't in the repository:** which error helper the team chose, how deploys work, what needs a migration review.
- **Corrections you've made twice.**

Leave out directory layouts and dependency lists, which Claude reads from the repository. Some lines belong somewhere else:

| If the line is | Move it to |
| --- | --- |
| A multi-step procedure, such as cutting a release | A [skill](https://5abeer.ai/en/guides/claude-code-skills), whose full text loads only when used |
| A rule for one part of the codebase | `.claude/rules/`, with a `paths` field |
| Something that must happen every time, such as running the formatter | A [hook](https://5abeer.ai/en/guides/claude-code-hooks), which runs on every matching event |
| Your personal preference | `CLAUDE.local.md` or `~/.claude/CLAUDE.md` |

## A CLAUDE.md template

Anthropic's best-practices guide gives this short file as an example. Replace the commands and rules with your own:

```text
# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
```

The typecheck line is only the command, so Claude can check its own work. "Always typecheck before you finish" works most of the time, not every time; to enforce it, use a `Stop` hook.

Write each line so you could verify it:

| Vague | Concrete |
| --- | --- |
| Format code properly | Use 2-space indentation |
| Test your changes | Run `npm test` before committing |
| Keep files organized | API handlers live in `src/api/handlers/` |

Keep the file under about 200 lines, grouped under headers and bullets, and run `/doctor prompt-audit` now and then to find stale or conflicting instructions.

## Imports and path rules

A `CLAUDE.md` can pull in another file with an `@path` line, such as `- Git workflow: @docs/git-instructions.md`. Relative paths resolve from the file that holds the import, and a path inside backticks stays plain text instead of an import. Imports organize a long file but don't lower its context cost, because the imported text loads with it.

To load a rule only where it applies, put it in `.claude/rules/` with a `paths` field. Without `paths`, a rule loads at launch like `CLAUDE.md`:

```text
---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it
```

## Does Claude Code read AGENTS.md?

Yes, from version 2.1.277, so a repository set up for other coding agents works without a `CLAUDE.md`. By default:

| Your repository has | Claude Code reads |
| --- | --- |
| `AGENTS.md`, and no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | `AGENTS.md` |
| `AGENTS.md` and one of those three files | The `CLAUDE.md` files only |
| A `CLAUDE.md` that imports `@AGENTS.md` | Both |

Your `~/.claude/CLAUDE.md` and `.claude/rules/` don't count for that check. A `CLAUDE.local.md` does, so adding one for your own notes stops Claude from reading the team's `AGENTS.md`. To have Claude read both, type `/config` and set **Project instructions** to `claude-md-and-agents-md`.

With a custom base URL, as on a 5abeer key, this needs version 2.1.281 or later, the release that brought `AGENTS.md` support to LLM gateways. On older versions, or to add lines only Claude needs, start a `CLAUDE.md` with an import:

```text
@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.
```

## Common CLAUDE.md mistakes

- **A long file.** Past about 200 lines, single lines get lost. Move procedures into skills and folder rules into `.claude/rules/`.
- **Contradictions.** When two lines disagree, Claude may pick either one, so read all your instruction files together.
- **Emphasis instead of a fix.** IMPORTANT or capital letters rarely help current models and mostly make Claude over-apply the rule.
- **Rules that must never bend.** "Never read .env" works almost every time, not every time. Use a deny rule or a hook for those.

## CLAUDE.md or auto memory?

You write `CLAUDE.md`. Auto memory is the notes Claude writes for itself, such as corrections you gave, in `~/.claude/projects/<project>/memory/`. Claude Code loads your `CLAUDE.md` in full, but only the first 200 lines or 25KB of the memory index, `MEMORY.md`. Auto memory stays on your machine, so your team never sees it.

Say "remember that the API tests need a local Redis" and Claude saves it to auto memory; say "add this to CLAUDE.md" to put it in the file. `/memory` opens both and turns auto memory on or off. For skills, hooks and subagents side by side, see [Claude Code skills](https://5abeer.ai/en/guides/claude-code-skills#vs-claude-md).

## Does CLAUDE.md add to the cost?

A little. On an API key, its text is ordinary input on every task, billed per token at the model's price. Block-level HTML comments are removed before the file reaches Claude, so notes you leave there cost nothing. The current price of the default model:

Claude Sonnet 5.5 (`claude-sonnet-5.5`) per 1M tokens: input $0.60 (official $2), output $3 (official $10). Official price checked October 19, 2026.

## CLAUDE.md through 5abeer

5abeer is an independent service, not affiliated with Anthropic. Its API follows the Anthropic Messages format, so Claude Code works with it as it ships, and both routes cost less than the official price. `CLAUDE.md` is a file on your machine, so it works the same on a 5abeer key; only the base URL and key change.

**With an API key:** create a key for Claude models, then set the base URL and key in Claude Code's settings:

| Format | Base URL | Key header |
| --- | --- | --- |
| OpenAI | `https://api.5abeer.ai/v1` | `Authorization: Bearer <KEY>` |
| Anthropic | `https://api.5abeer.ai` | `x-api-key: <KEY>` |
| Gemini | `https://api.5abeer.ai/v1beta` | `x-goog-api-key: <KEY>` |

`~/.claude/settings.json`

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.5abeer.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_5ABEER_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5.5"
  }
}
```

Every request is deducted from your balance by model and token count, and you control each key with a spend limit, an expiry date and an IP allow-list. The full setup is in [Claude Code setup](https://5abeer.ai/en/docs/apps/claude-code.md), and prices are on [Claude API](https://5abeer.ai/en/api/claude).

The Messages API doesn't read `CLAUDE.md`, so from your own code, send the same rules in the request's `system` field, as in [Anthropic Messages](https://5abeer.ai/en/docs/api/messages.md#params).

**With a plan:** the 5abeer AI app turns Claude Code on for your plan in one click, with no key and no files to edit. The plan runs with a 5-hour limit and a weekly limit, as in [Subscription limits](https://5abeer.ai/en/docs/subscriptions/limits.md). Plans are for the supported apps, and to use the models from your own code you need an API key. See [What each plan runs](https://5abeer.ai/en/docs/subscriptions/plan-apps.md#claude-code) and the [pricing page](https://5abeer.ai/en/pricing).

## FAQ

### Does the file have to be called CLAUDE.md?

Yes, or `CLAUDE.local.md` for your own notes. Claude Code also reads `AGENTS.md` when there is no `CLAUDE.md`. Any other file loads only through an `@path` import or from `.claude/rules/`.

### Should CLAUDE.md go in git?

The project file, yes: committing it gives your team the same instructions. Keep personal notes in `CLAUDE.local.md`, listed in `.gitignore`. That file exists only in the worktree where you made it, so across worktrees, import one from your home folder, such as `@~/.claude/my-project-instructions.md`.

### How long should CLAUDE.md be?

Under about 200 lines, as Anthropic recommends; Claude Code warns at startup and in `/status` when a file runs longer. Subfolder files and path rules, which load on demand, are cut at 40,000 characters on a 200K context window.

### Why does Claude ignore my CLAUDE.md?

Run `/context`. If a file that should load at launch isn't under **Memory files**, check its name and location. If it loaded, make the line more specific, remove anything that contradicts it, and shorten the file. A rule that must hold every time belongs in a hook.

### Does CLAUDE.md survive /compact?

The project-root `CLAUDE.md` does: Claude Code reads it again from disk after `/compact`. Subfolder files and path rules return when Claude next works on a matching file. Instructions you gave only in the chat can be lost, so put the ones you want kept in the file.

## Sources

Checked on 2 November 2026.

- [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Claude Code docs: Best practices for Claude Code](https://code.claude.com/docs/en/best-practices)
- [Claude Code changelog](https://code.claude.com/docs/en/changelog), versions 2.1.277 and 2.1.281

## Get started

To compare plans and keys for Claude Code, read [The cheapest way to use Claude Code](https://5abeer.ai/en/guides/claude-code-cheapest-way), or set up Claude Code now.