How to write a CLAUDE.md file is the definitive practitioner guide to 📝Claude Code's most important configuration layer — the markdown file that gives Claude persistent context about your project, your conventions, and your collaboration patterns. A well-written CLAUDE.md is the difference between an AI that starts cold every session and one that picks up where you left off. See: 📝CLAUDE.md as Infrastructure.

The Three Levels

📝Claude Code reads CLAUDE.md files at three levels, merged top to bottom:

Global (~/.claude/CLAUDE.md) — universal collaboration patterns, workflow principles, personal preferences. Applies to every project
Project root (./CLAUDE.md) — architecture decisions, deployment rules, coding conventions, project-specific context
Subdirectory (./src/CLAUDE.md, ./tests/CLAUDE.md) — domain-specific instructions for subsections of the codebase

Think of it as layered institutional knowledge: general principles at the top, specifics at the edges.

What to Include

Architecture & Context

## Architecture
- Next.js 14 app router, TypeScript, Tailwind CSS
- MongoDB via Mongoose for data, Supabase for auth
- MCP server at src/mcp/create-server.ts
- Railway deployment: staging branch → staging env, main → production

Tell Claude what the project is built with and how it's organized. The AI reads files, but explicit architecture context prevents it from making assumptions that waste time.

Decisions, Not Just Rules

Bad: Use Tailwind CSS

Good: We chose Tailwind over styled-components because the team values utility-first patterns and our design system maps to utility classes

Rules produce compliance. Decisions produce judgment. An AI with judgment handles edge cases better because it understands why the rule exists.

Deployment & Safety

## Deployment
- staging is the default working branch. Always check out staging before starting work
- Never commit to main — it triggers production deployment
- Never push to main without explicit instruction
- Run tests before every commit

These are your guardrails. Claude Code follows them consistently — which is the point. Encode your safety requirements once, and every session respects them.

Correction History

## Lessons Learned
- Never write to SQLite directly while pm2 is running — use the API (caused 4 incidents)
- Use #for-biobrian tag, not #for-brian-to-review
- Don't add error handling for scenarios that can't happen

This is where CLAUDE.md becomes 📝Collaborative Augmentation infrastructure. When you correct Claude, add the correction to the file. Future sessions inherit the lesson. You stop repeating yourself.

Workflow Patterns

## Workflow
- Enter plan mode for any non-trivial task (3+ steps)
- Use subagents for research and parallel analysis
- Never mark a task complete without verifying it works
- After any correction: update the appropriate section of this file

These instructions shape how Claude Code works, not just what it knows. They're the operating principles of your collaboration.

What NOT to Include

Entire codebase documentation — Claude reads the files. Don't duplicate them
Secrets or credentials — CLAUDE.md may be committed to git. Use environment variables
Exhaustive API references — link to them, don't paste them
Temporary context — CLAUDE.md is for durable knowledge. Use conversation for ephemeral tasks

The Evolution Pattern

Week 1: Architecture, deployment rules, basic conventions. ~20 lines
Month 1: Correction history grows as you work together. Workflow patterns emerge. ~50 lines
Month 3+: The file stabilizes. Most corrections are encoded. Sessions feel like continuing a conversation. The CLAUDE.md becomes the foundation of an 📝Augmentation Stack
Advanced: Sync from 📝MythOS so the file is editable from any device and always current. See: 📝Syncing CLAUDE.md from MythOS

I've written hundreds of CLAUDE.md iterations. The file that works isn't the longest one — it's the one that encodes the right corrections and the right decisions. My current CLAUDE.md is about 50 lines. Behind it is a year of collaboration context, a MythOS augmentation system, and 17,000+ memos. The file is the index. The system is the infrastructure.

The best advice I can give: start small, add corrections as they happen, and never delete the lessons section. That section is the compound interest of your collaboration. Every correction encoded is a correction you'll never repeat.