Here’s How I Get the Most Out of My CLAUDE.md

Aditi — Mon, 14 Sep 2026 07:33:07 +0000

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.

Where should you put CLAUDE.md?

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.

Replace good intentions with actual instructions

An instruction that feels clear to you can still be vague to your agent.

For example, if you keep giving prompts like these:

Write clean code
Follow best practices
Test thoroughly
Keep the architecture consistent

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:

Route handlers belong in src/routes/
Put database queries in src/repositories
Validate request bodies with the existing Zod schemas
Return errors through src/lib/api-error.ts
For bug fixes, add a regression test covering the reported failure

Now these are concrete decisions to follow.

Write Down the Commands Your Project Uses

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.

Install dependencies: pnpm install
Start development server: pnpm dev
Type-check: pnpm typecheck
Run unit tests once: pnpm exec vitest run
Run one test file: pnpm exec vitest run

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.

Capture the project quirks that look like mistakes

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

API and database amounts use integer cents
Convert to display currency only in the UI
Reuse formatMoney() from src/lib/money.ts

Or suppose an older mobile client depends on an unusual response:

Compatibility

POST/subscriptions return HTTP 200 for duplicate requests
Older mobile clients depend on this behaviour
Preserve it unless the task explicitly changes the API contract That last sentence also leaves room for intentional change. You don’t want a historical note to become an unexplained rule nobody can revisit.

A short explanation of why something exists can prevent an unnecessary fix.

Turn recurring corrections into reusable guidance

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

Check package.json and src/lib/ for an existing solution before adding a runtime dependency
For dates, reuse src/lib/date.ts
If a new dependency is needed, explain what the existing tools cannot handle
It identifies the check, points to the relevant code, and explains how to handle an exception.

Be selective, though. One unusual task doesn’t always justify a permanent rule. Ask whether the correction will still matter next month.

Keep temporary work out of permanent instructions

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/.

A simple format for your CLAUDE.md

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.

DEV Community: Aditi