Claude Code for agencies: one setup per client project
The short answer: Put everything about a client in that client's repository: CLAUDE.md, .claude/settings.json, project skills and .mcp.json. Keep only your own habits in your home folder. Then a colleague, a fresh clone or the client gets the same setup.
Key points
- If a rule is about the client, it goes in the client's repository, committed.
- Your home folder holds your own habits for every project, never one client's details.
- A CLAUDE.md in a parent folder loads into every project below it.
- Test the setup on a fresh clone before anyone else depends on it.
On this page
An agency runs many client projects side by side. Each has its own commands, its own rules and its own services. With Claude Code, the question is where that knowledge lives. On your laptop, it helps only you. In the client’s repository, it helps everyone who opens the project, including the client after the handover.
This post is about one habit: one complete setup per client project, inside that project.
Where Claude Code reads its setup from
Claude Code reads the same kinds of files at three levels: the project, you in this project, and you everywhere. The docs name each one.
| What | The client project (commit it) | You, in this project only | You, in every project |
|---|---|---|---|
| Instructions | CLAUDE.md |
CLAUDE.local.md |
~/.claude/CLAUDE.md |
| Settings and permissions | .claude/settings.json |
.claude/settings.local.json |
settings.json in ~/.claude/ |
| Skills | .claude/skills/ |
none | ~/.claude/skills/ |
| Tool connections (MCP) | .mcp.json |
local scope | user scope |
Sources: memory, settings, skills, MCP.
The first column is the only one that travels. The settings docs say it plainly: the project file reaches a teammate’s clone only once you commit it. Until then, nobody else has it.
The rule: if it is about the client, it goes in the client’s repository
Ask one question for each rule, permission or tool: is this about this client, or about how I work?
About this client goes in the project, committed:
CLAUDE.md: the commands that run and check this app, the decisions that aren’t visible in the code, the traps. Our CLAUDE.md guide covers what to write..claude/settings.json: what Claude may run without asking, and what it must never touch. The docs show a deny rule that stops Claude reading.envfiles (settings). Deny rules in a committed file apply at once; allow rules wait until each person trusts the folder..claude/skills/: the steps for this project’s release, review or data import. The docs say to commit project skills so the team gets them (skills). Our skills guide explains what a skill is..mcp.json: the services this project connects to. Write keys as${API_KEY}, so the file holds the name and each person’s machine holds the value (MCP docs).
About how you work stays with you: your editor habits, your preferred model, how you like answers written. That goes in ~/.claude/.
Watch out
Never put a client’s secret in any of these files. Committed files go to everyone with the repository, and the client keeps them after the handover.
Three traps across many clients
A parent folder leaks into every project. Claude Code loads CLAUDE.md from your working folder and every folder above it (memory docs). If all your clients sit in one clients/ folder with its own CLAUDE.md, that file loads into every client project. Keep client details out of it.
Your personal skill wins over the project’s. When two skills share a name, the personal one runs, not the project one (skills docs). A deploy skill in your home folder silently replaces each client’s own deploy. Give your personal skills names no project will use.
Some knowledge never leaves your machine. Auto memory, the notes Claude writes for itself, is machine-local and not shared (memory docs). So are CLAUDE.local.md and .claude/settings.local.json. Claude Code keeps the local settings file out of git when it creates it (settings docs). If something in those files matters for the project, move it into the committed files.
Setting up a new client project
- Create the repository under the client’s account, or plan to transfer it.
- Start Claude Code in the project folder and run
/initfor a firstCLAUDE.md. - Add the commands that check the work, and the decisions you already know.
- Add
.claude/settings.jsonwith the project’s deny rules, at least for secret files. - Commit all of it with the first code.
Ask Claude
Read this project and tell me which of my instructions, permissions, skills and MCP servers are about this client but live outside the repository. List each one with where it should move.
Test it on a fresh clone
The real test is a machine that has never seen the project. Clone it into a new folder, or ask a colleague to. Start Claude Code there and ask:
Ask Claude
Read CLAUDE.md and tell me how to run and check this project. Then run the check.
If Claude finds the commands and the check passes, the setup lives in the project. If it asks questions you answered weeks ago, those answers are still on your laptop.
- Every client rule is in the project’s
CLAUDE.md, not in~/.claude/CLAUDE.md. -
.claude/settings.jsonis committed and denies reading secret files. - Project skills are in
.claude/skills/, with names your personal skills don’t use. -
.mcp.jsonnames its keys with${…}and holds no values. - A fresh clone runs the check without your help.
A project set up this way is already half handed over. When the day comes, our handover guide lists the rest.