Claude.md: the file that makes Claude Code work for you

Your dev team keeps explaining the same things to Claude Code. Where the auth logic lives. Which folder holds the Stripe webhooks. Why nobody touches the legacy billing module? Every session starts from zero, and every session costs time you're paying for.

CLAUDE.md fixes that. It's a plain text file that sits in your project and gets read automatically before Claude starts working. Think of it as the onboarding doc you'd hand a new hire on day one, except this one actually gets read every single time.

Most teams get this wrong in one of two directions. They skip the file and pay for the same corrections over and over. Or they dump the entire engineering handbook into it and Claude drowns in detail it didn't need. Neither gets you what you're paying for.

If you're still deciding whether Claude Code is worth adopting in the first place, that's worth reading first. This piece assumes you've already made that call and want the setup done right.

Key takeaways

• CLAUDE.md is a file Claude Code reads automatically, so you stop paying for it to relearn your project every session
• It works like an onboarding doc for a new hire, not a technical config file
• A good one is short and specific to your project's quirks, not a list of generic rules copied from a template
• The best CLAUDE.md files get updated every time Claude repeats a mistake, the same way you'd correct a new employee
• Anthropic recommends keeping the file under roughly 200 lines, since bloated files eat context and hurt output quality
• A real example and a copyable template are below, no coding background required to use them

What is claude.md?

CLAUDE.md is a text file that lives at the root of your project. When you start a Claude Code session, it reads that file before touching anything else. That's the entire mechanism. No plugin, no dashboard, no setup wizard.

Where it lives

The file sits in your project's root folder, next to your package configuration and top-level source folders. Larger codebases sometimes add a second CLAUDE.md inside a specific subfolder, like an API service or a mobile app, so that folder gets its own local context on top of the project-wide one.

When Claude reads it

Claude checks the file at the start of a session, before it makes any changes. It doesn't re-read it mid-conversation unless you edit the file and start fresh. That's why the file needs to hold the instructions that stay true across the whole project, not a note about what you're working on today.

The problem it solves

Without a CLAUDE.md, you're typing the same context into chat every time: what the product does, which patterns to follow, which files are off limits. With it, you write that once and Claude checks it automatically at the start of every session. That's fewer explanations, fewer repeated mistakes, and less of your developer's time spent re-briefing an AI instead of building.

Chat instructions versus a persistent file

The founder-relevant difference is simple. Chat instructions are a conversation you have to keep having. CLAUDE.md is a decision you make once and Claude respects until you change it. If a rule needs to apply to every session going forward, it belongs in the file, not in a message.

What should you put in claude.md?

This is where most files fall apart, either too thin to matter or too bloated to read. Here's what actually earns a spot:

• Project overview. One or two sentences on what the product does. The kind of thing you'd say out loud to a new hire, not a spec document.
• Architecture and directory structure. How the pieces fit together, kept brief. This is orientation, not a deep dive.
• Coding conventions and commands. Even if you never open a code editor, this matters to you: consistency here means fewer bugs surfacing three weeks later.
• Testing instructions. How to check that nothing broke. This is the section that answers whether it's safe to ship.
• Dependencies. What the project relies on and why.
• Things Claude should never do. Founders read this section fastest because it's a guardrail, not a permission slip. Never touch the payments table directly. Never delete migration files. That kind of thing.
• Workflow and definition of done. What finished looks like on your team, not Claude's default assumption of finished.
• Known gotchas. The weird stuff. The API that lies about its rate limits. The one component that breaks if you touch it before 9am, metaphorically speaking.

Every one of these should exist because it changes what Claude does. If a line wouldn't change Claude's behavior, it doesn't belong.

Claude.md example

Here's what this looks like on a real stack: Next.js on the frontend, Supabase for the database and auth, Stripe for billing. Not a hypothetical, a project shape most founders in this position actually have.

Sample file

# CLAUDE.md

This file explains how Claude Code should work inside this repository.

Read it before making changes.

## Project

This is a web application for [briefly describe the users and product].

Current priority:
- Build: [current feature or phase]
- Deadline: [date, if relevant]
- Scope: [link or file containing requirements]

If requirements are unclear, ask before implementing.

## Tech stack

- Frontend: Next.js
- Language: TypeScript
- Database: PostgreSQL
- Hosting: Vercel
- Testing: [testing framework]

Do not introduce new frameworks or major dependencies without approval.

## Key project rules

- Follow the existing architecture and coding conventions.
- Keep changes limited to the requested task.
- Do not refactor unrelated code.
- Never modify an existing database migration. Create a new one.
- Add tests for new behaviour and bug fixes.
- Never expose secrets, API keys or environment variables.
- Ask before making architectural changes.

Add new rules here when important project decisions are made.

## Before coding

Before implementing a substantial change:

1. Read the relevant existing code.
2. Identify the files likely to change.
3. State any assumptions.
4. Explain the proposed approach.
5. Define how the result will be tested.

If something is ambiguous, stop and ask rather than guessing.

## Development guidelines

