Claude Mastery Course

The CLAUDE.md file is the single most impactful way to improve Claude Code's performance on your projects. It acts as persistent memory — instructions that Claude reads automatically at the start of every session.

How CLAUDE.md Files Are Loaded

Claude Code reads CLAUDE.md files from multiple locations, in order of priority:

• Project root (./CLAUDE.md) — Always loaded when you run claude in the directory
• Parent directories — Files in parent dirs are loaded with lower priority (useful for monorepos)
• User-level (~/.claude/CLAUDE.md) — Loaded for every project, ideal for personal preferences

Writing an Effective CLAUDE.md

A great CLAUDE.md is concise, specific, and actionable. Include:

• Project overview: What this project is and what stack it uses
• Build/test commands: How to build, test, and lint the project
• Architecture decisions: Key patterns, conventions, and constraints
• Do's and don'ts: Specific rules Claude should follow

Example: Production CLAUDE.md

# Project: API Gateway Service

## Stack
- Go 1.22, Chi router, PostgreSQL 16, Redis 7
- Deployed to AWS ECS Fargate via Terraform

## Commands
- Build: `go build ./cmd/api`
- Test: `go test ./... -v -race`
- Lint: `golangci-lint run`
- Migrate: `go run ./cmd/migrate up`

## Architecture
- Handler → Service → Repository pattern
- All DB queries go through the repository layer
- Errors are wrapped with fmt.Errorf("methodName: %w", err)
- Use structured logging via slog (never log or fmt.Println)

## Rules
- Never modify migration files that are already applied
- Always add new migrations, never alter existing ones
- All API endpoints require authentication middleware
- Tests must not depend on external services — use mocks