> ## Documentation Index
> Fetch the complete documentation index at: https://agentic.proxify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing CLAUDE.md

> How to write effective CLAUDE.md files — the highest-leverage configuration surface for Claude Code.

<Tip>**New to CLAUDE.md?** — Start with the [official CLAUDE.md guide](https://code.claude.com/docs/en/memory) for the basics. This page is the opinionated blueprint for making yours great.</Tip>

CLAUDE.md is the highest-leverage configuration surface for Claude Code. It's loaded into every conversation, so every line must earn its place. For how it fits into the broader instruction hierarchy alongside skills, agents, and hooks, see [Context Distribution](/patterns/distribution).

## What CLAUDE.md Does

When you launch Claude Code in a directory, it walks the directory tree collecting CLAUDE.md files. More specific locations take precedence:

| Priority    | Location                     | Scope                                   |
| ----------- | ---------------------------- | --------------------------------------- |
| 1 (highest) | `/etc/claude-code/CLAUDE.md` | Organization-wide                       |
| 2           | `~/.claude/CLAUDE.md`        | Personal, all projects                  |
| 3           | `./CLAUDE.md`                | Project root                            |
| 4           | `./CLAUDE.local.md`          | Personal project overrides (gitignored) |
| 5           | Parent directories           | Inherited in monorepos                  |
| 6           | Subdirectories               | Module-specific, on demand              |

## The 200-Line Budget

The system prompt already contains \~50 instructions. CLAUDE.md adds to that load. Frontier models follow approximately 150-200 instructions with reasonable consistency before quality degrades. Keep yours concise.

## What Goes In (and What Doesn't)

<Tabs>
  <Tab title="Include">
    * One-line project overview with tech stack
    * Build/test/lint commands (Claude uses these verbatim)
    * Brief architecture/directory map
    * Coding conventions Claude can't infer from existing code
    * Critical warnings about gotchas
    * Pointers to detailed docs using `@imports`
  </Tab>

  <Tab title="Exclude">
    * Standard language conventions Claude already knows
    * Code style rules enforced by linters (use [hooks](hooks-playbook.mdx) instead)
    * Detailed API documentation (link to it)
    * File-by-file codebase descriptions (Claude can read files itself)
    * Anything that changes frequently
  </Tab>
</Tabs>

## The Pointer Pattern

CLAUDE.md points; it doesn't explain. One line per concern — what to do and where to read more.

**Good:**

```markdown theme={null}
- **Auth flow:** See `@docs/authentication.md` before touching auth code
```

**Bad:** A 30-line section explaining five auth rules with examples inline.

## CLAUDE.md vs. Hooks

CLAUDE.md relies on LLM compliance — it's advisory. For things that must always happen (formatting, linting, blocking .env commits), use hooks. Hooks execute as code.

## Example

```markdown theme={null}
# ShopFront
Next.js 14 e-commerce app. App Router, Stripe payments, Prisma ORM.

## Commands
- `npm run dev`: Dev server (port 3000)
- `npm run test`: Jest tests
- `npm run lint`: ESLint check

## Architecture
- `/app`: App Router pages and layouts
- `/components/ui`: Reusable UI components
- `/lib`: Utilities and shared logic
- `/prisma`: Schema and migrations

## Conventions
- TypeScript strict mode, no `any` types
- Named exports only, never default exports

## Important
- NEVER commit .env files
- Stripe webhook must validate signatures

## Reference Documents
### Auth Flow — `@docs/authentication.md`
**Read when:** Touching auth-related code
```

No frameworks, no tables of code patterns, no examples of implementation details. Those live in skills or reference docs.

## Verifying Your Context

After editing CLAUDE.md, use the `/context` command inside Claude Code to see exactly what's loaded into the conversation. This shows every CLAUDE.md file, `@import`, and skill that Claude can see — so you can confirm your changes landed and nothing is missing or duplicated.

## Next Steps

* [Compose your skills stack](skills-stack.mdx) — layer domain knowledge on top of CLAUDE.md
* [Set up hooks](hooks-playbook.mdx) — enforce what CLAUDE.md can only suggest
* [Wire up MCP](mcp-wiring.mdx) — connect Claude to your external tools