The difference between a Claude session that drifts and one that stays sharp often comes down to one file: CLAUDE.md. Here's how to write one that actually works.
When you first start using Claude Code, it feels like magic. Claude reads your files, understands your codebase, and makes changes that look exactly right. Then, a few sessions later, it starts making assumptions you didn't expect — using the wrong framework, ignoring conventions, or re-explaining things you've already established.
The fix is simpler than you think: a well-written CLAUDE.md file.
CLAUDE.md is a markdown file placed at the root of your project (or in a .claude/ folder) that Claude reads automatically at the start of every session. It's your persistent context — the things you'd tell a new team member on day one that you don't want to repeat every time.
💡 Think of CLAUDE.md as onboarding documentation for Claude. The better your onboarding, the less time you spend correcting misunderstandings.
One paragraph. What does this project do, who uses it, and what's the core tech stack? Claude doesn't need your full README — just enough to orient itself.
This is the highest-ROI section. List things like: "We use tabs, not spaces", "All API routes follow REST conventions", "Error handling uses our custom AppError class, not raw exceptions." The more specific, the better.
Explicitly list anti-patterns. "Don't use jQuery — we're migrating away from it." "Don't modify the legacy auth module without flagging it." These guardrails save significant correction time.
A quick map of where things live. Claude will explore your files anyway, but a quick map helps it navigate faster and make better assumptions about where new code should go.
Include your common dev commands — how to run tests, build, lint, deploy locally. Claude can use these to verify its changes actually work.
agents.md (sometimes placed in .claude/agents/) is for multi-agent setups — it defines the role, scope, and constraints of a specific sub-agent. Where CLAUDE.md is for the whole project, agents.md is for a specific task or agent.
Use it when you're building pipelines where Claude orchestrates sub-agents: one agent for code review, one for testing, one for documentation. Each gets its own context file scoped to its job.
🚀 The result: A good CLAUDE.md turns a generic AI assistant into a team member who already knows your codebase, your conventions, and what not to touch.