Multi-Agent Claude Code Works Only With Architecture First

You spin up three Claude Code agents to build a subscription upgrade feature. Agent one creates a new PaymentService from scratch. Agent two wraps the existing BillingService in an adapter. Agent three skips both and writes the logic directly in the API route. Forty-five minutes later, you have three approaches to the same problem. None of them are compatible.

This is what multi-agent workflows look like without shared context. Every agent is productive. Every agent is building the wrong thing.

There is a fix, and it takes less time than the cleanup. It starts with a shared architecture contract that every agent reads before writing a single line of code.

Why multi-agent workflows break without context

Multi-agent Claude Code is powerful for parallel work. One agent explores the codebase, another implements, a third writes tests. The speed is real. But speed without alignment creates a specific kind of mess.

Without shared context, each agent makes its own assumptions. Which service owns the logic: the domain layer, the API handler, or a new file? What does InvoiceLine look like: does it include tax or not? Which dependencies are acceptable: dayjs, date-fns, or native Date? What is the error handling pattern: Result types, thrown exceptions, or status codes?

The result is code that compiles individually but conflicts when you merge it. You spend more time reconciling three agents' outputs than you would have spent writing it yourself.

The problem is not the tooling. The problem is that the agents have no shared playbook.

Architecture first means a shared contract

Architecture First is not about writing extensive docs before you start. It is a focused set of decisions you write down so agents stop guessing.

A context pack answers four questions. What is our stack, so agents do not import frameworks we do not use. Where does logic live, so business rules do not leak into API routes. What do our data shapes look like, so two agents do not invent different DTOs for the same entity. And what is off-limits, so nobody adds a dependency or skips tests without flagging it.

Here is what that looks like in practice:

# CONTEXT_PACK.md

## Stack
- Backend: FastAPI + SQLAlchemy 2.0 async
- Frontend: React 18 + TypeScript + Vite
- Database: PostgreSQL 15, RLS enabled
- Messaging: Event bus for order and billing events

## Domain boundaries
- src/domain/** owns business rules
- src/api/** is thin request orchestration
- src/integrations/** owns external vendors

## Contracts
- Events: OrderPlaced, PaymentCaptured, RefundRequested
- DTOs: OrderSummary, InvoiceLine, SubscriptionPlan

## Constraints
- No new dependencies without approval
- Follow Result<T, E> pattern in domain services
- Tests required for all billing edge cases

This file lives at the root of your repo. Every agent reads it before doing any work. It takes 15 minutes to write and it prevents the most common multi-agent failure: agents that are individually correct but collectively incompatible.

Quick start in Claude Code

1. Create CONTEXT_PACK.md at the repo root. Start with your stack, folder structure, and the two or three architectural rules your team already follows informally.
2. Add your contracts. List the DTOs, events, and error types that agents need to respect. You do not need every type. Focus on the ones at the boundaries between services.
3. Reference the context pack in your prompt. Start a multi-agent task and explicitly tell Claude Code to read CONTEXT_PACK.md before starting any work.
4. Give each agent a brief with a clear scope and a stop condition. An agent without a stop condition will keep going until it has rewritten half your codebase.

Give each agent a clear brief

Multi-agent workflows scale when responsibilities are clear and contained. The pattern that works: one agent plans, one builds, one reviews. Each has a defined scope and knows when to stop.

# Task: Fix subscription proration bug

## Agent: Planner
- Map current proration flow and failure case
- Propose a minimal change set
- List required tests

## Agent: Builder
- Implement change in src/domain/billing/ProrationService
- Update API handler in src/api/billing/proration
- Add tests in src/domain/billing/__tests__

## Agent: Reviewer
- Check logic against contracts in CONTEXT_PACK.md
- Verify edge cases: upgrade, downgrade, cancellation
- Ensure no new dependencies

The planner maps the problem and proposes changes without writing code. The builder implements exactly what the planner proposed, staying within the boundaries from the context pack. The reviewer checks the output against the contracts and flags anything that drifts.

This separation matters because it mirrors how engineering teams actually work. A developer who writes and reviews their own code misses things. The same applies to agents. An agent in "build mode" optimizes for completing the task. An agent in "review mode" optimizes for finding problems. Keeping those roles separate catches issues that a single agent would miss.

Architecture first workflow for Claude Code

Here is the full workflow, from context pack to merged code:

1. Write a context pack: stack, boundaries, contracts, constraints. If you already have a CLAUDE.md or architecture doc, extract the relevant sections.
2. Assign agent briefs: planner, builder, reviewer, and an optional integrator for cross-service changes. Each brief includes scope and a stop condition.
3. Plan first: the planner proposes a change set and test matrix. You review it before any code gets written. This is where you catch wrong assumptions early.
4. Build in parallel: the builder works inside the boundaries from the context pack. If it needs to cross a boundary, it flags it instead of deciding on its own.
5. Review against the contract: the reviewer checks types, dependencies, and test coverage against the context pack. Not "does this code work" but "does this code fit."
6. Integrate and run gates: type check, lint, tests. If anything fails, the builder fixes it within the existing plan.

Common failure modes and how to prevent them

Every failure in multi-agent workflows traces back to a gap in the context pack. Here are the ones that come up most often:

Failure mode	What it looks like	Fix
Conflicting types	Two different InvoiceLine shapes	Add DTO contract to context pack
Dependency drift	New library added by one agent	Lock deps and require approval
Boundary leak	API handler holds business logic	Enforce domain boundaries
Test gaps	Only happy path covered	Add edge case matrix

Conflicting types are the most common. Two agents build services that exchange data, but they each define InvoiceLine with different fields. One includes tax, the other does not. The code compiles fine until runtime, when the missing field causes a silent calculation error.

Dependency drift is the sneakiest. One agent decides dayjs would make date handling easier and installs it. Meanwhile, the codebase already uses date-fns everywhere. Now you have two date libraries doing the same thing, and neither agent knows about the other.

Boundary leaks happen when the context pack lists boundaries but does not explain why. An agent sees that putting validation in the API handler is faster than routing through the domain layer, and it takes the shortcut. The next agent does the same. Within a few tasks, your domain layer is hollow and your API routes contain business logic.

Test gaps happen when the builder tests only the path it implemented. It built the happy path, so it tests the happy path. Edge cases like mid-cycle upgrades, partial refunds, or two users applying the same discount code at the same time get skipped entirely.

The minimum viable context

You do not need a 20-page architecture document. You need four sections:

• Stack: frameworks, ORM, database, major libraries. Enough that agents do not guess.
• Boundaries: what belongs in domain, API, integrations. Where logic lives and where it does not.
• Contracts: DTOs, events, error types. The shapes that cross boundaries.
• Constraints: dependency rules, patterns, test expectations. The guardrails.

Write these once. Update them when your architecture changes. Every multi-agent task starts by reading them.

The difference between multi-agent workflows that ship and multi-agent workflows that create busywork is not the tooling or the number of agents. It is whether those agents share a common understanding of your codebase. Fifteen minutes of writing a context pack saves hours of reconciliation.

Start with the context pack on your next feature and see how the outputs change.

Read the full lesson: Documentation as Code →