What Is CLAUDE.md?#

CLAUDE.md is a configuration file read by AI coding agents (Claude Code, Codex, Cursor Agent, Gemini CLI) at the start of every session. It provides persistent context — build commands, coding conventions, architectural decisions, style preferences — so the agent doesn’t have to rediscover your project every time.

Think of it as your project’s constitution. Once it’s set, every agent session follows the same rules, every team member benefits from shared conventions, and you stop repeating yourself.

CLAUDE.md vs. Auto Memory: Two Systems, One Goal#

Claude and Codex both have two complementary memory systems. Understanding the difference matters:

Rule of thumb: Write CLAUDE.md for things you know. Let auto memory handle things the agent discovers.

Where to Place Your CLAUDE.md Files#

CLAUDE.md files follow a precedence hierarchy — more specific locations override broader ones:

1
Your repo/
2
├── CLAUDE.md               # Project-level (loaded first)
3
├── src/
4
│   ├── CLAUDE.md           # Scoped to /src
5
│   └── components/
6
│       └── CLAUDE.md       # Scoped to /src/components
7
├── .claude/
8
│   ├── CLAUDE.md           # Session local overrides
9
│   └── rules/
10
│       ├── backend.md      # Rules for /backend
11
│       └── frontend.md     # Rules for /frontend
12
└── tests/
13
    └── CLAUDE.md           # Test-specific rules

Practical tip: Start with one CLAUDE.md at the repo root. Add folder-scoped rules only when you find yourself repeating conventions that only apply to one part of the codebase.

The Anatomy of a Great CLAUDE.md#

Here’s a template that works for most projects:

1
# Project Overview
2

3
This is a Flutter mobile app for [what it does].
4
Tech stack: Flutter 3.24+, Dart 3.5+, Firebase, Riverpod.
5

6
## Build & Run
7

8
- Build: `flutter build apk --release`
9
- Run (dev): `flutter run`
10
- Test: `flutter test`
11
- Lint: `dart fix --apply`
12

13
## Architecture
14

15
- State management: Riverpod (not BLoC, not Provider)
16
- Navigation: GoRouter with shell routes
17
- DI: Riverpod providers only (no GetIt)
18
- API layer: Dio with interceptor-based auth
19

20
## Code Style
21

22
- Use `sealed class` not `freezed` for state classes
23
- Prefer `AsyncValue` over `FutureBuilder`
24
- Error handling: return `Either<Failure, T>` from repos
25
- Named parameters > positional (except for required IDs)
26
- No `print()` — use `Logger` from `logging` package
27

28
## Testing
29

30
- Unit tests for providers and repos
31
- Widget tests for screens
32
- Integration tests for critical flows
33
- Mock: `mocktail` (not `mockito`)
34

35
## Never
36

37
- Never use `BuildContext` outside of widget tree
38
- Never import `material.dart` in domain layer
39
- Never commit `print()` statements
40
- Never generate code with `build_runner` manually (use hooks)

Templates by Stack#

1
# Build
2
- Dev: `npm run dev`
3
- Test: `npm test`
4
- Build: `npm run build`
5
- Type check: `npx tsc --noEmit`
6

7
# Conventions
8
- File structure: Feature folders, not type folders
9
- Path aliases: `@/app`, `@/components`, `@/lib`
10
- Styling: Tailwind (no styled-components, no CSS modules)
11
- Data fetching: React Query (no SWR, no useEffect loading)
12
- State: Zustand for global, React context for auth only
13
- Components: Server components by default, 'use client' when needed
14

15
# Never
16
- Never import server-side code in client components
17
- Never use `any` — use `unknown` + type guards
18
- Never commit `console.log`
19
- Never use default exports (named exports only)

1
# Build
2
- Test: `pytest -x --cov`
3
- Lint: `ruff check . && mypy .`
4
- Format: `ruff format .`
5
- Run: `python manage.py runserver`
6

7
# Conventions
8
- Type hints required on all functions
9
- Django models: `class Meta` before fields
10
- Serializers: ModelSerializer with explicit fields
11
- Queries: select_related/prefetch_related for N+1
12
- Services: Service layer pattern (not fat models, not fat views)
13

14
# Never
15
- Never use `print()` — use `logger.info()` with structlog
16
- Never import `*` from anything
17
- Never put business logic in views
18
- Never use raw SQL unless the ORM can't express the query

1
# Build
2
- Test: `go test ./... -count=1`
3
- Build: `go build ./cmd/app`
4
- Lint: `golangci-lint run`
5
- Fmt: `gofumpt -l -w .`
6

7
# Conventions
8
- Error handling: check and return immediately, no nesting
9
- Struct constructors: `func New() *Struct` pattern
10
- Interface design: Accept interfaces, return structs
11
- Concurrency: errgroup over WaitGroup, channels over mutexes
12
- Dependency injection: wire (not manual, not uber/fx)
13

14
# Never
15
- Never use `interface{}` — use `any`
16
- Never swallow errors with `_`
17
- Never use `panic` outside of init/shutdown
18
- Never use `init()` functions

1
# Build
2
- Dev: `flutter run -t lib/main_dev.dart`
3
- Test: `flutter test --coverage`
4
- Build release: `flutter build apk --split-per-abi`
5
- Format: `dart format .`
6

7
# Conventions
8
- State: Riverpod (not BLoC, not Provider)
9
- Navigation: GoRouter with shell routes for bottom nav
10
- API: Dio with interceptor-based token refresh
11
- Models: toJson/fromJson by hand (no json_serializable)
12
- Error handling: sealed class Result<T> pattern
13

14
# Never
15
- Never use `BuildContext` after async gap
16
- Never put `BuildContext` in providers
17
- Never generate code with build_runner manually
18
- Never use dynamic — prefer Object? or a proper type

