CLAUDE.md Mastery: Complete Context Engineering Guide

Why Context Matters

Claude Code has a massive 200,000 token context window, but using it wisely is critical:

The Impact of Good Context

What CLAUDE.md Provides

1. →Persistent Memory: Project knowledge survives between sessions
2. →Style Enforcement: Consistent code patterns and conventions
3. →Security Guardrails: Prevent dangerous operations
4. →Workflow Optimization: Pre-configured commands and shortcuts

The honest reality about CLAUDE.md, based on what shows up on r/ClaudeAI and in open-source repos that ship with one: 80% of the value comes from the first 50 lines, and 80% of the regret comes from everything after line 200. Practitioners who treat CLAUDE.md like a README — short, opinionated, maintained — get durable wins. Those who treat it as a knowledge dump end up paying tokens for information the model already knows (e.g. "we use TypeScript", "we prefer arrow functions") while missing the single line that actually matters ("never touch /apps/legacy, it's autogenerated").

What Anthropic's own Claude Code documentation hints at but rarely emphasizes: CLAUDE.md is loaded on every session, so every kilobyte is a recurring tax. Engineers on r/ExperiencedDevs have documented how large CLAUDE.md files subtly degrade performance on unrelated tasks — not by hallucination, but by anchoring. The model starts seeing every problem through the lens of your written conventions, including problems where those conventions are irrelevant.

What the community agrees on: keep CLAUDE.md < 2 000 tokens, encode constraints rather than explanations, prefer negative rules ("do not X") over positive ones ("always do Y"), and link out to deeper docs via relative paths. The model is perfectly capable of following a link to docs/architecture.md when the task demands it — you don't need to preload everything.

Anatomy of CLAUDE.md

A well-structured CLAUDE.md has distinct sections, each serving a specific purpose:

# Project: [NAME]

## Overview
[High-level project description]

## Tech Stack
- Framework: [e.g., Next.js 14]
- Language: [e.g., TypeScript 5.3]
- Database: [e.g., PostgreSQL + Prisma]

## Code Style
[Specific conventions to follow]

## Architecture
[File structure and patterns]

## Commands
[Common operations]

## Constraints
[What NOT to do]

Interactive CLAUDE.md Editor

Use this interactive editor to build your perfect CLAUDE.md file. Choose a template, customize it, and download the result:

Understanding Your Context Budget

Claude Code has a 200K token context window that's shared across multiple sources. Use this visualizer to understand how context is allocated:

Context Allocation Strategy

Signs You're Hitting Context Limits

1. →Claude "forgets" earlier conversation parts
2. →Repetitive suggestions that ignore prior discussion
3. →Loss of project conventions mid-session
4. →Slower response times

Mitigation Strategies

## In CLAUDE.md - Use compact format

### Commands (one-liners)
dev: `npm run dev` | test: `npm test` | build: `npm run build`

### File patterns (compact)
Components: src/components/[Name]/index.tsx, [Name].module.css
Hooks: src/hooks/use[Name].ts
Services: src/services/[name].service.ts

Framework-Specific Templates

Next.js 14+ (App Router)

# Project: [NAME]

## Stack
- Next.js 14 (App Router)
- TypeScript 5.3 (strict mode)
- Tailwind CSS + shadcn/ui
- Prisma + PostgreSQL

## Patterns
- Server Components by default
- 'use client' only when needed
- Server Actions for mutations
- Route handlers for external APIs

## File Structure
app/
├── (marketing)/     # Public pages
├── (dashboard)/     # Protected pages
├── api/             # Route handlers
└── layout.tsx       # Root layout

## Naming
- Components: PascalCase
- Files: kebab-case
- Server Actions: verb + Noun (createUser, updatePost)

## Never
- Client-side data fetching for initial loads
- Prop drilling beyond 2 levels
- Inline styles (use Tailwind)

Python FastAPI

# Project: [NAME]

## Stack
- Python 3.11+
- FastAPI 0.100+
- SQLAlchemy 2.0 (async)
- Pydantic v2

## Patterns
- Async/await everywhere
- Dependency injection via Depends()
- Repository pattern for data access
- Pydantic models for validation

## Structure
src/
├── api/routes/      # Endpoint definitions
├── core/            # Config, security
├── models/          # SQLAlchemy models
├── schemas/         # Pydantic schemas
├── services/        # Business logic
└── repositories/    # Data access

## Style
- Type hints on all functions
- Docstrings (Google format)
- max line length: 88 (black)
- isort for imports

## Never
- Raw SQL without parameterization
- Blocking I/O in async functions
- Catching broad exceptions

React + TypeScript

# Project: [NAME]

## Stack
- React 18
- TypeScript 5 (strict)
- Vite
- Zustand/Jotai for state
- React Query for server state

## Patterns
- Functional components only
- Custom hooks for logic extraction
- Compound components for complex UI
- Render props when necessary

## Naming
- Components: PascalCase.tsx
- Hooks: useCamelCase.ts
- Utils: camelCase.ts
- Types: PascalCase.types.ts

## Style
- Destructure props in function signature
- Prefer interface over type for objects
- Export types alongside components
- Co-locate tests with components

## Never
- Class components
- PropTypes (use TypeScript)
- Index files as component files
- Default exports for components

Best Practices

1. Keep It DRY

Don't repeat information available in your codebase:

❌ Don't list every API endpoint
✅ Reference: "See src/api/routes/ for endpoint patterns"

❌ Don't duplicate package.json scripts
✅ Use: "Run `npm run` to see available commands"

2. Use Examples Over Rules

❌ "Use descriptive variable names"
✅ Examples:
   - userAuthenticationToken (not: token)
   - fetchUserProfile (not: getData)
   - isEmailValid (not: check)

3. Prioritize Safety

## Critical Rules
1. NEVER commit .env files
2. NEVER expose API keys in client code
3. ALWAYS validate user input
4. ALWAYS use parameterized queries

4. Version Your CLAUDE.md

Keep it in git and update it as your project evolves:

# Good commit messages for CLAUDE.md changes
git commit -m "docs(claude): add new API patterns for v2"
git commit -m "docs(claude): update testing conventions"

5. Team Conventions

For team projects, establish shared CLAUDE.md patterns:

## Team Standards
- PR template: .github/pull_request_template.md
- Issue labels: bug, feature, docs, refactor
- Branch naming: feature/ABC-123-description
- Commit format: conventional commits

Test Your Knowledge

Next Steps

Now that you understand CLAUDE.md and context engineering:

1. →Create Custom Skills - Build reusable agent capabilities
2. →Master Hooks - Automate with event-driven hooks
3. →Explore MCP Servers - Connect 50+ external services