Chapter 3 · Project Context and CLAUDE.md

Chapter goals: Understand the role and loading hierarchy of CLAUDE.md, learn to write effective project instruction files, and master nested priority rules.

3.1 Why CLAUDE.md Is Needed

Every time you start Claude Code, it knows nothing about the project. Without CLAUDE.md, it spends大量 tokens exploring the directory structure, guessing the tech stack, and trial-and-erroring build commands. With CLAUDE.md, it gets directly:

• What the project is (tech stack, framework versions)
• How to build and test
• Code style conventions
• Hard constraints that cannot be violated

The Highest-ROI First Step

Placing a CLAUDE.md file at the repo root is the single highest-ROI operation in harness engineering — one file may be more effective than upgrading to a more expensive model.

3.2 Loading Hierarchy

Claude Code loads instruction files in the following priority order (nearest overrides farther):

1. Enterprise policy   /Library/Application Support/ClaudeCode/CLAUDE.md  (highest)
2. User global         ~/.claude/CLAUDE.md
3. Project root        ./CLAUDE.md or ./.claude/CLAUDE.md
4. Subdirectory        src/components/CLAUDE.md (only when reading files in that directory)
5. Local override      ./.claude/CLAUDE.local.md (not committed to Git)

Nested Priority Example

my-project/
├── CLAUDE.md              ← "Use pnpm as the package manager"
├── frontend/
│   └── CLAUDE.md          ← "Frontend tests use vitest"
└── backend/
    └── CLAUDE.md          ← "Backend tests use pytest"

When working on frontend tasks, both files are active: pnpm + vitest. When working on backend tasks: pnpm + pytest.

3.3 Writing Effective CLAUDE.md

The official recommendation is about 100 lines or less — it's a "map," not an "encyclopedia." Content beyond that should be split into the docs/ directory for the agent to read on demand.

# CLAUDE.md

## Project Overview
E-commerce API built with FastAPI + PostgreSQL.

## Tech Stack
- Python 3.12, FastAPI 0.141, SQLAlchemy 2.0 (async)
- PostgreSQL 16, Redis 7

## Commands
- Install: pip install -e ".[dev]"
- Test: pytest tests/ -x --tb=short
- Lint: ruff check src/
- Type check: mypy src/ --strict
- Run dev: uvicorn app.main:app --reload

## Code Style
- Use Annotated dependencies for DI
- All API responses use Pydantic response_model
- Error handling via custom exceptions in app/exceptions.py

## Hard Constraints
- Never modify alembic/migrations manually
- Always run tests before marking task complete

3.4 Compatibility with AGENTS.md

Claude Code also supports reading AGENTS.md files (open standard). If both exist, both will be loaded. Recommended practice:

Scenario	Recommendation
Using only Claude Code	Use CLAUDE.md
Multi-tool team	Use AGENTS.md (also recognized by Codex/Cursor, etc.)
Need differentiated instructions	Maintain both; put Claude-specific config in CLAUDE.md

Chapter Summary

• CLAUDE.md tells the agent the project overview and constraints — very high ROI;
• Five-level loading priority: enterprise > global > project > subdirectory > local;
• About 100 lines or less; split overflow into docs/ for on-demand reading;
• AGENTS.md is compatible and can coexist.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. When the root CLAUDE.md says "use npm" but a subdirectory CLAUDE.md says "use pnpm", what happens when editing files in that subdirectory?

2. What is the ideal length for CLAUDE.md according to the official recommendation?

3. What is the purpose of .claude/CLAUDE.local.md?

4. What happens if both CLAUDE.md and AGENTS.md exist in the same project?

🛠️ Hands-on Practice

1. Write a CLAUDE.md for your project, including build commands and tech stack.
2. Create nested CLAUDE.md files in subdirectories with different test commands; verify the nearest-wins behavior.
3. Create .claude/CLAUDE.local.md with personal preferences and confirm it is not tracked by Git.

After completing, proceed to Chapter 4.