Claude Code: CLAUDE.md Usage Guide
Last updated: 2026-08-31
CLAUDE.md is Claude Code's "project manual" — write it well, and Claude Code works like an experienced team member; write it poorly, and it's like a clueless newcomer.
💡 Tip: CLAUDE.md's core principle is "explicit over implicit" — write out conventions you take for granted, because Claude Code won't guess.
📋 Prerequisites: Chapter 8 - Basic Usage
1. What You'll Learn
- CLAUDE.md complete syntax and structure
- Layered configuration strategy (global/project/directory)
- Writing best practices
- Common pitfalls and how to avoid them
- Practical comparison examples
2. CLAUDE.md Syntax and Structure
(1) Core Structure
MARKDOWN
# CLAUDE.md
## Project Overview
[One-line description of what the project is and does]
## Tech Stack
[Language, framework, database, toolchain]
## Common Commands
[Build, test, deploy, dev commands]
## Code Conventions
[Naming standards, file organization, style requirements]
## Constraints and Limitations
[What not to do, what must be done]
## Known Issues
[Technical debt and pitfalls requiring special attention]
(2) Instruction Types
| Type | Example | Priority |
|---|---|---|
| Must do | "All APIs must have error handling" | High |
| Must not do | "Don't directly modify database tables" | High |
| Should do | "Prefer functional style" | Medium |
| Reference info | "Project uses Monorepo structure" | Low |
▶ Example 1: High-Quality CLAUDE.md
MARKDOWN
# CLAUDE.md
## Project Overview
SaaS billing platform backend, handling subscription management, invoice generation, and payment integration.
## Tech Stack
- Node.js 20 + TypeScript 5.3
- Express 4.18 + middleware chain
- Prisma 5.x (PostgreSQL)
- Redis (cache + queue)
- Jest + Supertest (testing)
## Common Commands
- `npm run dev` — Start dev server (port 3000)
- `npm test` — Run all tests
- `npm run lint` — ESLint check
- `npx prisma migrate dev` — Database migration
## Code Conventions
- Service layer only handles business logic, no direct HTTP object access
- Controller layer handles request/response transformation
- All database operations via Repository pattern
- Errors use AppError class with statusCode and code
- API response format: `{ success: boolean, data: T, error?: string }`
## Constraints
- ❌ Never use pg client directly, must use Prisma
- ❌ Never access req/res in Service layer
- ❌ Never hardcode secrets and credentials
- ✅ Every API endpoint must have integration tests
- ✅ All amounts use cents (integer), avoid floating point errors
## Known Issues
- PaymentService.processRefund has concurrency issue (see ISSUE-342)
- InvoiceService.generatePDF performs poorly with many items (see ISSUE-156)
3. Layered Configuration Strategy
(1) Three-Layer Configuration System
TEXT
📖 Display only
~/.claude/CLAUDE.md # Global: Personal preferences
project-root/CLAUDE.md # Project: Team conventions
project-root/src/api/CLAUDE.md # Directory: Local instructions
| Layer | Scope | Typical Content | Priority |
|---|---|---|---|
| Global | All projects | Personal coding style preferences | Lowest |
| Project | Current project | Tech stack, commands, constraints | Medium |
| Directory | Sub-directory | Local specific instructions | Highest |
(2) Global CLAUDE.md
MARKDOWN
<!-- ~/.claude/CLAUDE.md -->
# Global Preferences
## Code Style
- Use TypeScript strict mode
- Prefer const, avoid let
- Functions no longer than 20 lines
- Add JSDoc comments
## Testing Preferences
- Use describe/it style
- Each test independent, no execution order dependency
- Mock external dependencies, not internal modules
(3) Directory-Level CLAUDE.md
MARKDOWN
<!-- src/api/CLAUDE.md -->
# API Module Conventions
## Route Registration
- All routes registered centrally in index.ts
- Middleware order: auth → rateLimit → validate → handler
## Response Format
- Success: { success: true, data: T }
- Failure: { success: false, error: { code, message } }
## Prohibited
- ❌ Don't write business logic directly in handlers
- ❌ Don't skip parameter validation
4. Writing Best Practices
(1) Effective vs Ineffective Instructions
| Ineffective | Effective | Reason |
|---|---|---|
| "Write good code" | "Functions under 20 lines, cyclomatic complexity < 10" | Quantifiable |
| "Pay attention to security" | "All user input must be sanitized, no SQL concatenation" | Specific and executable |
| "Follow best practices" | "Use Repository pattern, Services don't access DB directly" | Clear pattern |
| "Make code fast" | "DB queries must have indexes, N+1 queries use DataLoader" | Specific method |
(2) Pitfall Checklist
| Pitfall | Example | Correct Approach |
|---|---|---|
| Too vague | "Keep code clean" | Write specific standards |
| Too verbose | 500-line CLAUDE.md | Trim to core conventions |
| Self-contradicting | "Use REST" and "Use GraphQL" | Stay consistent |
| Outdated | Still writing "Use Express 3.x" | Update with project |
| Irrelevant info | Writing team org chart | Only write code-affecting info |
5. Dynamically Updating CLAUDE.md
▶ Example 2: Have Claude Code Maintain CLAUDE.md
TEXT
📖 Display only
> Update CLAUDE.md based on recent code changes
Claude Code:
→ Reading recent commits
→ Changes detected: Express → Fastify, added Redis, Jest → Vitest
→ Updating CLAUDE.md with current tech stack and commands
CLAUDE.md updated ✓
❓ FAQ
Q How long should CLAUDE.md be?
A 50-150 lines is optimal. Too short lacks information; too long and Claude Code may skip parts. Core conventions first, reference info minimal.
Q Will Claude Code always follow CLAUDE.md instructions?
A Mostly yes, but not 100%. High-priority instructions (❌ "never"/✅ "must") have higher compliance. Suggestive instructions may be overlooked.
Q Can multiple CLAUDE.md files conflict?
A Yes. Directory-level overrides project-level, which overrides global. More specific wins.
Q Can I put sensitive info in CLAUDE.md?
A Absolutely not. CLAUDE.md gets committed to git. Use environment variables for API keys, passwords, etc.
Q Does CLAUDE.md support conditional logic?
A No programming logic supported. Only static text instructions. Conditional judgment is Claude Code's decision.
Q When should CLAUDE.md be updated?
A When tech stack changes, new conventions added, or when Claude Code repeatedly makes mistakes.
📖 Summary
- CLAUDE.md is the project manual for Claude Code; "explicit over implicit" is the core principle
- Three-layer config: Global (personal) → Project (team) → Directory (local)
- Effective instructions: Specific, executable, quantifiable; avoid vagueness and verbosity
- ❌/✅ markers improve instruction compliance
- Continuously update as the project evolves
📝 Exercises
- Basic (⭐): Write a 50-line CLAUDE.md for your project with overview, tech stack, and commands.
- Intermediate (⭐⭐): Implement three-layer CLAUDE.md configuration, test instruction priority.
- Advanced (⭐⭐⭐): Write vague and precise instructions, compare Claude Code's execution differences, summarize golden rules for CLAUDE.md writing.
