How to manage CLAUDE.md files across multiple projects without going insane

You have six active projects. A Next.js SaaS, a Python data pipeline, two client sites, an internal tool, and that side project you keep meaning to finish. Each one has different conventions, different stacks, and different things Claude Code needs to know.

So you write a CLAUDE.md for project one. It works great. Claude stops using semicolons, uses your preferred test runner, follows your file structure. Then you start project two and realize you need to write another one from scratch. By project four, you're copying chunks from project one, editing them halfway, and ending up with a Frankenstein config that confuses Claude more than it helps.

This is the multi-project CLAUDE.md problem, and nearly everyone who uses Claude Code seriously runs into it. Here's how to solve it.

Why one-size-fits-all CLAUDE.md files don't work

The instinct is to write one master CLAUDE.md and drop it everywhere. Don't. A CLAUDE.md that says "use TypeScript strict mode, Tailwind, Vitest, Supabase" is actively harmful in your Python project. Claude reads it at session start, loads it into context, and then spends the entire session fighting between what the file says and what the code actually is.

Every line in your CLAUDE.md costs tokens. Lines that don't apply to the current project are wasted tokens that could be used for actual work. Worse, contradictory instructions cause Claude to make inconsistent choices, the AI equivalent of a developer who read two conflicting style guides and picks randomly.

Each project needs its own CLAUDE.md. The question is how to make that manageable.

The three-layer system

After managing configs across dozens of projects, the pattern that works is three layers:

Layer 1: Global defaults (~/.claude/CLAUDE.md)

Claude Code supports a global config at ~/.claude/CLAUDE.md. This is read for every project on your machine. Put things here that are true everywhere:

## Global Preferences
- Prefer named exports over default exports
- Never use `rm` — move to .trash/ instead
- Write tests for new functions, co-located with source
- Use descriptive variable names, no abbreviations
- Commit messages: imperative mood, under 72 characters

Keep this short. 10-20 lines max. Anything stack-specific does not belong here.

Layer 2: Project-specific CLAUDE.md

This is the main config per project. It defines the stack, conventions, file structure, and project-specific behavior. This is where most of the value lives.

## Project: InvoiceFlow
Next.js 14 App Router, TypeScript strict, Tailwind, Prisma + Postgres.

## Architecture
- /app — routes and layouts (App Router)
- /components — shared UI components
- /lib — business logic, no framework imports
- /prisma — schema and migrations

## Conventions
- Server components by default, 'use client' only when needed
- Zod for all validation (API inputs and form data)
- Prisma for all DB access, no raw SQL
- Error boundaries at layout level, not per-component

Layer 3: Subdirectory overrides (.claude/rules/)

For monorepos or projects with distinct sections, Claude Code reads .claude/rules/*.md files. Use these for section-specific rules:

# .claude/rules/api.md
API routes use Next.js Route Handlers. Always validate input with Zod.
Return consistent error shapes: error string + code number.

# .claude/rules/testing.md
Use Vitest for unit tests, Playwright for e2e.
Mock external APIs with msw, never mock the database.

This layered approach means you write the global stuff once, the project stuff once per repo, and the specialized stuff only where it matters.

Managing the copy-paste problem

Even with layers, you still need to write that Layer 2 config for every new project. And every project has some overlap: most of your Next.js projects share similar conventions, most of your Python projects use the same test setup.

Three approaches, from manual to automated:

Option 1: Template directory

Keep a folder of starter CLAUDE.md files organized by stack:

~/templates/claudemd/
  nextjs-app-router.md
  python-fastapi.md
  astro-tailwind.md
  react-native.md
  go-api.md

When starting a new project, copy the right template and customize. Simple, works, but you have to remember to update the templates when you learn something new. Most people don't.

Option 2: Generator script

Write a script that scans your project structure and generates a starter CLAUDE.md. Check for package.json (Node), pyproject.toml (Python), go.mod (Go), and extract the stack from dependencies. This gets you 70% of the way there.

The problem: scripts are good at detecting what's installed but bad at understanding how you use it. They'll see Prisma is installed but won't know your convention of putting all queries in /lib/db/.

Option 3: Use a dedicated tool

ContextKit is built exactly for this problem. It's a free CLAUDE.md generator that walks you through a 5-step wizard: pick your language, framework, and conventions, and it generates a production-ready CLAUDE.md. It also exports to .cursorrules, AGENTS.md, and GEMINI.md if you use multiple tools.

The advantage over templates is that the generator knows about common patterns per stack and suggests conventions you might not think of. It's like a checklist you walk through rather than a blank page you stare at.

What belongs in every project config

Regardless of how you create them, every project CLAUDE.md should cover these six areas:

1. Stack declaration — Language, framework, major libraries. One line is enough.
2. File structure — Where the main directories are and what goes in each.
3. Coding conventions — Naming, imports, error handling. The stuff that varies between projects.
4. Testing setup — Which runner, where tests live, what to mock (and what not to).
5. Build and deploy — How to build, how to run locally, where it deploys.
6. Guardrails — What Claude should never do autonomously in this project.

Skip any area that's standard for the stack and not project-specific. If your Python project uses pytest with default config, you don't need to mention it. Claude already knows.

Keeping configs up to date

The hardest part of multi-project CLAUDE.md management isn't creating them. It's maintaining them. You add a new library, change your test setup, or restructure the codebase, and the CLAUDE.md silently becomes wrong. Claude keeps following the old instructions, you get confused output, and you spend twenty minutes debugging before you realize the config is stale.

Three practices that help:

• Review CLAUDE.md during major refactors. If you're moving to a new test framework or restructuring directories, update the config in the same PR.
• Add a quarterly reminder. Set a recurring task to review your active project configs. Takes 10 minutes per project.
• Let Claude tell you. If Claude keeps doing something wrong, check whether your CLAUDE.md is the cause. Often the fix is updating one line in the config rather than repeating the instruction every session.

The monorepo case

Monorepos need special attention. You have a root CLAUDE.md for shared conventions, plus each package or app might need its own rules. The layering system handles this:

my-monorepo/
  CLAUDE.md              # shared conventions
  .claude/rules/
    ci.md                 # CI/CD rules
  packages/
    api/
      CLAUDE.md           # API-specific rules
    web/
      CLAUDE.md           # Frontend-specific rules
    shared/
      CLAUDE.md           # Shared library rules

When you cd packages/api and start Claude Code, it reads the API-specific CLAUDE.md. The root config sets the baseline. This is built into Claude Code's resolution order, no special setup needed.

When switching between projects mid-day

The reality of freelancing or agency work is context-switching between projects multiple times a day. Claude Code handles this automatically: close the terminal, open a new one in the next project, and Claude reads that project's CLAUDE.md. No state bleeds between sessions.

But there's a productivity trap: you spend the first few minutes of each project remembering where you left off. A one-line "current focus" note at the top of your CLAUDE.md helps:

## Current Focus
Working on payment integration. Stripe checkout flow is half-done.
See /app/api/stripe/ for the webhook handler that needs testing.

Update this before you switch away. When you come back, Claude reads it and knows exactly where to pick up.

Bottom line

Managing CLAUDE.md across multiple projects comes down to: don't try to share one config, use layers to reduce duplication, and have a system for creating new configs quickly. Whether that's a template folder, a generator, or ContextKit's free wizard, the goal is the same: every project gets a specific, accurate config without you writing it from scratch each time.

The developers getting the most out of Claude Code aren't the ones writing the fanciest prompts. They're the ones with clean, current configs in every project they touch.