### Keep it simple

Write the minimum code required to solve the requested problem.

Avoid:
- unnecessary abstractions
- speculative features
- new dependencies without a clear reason
- changes unrelated to the task

### Make surgical changes

Every changed line should have a reason connected to the task.

Match the existing project's conventions instead of rewriting surrounding code to match your preferences.

### Verify your work

For a bug:

1. Reproduce the problem.
2. Add or identify a test that catches it.
3. Fix the problem.
4. Run the relevant tests.

For a feature:

1. Define the expected behaviour.
2. Implement it.
3. Test the main path and important edge cases.
4. Run the relevant test suite.

Do not describe work as complete until the relevant checks pass.

## Git workflow

Never work directly on `main`.

For each task:

1. Pull the latest `main`.
2. Create a dedicated branch.
3. Make focused commits.
4. Run tests before opening a pull request.
5. Review the final diff for unrelated changes.

## Communication

Keep explanations short and clear.

When finishing a task, report:

- what changed
- which files were affected
- what was tested
- anything that still needs human review

If you are uncertain about a requirement, say so instead of silently choosing an interpretation.

Why this version works

Nothing in that file explains what Next.js is or what a webhook does in general. It only says what's true about this project. That's the whole point. A founder reading it can still follow the shape of it: what exists, what's off limits, and what counts as done, without needing to read a single line of the actual codebase.

Claude.md template

Strip the specifics out and this is what you're left with. Copy this, hand it to your developer, and have them fill in the brackets.

Copyable structure

# Project overview
[What the product does, in one or two sentences]

# Architecture
[Key folders and what lives in each]

# Conventions
[Patterns to follow, patterns to avoid]

# Commands
[Dev server, tests, build, lint, whatever you actually run]

# Never do this
[Specific actions that would break something or violate a business rule]

# Definition of done
[What finished means before something ships]

# Known gotchas
[The non-obvious stuff that's bitten your team before]

Seven sections. If your file is longer than a page and a half, something in there is probably explaining what the code already explains on its own.

Claude.md best practices

Anthropic's own guidance points at a specific number: keep these files under roughly 200 lines. Past that, the file starts eating context that Claude needs for the actual work, and instruction-following gets worse, not better. More isn't more useful here. It's the opposite.

Don't document what Claude can already read

If a function is named calculateInvoiceTotal, you don't need a line explaining what it calculates. Claude reads code. Reserve the file for what the code can't tell it on its own.

Prioritize what's unique to your project

Writing clean code tells Claude nothing. Never bypass the RLS policy in the invoices table tells it something it couldn't have guessed. Generic advice is free everywhere. Your project's specific rules are the only thing this file can offer that a general AI coding guide can't.

Use commands, not descriptions

Run npm run test beats a vague reminder to make sure it's tested. An instruction Claude can execute directly is worth more than a description it has to interpret.

Document the boundaries

Be specific about what Claude shouldn't touch: which tables, which files, which folders are off limits and why. This is the section that prevents the expensive mistakes, the ones that cost a founder real money to undo.

Tell Claude how to verify its own work

If there's a test suite or a typecheck command, say so directly in the file. A model that knows how to check its own output catches more problems before they reach you.

Don't turn it into your engineering handbook

A full onboarding manual, style guide, or architecture decision record can live somewhere else. CLAUDE.md is for what actually changes Claude's behavior in this specific codebase, nothing more.

Let it evolve from Claude's failures

This is the practice that matters most, and it rarely shows up in generic guides. When Claude makes the same project-specific mistake twice, that's not a one-off correction anymore. That's a line that belongs in the file, the same way you'd update onboarding material after a new hire tripped on the same thing twice. Treat every repeated error as a prompt to update the file, not just the code.

How we use claude.md in AI-assisted development

We're not writing this from a whiteboard. Every project we build with Claude Code starts with a CLAUDE.md file that gets built out as the codebase does, not written once and abandoned. If you're weighing Claude Code against other coding agents for your team, our comparison of Gemini CLI and Claude Code covers where each one holds up.

Less repeated explanation

Time spent re-explaining context session to session drops close to zero, because the file already carries it. That's hours back on every project, not just the first week of one.

More consistency across the codebase

A codebase built over weeks stays consistent when the same rules apply automatically in every session. That matters when a founder is trusting AI-assisted work to hold up under real usage, not just in a demo.

Fewer invisible architectural changes

Boundaries documented in the file stop Claude from making changes a non-technical founder would have no way to catch until something broke in production.

More reliable tests and checks

Tests and checks actually run the way they're supposed to, because the file tells Claude how to verify its own work instead of leaving that step optional.

Better continuity between sessions

That continuity is what makes AI-assisted development hold up at the pace founders actually need, not just in a demo, but across the months it takes to build something real.

Ready to build your project with a team that treats claude.md as part of the deliverable?

We set up context files like this on every AI-assisted build we run, so your codebase stays consistent long after the first sprint. Book a call and we'll show you what that looks like for your project.

Start your project, call Tom.

‍