Managing Multiple Projects in Claude Code With CLAUDE.md

Claude Code decides which instructions to load from the directory you start it in. It reads your personal ~/.claude/CLAUDE.md, then every CLAUDE.md from the filesystem root down to that directory, and picks up CLAUDE.md files in subdirectories only when it reads files there. So the working rule for several projects is simple: habits that apply everywhere go in the user file, each repository gets its own CLAUDE.md, and you start Claude Code inside the project you are working on. The rest of this article is the detail behind that rule, and how to keep each project’s work in its own place on a board.

The layers, broadest first

The Claude Code memory documentation↗ (opens in a new tab) lists four places a CLAUDE.md can live. They load in this order, so a more specific file is read after a broader one:

• Managed policy — a file your organisation deploys (on Windows, C:\Program Files\ClaudeCode\CLAUDE.md). It applies to every session on the machine and cannot be excluded.
• User — ~/.claude/CLAUDE.md. Your own preferences, in every project.
• Project — ./CLAUDE.md or ./.claude/CLAUDE.md, committed so everyone who clones the repository gets it.
• Local — ./CLAUDE.local.md, your private notes for one project. Add it to .gitignore.

Two details matter when you run several projects. First, the files are concatenated, not merged: nothing overrides anything. If your user file says “use npm” and a project file says “use pnpm”, the documentation warns that Claude may pick either. Keep the user file to things that are true in every project, and put anything project-specific in that project. Second, there is a size target: under 200 lines per file. A user file that tries to describe all your projects fails both tests.

Where you start Claude Code decides what loads

Take a common layout: a folder of separate repositories, each with its own CLAUDE.md.

~/code/
  CLAUDE.md            # optional: rules for everything in ~/code
  billing-api/
    CLAUDE.md
  web-app/
    CLAUDE.md
  mobile-app/
    CLAUDE.md

• Start in ~/code/billing-api and Claude Code loads billing-api/CLAUDE.md and ~/code/CLAUDE.md at launch — the directory and its ancestors.
• Start in ~/code and only ~/code/CLAUDE.md loads at launch. web-app/CLAUDE.md arrives later, and only if Claude reads a file in web-app/.

The second case is the one that catches people. A session started at the container can reach every project but begins with none of their rules, and a project’s rules turn up only once Claude happens to open a file there. For work in one project, start in that project. Start higher up only when the job genuinely spans several, and even then say which project each change belongs to.

The same applies inside a monorepo. The documentation’s own layout↗ (opens in a new tab) is a root CLAUDE.md with rules for every package, plus one per package with that package’s conventions. Start in packages/api/ and you get both, with nothing from packages/web/ in context. Start at the root and the package files load as Claude works in each package. If other teams’ packages keep turning up, the claudeMdExcludes setting skips them by glob; put it in .claude/settings.local.json if the exclusion is only for you.

Reaching a second repository from one session

Sometimes a change really does span two repositories: an API field and the screen that shows it. --add-dir gives the session read and write access to another directory. What it does not do, by default, is load that directory’s CLAUDE.md. You get the reach without the rules.

cd ~/code/web-app
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../billing-api

With that variable set↗ (opens in a new tab), Claude Code also loads the added directory’s CLAUDE.md, .claude/CLAUDE.md, .claude/rules/ and CLAUDE.local.md. Skills in an added directory load either way. The additionalDirectories permission in settings.json is different again: it grants file access only and never loads instructions or skills. Project settings do not travel the way instructions do, either: the documentation notes that .claude/settings.json is not inherited from parent directories as CLAUDE.md files are.

Imports: sharing text without copying it

A CLAUDE.md can pull in other files↗ (opens in a new tab) with @path. Relative paths resolve from the file that contains the import, imports can nest up to four hops, and an import inside backticks is left as plain text. Two uses help most with several projects:

• One source for every tool. If a repository already has an AGENTS.md for other coding assistants, a CLAUDE.md containing @AGENTS.md keeps a single file of rules. Recent versions of Claude Code also read AGENTS.md directly when there is no CLAUDE.md on the path.
• Shared personal notes. @~/.claude/my-conventions.md in a project file pulls in a file from your home directory. Because that path is outside the project, Claude Code asks you to approve external imports the first time it meets one in that project.

Imports organise text; they do not save context. An imported file loads at launch just as if it were pasted in. If a block of instructions only matters for one part of a codebase, a path-scoped rule in .claude/rules/ or a skill is the better tool, because those load only when they apply.

Memory is per repository too

Alongside the files you write, Claude Code keeps auto memory: notes it writes for itself, in ~/.claude/projects/<project>/memory/. The <project> part comes from the git repository, so every subdirectory and worktree of one repository shares one memory, and two repositories never share. It is machine-local. Start a session somewhere unusual — a container folder above your repositories, say — and you get that folder’s memory, not the one your project has been building up.

One board, a project per repository

The instructions tell Claude how to work in each codebase. The work itself — what is open, what is being done, what came of it — needs somewhere that is not tied to one repository’s files or one machine. Keep it on a board, and give each repository a project on that board.

In fenbs, projects are labels on a board, made the moment you name one, and the board filters and groups by them. A developer with several repositories usually needs one board with a project per repository; a separate team board makes sense where the people differ, such as one per client. Connect the board once, at user scope↗ (opens in a new tab), so every repository on your machine can reach it without anything written into the repository:

claude mcp add --scope user --transport http fenbs https://fenbs.ai/api/mcp

Then /mcp, choose fenbs and sign in. Each repository’s CLAUDE.md names its own project, so the assistant files work in the right place whichever folder it was started in:

## The board
Project: billing-api. File every feature, enhancement and bug under this project.
- At the start of a session, call fenbs_get_context with project billing-api.
- If fenbs_list_projects does not show billing-api, add it with fenbs_add_project.

Naming the project does a second job. AI context in fenbs has two levels: notes for everything, and notes for one project. fenbs_get_context with a project returns the shared notes plus that project’s, never the other projects’, so the assistant in billing-api is not reading about the mobile app’s release steps. What goes in the rest of that section — reading the board before starting, moving tasks as work progresses — is the rhythm in a task-tracking workflow for Claude Code.

A short checklist

1. User CLAUDE.md: only what is true in every project. No project names.
2. One CLAUDE.md per repository, and per package in a monorepo, each under 200 lines.
3. Start Claude Code in the project you are working on. Run /context to see which memory files loaded.
4. Crossing into another repository: --add-dir, with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 if its rules should come too.
5. One board, one project per repository, named in that repository’s CLAUDE.md.