# CLAUDE.md: how to write one that actually works

> What CLAUDE.md is, where it goes, how /init and imports work, and a template of rules a coding agent follows. Includes what to leave out and how AGENTS.md fits in.

Source: https://devaiper.com/blog/claude-md-guide
Published: 2026-10-08
Topics: Claude Code, Prompt engineering, Context

**Short answer:** CLAUDE.md is a markdown file Claude Code reads at the start of every session. Keep it under about 200 lines, make each rule concrete and checkable, put only repo-wide facts in it, and run /init to generate a first draft.

Every Claude Code session starts with an empty context window. It does not remember that your tests run with `pnpm test:unit`, that you banned default exports, or that the `legacy/` folder is off limits. **CLAUDE.md is where you write that down once** so you stop retyping it.

## What belongs in it

Treat it as the page you would hand a new teammate on day one. Add a line when:

- the agent makes the same mistake a second time,
- a code review catches something it should have known about this repo,
- you type the same correction into chat that you typed yesterday.

Good content is facts that hold in **every** session: build, test and lint commands, project layout, naming conventions, and "always do X" or "never do Y" rules.

## Where the file lives

> **Diagram:** CLAUDE.md files load from broadest to most specific. Organization policy first, then your user file in the home folder, then the project file in the repo, then the local personal file. More specific instructions appear later in context.
> Managed policy (organization-wide, set by IT) → ~/.claude/CLAUDE.md (your personal rules for every project) → ./CLAUDE.md or ./.claude/CLAUDE.md (team rules, committed to git) → ./CLAUDE.local.md (your private notes for this repo, in .gitignore)
> Load order, broadest first. Later (more specific) files appear later in context.

Files in parent directories load at launch; files in subdirectories load on demand when the agent works there. Run `/context` in a session to confirm your file loaded.

## Start with /init

Run `/init` in your repo. Claude analyzes the codebase and writes a first CLAUDE.md with the build commands, test instructions and conventions it finds. If one exists, it suggests improvements instead of overwriting. Then **edit it**: delete what the agent could work out itself and add what it could not.

## Write rules it can verify

Vague rules get ignored. Concrete ones get followed.

| Weak | Strong |
|---|---|
| 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/` |
| Write good commits | Commit messages: imperative mood, max 72 chars, no emoji |

## A template that stays short

```markdown
# Project: invoice-api

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint + types (run before every commit): `pnpm lint && pnpm tsc --noEmit`

## Layout
- `src/api/handlers/` HTTP handlers, one file per route
- `src/domain/` pure business logic, no I/O
- `src/db/` queries; never import from here in `domain/`

## Conventions
- TypeScript strict, no `any`. Use `unknown` and narrow.
- Named exports only.
- Errors: throw `AppError` subclasses, never strings.

## Don't
- Don't edit files in `generated/`.
- Don't add dependencies without asking.
```

## Import instead of copy

CLAUDE.md can pull in other files with `@path` syntax:

```markdown
See @README.md for the overview and @package.json for npm scripts.
- Git workflow: @docs/git-instructions.md
```

Imports load at launch, so they organize a long file but **do not reduce its context cost**. For rules that only matter in one area, use path-scoped rules in `.claude/rules/` or a skill so they load only when relevant.

## If you already have AGENTS.md

Claude Code can read a repo's `AGENTS.md` in place of CLAUDE.md. To keep one source of truth, make `CLAUDE.md` a thin file that imports it:

```markdown
@AGENTS.md

## Claude Code only
- Use plan mode for changes that touch more than three files.
```

## Mistakes that make it worse

- **Too long.** Past roughly 200 lines, adherence drops and you pay for the tokens every session.
- **Contradictions.** Two rules that disagree get resolved arbitrarily. Review it now and then; `/doctor prompt-audit` can find outdated and conflicting instructions.
- **Style essays.** "Write clean, maintainable code" does nothing. Delete it.
- **Treating it as enforcement.** It is context. For must-never-happen rules, use a hook.
- **Secrets.** It is committed to git. Never put keys in it.

## Quick checklist

1. Run `/init`, then cut it down.
2. Every line is checkable by a test, a command or a glance.
3. Under about 200 lines.
4. Personal stuff in `~/.claude/CLAUDE.md` or `CLAUDE.local.md`.
5. Review it whenever the agent repeats a mistake.

Related: [what is Claude Code](https://devaiper.com/blog/what-is-claude-code) and [context engineering](https://devaiper.com/blog/what-is-context-engineering). Official reference: [How Claude remembers your project](https://code.claude.com/docs/en/memory).

## FAQ

### What is a CLAUDE.md file?

A markdown file of persistent instructions that Claude Code loads at the start of every session: build and test commands, conventions, project layout and always-do rules.

### Where do I put CLAUDE.md?

For a project, put it at ./CLAUDE.md or ./.claude/CLAUDE.md and commit it. Personal preferences for all projects go in ~/.claude/CLAUDE.md. Private per-project notes go in CLAUDE.local.md, which you add to .gitignore.

### How long should CLAUDE.md be?

Aim for under 200 lines. Longer files use more context and make the agent less likely to follow each rule. Move part-of-the-codebase instructions into path-scoped rules or skills.

### Is CLAUDE.md guaranteed to be followed?

No. It is context, not enforced configuration. If an action must be blocked every time, use a hook, not an instruction.

### What is the difference between CLAUDE.md and AGENTS.md?

AGENTS.md is a tool-neutral convention some repositories use for agent instructions. Claude Code can read a repository's AGENTS.md in place of CLAUDE.md, and you can import AGENTS.md from CLAUDE.md so both stay in sync.