Structure CLAUDE.md So Claude Code Gets the Right Context

An agent cannot infer your repository's commands, boundaries and non-obvious rules reliably from filenames alone. CLAUDE.md supplies the small set of durable facts Claude Code should know before it edits anything.

When to use

Document the exact commands that validate a change.
Protect generated files and architectural boundaries.
Load specialized instructions only when work enters a subdirectory.

Example

A React and API monorepo requires tenant checks in every endpoint and forbids direct database access outside one folder. Put those rules beside the commands Claude must run.

TL;DR

Short, specific, commands first. Generate a draft with /init, then cut it down.

Claude Code

/init

Steps

Use this skeleton

Replace this compact example with your real commands and the few architectural rules that are easy for an agent to violate.

CLAUDE.md

# Project
TypeScript API + React app. Postgres via Drizzle.

## Commands
- Dev: `npm run dev`
- Test one file: `npx vitest run <path>`
- Typecheck: `npm run typecheck`

## Architecture
- API handlers: src/server/routes/
- DB access only through src/server/db/

## Rules
- Never edit generated files in src/gen/
- Every endpoint checks the tenant from the session, never from the body
- Add a test for every bug fix

@docs/api-conventions.md

2
Know where files load from
Choose the narrowest scope that fits the rule: personal defaults, a committed project file, or instructions local to one module.
paths
```
./CLAUDE.md            # project, committed
~/.claude/CLAUDE.md    # personal, all projects
src/billing/CLAUDE.md  # loaded when working in that folder
```
3
Add a rule on the fly
Use /memory to inspect which files are loaded and edit the appropriate one when Claude repeats a project-specific mistake.
Claude Code
```
/memory
```

Gotchas

Long files get ignored; keep it to what the agent gets wrong without it.
Write rules as commands ("Never…", "Always…"), not explanations.
Do not paste code style a linter already enforces.
Use @path imports instead of duplicating other docs.

Cheat sheet

/init	Generate a first CLAUDE.md
/memory	Edit loaded memory files
@path/to/file.md	Import another file
~/.claude/CLAUDE.md	Personal rules

Sources

Claude Code docs: Memory

Reviewing agent output? CodeCrab reviews pull requests locally with your own AI tools.

Previous Next