If you've used Claude Code for more than a week, you've probably hit this moment: you start a new session, and Claude has no idea what you built yesterday. No memory of your file structure, your naming conventions, the fact that you never want it touching your production database. You explain it again. And again.
Here's a concrete example. You're building a Next.js app. You've standardised on SWR for data fetching. On Monday you tell Claude this. On Wednesday, new session, Claude suggests React Query. You correct it. Friday, same thing. That's the problem CLAUDE.md solves. You write the context once, and Claude shows up already knowing it.
It's the single most underrated feature in Claude Code, and almost nobody writes about it properly. This is the guide I wish existed when we started using it at AMPL.
What CLAUDE.md is
CLAUDE.md is a plain text file that sits in the root of your project. Claude Code reads it automatically at the start of every session, before you type anything. It's basically a briefing document. Write it once, and Claude already has the context it needs to be useful. No special syntax, no schema, no required fields. Just markdown that Claude reads and uses to shape its behaviour for the entire session.
How Claude Code reads your CLAUDE.md file and why it changes results
When you open a project in Claude Code, it looks for a CLAUDE.md file in the project root. If it finds one, the contents get loaded into context before anything else happens. Before you type your first message, Claude already has your project context, your rules, your constraints.
You can also nest CLAUDE.md files in subdirectories. If you have a complex monorepo with separate frontend and backend codebases, each can have its own CLAUDE.md. Claude loads the root file first, then any subdirectory files relevant to what you're working on.
One practical thing worth knowing: CLAUDE.md content counts against your context window. Write a 5,000-word CLAUDE.md and that's 5,000 words of context gone before you've typed anything. Keep it thorough but not verbose. Every line should earn its place.
When we first started using Claude Code at AMPL, we skipped CLAUDE.md for a few weeks. We thought it was optional, a nice-to-have. We were wrong about that.
Without it, every session started from scratch. We're using Supabase, not PostgreSQL directly. Don't use axios, we've standardised on fetch. The client wants TypeScript strict mode. After the third time explaining the same constraints, we wrote them down. After we wrote them down, the quality of Claude's output improved substantially. Not because Claude got smarter, but because it was no longer guessing.
The other thing that changes is consistency across sessions. When you're working on a project over weeks or months, you want Claude to make the same kinds of decisions on day forty as it did on day one. Without CLAUDE.md, you drift. Small inconsistencies accumulate. With it, you get a baseline that holds.
For teams, this matters even more. If two people are both using Claude Code on the same project, a shared CLAUDE.md means they're both working with Claude that has the same understanding of the codebase. Without it, you're basically running two different AI assistants with two different mental models of how things work.
How to set up your CLAUDE.md: 5 steps
There's no single right structure, but after building this out across a number of projects, we've settled on five core sections. Here's how to build yours.
Write your project context and tech stack. Start with a short description of what the project actually is. Not a marketing paragraph, a functional description. What does it do, who uses it, what's the overall architecture. Then list your tech stack explicitly. Don't assume Claude will infer it from your files. List your framework, your database, your key libraries, your deployment environment. If you're using specific versions that matter, say so. Two short sections. Everything Claude needs to orient itself.
Add your coding conventions and style rules. This is where most of the value lives for code projects. Claude Code has opinions about how to write code. Some of them match yours. Most need adjusting. The things worth specifying: file naming conventions, component structure preferences, whether you use default or named exports, error handling patterns, how you handle async operations, import order, TypeScript strictness settings, and any libraries you prefer for specific tasks. List the things where Claude making the wrong call would create actual rework. If you don't care about something, don't mention it.
Set your workflow instructions and constraints. These are the process rules. How do you want Claude to approach tasks? Whether to ask clarifying questions before starting a large task or make reasonable assumptions and flag them. How you want changes presented. Whether to run tests after making changes. This is also where you put environment-specific constraints. Never write directly to production tables. Always use the staging environment for database changes. That kind of rule prevents expensive mistakes.
Write a do-not section. This gets underused and it shouldn't. Negative constraints are often more valuable than positive ones, because they stop Claude from doing something that looks plausible but is wrong for your project. On one client project, Claude kept reaching for React Query because it's a sensible default. The client's team didn't know React Query. They'd standardised on SWR. One line fixed weeks of back-and-forth: Do not use React Query. Use SWR for all data fetching.
Iterate and update it as the project changes. You don't write the perfect CLAUDE.md on day one. Start with what you know, then add to it every time Claude does something that surprised you. The version that works is the one that's been through a few iterations based on what actually kept going wrong.
CLAUDE.md setup for non-code projects (automation, ops, content)
Most of the existing writing about CLAUDE.md focuses on software projects. But we use it on non-code projects constantly, automation builds, content workflows, ops systems, and it works just as well.
For an automation project, CLAUDE.md might include the tools in the stack, the business process being automated, data models and what fields matter, error handling preferences, and rate limits or constraints from external APIs.
For a content workflow project, it might include brand voice guidelines, structural templates for different content types, SEO rules and keyword targets, things the brand never says, and the approval workflow before publishing.
The underlying principle is the same regardless of project type: what does Claude need to know upfront to avoid making you explain the same things repeatedly? Write that down.
A real CLAUDE.md example, annotated
Here's a sanitised version of a CLAUDE.md we use on an internal AMPL project. I've added notes to explain the thinking behind each section.
What this is: A Claude Code project that builds and manages AI skills for AMPL's internal operations. Skills are markdown files that Claude reads as instructions for specific tasks.
Key directories: /skills for individual skill files, /context for brand voice and reference files, /data for outputs from skill runs (never auto-delete), /logs for run logs (append only, never modify existing entries).
Rules: Never modify files in /data/client without explicit confirmation. New skills go in /skills/[department]/[skill-name]/skill.md. All skill files must include: purpose, triggers, input, process, output. Context files are read-only references.
Do not: Create new top-level directories without asking first. Assume a skill should overwrite previous outputs, always version or append. Use relative imports in skill files.
A few things to notice. The project description is two sentences. Enough for Claude to understand the purpose without over-explaining. The directories section is explicit about which paths matter and the rules for each. The do-not section covers the three mistakes Claude kept making before we wrote them down.
This CLAUDE.md went through about four iterations. The first version was too vague. Lots of high-level description, not enough specific rules. The second version over-corrected. Too long, too much detail on things that didn't actually cause problems. The version above is where we landed after a few weeks of noting what kept going wrong and adding rules for it.
Common CLAUDE.md mistakes and how to fix them
Making it too long. The most common mistake. People write everything they know about the project and end up with a document that eats most of the context window. The fix: include only things that affect Claude's decisions. Background information for your own reference goes in a separate doc.
Being too vague. Follow best practices is not useful. Use TypeScript strict mode, avoid any types, prefer type assertions over non-null assertions is useful. Specific instructions produce specific compliance.
Writing it once and never updating it. Your project changes. Your CLAUDE.md should change with it. When you add a new library, update the stack section. When you find a pattern Claude keeps getting wrong, add a rule. Treat it like a living document.
Forgetting the negative constraints. Most CLAUDE.md files are all positive instructions. The do-not section is often what actually changes behaviour. Think about what Claude keeps doing that you don't want, and write those down explicitly.
Not using subdirectory CLAUDE.md files in complex projects. If you have a large project with meaningfully different parts, the root CLAUDE.md gets overloaded trying to cover everything. Put a separate CLAUDE.md in each major subdirectory covering the specific context for that part of the codebase.
Explaining why without stating the rule. We moved away from class components because of maintainability concerns doesn't tell Claude what to do. Use functional components only. No class components. does. Background is occasionally useful, but the rule needs to be explicit.
FAQ: CLAUDE.md questions
Does Claude Code automatically find my CLAUDE.md file?
Yes. When you open a project in Claude Code, it looks for CLAUDE.md in the project root and loads it automatically. You don't need to reference it in your prompt. It's already in context before you type anything. Subdirectory CLAUDE.md files are loaded when you're working in those directories.
How long should a CLAUDE.md file be?
Long enough to cover what matters, short enough to leave room in the context window for actual work. For most projects, somewhere between 200 and 600 words hits the right balance. If yours is significantly longer, review it for anything that doesn't actively affect Claude's behaviour and cut it.
Can I have multiple CLAUDE.md files in one project?
Yes. You can put a CLAUDE.md in any subdirectory. Claude loads the root file for the whole session and subdirectory files when relevant. This is useful for monorepos or projects with distinct components that have different conventions. A frontend and backend with different patterns, for example.
Does CLAUDE.md work for non-developers?
Completely. The file is plain markdown, no coding required to write it. If you're using Claude Code for automation, operations, or content workflows, the same principles apply: write down the context, rules, and constraints Claude needs to behave consistently. Write in whatever structure makes sense for your project.
What's the difference between CLAUDE.md and a system prompt?
A system prompt sets general instructions for how Claude behaves. CLAUDE.md is project-specific context. This codebase, these conventions, this team's preferences. Think of the system prompt as the job description and CLAUDE.md as the onboarding document for a specific role. Both matter, and they work together rather than replacing each other.
How often should I update my CLAUDE.md?
Any time the project changes in a way that affects how Claude should work in it. When you add a new library, when you decide to change a convention, when you find Claude repeatedly making the same mistake. Some teams do a quick CLAUDE.md review at the start of each sprint. Not a bad habit during an active build phase.
If you're using Claude Code seriously and you haven't written a CLAUDE.md yet, that's the first thing worth doing today. Start with ten minutes, write down what you know, and iterate from there. The return on that compounds every session.
If you're building something where the setup matters, a custom AI system, an ops automation build, a complex codebase, and you want someone who's already done the iteration work, that's what we do at AMPL. You might also find our Claude Code getting started guide useful if you're earlier in the process. Or if you're ready to look at what's worth automating in your business, book a free audit at amplconsulting.ai.
