让Claude Code更懂你：写好CLAUDE.md的8条实战经验

Many people new to Claude Code stuff everything into CLAUDE.md: project history, technical decisions, personal preferences, even company values. The result? Claude gets lost in 2000 lines of context, generates nonsensical output, and you have no idea why.

This article isn't about the structural spec of CLAUDE.md. It's about 8 hard-won lessons from real practice—which counter-intuitive approaches work better, and which pitfalls you only need to step in once.

Counter-intuitive: You think more information means Claude understands you better. In reality, more information means Claude is more likely to ignore what's truly important.

Boris Cherny, author of claude-code-best-practice, explicitly recommends: CLAUDE.md should not exceed 200 lines. This isn't arbitrary—Claude Code loads CLAUDE.md on every session, consuming context window. Every extra line you write crowds out space for Claude to understand your code.

Practical standards:

# ❌ Don't do this
## Project History
In 2023, our CTO proposed this idea at a hackathon...
(300 lines of company narrative + marketing copy)

# ✅ Do this
## Project Overview
B2B analytics dashboard for operations managers.
Core goal: shorten time from data to insight.
Optimization priority: load speed > interaction richness > visual flashiness.

Validation standard: A person unfamiliar with your project, after reading CLAUDE.md, can answer three questions in 30 seconds—what is this product? What's the tech stack? Where do new files go?

Counter-intuitive: You list your tech stack, thinking Claude won't go rogue. But Claude's knowledge cuts off at its training date—it doesn't know your project's historical baggage.

A CLAUDE.md without a 'forbidden list' is dangerous. Claude will, out of good intentions, introduce the 'best' solution it knows, which could completely conflict with your project.

## Tech Stack
- Next.js 15 App Router + TypeScript
- Tailwind CSS + shadcn/ui
- Supabase (auth + data)

Do NOT introduce unless explicitly requested:
- Redux (project migrated to React Context + Zustand)
- styled-components (full site Tailwind, no CSS-in-JS)
- Material UI (style conflict with shadcn/ui)
- MongoDB (data layer locked to PostgreSQL)

This rule is worth its weight in gold. It doesn't just save one correction—it prevents Claude from introducing incompatible dependencies without you noticing, causing the next 10 sessions to fix compatibility issues.

Counter-intuitive: 'Write clean code' sounds like a good rule, but to an AI it says nothing.

Claude doesn't understand 'clean'. It understands 'use named exports instead of default exports', 'components under 200 lines', 'async/await instead of promise chains'.

Compare:

# ❌ Vague—Claude can't execute
## Coding Rules
- Write clean code
- Keep it simple
- Focus on performance

# ✅ Specific—Claude can execute directly
## Coding Rules
- Use named exports (except route files)
- No `any` type; use generics or interfaces
- Single component under 200 lines (exceptions with justification)
- async/await over Promise chains
- Full variable names, no abbreviations (except id/url/ctx)
- Comments only when intent is non-obvious
- No commented-out code blocks or console.log

Test method: After reading this rule, can you tell within 5 seconds whether a piece of code complies? Yes—rule passes. No—rewrite it.

Counter-intuitive: You want to cram all architectural docs into CLAUDE.md. But CLAUDE.md's job isn't to store information—it's to tell Claude where to find it.

This is the dividing line between top-tier and average users. The average user's CLAUDE.md is a knowledge dump; the top-tier user's CLAUDE.md is a router.

## Project Context
- Architecture overview: `docs/architecture.md`
- Architecture Decision Records: `docs/adrs/`
- API docs: `docs/api.md`
- Deployment process: `docs/deploy.md`

Claude doesn't need to read all architecture docs in CLAUDE.md. It just needs to know: 'When I need architecture info, open docs/architecture.md.'

More advanced usage—Progressive Disclosure:

## Context Tiers
Tier 1 (loaded every time): CLAUDE.md — what the project is + how it works
Tier 2 (loaded on demand): docs/architecture.md, docs/api.md — Claude auto-reads while working
Tier 3 (ignored): docs/archive/ — don't touch unless explicitly asked

This way Claude doesn't waste context reading historical docs on irrelevant requests, but knows where to look when needed.

Counter-intuitive: There's only one CLAUDE.md, in the root directory. But some modules carry 10x the risk of others.

Place a local CLAUDE.md under src/auth/, src/payments/, infra/—Claude automatically loads it when operating in those directories. It's like installing guardrails in dangerous zones.

# src/auth/CLAUDE.md

## Security Hardlines
- Never modify token verification logic unless explicitly requested and reviewed
- Never introduce new auth methods without updating tests
- All auth-related changes must pass `pnpm test src/auth`

## Known Traps
- Magic link generation depends on `crypto.randomUUID()`, do not replace with other random methods
- Session stored in Redis, not memory—survives restarts

Counter-intuitive: You write testing rules, but Claude never runs tests after writing code—because it forgot.

Claude's memory is unreliable. Hooks are reliable. Turn rules in CLAUDE.md into hook triggers:

## Hooks & Quality Gates
The following rules are enforced by `.claude/hooks/`, not reminders:
- Auto-format after each edit (PreToolUse hook → prettier)
- Auto-run tests after core module changes (PostToolUse hook → vitest related)
- No direct edits to `src/auth/`, `src/billing/`, `prisma/migrations/` without confirmation

Corresponding hook example:

// .claude/hooks/pre-tool-use.json
{
  "hooks": [
    {
      "matcher": "Edit|Write",
      "command": "npx prettier --write ${CLAUDE_FILES}",
      "on_failure": "warn"
    }
  ]
}

Hooks are the enforcement layer for CLAUDE.md rules. Rules in CLAUDE.md say 'please remember'; rules backed by hooks say 'you must'.

Counter-intuitive: Every new session, Claude re-learns your project like it has amnesia. But you don't need a complex vector database to solve this.

Add an instruction in CLAUDE.md for Claude to maintain a MEMORY.md itself:

## Memory
`MEMORY.md` records key insights, best practices, and known pitfalls discovered in previous tasks.
Before each new task, read MEMORY.md first.
After each task, if there are new discoveries

This is simpler, more controllable, and Git-trackable than any 'AI long-term memory MCP'. Cost: one file. Benefit: Claude retains the most valuable 5% of context across sessions.

Counter-intuitive: You should train Claude, not ask it 'Can you help me do X?' every time. Let CLAUDE.md carry your working style, so Claude knows what you hate from the very first conversation.

Real-world summary from Claude Code Cowork—a great CLAUDE.md includes 'who you are' and 'what you hate':

## My Working Style
- Propose a plan first, don't write code directly
- List options when uncertain, don't guess
- Ask before major changes, execute minor optimizations directly
- Don't use fluff like 'Great question!' or 'I'd be happy to help!'
- Respond in Chinese, code comments in English
- Use absolute paths for files, not relative paths

These 6 lines eliminate the first 5 messages of every new session. Claude knows from the first sentence what you care about, what you hate, and what interaction rhythm you expect.

CLAUDE.md isn't a file you write once and leave. It's alive—every time you discover a pitfall Claude repeatedly steps in, or distill an effective rule, update it. Look back a month later, and you'll find Claude has evolved from a rookie intern into a senior engineer who truly understands your project.