Every time I started a new session with Claude, I found myself repeating the same instructions. Which commands to use, how I wanted the code written, what to test. I kept copy-pasting the same saved message from my notes whenever I started a new chat.
That’s when I found out about the CLAUDE.md file.
It gives those recurring instructions a place in your project, so Claude can read them across sessions without you having to repeat yourself.
There are plenty of ways to write a CLAUDE.md file, but here’s how I like to approach it for maximum benefits. I’ll walk you through the structure I use, what I include, and what I leave out, with a few examples you can adapt to your own project.
Start with your project’s root folder, the same place you’d usually find the README. Create a file named CLAUDE.md, like this:
my-project/
- CLAUDE.md
- README.md
- package.json
- src/
- tests/
Commit the file to Git so your teammates can use the same guidance.
You can also keep this file at .claude/CLAUDE.md
As the project grows, you might need different instructions for particular areas. In such cases, you can create CLAUDE.md at sub-directory paths as well. For example:
my-project/
- CLAUDE.md
- src/
- frontend/
- CLAUDE.md
- backend/
- CLAUDE.md
For a start, one file at the root is enough. Add more when different parts of your project actually need different instructions.
An instruction that feels clear to you can still be vague to your agent.
For example, if you keep giving prompts like these:
These sound like good instructions, but they leave a lot for your AI agent to guess. Think from its perspective: what does thorough testingmean in your project, and which best practices should it follow? You know what you mean, but your agent needs those details spelled out.
Here’s a more useful version for an example TypeScript API:
Now these are concrete decisions to follow.
A project might have unit tests, integration tests, browser tests, and several ways to start the app. In such cases, writing “Run the tests after any edit” doesn’t give concrete steps to the agent.
For a hypothetical project using pnpm and Vitest, you could write:
Commands
Run these from the repository root.
The working directory and prerequisites matter as much as the command.
Before adding these, run them yourself. A copied command that starts watch mode or needs an undocumented service creates another problem to debug.
Also, avoid making every tiny change trigger every expensive check. Describe the checks that make sense for your project and let CI enforce the required gates.
This is where the file can earn its place.
Suppose an API represents money in integer cents. A price of $19.99 travels through the system as 1999. Without that context, a perfectly reasonable looking change could introduce inconsistent values.
Better way:
Money
Or suppose an older mobile client depends on an unusual response:
Compatibility
A short explanation of why something exists can prevent an unnecessary fix.
Imagine Claude adds a new date formatting library when the project already has a shared formatter.
You could respond with:
Don’t add unnecessary dependencies.
But the next task might produce the same disagreement about what unnecessary means.
A better instruction would be:
Dependencies
Be selective, though. One unusual task doesn’t always justify a permanent rule. Ask whether the correction will still matter next month.
A note like this has an expiry date:
We are fixing the checkout bug today.
The failing account is test-user-42.
Try increasing the timeout first.
These kinds of instructions don’t belong in CLAUDE.md because, if they’re left there after the work is done, they can cause confusion later.
That’s why I prefer keeping task-specific instructions in separate files.
Claude Code supports path-scoped rules in .claude/rules/.
Start with the information Claude needs to work on your project: what it does, how to run it, which conventions to follow, and how to check changes. You can use this structure and fill in the details.
Project overview
- Briefly explain what this project does and its main technologies.
Useful commands
- Set up the project: [command]
- Run locally: [command]
- Run tests: [command]
- Check formatting and linting: [command]
Mention where to run these commands and any required setup.
Where things live
- Point to the main source code, tests, and important documentation.
- Include locations that may be difficult to find or easy to confuse.
Project conventions
- Describe the patterns to follow and existing helpers to reuse.
- Focus on decisions that aren't obvious from reading the code.
Things to watch out for
- Explain unusual behavior that must be preserved.
- Identify generated files and how they should be updated.
- Give a short reason for each restriction.
Checking changes
- Explain how to choose and run the relevant checks.
- Ask Claude to report what it checked and anything it couldn't verify.
You don’t have to fill every section. If there’s nothing useful to say under one, leave it out. Replace the placeholders with real commands and paths before using the file.
That brings us to the end of this blog! If there’s a practice you find helpful when writing your CLAUDE.md, share it in the comments. I’d love to give it a try.
Originally published on Medium. Follow me there for more articles on AI tools and software development.