Every time I opened Claude Code on a new project last year, I spent the first five minutes re-explaining my business. Who the client is. What our coding standards are. Which files matter. How we name things. Five minutes of context-setting before any real work happened, every single session.
Then I wrote my first CLAUDE.md file. That five-minute ritual disappeared overnight. Claude Code already knew. It knew our stack, our conventions, our file structure, our deployment process. Not because the model got smarter — because I told it once, in a file it reads every time it starts.
This CLAUDE.md guide is what I wish someone had handed me before I wasted three months on ad-hoc context. If you're using Claude Code and you haven't configured a CLAUDE.md file, you're running one of the most capable AI agents on the market with no memory of who you are or what you care about. That's the equivalent of hiring someone new every morning and spending the first meeting explaining your business from scratch.
What Is a CLAUDE.md File?
A CLAUDE.md file is a plain markdown file that sits in the root of your project directory. When Claude Code starts a session in that directory, it reads the file automatically and treats everything in it as persistent context — instructions, constraints, background information, and standards that apply to every interaction.
Think of it as a briefing document that your AI agent reads before it starts working. Not a prompt. Not a template. A configuration file that shapes how Claude Code thinks about your project, your codebase, and your business.
The file can contain anything: business context, coding standards, deployment instructions, file structure explanations, naming conventions, quality requirements, or explicit rules about what the agent should and shouldn't do. There's no required schema. It's just markdown.
That simplicity is the point. You write natural language instructions in a file, and your AI agent follows them every session. No API calls, no JSON configuration, no custom tooling. Just a file in your repo.
Why Operators Without a CLAUDE.md Are Burning Hours Every Week
I track my time carefully across four ventures. Before CLAUDE.md files, I was spending an average of 23 minutes per day just re-establishing context with Claude Code. That's over two hours a week of telling my AI agent things it should already know.
The problem isn't that Claude Code has a bad memory. It doesn't persist context between sessions by design — each session starts clean. The problem is that most operators treat this as an immutable fact rather than a configuration opportunity.
Here's what happens without a CLAUDE.md:
- You explain your file structure every time you ask Claude to find something
- You re-state your coding style every time you ask for code changes
- You remind it about deployment constraints every time you ask for infrastructure changes
- You describe your business model every time you need a decision that requires business context
- You correct the same mistakes repeatedly because the agent doesn't know your preferences
Every one of those re-explanations is a failure of configuration, not a failure of the model.
The Five Sections Every Operator's CLAUDE.md Needs
After writing CLAUDE.md files for twelve projects across four businesses, I've settled on five sections that cover 90% of what an operator needs. You don't need all five for every project. But these are the categories that consistently eliminate re-explanation.
1. Project Identity
Two to four sentences explaining what this project is, who it's for, and what it does. This sounds obvious, but without it, Claude Code makes generic assumptions that waste your time.
## Project
This is the marketing site for Titan Commerce, an Amazon agency serving
7- and 8-figure brands. The site runs on Eleventy with Tailwind CSS,
deploys to Vercel on push to main, and targets brand owners searching
for Amazon growth partners.
That's it. Four sentences. But they prevent dozens of wrong assumptions about audience, tech stack, and purpose.
2. Architecture and File Structure
Tell Claude Code where things live. Which directories matter. How the project is organized. This eliminates the guessing that leads to wrong file edits and missed dependencies.
## Architecture
- `src/pages/` — Nunjucks page templates
- `src/blog/posts/` — Markdown blog posts with YAML frontmatter
- `src/css/` — Tailwind source, compiled at build time
- `src/_data/` — Global data files (JSON) available to all templates
- `src/_includes/` — Shared layout and partial templates
- Static assets live in `src/assets/` and copy to `_site/` at build
You're not documenting every file. You're giving the agent a map so it navigates without asking.
3. Coding Standards and Conventions
This is where you eliminate style corrections. Every rule you put here is one fewer "actually, we do it this way" correction per session.
## Standards
- Use const over let; never use var
- Component files use PascalCase; utility files use kebab-case
- All API calls go through src/lib/api.ts — never call fetch directly
- Test files live next to the file they test with .test.ts suffix
- Commit messages: imperative mood, lowercase, no period
Example: "add retry logic to order sync"
Be specific. "Follow best practices" teaches Claude Code nothing. "API calls go through src/lib/api.ts" teaches it exactly where to put the code.
4. Deployment and Infrastructure
How does code get from the repo to production? What breaks if the agent doesn't know the constraints?
## Deployment
- Push to main triggers Vercel deploy automatically
- Environment variables live in Vercel dashboard, not in repo
- The build command is `npm run build` which runs Eleventy
- Do NOT modify _site/ directly — it's the build output
- All images must be optimized before commit (max 200KB)
This section prevents the "I pushed and broke production" scenario. Every infrastructure constraint the agent might violate belongs here.
5. Business Rules and Domain Knowledge
This is the section that separates an operator's CLAUDE.md from a developer's. Your business has rules that don't exist in code. Put them in the configuration.
## Business Context
- We serve Amazon sellers doing $1M+ annual revenue
- Our pricing is value-based, never hourly
- Client-facing content uses "we" not "I" — we present as a team
- Blog posts target operators and founders, not enterprise procurement
- We never mention competitor agencies by name in public content
These rules get violated constantly without explicit configuration. The agent doesn't know your brand voice, your pricing model, or your audience unless you tell it.
How to Write Your First CLAUDE.md in 15 Minutes
Don't try to write a perfect configuration file on day one. Start with the minimum that eliminates your most frequent re-explanations, then build from there.
Step 1: Open a terminal in your project directory and create the file:
touch CLAUDE.md
Step 2: Write the project identity section. Three sentences: what is this, who is it for, what technology does it use.
Step 3: Add your top five rules. Think about the last ten Claude Code sessions you ran on this project. What did you have to correct or re-explain more than once? Those corrections are your first five rules.
Step 4: Add the file structure section if your project has more than a handful of directories. If Claude Code has ever edited the wrong file or created a file in the wrong place, this section prevents that.
Step 5: Commit the file and start a new Claude Code session. You'll immediately notice the difference. Instructions you used to repeat are now handled automatically.
The file will grow over time. Every time you correct Claude Code about something project-specific, add that correction to the CLAUDE.md. After a month, you'll have a comprehensive configuration that covers 95% of your project's context.
Project-Level vs User-Level: What Goes Where
Claude Code reads configuration at multiple levels, and understanding the hierarchy prevents duplication and conflicts.
Project CLAUDE.md (in your repo root) — Instructions specific to this project. Tech stack, file structure, coding standards, deployment rules. This file is shared with anyone who works on the project. Put objective rules here.
User-level configuration (~/.claude/ directory) — Instructions that apply to every project you work on. Your personal preferences, your writing style, your default behaviors. These are your operator-wide standards.
The rule of thumb: if the instruction would help a collaborator working on the same project, it goes in the project CLAUDE.md. If it's a personal preference that wouldn't apply to someone else's workflow, it goes in user-level configuration.
For operators running multiple ventures, this hierarchy is powerful. My user-level configuration contains my writing voice, my preferred commit message format, and my standard for code comments. Each project's CLAUDE.md contains only what's specific to that project. Zero duplication.
From CLAUDE.md to Skills: When Instructions Deserve Their Own File
Your CLAUDE.md handles persistent context — the things that are true across every session. But some instructions are task-specific. You don't need your blog-writing rules loaded when you're debugging a deployment issue.
That's where Claude Code skills come in. Skills are standalone instruction files that live in the .claude/skills/ directory of your project. Each skill is a focused set of instructions for a specific task type, invoked on demand rather than loaded automatically.
The difference:
| CLAUDE.md | Skills |
|---|---|
| Loaded every session | Loaded on demand |
| Project-wide context | Task-specific instructions |
| Identity, standards, rules | Workflows, processes, checklists |
| Always relevant | Relevant for one type of work |
A skill file is just markdown with frontmatter that tells Claude Code when and how to use it. Here's a real skill I use for writing blog posts:
---
name: blog-post
description: Write a blog post for the site
---
## Blog Post Writing
When writing a blog post:
- Use first person, John Aspinall's voice
- No corporate jargon: never "leverage," "utilize," "holistic"
- Include specific numbers and real examples
- Target 2000-3000 words
- Structure: problem-led opening, H2 sections, FAQ, action close
- Frontmatter must include title, description, date, author,
category, keywords, permalink
- Do NOT start with an H1 — the template renders the title
When I invoke this skill, Claude Code gets these specific instructions on top of the project CLAUDE.md. When I'm doing something else — fixing a bug, updating styles — these blog-specific rules stay out of the way.
The progression for most operators: start with a CLAUDE.md that covers everything, then extract task-specific blocks into skills as the file grows past a couple of pages. You'll know it's time when your CLAUDE.md has sections that only apply to specific types of work.
CLAUDE.md Mistakes That Kill Agent Quality
I've reviewed configuration files for a dozen operators in my network. The same mistakes show up repeatedly.
Writing aspirational rules instead of specific ones. "Write clean, maintainable code" tells Claude Code nothing. "Functions longer than 30 lines should be split" tells it exactly when to act. Every rule should be testable — if you can't tell whether the agent followed it or not, rewrite it.
Stuffing the file with documentation. CLAUDE.md is an instruction file, not a README. If you're explaining how a library works or documenting API endpoints, that content belongs in docs that CLAUDE.md can reference — not in CLAUDE.md itself. Long configuration files dilute the important rules with noise.
Forgetting to update the file. Your CLAUDE.md is a living document. When you change your tech stack, your deployment process, or your standards, the file needs to change too. I review mine monthly and update whenever I catch myself correcting Claude Code about something the file should already cover.
No negative rules. Telling Claude Code what NOT to do is as important as telling it what to do. "Do not modify the database schema without explicit approval" and "never commit .env files" are the kind of negative rules that prevent costly mistakes.
Duplicating information across CLAUDE.md and skills. If your CLAUDE.md says "use TypeScript strict mode" and a skill file also says "use TypeScript strict mode," you now have two places to update when that rule changes. Put universal rules in CLAUDE.md. Put task-specific rules in skills. Never both.
Frequently Asked Questions
Does CLAUDE.md work with other AI tools, or only Claude Code?
CLAUDE.md is specific to Claude Code — it's the file that Claude Code reads automatically at session start. However, the concept of persistent agent configuration works everywhere. Other tools have their own equivalents: Cursor uses .cursorrules, GitHub Copilot uses instruction files. The principles in this guide — project identity, architecture, standards, deployment rules, business context — apply regardless of which tool reads the file.
How long should a CLAUDE.md file be? Most effective CLAUDE.md files I've seen are between 50 and 200 lines. Under 50 and you're probably missing rules that would save you time. Over 200 and you should be extracting task-specific sections into skills. The goal is comprehensive enough to eliminate re-explanation, concise enough that every line carries weight.
Should I commit CLAUDE.md to version control? Yes. It's project configuration, and it should travel with the project. If someone else clones your repo and uses Claude Code, they get the same context you do. The exception is personal preferences that only apply to your workflow — those belong in user-level configuration, not the project file.
Can I use CLAUDE.md for non-code projects? Absolutely. I have CLAUDE.md files for content projects, data analysis projects, and automation repositories. The file doesn't require code. If Claude Code opens a directory and finds a CLAUDE.md, it reads it — whether the directory contains Python, markdown, CSVs, or anything else.
How do I know if my CLAUDE.md is working? Track your corrections. Every time you manually correct Claude Code about something project-specific — a wrong file location, a style violation, a deployment constraint — that's a signal your CLAUDE.md is missing a rule. When you go a full week without correcting something that should be in the config, your file is doing its job.
Three Actions to Take Today
-
Create a CLAUDE.md file in your most-used project with the five sections from this guide. Project identity, architecture, standards, deployment, and business rules. Fifteen minutes of writing saves hours of re-explanation.
-
Track your corrections for one week. Every time you tell Claude Code something it should already know about your project, write it down. At the end of the week, add every correction to your CLAUDE.md. This is how the file compounds.
-
Extract your first skill file once your CLAUDE.md passes 150 lines. Find the section that only applies to one type of task — writing, deploying, analyzing, building — and move it to
.claude/skills/. You'll immediately notice that your general sessions get faster because they're no longer loading task-specific instructions they don't need.
Your AI agent is only as good as the context it starts with. A well-written CLAUDE.md file isn't a nice-to-have — it's the difference between an agent that needs hand-holding and one that knows your business well enough to work independently. Write the file once. Update it as you go. Watch every session get faster from the first message.