Think of it as a briefing document written for the AI, not for humans.
Why AI Assistants Need Context Files
Every time you start a new conversation with an AI coding tool, you lose all the context from the last session. You end up re-explaining the same things: "this project uses TypeScript strict mode", "we use named exports only", "never touch the generated files in /dist". That repetition is frustrating and wastes tokens.
CLAUDE.md solves this by making project context durable. It is read once, at the start, and informs every decision the AI makes during the session.
The Anatomy of a Good CLAUDE.md
A well-structured CLAUDE.md covers six areas:
1. Project Overview
A brief description of what the project does, who it is for, and its current status. Keep it to a paragraph — just enough to orient the AI.
2. Tech Stack
List every major dependency and its version. AI assistants have training data cutoffs and can suggest outdated APIs if they do not know your exact versions.
3. Architectural Patterns
This is the most important section. List the patterns the AI must follow — and the anti-patterns it must avoid. For example: "Named exports only — NEVER export default (except Next.js page files)" or "Tailwind utility classes only — NEVER CSS modules or inline styles."
4. Key Files
Tell the AI which files are the source of truth for different concerns. This prevents it from making conflicting changes across files.
5. Commands
List the commands for running the development server, tests, and build. The AI needs these to validate its own changes.
6. Off-Limits Rules
Explicit prohibitions save you from AI errors. Be direct: "Never modify files in /node_modules", "Never add console.log statements to production code", "Never use any TypeScript type."
CLAUDE.md vs README.md — What is the Difference?
A README is written for human developers joining the project. It explains the project's purpose, how to get started, and how to contribute.
CLAUDE.md is written for an AI assistant. It is not meant to be read by humans (though it can be). It is optimized for machine comprehension: precise, structured, and focused on constraints and conventions. It is less "what is this project" and more "what rules must you follow."
You need both. They serve different readers.
How Claude Code Uses CLAUDE.md
Claude Code (Anthropic's official CLI) reads CLAUDE.md automatically from:
1. The project root when you start a session 2. Any subdirectory CLAUDE.md files when working in that folder 3. A global CLAUDE.md in your home directory (for rules that apply to all projects)
This hierarchical loading means you can have project-wide rules at the root and component-specific rules in subdirectories — the AI merges them automatically.
Other tools have equivalent mechanisms: Cursor uses .cursorrules, GitHub Copilot uses .github/copilot-instructions.md, and Windsurf has its own context file format. The concept is the same across all of them.
Writing CLAUDE.md for Maximum Effectiveness
Be explicit, not implicit. Do not write "use modern patterns" — write "use the App Router, not the Pages Router". Vague guidance leads to vague results. Use structured markdown. Headings, bullet lists, and code blocks help the AI parse and categorize rules. A wall of prose is harder to extract rules from. Update it as you build. CLAUDE.md is a living document. When you make an architectural decision, add it immediately. When you install a new library, update the tech stack section. Keep it lean. Longer is not better. Every extra sentence competes for attention with the truly important rules. Aim for under 500 lines for most projects.Formatting and Previewing CLAUDE.md
Because CLAUDE.md is a markdown file, you can preview it with any markdown renderer. Paste it into MarkdownTools to see a clean HTML preview, or export it as a PDF to share with your team as a reference document.
This is especially useful if you want to review your context file before a long AI-assisted session — rendering it visually helps you spot sections that are unclear, overly long, or missing entirely.
The Broader Shift: Markdown as AI Instructions
CLAUDE.md is part of a larger pattern in AI-assisted development: using markdown as the primary format for human-to-AI communication. Prompts, context files, specification documents, and agent instructions are all increasingly written in markdown.
This makes sense. Markdown is lightweight, readable by both humans and machines, easy to version control in git, and well-supported by every AI model. As AI coding tools become more sophisticated, the ability to write clear, structured markdown instructions is becoming a core developer skill.
For a deeper look at how markdown interacts with AI tools, see Why Do AI Tools Like ChatGPT Output Markdown? and Markdown in AI Agent Workflows.