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

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