Writing a good Claude.md
TL;DR Highlight
Because Claude Code (coding agent) needs to re-learn the codebase every session, maintaining a well-structured CLAUDE.md file has a huge impact on performance.
Who Should Read
Developers using Claude Code (or similar coding agents) who want to maximize the agent's effectiveness and reduce repetitive context-setting.
Core Mechanics
- Claude Code starts each session without persistent memory of previous sessions — it re-reads the codebase each time
- CLAUDE.md acts as the agent's 'long-term memory': architecture overviews, coding conventions, known gotchas, and workflow instructions
- Well-maintained CLAUDE.md significantly reduces the number of clarifying questions and wrong-path attempts
- Recommended structure: project overview, tech stack, directory layout, coding conventions, common commands, do's and don'ts
- Treat CLAUDE.md as a living document updated whenever you correct the agent's behavior
Evidence
- Developer community experience reports comparing session quality with and without CLAUDE.md
- Anthropic's own documentation recommending CLAUDE.md best practices
- Anecdotal but consistent reports of 30–50% reduction in agent errors with good CLAUDE.md
How to Apply
- Create a CLAUDE.md at your project root with: project purpose, tech stack, directory structure, key conventions, and common pitfalls.
- When the agent makes a mistake due to missing context, add that context to CLAUDE.md immediately — not just correct it for this session.
- Keep CLAUDE.md concise; aim for <500 lines. Overly long files dilute attention on the most critical constraints.
Code Example
snippet
# CLAUDE.md Table of Contents Style Example
## Documentation References
- For CSS work: docs/ADDING_CSS.md
- For adding assets: docs/ADDING_ASSETS.md
- For working with user data: docs/STORAGE_MANAGER.md
## Stack
- Runtime: Bun (not Node)
- Tests: `bun test`
- Typecheck: `bun tsc --noEmit`Terminology
CLAUDE.mdA markdown file at the root of a project read by Claude Code at session start, providing persistent context about the codebase and conventions.
Session MemoryThe LLM's ability to retain context within a conversation; Claude Code's session memory resets each time a new session starts.
Context WindowThe maximum amount of text (tokens) an LLM can process at once. CLAUDE.md content consumes context window budget.
Coding AgentAn LLM-powered system that autonomously reads, writes, and runs code to complete development tasks.