CLAUDE.md

An unconfigured Claude Code session is like hiring a brilliant engineer and giving them no onboarding — tremendous capability, zero project context. Without configuration, you spend 15-30% of every session re-explaining your project structure, coding style, and conventions. As Boris Cherny, engineering lead for Claude Code at Anthropic, puts it: "You should never have to correct Claude twice for the same mistake."

CLAUDE.md is the single most important configuration mechanism in Claude Code. It is a plain markdown file that Claude reads automatically at the start of every session. Whatever you put in this file becomes part of Claude's working knowledge.

Claude Code supports CLAUDE.md files at four levels, each with a different scope. See the official memory docs  for the full specification.

More specific wins: if your global CLAUDE.md says "use tabs" but the project CLAUDE.md says "use 2-space indentation," the project rule wins. Most teams only ever use the Global and Project tiers; the Managed tier appears mainly in enterprise deployments.

~/.claude/CLAUDE.md — just your personal preferences. Typically 2-5 lines:

- Use conventional commits format (feat:, fix:, chore:)
- Prefer verbose explanations over brevity

CLAUDE.local.md at the repo root — machine-specific overrides. Most developers never need this. Use it when your setup differs from the team (e.g., "My local API runs on port 4000 because 3000 is taken"). Add it to .gitignore so it stays off the repo.

CLAUDE.md at the repository root should give Claude the recurring context it needs to act correctly without rediscovering the project every session. A concise M.A.S.C.O.T. structure keeps that guidance operational.

Mission

State the product purpose and the outcomes that should guide tradeoffs.

1
2
3
## Mission
TaskFlow helps support teams triage, assign, and resolve customer requests.
Optimize for reliable ticket status, clear ownership, and a fast keyboard-friendly workflow.

Architecture

Name the key boundaries and where new behavior belongs.

1
2
3
4
5
6
## Architecture
- src/app: route handlers and page composition
- src/features/tickets: ticket domain logic and UI
- src/components: reusable presentational components
- src/lib: API clients, validation, and shared utilities
Keep business rules in features; do not place them in route handlers.

Tech Stack

List the technologies that affect implementation choices.

1
2
3
4
5
6
## Tech Stack
- TypeScript, React, and Vite
- Node.js API with PostgreSQL via Prisma
- Tailwind CSS for styling
- Zod for runtime validation
Use the existing libraries before adding dependencies.

Commands

Give Claude the canonical commands rather than asking it to infer them from package files or CI.

1
2
3
4
5
6
## Commands
npm install          # install dependencies
npm run dev          # start local development
npm run test         # run the unit test suite
npm run lint         # run static checks
npm run build        # create the production build

Operational Workflow

Describe the repeatable way work should be carried out, including decision boundaries.

1
2
3
4
5
6
## Operational Workflow
1. Inspect the relevant feature and its existing tests before editing.
2. Propose an approach when a change affects data models, public APIs, or permissions.
3. Keep edits scoped to the requested outcome; preserve existing conventions.
4. Stop and ask before deleting data, changing migrations, or altering authentication behavior.
5. Summarize changed files, validation, and any follow-up work.

Testing

Make the definition of done explicit so validation is not left to interpretation.

1
2
3
4
5
## Testing
- Add or update tests for changed business behavior.
- Run npm run test and npm run lint after implementation.
- Run npm run build for changes that affect the application bundle.
- Do not claim completion when required checks fail; report the failure and its cause.

M.A.S.C.O.T. is a starting structure, not a place for every instruction. Keep CLAUDE.md short and durable; move task-specific workflows into skills that Claude loads only when they apply.

Import supporting files when needed. CLAUDE.md can import focused guidance with @path/to/import syntax. For example, use @docs/testing.md to bring in shared test conventions without making the root CLAUDE.md longer.

Imports work well for durable, related guidance such as API conventions, deployment rules, or testing expectations. Keep the root file focused on the project-wide M.A.S.C.O.T. context, and use imports to organize the details.

Your first CLAUDE.md should be 10-20 lines — just the essentials. Then let it grow from real usage: (1) Claude makes a mistake, (2) you correct it, (3) you add a rule to CLAUDE.md so it never happens again. After two weeks of active development, your CLAUDE.md will contain exactly the rules that matter — every one earned from a real correction, no speculative bloat.

The /memory command adds notes to your CLAUDE.md automatically. When Claude makes a mistake, fix it and say: "Remember: always use our custom logger instead of console.log." Claude encodes this into your project memory.

Keep it under 200 lines: CLAUDE.md files are loaded in full at session start — there is no hard cutoff. But the official guidance is to target under 200 lines per file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using .claude/rules/ files with path scoping (covered in the Rules section).

Use /init to generate the project-level CLAUDE.md, then create the global tier with your personal preferences.

Step 1 — Auto-generate project CLAUDE.md: Generate the project-level CLAUDE.md automatically. Claude will analyze the codebase and produce a first draft:

Tell Claude:

/init

Observe: Claude scans package.json, source files, and project structure, then writes a CLAUDE.md with commands, architecture, and conventions it discovered. Review the output — this is a solid starting point that you can refine over time.

Step 2 — Exit Claude Code: Exit the Claude Code session so you can work in the terminal:

Tell Claude:

/exit

Step 3 — Create global tier: Create a global CLAUDE.md with your personal preferences (applies to all your projects on this machine):

Run in terminal:

1
2
3
4
5
6
mkdir -p ~/.claude && cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences

- Use conventional commits format (feat:, fix:, chore:)
- This is a learning environment — prefer verbose explanations over brevity
EOF

Observe: This file now exists at ~/.claude/CLAUDE.md and will be loaded for every Claude Code session on this machine, regardless of which project you are in.

Step 4 — Launch Claude Code: Start a new session and verify both tiers load:

Run in terminal:

1
claude

Step 5 — Verify the hierarchy: Ask Claude what it knows:

Tell Claude:

What do you know about this project from your CLAUDE.md files? List the instructions you received from each tier.

Observe: Claude should describe instructions from both tiers — your global preferences and the project conventions from /init. This is the complete picture Claude starts every session with.

CLAUDE.md is not the only configuration file. The .claude/ directory at your project root is the complete extension system — settings, agents, commands, hooks, and rules. Everything is committed to git except personal files, so new developers get the full AI configuration on clone.

<repo root>/
├── CLAUDE.md                   # Project instructions              ← committed   (this section)
├── CLAUDE.local.md             # Personal overrides                ← gitignored
├── .mcp.json                   # MCP server configuration          ← committed   (Extensions: MCP)
└── .claude/
    ├── settings.json           # Permissions & config              ← committed   (Settings section)
    ├── settings.local.json     # Personal settings                 ← gitignored
    ├── rules/                  # Path-scoped instructions          ← committed   (Rules section)
    ├── agents/                 # Specialist sub-agent definitions  ← committed   (Extensions)
    ├── skills/                 # Reusable slash commands           ← committed   (Extensions)
    └── hooks/                  # Lifecycle automation scripts      ← committed   (Extensions)

We will build this directory out piece by piece over the next sections.