Single-project AI workflows are tractable. You have one CLAUDE.md, one context, one set of decisions. You brief the agent once, keep the session-state current, and it works.
Multi-project workflows break this in three specific ways.
Context bleed. You've been working on Project A all morning. The auth architecture, the deployment constraints, the open questions — all of that is live in your session. You switch to Project B. The agent carries residual context from A into B. It makes suggestions that would be correct for A but are wrong for B.
Re-briefing overhead. You switch projects cleanly, but now you need to re-establish context for B from scratch. Fifteen minutes of re-orientation. You do this every context switch, several times a day.
Decision contamination. You've made decisions on Project A that you're tempted to apply to Project B because they're fresh in mind — even though B has different constraints that make those decisions wrong.
I run six simultaneous workstreams. Here's the structure that eliminated all three.
The core principle: one session-state per project, never shared
The session-state is the working memory for a single project at a single point in time. It must be completely isolated. Nothing from Project A's session-state should ever appear in Project B's.
This sounds obvious. The implementation is less obvious.
The naive approach — one CLAUDE.md per project directory — works if your projects live in separate repos you never open simultaneously. It breaks the moment you're switching between projects in a shared knowledge environment, or when projects share common concepts and you're not careful about which project's context the agent is loading.
The structure that actually works has three layers.
Layer 1: Project-isolated context files
Each project gets its own set of context files:
wiki/
projects/
project-alpha/
Alpha Hub.md ← entry point, links out
Alpha Session State.md ← 5-field operational record
Alpha Constraints.md ← non-obvious limits
Alpha Decision Log.md ← decisions + rejected alternatives
project-beta/
Beta Hub.md
Beta Session State.md
Beta Constraints.md
Beta Decision Log.md
Nothing is shared between these directories. If two projects share a technology or pattern, they each link to the same concept note in wiki/concepts/ — but their session-states, constraints, and decision logs are completely separate.
Layer 2: The project hub as session entry point
Each project hub is a clean entry point that loads exactly what the agent needs for that project — and nothing else.
# Project Alpha Hub
**Active as of:** 2026-04-20
## What This Is
One sentence. What Project Alpha is building.
## Current State
→ Read [[Alpha Session State]] — updated at every session close
## Constraints
→ [[Alpha Constraints]] — non-obvious limits, always check before proposing
## Decisions
→ [[Alpha Decision Log]] — what was decided and what was rejected
## Key Context
- Stack: [specifics]
- Repo: ~/repos/alpha
- Deploy: [specifics]
## For the agent
Load session state first. Check constraints before proposing solutions.
Do not apply patterns from other projects unless explicitly asked.
The last line is load-bearing. It explicitly tells the agent not to transfer patterns from other sessions. This won't prevent all context bleed (the agent doesn't have true memory isolation), but it establishes a clear behavioral norm.
Layer 3: The routing entry file
With six projects, you need a routing layer — a master entry that points to the right hub without loading everything at once.
# Project Router
## Active Projects
| Project | Hub | Last Session | Status |
|---------|-----|-------------|--------|
| Alpha | [[Alpha Hub]] | 2026-04-20 | Active |
| Beta | [[Beta Hub]] | 2026-04-19 | Blocked — waiting on client |
| Gamma | [[Gamma Hub]] | 2026-04-18 | Active |
| Delta | [[Delta Hub]] | 2026-04-15 | Parked |
| Epsilon | [[Epsilon Hub]] | 2026-04-20 | Active |
| Zeta | [[Zeta Hub]] | 2026-04-10 | Closing |
## How to start a session
1. Name the project in your first message
2. Load the hub for that project
3. Read session state before anything else
4. Work within that project's context only
Your CLAUDE.md points to this router. At session start, you tell the agent which project you're working on. It loads the hub, reads the session-state, and operates in that project's context.
The key: you only load one hub per session. The router exists so you can see all projects at a glance, but loading it doesn't load all the session-states. You navigate to the right one explicitly.
The context-switch protocol
When switching projects mid-session:
Close the current project. Update its session-state (what changed, what was decided, next step). This takes 3–4 minutes.
Start a new session (or explicitly tell the agent you're switching projects). Don't try to continue in the same session with a different project context — the residual is too strong.
Open the new project. Tell the agent which project you're switching to. Load its hub. Read its session-state. Work.
The session-state update at step 1 is the mechanism that makes the switch clean. If you don't update before switching, you lose the current project's state and you can't re-establish it without re-reading everything.
Handling shared concepts
Projects often share concepts: a shared API, a common design system, a regulatory framework both projects operate under.
These go in wiki/concepts/ or wiki/shared/ — notes that any project can link to but that don't belong to any single project.
wiki/
concepts/
EU AI Act Requirements.md ← both Projects Alpha and Gamma link here
Design System Tokens.md ← shared by Alpha, Beta, Epsilon
PIPEDA Compliance Notes.md ← shared regulatory context
Each project's constraint file links to the relevant shared concepts:
# Alpha Constraints
## Regulatory
- PIPEDA applies — see [[PIPEDA Compliance Notes]] for specifics
- EU AI Act: deferred to v2 (see [[EU AI Act Requirements]] for scope)
The shared concept note is updated once. All projects that link to it get the update automatically. No duplicated content, no risk of projects having different versions of the same regulatory information.
What this looks like in practice
A typical day running this system:
9:00am — Project Alpha session
Open Claude. Load Alpha Hub. Read Alpha Session State. Work on the endpoint spec that was the "next step" from yesterday's close. 90 seconds to orient.
11:30am — Switch to Project Gamma
Close Alpha: update session-state (decided on caching strategy, rejected option C, next step is load testing). Start fresh session. Load Gamma Hub. Read Gamma Session State. 90 seconds to orient. Work.
2:00pm — Back to Alpha
Start fresh session. Load Alpha Hub. Read Alpha Session State (which I updated at 11:30). Pick up from the next step I left. No re-briefing. 90 seconds.
The context bleed is gone because each session is a clean start from an isolated session-state. The re-briefing overhead is gone because the session-state captures everything. The decision contamination is gone because each project's decision log is separate.
The cost without this structure
Without isolated session-states, context-switching has a compounding tax. Each switch costs 15 minutes of re-orientation. Each project degrades the next one slightly through residual context. Decisions made in one project bleed into another.
For six projects, that tax is 1–2 hours of overhead per day. Over a month, it's real time lost.
The structure above takes half a day to set up once. It pays back within the first week.
The vault template that ships with the per-project hub structure, session-state format, constraint files, decision logs, and routing pattern is $49.
→ https://pharosml.gumroad.com/l/kvbhdo
$299 for a guided setup — I configure the multi-project structure for your specific workstream mix. Worth it if you're running 4+ simultaneous projects and the context overhead is already noticeable.
Top comments (0)