CLAUDE.md — The Configuration Layer Most Claude Code Users Underutilize

CLAUDE.md is the single most leveraged file in any Claude Code project. It persists across sessions, ships with your repo, and shapes every action Claude takes. Yet most users either ignore it or dump a wall of vague instructions into it.

This is a reference for patterns that work in production.

The Three-Level Hierarchy

Claude Code loads CLAUDE.md from three scopes, all active simultaneously:

All three levels compose. They don’t override — they stack. A project-level instruction doesn’t cancel a global one. Claude sees everything.

Implication: Put personal preferences in global (language, formatting, tool preferences). Put project invariants in project-level. Put module-specific constraints in directory-level.

Pattern 1: Hard Constraints

The highest-value use of CLAUDE.md is things Claude must never do. These are more valuable than positive instructions because they prevent irreversible mistakes.

# In project CLAUDE.md
- Never run `git add -A` or `git add .`
- Never modify files under backend/lib/ unless explicitly asked
- Never commit .env files or any file containing API keys

Why this works: Claude Code checks CLAUDE.md on every action. A hard constraint stated clearly gets respected consistently. Vague guidance (“be careful with git”) does not.

Tested pattern: State the constraint, then state why.

- Never run `git push --force` on main. This repo has CI that depends on
  linear history, and force-push breaks other developers' branches.

The “why” helps Claude make correct judgment calls in edge cases the constraint doesn’t literally cover.

Pattern 2: Scope Limitation

Tell Claude what the project IS and what parts are stable.

- The engine source code (backend/) is in test phase. Do not modify engine
  source unless the change is critical and explicitly requested.
- This project's value hierarchy: data files > engine code > interface code.
  When in doubt, protect data integrity over convenience.

This prevents Claude from “helpfully” refactoring stable code when asked to fix a bug in a different layer. Without scope limitation, Claude will follow the path of least resistance, which often means modifying things you didn’t intend.

Pattern 3: Workflow Triggers

CLAUDE.md can instruct Claude to perform actions on certain events:

- After completing any concrete feature (new functionality, new pipeline,
  architecture change — not typos or minor tweaks), update
  `supervisor_state/CURRENT_STATE.md` with: what was done, system state
  changes, and remaining tasks.

This turns Claude into a self-documenting system. Every feature completion automatically produces a state update that the next session can read.

Other workflow trigger patterns:

- After modifying any test file, run the test suite before considering
  the task complete.
- When creating a new API endpoint, also add it to docs/API.md.
- When changing database schema, update the ERD in docs/schema.md.

Pattern 4: Language and Style Control

- Interact with the user in Chinese, but write all code comments
  and documentation in English.
- Do not add docstrings or type annotations to code you didn't change.
- Only add comments where the logic isn't self-evident.

These instructions survive across sessions. Without them, Claude defaults to its training distribution — which means English responses, liberal docstrings, and “helpful” comments on obvious code.

Pattern 5: Decision Framework

Instead of telling Claude what to do, tell it how to evaluate:

- When evaluating project changes, the correct framework is: "Can this
  structure support 10 years of evolution without a rewrite?" Not "when
  will it ship" or "what's the MVP."
- Evaluate: are abstraction boundaries clean? Is module coupling minimal?
  Is extension cost O(1)?

This is more powerful than specific instructions because it covers situations you haven’t anticipated. Claude applies the framework to novel decisions.

Pattern 6: Tool Preferences

Global CLAUDE.md is the right place for environment-specific tooling:

# In ~/.claude/CLAUDE.md
- Python3 and Node are installed and in PATH
- Never use pip. Use `uv run --with package_name` for all Python packages
- Never use npm. Use pnpm for all Node package management
- ripgrep (rg) and fd are available — use them over find/grep

This prevents Claude from installing tools you don’t want or using package managers that conflict with your setup.

Anti-Patterns

Walls of text

A 500-line CLAUDE.md is counterproductive. Every instruction competes for attention in the context window. A long CLAUDE.md dilutes the instructions that actually matter.

Fix: Keep CLAUDE.md under 50 lines. Move detailed reference material to separate files and have Claude read them on demand.

Contradictory instructions

Global says “always add type annotations.” Project says “don’t add type annotations to unchanged code.” Claude will oscillate or pick whichever it saw last.

Fix: Global CLAUDE.md should contain only universal preferences. Project-level should contain project-specific overrides stated explicitly as overrides.

Vague guidance

“Be careful with the database” tells Claude nothing actionable.

Fix: “Never run DROP TABLE, ALTER TABLE, or DELETE without WHERE clause on production databases. Always generate migration files instead of direct SQL.”

Missing the why

“Use pnpm not npm” is weaker than “Use pnpm not npm because this project uses pnpm workspaces and npm would create conflicting lock files.”

Composition Example

A production setup with all three levels:

~/.claude/CLAUDE.md          (global: language, tools, style)
./CLAUDE.md                   (project: scope limits, constraints, workflows)
./backend/CLAUDE.md           (directory: engine-specific rules)
./frontend/CLAUDE.md          (directory: UI-specific rules)

Each level is short (10-20 lines), focused, and non-overlapping. The total instruction set is substantial but no single file is bloated.

Verification

How to know your CLAUDE.md is working:

1. Start a new session and ask Claude to do something your constraints should prevent. Does it refuse or ask for confirmation?
2. Complete a feature. Does Claude automatically run your workflow triggers?
3. Ask Claude to explain your project’s architecture. Does it cite the scope and decision framework from CLAUDE.md?

If any of these fail, your instructions are either too vague or buried in too much text. Sharpen and trim.