How to Write a CLAUDE.md for a Client Project (The Five-Block Template)

What a CLAUDE.md Is and Why Client Work Needs One

A CLAUDE.md is a plain markdown file you put in the root of a project folder. Claude Code reads it automatically at the start of a session in that project, so whatever it says becomes standing context for every request you make afterwards. You do not paste it, reference it, or remind anybody it exists. Open the project in the desktop app and it is already loaded.

On your own projects that is a convenience. On client work it is infrastructure. A paid build runs over weeks, across many separate sessions, often with gaps of days between them. Without a standing brief, every session starts from nothing and the work drifts: a different folder structure here, a second state library there, a test suite written in a style that does not match the first one. You end up spending billable hours correcting a codebase that is arguing with itself.

The file also does a job nobody warns you about. It is the cheapest scope document you will ever write. When the rules of the project are written down in the repo, the boundary between what was agreed and what is a new request stops being a memory exercise. That connects directly to [stopping scope creep on a Claude Code project](/blog/stop-scope-creep-on-a-claude-code-project), which is the other half of the same problem.

The Five-Block CLAUDE.md

Write the file in five blocks, in this order: outcome, stack, commands, conventions, boundaries. This is the Profit Room's Five-Block CLAUDE.md, and the order is the point. Instructions near the top of a long context carry more weight than instructions buried at the bottom, so the things you least want ignored go first.

Keep the whole thing to roughly one screen of text. A long CLAUDE.md is a worse CLAUDE.md. Every line you add dilutes the ones that matter, and a file full of aspirational rules nobody enforces trains you to stop trusting it. If a rule has not mattered in three sessions, delete it.

Block One: The Outcome, Not The Feature List

Open with one short paragraph explaining what the project is for in the client's language, not yours. Who uses this, what job it does for them, and what a good outcome looks like. Not a feature list.

This block does most of the quiet work in the file. When a request is ambiguous, and on client projects most of them are, the outcome paragraph is what resolves it. A build described as an internal tool for two staff to check order status gets simple, direct implementations. The same build described only as a Next.js dashboard with authentication gets an architecture nobody needed and an invoice conversation you did not want.

• Name the actual users. Two warehouse staff on a shared desktop is a different build from three hundred customers on phones, and one sentence saves you from guessing.
• State the one thing that must work. Every project has a single feature that, if it breaks, means the project failed. Write it down.
• Name the deadline pressure if there is one. Shipping before a client's busy season is a real constraint and it changes the right technical call.
• Leave the commercial terms out. The rate, the payment schedule and the contract belong in [your one-page agreement](/blog/one-page-agreement-before-you-build), not in a file that ships with the code.

Block Two: Stack, Versions, and What May Not Be Added

List the stack with versions, then list what may not be added. The second half is the part most people skip and it is the half that saves you money.

Left unconstrained, a long build accumulates dependencies. A date library on Tuesday, a second one on Friday because a different session picked a different favourite. None of it is wrong in isolation and all of it becomes your maintenance problem, because you are the one who will be supporting this in six months when the client emails about a bug.

So write the constraint plainly. Name the framework and major version, the database, the styling approach, the test runner, the deployment target. Then add a line saying no new dependencies without asking first, and mean it. On a client project a new package is a decision with a support cost attached, not a convenience.

Block Three: The Commands That Actually Run

Write out the exact commands for install, run, test, build and deploy, copied from a terminal where you have just watched them succeed. Not from memory, and not from the README, which is frequently out of date.

This is the highest-value block per line of text in the whole file. Without it, verification becomes guesswork: a plausible test command gets tried, it fails for an environment reason, and time disappears into a problem that never existed. With it, the work can be checked before you look at it, which is the entire point of writing anything down.

1. Install, with the package manager the project actually uses. Mixing package managers in one repo creates lockfile problems that are tedious to unpick.
2. Run locally, including any environment variables that must be present and where they come from. Name the variables. Never paste the values.
3. Test, and say which command is the real gate. Many repos have several test scripts and only one of them is the one that has to pass.
4. Build, exactly as the deploy platform runs it, so a local pass means something.
5. Deploy, and state explicitly who is allowed to run it. On client work that answer is usually you and only after the client has signed off.

Block Four: Conventions and Review Rules

Describe the conventions by pointing at real files rather than by writing rules in the abstract. One line saying new API routes follow the pattern in a named existing file does more than three paragraphs describing that pattern in prose.

Point at the best examples you have. The cleanest component, the clearest route handler, the test file you would be happy to show the client. Those become the template for everything added afterwards, and the codebase converges on a single style instead of accumulating five.

