Claude Code Project Setup for Multi-Repo Work

March 15, 2026

I work across 6-8 repositories on any given day. Scouter, Triumfit, Lucid, the Octopus Coder site, client projects. Each one has its own stack, its own conventions, its own state.

Running Claude Code across all of them without things bleeding together requires deliberate setup. Here’s what that looks like.

CLAUDE.md per repo

Every repository gets its own CLAUDE.md in the root directory. This is the first file Claude reads when it starts a session, and it’s how you avoid re-explaining your project every time.

Here’s a trimmed version of what Scouter’s looks like:

# Scouter

B2B lead enrichment SaaS. Next.js frontend, Express API,
PostgreSQL, deployed on Railway.

## Structure
- src/app/ — Next.js app router pages
- src/routes/api/ — Express API endpoints
- src/lib/ — Shared utilities
- src/models/ — Drizzle ORM models
- src/types/ — TypeScript type definitions

## Conventions
- API routes follow REST patterns, see src/routes/api/scouts.ts
- All database queries go through Drizzle, never raw SQL
- Error responses use the format in src/lib/errors.ts
- Tests live next to the files they test (*.test.ts)

## Do Not
- Add new npm dependencies without being asked
- Modify database migrations directly
- Change the auth middleware

The “Do Not” section matters. Without it, Claude will occasionally make decisions you didn’t authorize. Spell out the boundaries upfront.

For projects with complex architecture, I also keep a .claude/ directory with additional context files — a BRIEF.md for product context, architecture docs, whatever Claude might need. The CLAUDE.md references these so Claude knows they exist.

Directory structure and terminal layout

I keep all projects under ~/projects/. Each Claude Code session runs in its own terminal tab, rooted in that project’s directory.

Tab 1: ~/projects/scouter          — Scouter API + frontend
Tab 2: ~/projects/triumfit         — Triumfit mobile app
Tab 3: ~/projects/lucid            — Lucid iOS app
Tab 4: ~/projects/logline          — Logline iOS app
Tab 5: ~/Marketing/jwp/sites/octopuscoder  — This site
Tab 6: ~/Marketing/jwp/sites/jwallaceparker — Portfolio site

I covered the full terminal setup in how I run 8 sessions at once. The key detail: each tab is a full-screen Claude Code session. No split panes. When I’m reviewing one project, that’s all I see.

Keeping context separate

The biggest risk with multi-repo work is context contamination — Claude in one session making assumptions based on patterns from a different project.

This doesn’t happen if you follow one rule: one Claude Code instance per project directory, always.

Claude Code picks up context from the directory it’s running in. It reads CLAUDE.md, it sees the file structure, it understands the stack. As long as you never ask a Scouter session about Triumfit code, the contexts stay clean.

What does cause problems:

Copying prompts between sessions without adjusting file paths
Referencing patterns from one project in another (“do it like Scouter does”) without providing the actual code
Running a session in a parent directory that contains multiple projects

Keep each session in its own project root. Simple rule, zero confusion.

When to use git worktrees

If you’re doing parallel work within the same repository — say, two features for Scouter at once — you need separate working directories. Git worktrees handle this.

# Create a worktree for a feature branch
cd ~/projects/scouter
git worktree add ../scouter-feature-export feature/export-csv
git worktree add ../scouter-feature-filters feature/advanced-filters

Now you have three directories:

~/projects/scouter/                  — main branch
~/projects/scouter-feature-export/   — export feature
~/projects/scouter-feature-filters/  — filters feature

Each one gets its own Claude Code session. Each one has its own branch. They don’t interfere with each other.

I use worktrees when I have two or more tasks that touch overlapping files. If the tasks are in separate parts of the codebase, regular branches and stashing work fine. But when two features both need to modify src/routes/api/scouts.ts, worktrees prevent merge headaches.

Git workflow for reviewing agent output

When Claude finishes a task, I don’t merge immediately. Every piece of agent-generated code goes through the same review flow.

# See what changed
git diff --stat
git diff

# If it looks good, commit on the feature branch
git add -A
git commit -m "Add CSV export for scout results"

# If it doesn't look good, reset and re-scope
git checkout .

Across multiple repos, this means my daily review workflow is a loop: tab through each project, check the diff, commit or reset, move on.

The critical habit: commit frequently on feature branches. If Claude is working on a multi-step task, I commit after each step. That way, if step 3 goes sideways, I can roll back to step 2 without losing everything.

git add src/routes/api/scouts/export.ts src/lib/csv.ts
git commit -m "Add CSV export endpoint and utility"

# Then scope the next step
# "Now add tests for the CSV export in src/routes/api/scouts/export.test.ts"

Branch naming for agent work

I use a consistent naming pattern so I can tell at a glance which branches were agent-generated:

feature/export-csv        — feature work
fix/timezone-offset       — bug fixes
chore/update-deps         — maintenance

Nothing special about these names. The point is consistency across repos. When I run git branch in any project, I know what each branch is without checking the log.

The .claudeignore file

Every repo gets a .claudeignore alongside the CLAUDE.md. This keeps Claude from reading files that waste context or shouldn’t be touched.

# .claudeignore
node_modules/
dist/
build/
.env
.env.*
*.lock
coverage/
.next/

For monorepos or larger projects, I also ignore directories that aren’t relevant to the current work. If I’m only working on the API, I might temporarily add the frontend directory to .claudeignore to keep Claude focused.

Setting up a new project

When I start a new project or bring Claude Code into an existing one, the setup takes about 5 minutes:

Write a CLAUDE.md — project description, structure, conventions, boundaries
Create a .claudeignore — standard ignores plus anything project-specific
Run one test session — give Claude a small task and see if the output matches your conventions
Adjust — if Claude’s output doesn’t match your style, add more specific conventions to CLAUDE.md

That’s it. Once the setup is done, every future session in that project starts with the right context.

The compound effect

One repo with good setup saves you minutes per session. Six repos with good setup saves you hours per week. This is the foundation that makes parallel development possible — each project is self-contained, self-documented, and ready for Claude to work in without a preamble.

The setup is boring. It’s also the difference between Claude Code being a useful tool and Claude Code being a frustrating one.