Writing a Good CLAUDE.md

CLAUDE.md onboards Claude with WHY, WHAT, HOW. Keep it minimal, universally applicable, and carefully crafted.

Also applicable to AGENTS.md for OpenCode, Zed, Cursor, Codex.

Core Principle: LLMs are Stateless

LLMs function as stateless systems with frozen weights at inference time:

• Zero codebase knowledge at session start
• No persistent learning across sessions
• Only possess knowledge contained within provided tokens

Implication: CLAUDE.md is the preferred delivery mechanism for essential context.

The Onboarding Function

Cover three dimensions:

# Example CLAUDE.md Structure

## What
- Next.js 14 app with TypeScript
- Python FastAPI backend in `/api`
- Shared types in `/packages/types`

## Why
- SaaS product for [domain]
- Frontend handles [X], Backend handles [Y]

## How
- Use `bun` not `npm`
- Run `bun test` before committing
- API changes require updating `/packages/types`

Why Claude Often Ignores CLAUDE.md

The system injects this reminder with your file:

Result: Claude disregards instructions that aren’t universally applicable. Anthropic optimizes for filtering irrelevant instructions.

Less (Instructions) is More

Research shows frontier LLMs reliably follow approximately 150-200 instructions:

• Smaller models degrade exponentially
• Frontier thinking models degrade linearly

Critical insight: Claude Code’s system prompt already contains ~50 instructions, consuming roughly one-third of reliable instruction capacity.

File Length Guidelines

Avoid: Database schema instructions when working on unrelated code.

Progressive Disclosure

Instead of embedding all instructions directly, maintain task-specific documentation separately:

agent_docs/
  ├── building_the_project.md
  ├── running_tests.md
  ├── code_conventions.md
  ├── service_architecture.md
  ├── database_schema.md
  └── service_communication_patterns.md

In your CLAUDE.md:

## Documentation

When working on specific areas, read the relevant doc first:

- Building/deploying: See `agent_docs/building_the_project.md`
- Database work: See `agent_docs/database_schema.md`
- Adding services: See `agent_docs/service_architecture.md`

Reference format: Use `file:line` not inline code snippets.

Why: Inline code snippets become outdated. File references stay current.

Claude is Not an Expensive Linter

Never delegate linting to LLMs:

• Costly and slow compared to deterministic tools
• Style instructions bloat context
• Degrade instruction-following capacity
• Waste tokens on pattern matching

LLMs excel at in-context learning – they should infer conventions from existing code without explicit instruction.

Better Approaches

# 1. Claude Code Stop hooks that run formatters
# .claude/hooks/post-edit.sh
biome check --apply "$EDITED_FILE"

# 2. Slash commands for verification
# .claude/commands/lint.md
Run `biome check` on staged files and fix any issues.

Recommended: Use auto-fixing linters like Biome instead of instruction-based style guides.

Don’t Auto-Generate CLAUDE.md

Since CLAUDE.md affects every workflow phase:

1. Planning phase reads it
2. Implementation follows it
3. Artifacts inherit its patterns

Bad instructions cascade through all phases, multiplying errors.

Invest deliberate effort in crafting each line. Don’t use /init or auto-generate.

Template: Minimal Effective CLAUDE.md

# Project Name

## Stack
- [Language/Framework]
- [Key dependencies]

## Structure
- `src/` - Main application code
- `tests/` - Test files
- `scripts/` - Build and utility scripts

## Commands
- `[package-manager] dev` - Start development server
- `[package-manager] test` - Run tests
- `[package-manager] build` - Production build

## Conventions
- [1-2 critical patterns only]

## Before Committing
- Run tests: `[command]`
- Type check: `[command]`

## Documentation
- For [X] work, see `docs/x.md`
- For [Y] work, see `docs/y.md`

Checklist

• < 300 lines (ideally < 100)
• Every instruction is universally applicable
• No style/linting rules (use tooling instead)
• No inline code snippets (use file:line references)
• Task-specific docs are separate files
• Manually crafted, not auto-generated
• Covers WHAT, WHY, HOW

Key Takeaways

1. CLAUDE.md onboards Claude with WHY, WHAT, HOW dimensions
2. Minimize instructions while maintaining necessary coverage
3. Maintain concise, universal applicability
4. Use progressive disclosure to avoid context bloat
5. Delegate code style to linting tools, not LLMs
6. Carefully craft rather than auto-generate

References

• Instruction-following performance analysis

Related

• 12 Factor Agents – Factor 2: Own Your Prompts
• Context-Efficient Backpressure
• The Compound Systems Engineer Doctrine