CLAUDE.md Best Practices

Overview

CLAUDE.md is your persistent context file. Put it in the project root. Include: tech stack, conventions, boundaries. Keep it under 500 lines. Update it when Claude makes repeated mistakes. This guide is the practical companion to AOL 2 - Aware.

What CLAUDE.md does

Claude Code reads CLAUDE.md at the start of every session. It is system-level context that shapes all of Claude's responses for your project. The agent knows where it is and what the rules are before the first message.

Must have

What the project is and what it does
How to run, build, and test the project
The main technologies and frameworks used
Rules the agent must follow - naming, patterns, what not to touch

Good to have

Project folder structure with short explanation
Links to key /docs files the agent should read first
Recurring corrections - mistakes Claude kept making that you fixed

Avoid

Everything at once - keep it focused
Outdated information - a wrong map is worse than no map
Repeating what Claude can already see in your code

The three-layer strategy

One CLAUDE.md is a start. Three layers is structured intelligence. Each layer loads only where it is needed.

Root - /CLAUDE.md

Global rules: tech stack, build commands, architecture constraints. Every session starts here. Keep it short - this is the map, not the territory.

Sub-folder - /src/api/CLAUDE.md

Folder-specific rules loaded on demand. Less noise. "Always use Zod for API validation" belongs here, not in the root.

Local - CLAUDE.local.md

Your personal preferences. Add to .gitignore. Never commits. Does not affect team standards or token budget.

Traffic Controller pattern

Use CLAUDE.md as a navigation map, not a copy of your docs. Claude fetches only what it needs, when it needs it - keeping the main context lean and focused:

## Documentation Map
For API rules: @docs/api/contracts.md
For UI rules: @docs/design/design-system.md
For business constraints: @docs/business/rules.md

Rule: if it is documented, read it. Do not guess.

If the agent can find it by scanning the project (ls or grep), remove it from CLAUDE.md. TypeScript is visible in package.json. Tailwind is visible in the config. Writing it again wastes tokens and creates drift when things move.

Patterns that work

These three patterns cover most of what makes a CLAUDE.md effective. Each one addresses a common failure mode - vague descriptions, missing boundaries, and repeated corrections.

Reference files

Point Claude to examples rather than describing patterns in prose:

## Reference Files
When creating components, follow the patterns in:
- src/lib/components/ui/Button.svelte (props structure)
- src/lib/components/hub/HubNavCard.svelte (styling approach)

Boundaries

Explicit rules are more reliable than implicit expectations. Tell the agent what it must never do - and what it must always do:

## Boundaries

### Do NOT
- Modify package.json without asking
- Change the build configuration
- Touch .env or credentials files
- Refactor code I did not ask about

### Always
- Run tests after changes
- Use existing design tokens
- Follow the patterns in similar files

Common fixes

Document recurring corrections once, so you stop repeating them in every session:

## Common Mistakes to Avoid
- Do not use $app/stores - use $app/state for Svelte 5
- Do not add comments unless the logic is non-obvious
- Do not create new utility files for one-off functions

Anti-patterns

Most CLAUDE.md files fail in one of these four ways. The result is always the same - the agent ignores the file, contradicts it, or uses it as a source of false confidence.

Too long

Keep under 500 lines. A bloated CLAUDE.md buries the important rules under noise.

Too vague

"Write good code" does nothing. Be specific: what pattern, what file, what token.

Outdated

If your stack or patterns change, the file must change. An outdated map misleads more than no map.

Duplicating docs

Link to /docs files, do not paste them in. CLAUDE.md is the index. /docs is the content.

Iteration process

CLAUDE.md is not a setup task - it is a living document. The best version is never the first version. Build it by working with the agent, not before.

1 Start with the basics - stack, conventions, boundaries

2 Use Claude Code for a week on real work

3 When Claude makes the same mistake twice, add the fix to CLAUDE.md

4 When Claude asks questions you have answered before, add the answer

Treat CLAUDE.md like code. Every repeated correction is a signal that the file needs updating. Every answered question that reappears is a missing rule.

To get started faster, download the ABA starter files and let Claude set up or improve your project from them. See Downloads for the files and the setup prompt.

Starter file

CLAUDE.md Starter A clean template with the structure that matters. Delete what does not apply, keep what does.