What a CLAUDE.md File Does, and Why the Template Matters
A CLAUDE.md file sits in your project and is the first thing Claude Code reads before it does anything. Think of it as the briefing you would give a new senior developer on their first morning - what this project is, how it is built, how to run it, and the standards you expect. Without it, the agent infers all of that from scratch every session and often guesses wrong. With it, the agent starts already knowing your world, and its output fits instead of fighting your conventions.
The reason a template matters is that a blank page invites either too little or too much. Too little, and the agent still has to guess. Too much, and the important rules drown in noise. A good CLAUDE.md is short, specific, and skimmable - the handful of things that actually change the output. The templates below give you that shape for the most common kinds of project so you are editing a starting point rather than staring at nothing.
The Common Backbone Every CLAUDE.md Should Have
Whatever you are building, five sections carry most of the value. Get these right and you have covered eighty percent of what the agent needs. The rest is project-specific flavor.
- Overview: one short paragraph on what this project is and who it is for.
- Stack and structure: the main languages, frameworks, and how the folders are laid out.
- How to run it: the exact commands to install, run, build, and test.
- Conventions: the patterns and style you want followed, stated plainly.
- Never do this: the specific traps, the destructive commands, and the rules that must not be broken.
Template: A Web App or SaaS Project
For a web application, the agent needs to know your framework, how data flows, and how you ship. Fill the backbone, then add the specifics that keep front end and back end consistent.
- Stack: the framework, language, styling approach, and database, named exactly.
- Structure: where pages, components, shared logic, and API routes live.
- Data: how state is managed and how the app talks to its backend or database.
- Commands: install, local dev server, build, test, and how you deploy.
- Conventions: component patterns, naming, and how new features should be wired in.
- Never do this: touch production data, commit secrets, or bypass the type checker.
Template: A Client or Agency Build
On client work, the file carries an extra job - protecting the relationship and the boundaries of the engagement. Alongside the technical backbone, spell out what is in scope and what must never happen on someone else's system.
- Context: whose project this is, the goal of the engagement, and what done looks like.
- Environments: which is development and which is live, stated unmistakably.
- Access rules: what the agent may touch and what is strictly off limits.
- Deliverables: the specific things being built, so work stays inside scope.
- Conventions: the client's existing style, so your work blends in rather than stands out.
- Never do this: run destructive commands, alter live data, or expose client credentials.
Template: Automation and Scripts
Automation projects are smaller in code but higher in consequence, because they run on their own and touch real systems. The file should make the blast radius of every action obvious before anything runs.
- Purpose: what this automation does and what triggers it.
- Inputs and outputs: where data comes from and where results go.
- External systems: the APIs, files, or accounts it touches, and any limits on them.
- Safety: what counts as a safe dry run versus a real action with side effects.
- Commands: how to test a run without consequences before letting it act for real.
- Never do this: send, delete, or spend without an explicit confirmation step.
Template: A Content or Marketing Site
For a content site, the technical stack matters less than voice, structure, and consistency. The file should protect how the site reads and how new pages are made so everything stays on brand.
- Purpose: what the site is for and who it speaks to.
- Voice: the tone and style, with a plain do and do-not list.
- Structure: where pages, posts, and shared layout live, and how a new page is added.
- Content rules: formatting standards, and anything that must never appear.
- Commands: how to run the site locally and publish a change.
- Never do this: break the house style, or ship a page without the required fields.
How to Keep Your CLAUDE.md From Going Stale
A context file is only useful while it is true. The fastest way to lose the benefit is to write it once and let the project drift away from it, because now the agent is following instructions that no longer match reality. Treat the file as living documentation. When you change the stack, add a command, or set a new rule, update the file in the same breath. A two-minute edit keeps every future session accurate, and it costs far less than the confusion of an agent working from a description that has quietly gone wrong.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is a CLAUDE.md file?
It is a file in your project that Claude Code reads before it does anything, describing what the project is, how it is built, how to run it, and the rules to follow. It works like the briefing you would give a new senior developer, so the agent starts each session already knowing your project instead of guessing.
What should I put in a CLAUDE.md file?
Five things carry most of the value: an overview of the project, the stack and folder structure, the exact commands to run and test it, the conventions you want followed, and a clear list of things never to do. Everything else is project-specific detail on top of that backbone.
Does the CLAUDE.md change depending on the project?
The backbone stays the same, but the details shift. A web app needs data flow and deploy steps; a client build needs scope and access boundaries; an automation project needs the blast radius of each action; a content site needs voice and structure. The templates above give you a starting point for each.
How long should a CLAUDE.md file be?
Short and skimmable. A blank page invites too little or too much, and the important rules drown when the file is bloated. Aim for the handful of things that actually change the output, and cut the nice-to-know. A tight file that is true beats an exhaustive one that is out of date.
How do I stop my CLAUDE.md from going out of date?
Treat it as living documentation and update it in the same breath as the change. When you switch part of the stack, add a command, or set a new rule, edit the file right then. A two-minute update keeps every future session accurate and avoids the agent following instructions that no longer match the project.
Where does the CLAUDE.md file go?
In the project so the agent picks it up automatically as context. The key point is that you do not have to paste this information into every conversation - once it lives in the file, Claude Code reads it each session, which is exactly why keeping it accurate is worth the small effort.
Last reviewed by Duncan Rogoff on July 17, 2026
