How to Set Up a CLAUDE.md That Actually Helps

CLAUDE.md is the file Claude Code reads at the start of every session. Put your project’s rules in it and stop repeating yourself. It can live at the repo root as ./CLAUDE.md or as ./.claude/CLAUDE.md — both work.

1. Generate a draft

/init

What it does: analyzes your codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it can discover. If one already exists, /init suggests improvements rather than overwriting it.

2. Write what it keeps getting wrong

The draft covers what Claude could work out for itself. Your job is the rest:

# Project: my-app

## Commands
- Install: `pnpm i`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Conventions
- TypeScript strict. No `any`.
- Use the existing `db` helper in `src/lib/db.ts` — don't add a new client.

## Don't
- Don't edit anything in `src/generated/`.

What it does: gives commands, conventions and no-go zones in a shape Claude can scan. Add an entry when Claude makes the same mistake twice, or when you type the same correction you typed last session.

3. Keep it under 200 lines

Anthropic’s guidance is explicit: longer files consume more context and reduce how reliably Claude follows them. Specific beats vague — “Use 2-space indentation” works where “format code properly” does not.

4. Split anything bigger

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- All endpoints validate input before touching the database.

What it does: as .claude/rules/api.md, this loads only when Claude reads a matching file, so specialist rules cost nothing on unrelated work. You can also pull in another file anywhere in CLAUDE.md with @path/to/file — including @AGENTS.md, since Claude Code doesn’t read AGENTS.md on its own.

Verify it worked

/context

What it does: shows what actually loaded. Check the Memory files list — if your file isn’t there, Claude cannot see it and nothing in it is being applied. This is the single check most people skip.

Good to know

• ~/.claude/CLAUDE.md applies to all your projects. CLAUDE.local.md is per-project and belongs in .gitignore.
• Commit the project file so your team benefits.
• /memory opens memory files for editing and toggles auto memory — the notes Claude now saves itself from your corrections.
• It’s context, not enforcement. For a rule that must hold regardless, use a hook.

CLAUDE.md is one of three habits that fix most bad agent output — see giving an agent the right context.

Source: How Claude remembers your project.