CLAUDE.md Optimization Guide

3 rules that cut token costs by 40%. Based on 800+ hours of Claude Code operation.

The Problem

Your CLAUDE.md is included in every single API turn. A 100-line CLAUDE.md costs ~2,000 tokens per turn. At 20 turns/session × 5 sessions/day, that's 200,000 tokens/day just for instructions.

The 3-Rule Framework

Rule 1: If a tool enforces it, don't write it

Before (wasteful):

# Don't use rm -rf
# Don't force push to main
# Don't commit .env files
# Always run tests before committing
# Format code with Prettier

5 lines × ~100 tokens = 500 tokens/turn wasted. Hooks and linters already enforce these.

After (efficient):

# Safety handled by hooks (npx cc-safe-setup)
# Style handled by ESLint + Prettier

2 lines. Same protection. 300 fewer tokens/turn.

Rule 2: One example beats ten rules

Before:

# When writing tests, use descriptive names
# Tests should be independent
# Mock external services
# Test edge cases
# Use beforeEach for setup

After:

# Tests: see tests/user.test.ts for patterns

Claude reads the example file when it needs to. Your CLAUDE.md stays small.

Rule 3: Context, not rules

What Claude can't figure out on its own:

# DB: PostgreSQL 15 (docker-compose.yml)
# API: /api/v2/ prefix, JWT auth
# Deploy: GitHub Actions → AWS ECS
# Current sprint: auth refactor (see JIRA-1234)

Project-specific context that saves Claude from asking or guessing.

Results

CLAUDE.md	Tokens/turn	Cache hit rate	Monthly cost (Max)
100 lines (typical)	~2,000	89%	Baseline
50 lines (trimmed)	~1,200	92%	-20%
35 lines (optimized)	~800	95%	-40%

Check Your CLAUDE.md Now

CLAUDE.md Analyzer (free) — Paste your CLAUDE.md and see exactly how many tokens it costs per turn. Nothing leaves your browser.

More Token Savings

Effort Level Calculator — Opus 4.7 defaults to xhigh. Switch to save 30-50%.

Token Checkup — 5-question diagnostic, 30 seconds, free.

Token Book (¥2,500) — Full guide: 10 chapters, 32 failure patterns, all templates included. Ch.1 free.