How to Use Claude Code's Context Inheritance for Multi-Client Projects

The Multi-Client Context Problem

If you manage work for more than one client, you’ve probably hit this wall: your AI coding assistant either knows too much about the wrong client, or knows nothing about the right one. You paste the same coding standards into every new conversation. You re-explain your preferred file structure. You remind it that Client A uses Tailwind while Client B hates it.

Claude Code’s context inheritance changes this. By structuring your workspace around a parent-folder system and using layered CLAUDE.md files, you can share your core skills and methodology across every client project while keeping each client’s brand context, memory, and preferences completely isolated.

This guide walks through exactly how to set that up — folder structure, what to put where, and how to avoid the mistakes that break the inheritance model.

---

What Claude Code Context Inheritance Actually Is

Claude Code reads instructions from CLAUDE.md files. These are plain markdown files you place in your project directories. What makes them powerful for multi-client work is that Claude Code reads them hierarchically — it starts from the current working directory and walks up the folder tree, collecting CLAUDE.md files as it goes.

This means context stacks. A CLAUDE.md at /projects/ applies everywhere inside that folder. A CLAUDE.md at /projects/client-acme/ applies only to that client’s work, and it builds on top of whatever the parent defined.

The Inheritance Chain

Here’s the basic chain:

~/ (home or workspace root)
└── CLAUDE.md  ← global developer identity, universal preferences
    └── projects/
        └── CLAUDE.md  ← shared methodology, standards across all clients
            ├── client-acme/
            │   └── CLAUDE.md  ← Acme's brand, stack, tone, memory
            └── client-beta/
                └── CLAUDE.md  ← Beta's brand, stack, tone, memory

When you work inside client-acme/, Claude Code sees all three CLAUDE.md files. When you work inside client-beta/, it sees the root, the projects-level, and Beta’s — but nothing from Acme.

This is the core mechanic. Parent context is shared. Sibling context is invisible.

What Gets Inherited vs. What Stays Isolated

Inherited from parent (shared across clients):

• Your preferred code style and formatting conventions
• Testing philosophy and patterns
• Git commit message format
• Common utility functions or patterns you reuse
• How you like responses formatted (concise vs. verbose, etc.)
• Security practices and things to always check

Isolated per client:

• Brand voice and tone for copy, comments, or docs
• Tech stack and framework choices
• Deployment targets and environment variables
• Client-specific terminology and naming conventions
• Ongoing project memory (what’s been built, what’s in progress)
• Relationship context (who the stakeholders are, what they care about)

Getting this split right is the whole game.

---

Setting Up Your Folder Structure

Before writing any CLAUDE.md content, get your folder structure right. The structure determines what context is visible where.

Recommended Structure for Freelancers and Agencies

~/work/
├── CLAUDE.md                   ← your global developer profile
├── shared/
│   ├── components/             ← shared code you reuse across clients
│   └── templates/
├── client-acme/
│   ├── CLAUDE.md               ← Acme-specific context
│   ├── website/
│   ├── dashboard/
│   └── mobile-app/
├── client-beta/
│   ├── CLAUDE.md               ← Beta-specific context
│   └── internal-tools/
└── client-gamma/
    ├── CLAUDE.md               ← Gamma-specific context
    └── ecommerce/

Each client lives in its own top-level folder. The ~/work/CLAUDE.md handles everything that applies to all of them.

If your clients share a tech stack (say, everyone is on Next.js), you can add an intermediate layer:

~/work/
├── CLAUDE.md                   ← global preferences
├── nextjs-clients/
│   ├── CLAUDE.md               ← Next.js-specific patterns, shared across this subset
│   ├── client-acme/
│   └── client-beta/
└── rails-clients/
    ├── CLAUDE.md               ← Rails patterns
    └── client-gamma/

This is worth doing when you have 4+ clients on the same stack. It keeps framework-specific knowledge in one place.

One Project vs. Multiple Projects Per Client

If a client has multiple projects — say a marketing site, an internal dashboard, and a mobile app — keep them all inside the same client folder. Their shared CLAUDE.md will carry context across all three projects, which is usually what you want. Client-level memory (like “they moved to AWS in Q3” or “the CTO prefers functional components”) applies to everything you build for them.

