# How to Set Up a CLAUDE.md That Actually Helps

> Run /init, keep CLAUDE.md under 200 lines, and confirm it loaded with /context. Plus .claude/rules for path-scoped instructions and @path imports.

- Canonical: https://guides-ai.pages.dev/guides/create-claude-md-project-memory/
- Plate 03.01 · Topic: Claude Code commands (https://guides-ai.pages.dev/topics/commands/)
- Published: 10 Jun 2026 · Updated: 06 Sept 2026 · 4 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

`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

```text
/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:

```markdown
# 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

```markdown
---
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

```text
/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](/guides/claude-code-hooks/).

[CLAUDE.md](/glossary/#claude-md) is one of three habits that fix most bad agent output — see
[giving an agent the right context](/guides/ai-coding-agent-context/).

Source: [How Claude remembers your project](https://code.claude.com/docs/en/memory).