CLAUDE.md onboards Claude with WHY, WHAT, HOW. Keep it minimal, universally applicable, and carefully crafted.
Source: HumanLayer | Author: Kyle (@0xblacklight) | Date: November 2025
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:
| Dimension | What to Include |
|---|---|
| WHAT | Tech stack, project structure, codebase mapping (critical for monorepos) |
| WHY | Project purpose, functional objectives for each component |
| HOW | Workflow requirements, package managers, verification procedures |
# 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:
“IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.”
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.
Minimize CLAUDE.md to universally applicable guidance only.
File Length Guidelines
| Metric | Recommendation |
|---|---|
| Optimal length | < 300 lines |
| HumanLayer example | < 60 lines at root |
| Target | Shorter is better |
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:
- Planning phase reads it
- Implementation follows it
- Artifacts inherit its patterns
Bad instructions cascade through all phases, multiplying errors.
Invest deliberate effort in crafting each line. Don’t use
/initor 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
CLAUDE.mdonboards Claude with WHY, WHAT, HOW dimensions- Minimize instructions while maintaining necessary coverage
- Maintain concise, universal applicability
- Use progressive disclosure to avoid context bloat
- Delegate code style to linting tools, not LLMs
- Carefully craft rather than auto-generate
References
Related
- 12 Factor Agents – Factor 2: Own Your Prompts
- Context-Efficient Backpressure
- The Compound Systems Engineer Doctrine
Part of the field guide
This is one of my field notes in AI Native Software Engineering, a plain-English guide to building software with AI agents. The terms behind it are defined in the AI Coding Dictionary.