If two projects for the same client are drastically different enough to need conflicting instructions, add a project-level CLAUDE.md inside each project subfolder. That narrows scope without breaking the parent chain.

---

Writing an Effective Parent CLAUDE.md

The parent CLAUDE.md is where you define who you are as a developer. Think of it as your permanent professional context — the things that should be true for every engagement, regardless of client.

What Belongs in the Root CLAUDE.md

Your coding standards. Be specific. Don’t write “write clean code.” Write the actual rules:

## Code Style
- Use TypeScript everywhere. No plain JS files.
- Functional components only in React. No class components.
- Prefer named exports over default exports.
- Max function length: 40 lines. Extract if longer.
- All async functions must handle errors explicitly — no naked awaits.

Your workflow preferences. How you like Claude Code to approach problems:

## Workflow
- Before implementing anything, state the approach in 2-3 sentences and wait for confirmation.
- When refactoring, show the before/after diff, not just the new version.
- When multiple solutions exist, list them with tradeoffs. Don't just pick one.

Security defaults. Things you never want bypassed:

## Security
- Never log sensitive data (tokens, passwords, PII) even in debug output.
- All user inputs must be validated server-side regardless of client validation.
- Flag any use of eval(), innerHTML assignment, or dynamic SQL construction.

Communication style. How you want responses formatted:

## Response Format
- Be concise. Skip preamble.
- Use code blocks for all code, even short snippets.
- For errors, show: what went wrong, why, and how to fix it.

What NOT to Put in the Root CLAUDE.md

Don’t put anything client-specific here, even if it applies to most clients. The exception leaks into the rule.

Also avoid framework-specific instructions unless every client uses that framework. If 4 of 5 clients use React but one uses Vue, put the React instructions in a react-clients/CLAUDE.md, not the root.

Keep the root CLAUDE.md to about 200-400 words. It should be dense but scannable. Claude Code reads it every time — make it worth reading.

---

Writing Client-Level CLAUDE.md Files

Each client CLAUDE.md handles everything specific to that relationship. The goal is that when you cd into a client folder, Claude Code has everything it needs to work in that client’s world without you saying anything.

The Core Sections Every Client CLAUDE.md Should Have

Project overview. Short, factual:

## Client: Acme Corp
E-commerce platform built on Next.js 14, Prisma, PostgreSQL (Supabase). 
Primary repo: github.com/your-org/acme-platform.
Production at acme.com. Staging at staging.acme.com.

Tech stack specifics. This is where you record the client’s actual setup, not your preferences:

## Stack
- Frontend: Next.js 14 App Router, Tailwind CSS, shadcn/ui
- Backend: Next.js API routes + tRPC
- Database: PostgreSQL via Supabase (no direct DB access from client)
- Auth: NextAuth.js with Google + email providers
- Deployment: Vercel (preview deploys on every PR)
- State management: Zustand for local, React Query for server state

Brand and tone. If you write any copy, comments, documentation, or error messages:

## Brand Voice
- Tone: friendly but efficient. Not casual, not corporate.
- Error messages: clear and actionable. Never blame the user.
- Documentation: write for a mid-level developer, not a beginner.
- Avoid jargon in user-facing text. "Something went wrong" > "HTTP 500 error".

Project memory. This is the most valuable part over time. Keep it updated:

## Project History & Decisions
- Migrated from Pages Router to App Router in Oct 2024. Old patterns still exist in /pages/legacy.
- Switched from Clerk to NextAuth in Nov 2024 — Clerk had pricing issues.
- Cart functionality is in /features/cart. Avoid touching checkout flow — it's fragile.
- The "promo codes" feature is intentionally limited to admin-only. Client's decision.
- Performance: the homepage has a known LCP issue with the hero image. Tracked in issue #234.

Naming conventions. Every codebase develops its own language:

## Conventions
- Database tables: snake_case. TypeScript types: PascalCase. 
- Files: kebab-case for components, camelCase for utilities.
- The "user" object always refers to the authenticated session user.
  The "customer" object refers to the Stripe customer record. Don't mix them.