Then add the review rules, which are the ones about how work gets delivered rather than how it gets written. Small commits. No unrelated refactors inside a feature change. No rewriting a working file to tidy it. On client projects a surprise refactor is not a gift, it is an unbudgeted risk to something that was already working and already paid for.

Block Five: The Do-Not-Touch List

End with an explicit list of what must never be modified, run, or read. Files, directories, systems, and data. This is the block that prevents the expensive kind of mistake rather than the annoying kind.

On a personal project the worst outcome is your own wasted afternoon. On a client project the worst outcome involves somebody else's live system, their customers, or their data, and it arrives as a phone call rather than a git revert. The list costs you five minutes to write.

• Production configuration and any environment file. Name them so there is no ambiguity about which files are off limits.
• Live databases and any script that writes to one. State that migrations are proposed, reviewed by you, and run deliberately, never as part of a feature task.
• Vendor directories, generated code and build output, which should be regenerated rather than hand edited.
• Anything owned by another team at the client. On larger engagements parts of the codebase belong to people you have never met, and editing their files is a political problem as much as a technical one.
• Client data of any kind. If real records are needed for testing, use a scrubbed copy and say so here. The wider version of this argument is in [is it safe to use Claude Code with client data](/blog/is-it-safe-to-use-claude-code-with-client-data).

Where the File Lives and Who Else Reads It

Put it at the root of the project folder and commit it to the repository. The desktop app picks it up when you open that folder, so there is no setup step and nothing to remember on a Monday morning.

Committing it has a second effect worth planning for. The client can read it. Anyone they hire after you can read it. That is a feature, as long as you write it knowing it will be read. Keep the tone factual, keep opinions about the client out of it, and keep every rule justifiable to a stranger.

On a big project you can also put a short CLAUDE.md inside a subdirectory that has its own rules, which is useful when a repo contains, say, a marketing site and an application with genuinely different conventions. Do this sparingly. Two files that quietly disagree are worse than one file that is slightly too general.

Keeping It Current Without Making It a Chore

Update the file when a decision changes, not on a schedule. The trigger is simple: any time you correct the same thing twice, that correction becomes a line in the CLAUDE.md.

That rule keeps the file honest and keeps it short. It only ever grows in response to something that actually went wrong, which means every line in it has earned its place. A file maintained on a calendar fills up with rules nobody needed and starts getting ignored wholesale, including the five lines that mattered.

Prune at the same time. When a section of the project is finished and frozen, its conventions can come out. When the stack decision is now visible in the code itself, the paragraph explaining it can go. Treat the file as a working brief, not an archive, and it stays useful across the whole engagement. It also slots naturally into a repeatable delivery process, which is covered in [systematize your delivery pipeline](/blog/systematize-your-delivery-pipeline).

What This Does for Scope, Handoff, and Your Rate

The commercial return on this file is three things: fewer disputes about what was agreed, a faster handoff at the end, and a stronger case for being paid as a professional rather than a pair of hands.

On scope, the file is contemporaneous evidence. When a request arrives that contradicts a written rule, the conversation is about a change to an agreed constraint rather than about whose memory is better. That is a much calmer conversation and it is far more likely to end with a change order than an argument.

On handoff, a project with a clear standing brief can be picked up by somebody else without a week of archaeology. That sounds like a reason not to write it. It is the opposite. Clients pay more, and stay longer, with suppliers who leave things in a state where they are not trapped. The full version of that argument is in [how to offboard a Claude Code client](/blog/how-to-offboard-a-claude-code-client).

Common Mistakes in Client CLAUDE.md Files

Almost every bad version of this file fails in one of six ways, and all six are easy to check for before you commit it.

1. Secrets in the file. API keys, database URLs, passwords, tokens. It is committed and it is shared. Name the variable, never the value.
2. Too long. A file nobody reads to the end is a file whose last section does not exist. One screen is the target.
3. Aspirational rules. Writing that everything must have full test coverage when the project does not have a test suite teaches everybody, including you, to treat the file as decoration.
4. Vague conventions. Follow best practices means nothing. Point at a specific file that already does it right.
5. Client business context that should be private. Their revenue, their staff problems, their commercial plans do not belong in the repo.
6. Never updated. A file describing a stack the project abandoned in week two is worse than no file, because it is confidently wrong.

Read your file back once before the first commit and ask one question about every line: would I be comfortable if the client's next developer read this? Anything that fails that test comes out. Everything that survives is worth keeping.