Freedium
This article breaks down the key sections and best practices for your CLAUDE.md file, the project context guide that Claude Code reads before writing or editing code. It covers what to include—from project overview and tech stack to safety rules and commands—so the AI stays aligned with your repo’s structure and standards.
- CLAUDE.md is read by Claude Code before every code write/edit, so it functions as persistent project context rather than a one-time config file
- Specificity beats generality: naming exact versions/libraries ("Next.js App Router + TypeScript + Tailwind + shadcn/ui + Supabase") works far better than vague stack descriptions
- Concrete coding rules like "use named exports except in route files" or "avoid any; prefer explicit interfaces" produce better-fitting code than generic guidance like "clean code"
- The file should act as a living reference to guide suggestions, not a rigid enforcement mechanism that blocks workflow
CLAUDE.md sits at the root of your repo and feeds project context straight into Claude Code. It’s a markdown file that outlines your project overview, tech stack, architecture, coding rules, design patterns, and more. Each time Claude writes or tweaks code, it first reads CLAUDE.md to figure out your app’s goals, preferred tools, folder structure, naming conventions, UI guidelines, testing requirements, and other specifics. Treat it as a living reference rather than a strict enforcement mechanism—Claude uses it to shape intelligent suggestions, not to bottleneck your workflow.
The article breaks down ten key sections you should include. Start with a crisp project overview: define what the product is, who uses it, its main purpose, and any critical UX or business constraints. Follow up with an explicit tech stack—list actual versions and libraries in use and call out what not to introduce. The architecture section then maps folders to responsibilities, data flow, and where new code belongs. In coding conventions, spell out naming rules, export preferences, file size limits, and comment guidelines. UI and design rules cover spacing, typography, interaction states, and accessibility. Other sections cover copy tone, testing and quality checks, command shortcuts, and so on.
Every section comes with concrete examples and “pro tips.” For instance, instead of saying “use React stack,” specify “Next.js App Router + TypeScript + Tailwind + shadcn/ui + Supabase.” Or don’t just mention “clean code”—list out “use named exports except in route files” or “avoid any; prefer explicit interfaces.” These actionable rules help Claude produce code that fits your project’s style from day one.