- Environment variables use NEXT_PUBLIC_ prefix for client-accessible vars only.

Stakeholder context. Optional, but useful for anything involving communication:

## Team Context
- Primary contact: Sarah (Product Manager). Technical background, direct communication style.
- Lead developer on their side: Marcus. Prefers detailed PR descriptions.
- They do code review on all PRs — account for review time in estimates.

Keeping Client CLAUDE.md Files Current

A client CLAUDE.md is only useful if it’s accurate. Stale context is worse than no context — it gives Claude Code confident wrong information.

Build a habit: after any significant decision or change, update the relevant CLAUDE.md before closing your editor. Treat it like a living document, not a one-time setup.

Some developers add a note at the top of each client CLAUDE.md:

## Last Updated
2025-01-15 — Added cart migration notes, updated auth stack after Clerk removal.

It takes 30 seconds and prevents future confusion.

---

Practical Use Cases

Here’s what this system enables in practice.

Use Case 1: Switching Between Clients Mid-Day

You’re working on Acme’s dashboard in the morning. After lunch, you switch to Beta’s API work. With the inheritance model, you just change directories. No context resetting, no pasting instructions. Claude Code reads the new client’s CLAUDE.md automatically.

More importantly, Claude Code won’t bleed Acme’s context into Beta’s work. The stacks, conventions, and project memory stay where they belong.

Use Case 2: Onboarding a Junior Developer

If another developer joins your team, they get full context the moment they open the project. All the “tribal knowledge” — why certain decisions were made, what to avoid, what the naming conventions mean — is in CLAUDE.md files that travel with the repo.

You can even commit client CLAUDE.md files to the client’s private repo (excluding any sensitive details), so the context is version-controlled alongside the code.

Use Case 3: Consistent Code Reviews Across Clients

Your root CLAUDE.md defines your review standards. When you ask Claude Code to review code in any client project, it applies your universal quality bar. But it also knows Client A hates TypeScript generics (noted in their CLAUDE.md) and Client B requires JSDoc on every exported function.

The review is both consistent in standards and appropriate for that client’s specific context.

Use Case 4: Generating Client-Specific Documentation

Each client CLAUDE.md has their brand voice. When you ask Claude Code to generate a README, API docs, or error messages for Client A, it writes in A’s tone. Same request for Client B gets B’s tone. You don’t change your prompt — you change your directory.

---

Extending Your Workflow Beyond Code

Context inheritance handles the “knowledge” layer — what Claude Code knows. But multi-client work also has a significant operational layer: sending deliverables, tracking project status, triggering builds, notifying stakeholders.

This is where MindStudio’s Agent Skills Plugin becomes useful alongside your Claude Code workflow. The plugin is an npm SDK (@mindstudio-ai/agent) that gives any AI agent — including Claude Code’s agentic workflows — access to 120+ typed capabilities as simple method calls.

So when your Claude Code workflow completes a task, it can call agent.sendEmail() to notify a client, agent.runWorkflow() to trigger a deployment pipeline, or agent.searchGoogle() to pull in context it needs. The plugin handles rate limiting, retries, and auth — your agent just calls the method.

The practical value for multi-client work: you can build MindStudio agents that represent each client’s operational context (their Slack workspace, their project management tool, their deployment process) and call them from your code workflow via the SDK. Your code stays focused on code. The operational layer runs separately.

You can try MindStudio free at mindstudio.ai — and the Agent Skills Plugin is available on npm for any agentic workflow you’re building.

---

Common Mistakes to Avoid

Mistake 1: Putting Too Much in the Root CLAUDE.md

The root file is for universal truths only. If you’re writing “usually” or “for most projects” anywhere in it, that line belongs in a client-level file, not the root.

Overstuffed root CLAUDE.md files create noise. Claude Code has to parse more context, and the signal-to-noise ratio drops. Keep it lean.

Mistake 2: Letting Client Files Go Stale

The second a client switches frameworks or makes a significant architectural decision, that CLAUDE.md is wrong. Set a recurring calendar reminder — monthly works — to audit each active client’s file. Even a quick scan to confirm nothing major has changed is worth the 5 minutes.