Hooks: The Power Move Beyond CLAUDE.md#

CLAUDE.md tells the agent what you want. Hooks tell the agent what it must do. They’re event-driven scripts that run at specific points in the agent’s workflow:

1
#!/bin/bash
2
if echo "$@" | grep -E '(api_key|secret|token|password)=' > /dev/null 2>&1; then
3
  echo "❌ Blocked: committing secrets is not allowed"
4
  exit 1
5
fi
6
exit 0

1
#!/bin/bash
2
flutter test --coverage || exit 1

Skills: Reusable Instruction Sets#

Skills are reusable CLAUDE.md-equivalents for specific tasks. You invoke them via slash commands:

1
/clang-tidy-fix    — Run clang-tidy and apply all safe fixes
2
/changelog          — Generate CHANGELOG.md from conventional commits
3
/pr-describe        — Write a PR description from the git diff
4
/test-triage        — Find untested functions and generate test scaffolds
5
/docs-from-code     — Parse source comments and generate markdown docs

Skills live in .claude/skills/ and each skill is a directory with a SKILL.md:

1
.claude/skills/
2
├── changelog/
3
│   └── SKILL.md
4
├── test-triage/
5
│   └── SKILL.md
6
└── pr-describe/
7
    └── SKILL.md

Auto Memory: Let the Agent Learn#

Auto memory is the AI equivalent of taking notes. When you correct an agent, it writes that correction to a memory file. Next session, it starts with that knowledge.

1
# See what the agent has learned
2
cat .claude/memory.json

Example auto-memory entries:

• “Run flutter test --coverage, not flutter test”
• “Use Logger from logging package, not print()”
• “Deploy via firebase deploy --only hosting”

Auto memory is capped at 200 lines or 25KB. It’s best for discoverable preferences (build commands that took you a while to find, debugging tricks) — not for rules you should write into CLAUDE.md.

Practical Workflow with CLAUDE.md#

Here’s how a session looks with a well-configured CLAUDE.md:

1
# Start Claude Code
2
$ claude
3

4
# Loaded: CLAUDE.md (project), ~/.claude/CLAUDE.md (user)
5
# Auto memory: 14 learnings loaded
6

7
# Ask about codebase
8
$ "How does the auth flow work?"
9

10
  Claude reads the codebase, finds auth files,
11
  maps the flow from login → token → API calls.
12

13
# Make a change
14
$ "Add rate limiting to the API client"
15

16
  Claude reads CLAUDE.md, knows to use Dio with interceptors,
17
  adds rate limit interceptor, runs `flutter test` automatically.
18

19
# Correct a mistake
20
$ "No, use the sliding window algorithm, not token bucket"
21

22
  Claude fixes it, and writes this correction to auto memory.
23
  Next session, it'll know sliding window is preferred.

The difference from a session without CLAUDE.md? No explaining the tech stack. No clarifying the state management pattern. No “wait, I said Dio not HTTP.” The agent just works.

Performance Impact: Does CLAUDE.md Actually Help?#

The claude-code-best-practices repository published benchmarks. The results on a real Next.js codebase:

Bottom line: A well-written CLAUDE.md cuts both time and cost in half. The ROI on 20 minutes of writing is measured in hours saved.

Common Mistakes#

1
# Bad
2
Prefer Riverpod for state management.
3

4
# Good
5
Use Riverpod for state management.
6
Never use BLoC, Provider, or GetIt.

1
## Build & Test
2
- Build: `npm run build`
3
- Test: `npm test -- --watch=false --bail`
4
- Lint: `npm run lint`
5
- Type check: `npx tsc --noEmit`

CLAUDE.md Beyond Claude Code#

While “CLAUDE.md” is named for Claude Code, the pattern works across:

• Codex — reads .codex/CLAUDE.md or root CLAUDE.md
• Cursor — reads .cursorrules (functionally equivalent)
• Gemini CLI — reads GEMINI.md
• OpenCode — reads OPENCODE.md

The naming changes but the principle is identical. Many teams maintain a single CLAUDE.md that works across all agents.

Getting Started in 10 Minutes#

1
# 1. Create your CLAUDE.md
2
cat > CLAUDE.md << 'EOF'
3
# [Project Name]
4
Tech stack: Flutter 3.24 / Dart 3.5, Riverpod, GoRouter
5

6
## Build & Run
7
- Dev: flutter run -t lib/main_dev.dart
8
- Test: flutter test --coverage
9
- Build: flutter build apk --release
10
- Format: dart format .
11

12
## Conventions
13
- State: Riverpod (no BLoC, no GetIt)
14
- API: Dio with interceptors
15
- Errors: sealed class Result<T>
16
- Tests: mocktail (not mockito)
17

18
## Never
19
- Never use BuildContext after async gap
20
- Never commit print() statements
21
- Never generate code with build_runner manually
22
- Never import material.dart in domain layer
23
EOF
24

25
# 2. Add it to git
26
git add CLAUDE.md
27
git commit -m "Add CLAUDE.md with project conventions"
28

29
# 3. Test it
30
claude "What's the first thing you notice about this project?"

The Bottom Line#

CLAUDE.md is the single highest-leverage file in modern AI-assisted development. It costs 20 minutes to write and saves hours daily. It eliminates the “explain yourself every session” problem. It makes your team’s agent usage consistent. And it cuts costs by preventing wrong-tool, wrong-framework, wrong-pattern mistakes.

If you’re using AI coding agents without CLAUDE.md, you’re paying twice — once in token costs and once in frustration. Write it today.

The CLAUDE.md templates in this post are adapted from the claude-code-best-practices repository and Anthropic’s CLAUDE.md documentation.