Mistake 3: Duplicating Root-Level Instructions

If your root CLAUDE.md says “always use TypeScript,” don’t repeat that in every client CLAUDE.md. Duplication creates inconsistency risk — if you update the root rule, you’ll forget to update five client files.

Trust the inheritance. Only override at the client level when the client genuinely differs from your default.

Mistake 4: Forgetting That CLAUDE.md Is Visible

If you commit CLAUDE.md files to a client repo, remember they can be read by anyone with repo access — including the client. Don’t write anything in a client’s CLAUDE.md that you wouldn’t say directly to them. Stakeholder notes especially should stay professional.

For sensitive context you don’t want committed, keep a local CLAUDE.md that lives in your .gitignore.

Mistake 5: No Project Structure Context

One of the most useful things you can put in a client CLAUDE.md is a map of the project structure — which directories contain what, which areas are stable vs. active, which files to avoid. Claude Code can infer a lot from reading the codebase, but you save significant time by stating it explicitly.

---

Frequently Asked Questions

How many CLAUDE.md files can Claude Code read at once?

Claude Code reads all CLAUDE.md files from the current directory up to the root of the filesystem. In practice, for a two-level structure (root + client), you’re looking at 2-3 files. There’s no published hard limit, but keep total CLAUDE.md content under ~2,000 words across the whole chain for reliable, fast context loading.

Can I use Claude Code context inheritance with a team, or is it only for solo developers?

It works well for teams. CLAUDE.md files are just text files — they can be committed to version control and reviewed like any other project file. The convention is to commit project-level and client-level CLAUDE.md files to their respective repos, and keep a root-level developer identity CLAUDE.md locally (since that’s personal to each developer).

What’s the difference between CLAUDE.md and a system prompt?

A system prompt is set at the API level and applies to a single conversation. CLAUDE.md files are file-based instructions that Claude Code automatically discovers based on your directory. They’re persistent, version-controllable, and hierarchical in a way API system prompts aren’t. For long-term project work, CLAUDE.md files are the better mechanism.

Should I include sensitive client information in CLAUDE.md files?

No. CLAUDE.md files are plaintext and often committed to source control. Never include passwords, API keys, secret tokens, or sensitive personal data. For credentials, use environment variables and reference them by name in CLAUDE.md (e.g., “Auth token is in ACME_AUTH_TOKEN env var”). For sensitive context you need Claude Code to know but don’t want committed, keep a local CLAUDE.md and add it to .gitignore.

How do I handle a client who has multiple separate repos?

If a client’s projects are in separate repos but you still want shared client context, you have two options. Option one: keep a local client CLAUDE.md outside the repos but inside a client parent folder. Option two: add the shared context as a committed CLAUDE.md in a shared config repo, and symlink or copy it into each project’s root. Most developers prefer the local parent folder approach — simpler and no sync headaches.

Does context inheritance work the same way on Windows as on Mac/Linux?

Claude Code handles path resolution cross-platform, so the hierarchy works the same way. The folder structure conventions in this article use Unix-style paths, but the same logic applies with Windows paths. If you’re using WSL, you’ll want your projects inside the WSL filesystem rather than the Windows-mounted drives for best performance.

---

Key Takeaways

• Parent CLAUDE.md files are for universal truths — your coding standards, workflow preferences, security rules, response format. Keep them short and precise.
• Client CLAUDE.md files are for isolated context — tech stack, brand voice, project memory, stakeholder details, naming conventions. Update them whenever something significant changes.
• The folder structure determines context scope — siblings never see each other’s context; children always inherit from parents.
• Don’t duplicate across levels — trust the inheritance chain. Only override at a lower level when a client genuinely differs from your default.
• Stale context causes real problems — a CLAUDE.md that describes last year’s stack gives Claude Code confident wrong information. Audit regularly.

If you want to extend what Claude Code can do beyond the code itself — triggering workflows, notifying clients, connecting to project management tools — MindStudio’s Agent Skills Plugin is worth exploring. It lets your Claude Code workflows call operational capabilities without building the infrastructure yourself. You can also explore how to build automated workflows with MindStudio or learn about connecting AI agents to your existing tools to see how the two layers can work together.