Multi-agent Claude Code met Architecture First

Je start drie Claude Code-agenten om een upgrade-functie voor abonnementen te bouwen. De eerste maakt een compleet nieuwe PaymentService. De tweede wrapet de bestaande BillingService in een adapter. De derde slaat beide over en schrijft de logica rechtstreeks in de API-route. Drie kwartier later heb je drie aanpakken voor hetzelfde probleem. Geen ervan past bij de ander.

Dit is hoe multi-agent werkstromen eruitzien zonder gedeelde context. Elke agent is productief. Elke agent bouwt het verkeerde.

Er is een oplossing, en die kost minder tijd dan het opruimwerk. Het begint met een gedeeld architectuurcontract dat elke agent leest voordat er ook maar een regel code geschreven wordt.

Waarom multi-agent werkstromen breken zonder context

Multi-agent Claude Code is krachtig voor parallel werk. Een agent verkent de codebase, een ander implementeert, een derde schrijft tests. De snelheid is echt. Maar snelheid zonder afstemming levert een heel specifiek soort rommel op.

Zonder gedeelde context maakt elke agent zijn eigen aannames. Welke service beheert de logica: de domeinlaag, de API-handler of een nieuw bestand? Hoe ziet InvoiceLine eruit: inclusief btw of niet? Welke afhankelijkheden zijn acceptabel: dayjs, date-fns of de standaard Date? Wat is het foutafhandelingspatroon: Result-types, exceptions of statuscodes?

Het resultaat is code die afzonderlijk compileert maar conflicteert zodra je merget. Je bent meer tijd kwijt aan het samenvoegen van drie agent-outputs dan wanneer je het zelf had geschreven.

Het probleem is niet het gereedschap. Het probleem is dat de agenten geen gedeeld draaiboek hebben.

Architecture First is een gedeeld contract

Architecture First betekent niet dat je uitgebreide documentatie schrijft voordat je begint. Het is een beknopte set beslissingen die je vastlegt zodat agenten stoppen met gokken.

Een contextpakket beantwoordt vier vragen. Wat is onze stack, zodat agenten geen frameworks importeren die we niet gebruiken. Waar hoort logica thuis, zodat businessregels niet in API-routes terechtkomen. Hoe zien onze datastructuren eruit, zodat twee agenten niet verschillende DTO's verzinnen voor dezelfde entiteit. En wat mag niet, zodat niemand een afhankelijkheid toevoegt of tests overslaat zonder dit te melden.

Dit is hoe dat eruitziet in de praktijk:

# 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

Dit bestand staat in de root van je repository. Elke agent leest het voordat er werk begint. Het kost een kwartier om te schrijven en voorkomt de meest voorkomende multi-agent fout: agenten die individueel correct zijn maar collectief niet samenpassen.

Snel starten in Claude Code

Maak CONTEXT_PACK.md aan in de repo-root. Begin met je stack, mappenstructuur en de twee of drie architectuurregels die je team al informeel volgt.
Voeg je contracten toe. Beschrijf de DTO's, events en fouttypes die agenten moeten respecteren. Je hebt niet elk type nodig. Focus op de types die de grenzen tussen services kruisen.
Verwijs naar het contextpakket in je prompt. Start een multi-agent taak en vertel Claude Code expliciet om CONTEXT_PACK.md te lezen voordat het werk begint.
Geef elke agent een brief met een duidelijke scope en stopconditie. Een agent zonder stopconditie gaat door totdat de helft van je codebase herschreven is.

Geef elke agent een heldere brief

Multi-agent werkstromen schalen wanneer verantwoordelijkheden helder en afgebakend zijn. Het patroon dat werkt: een agent plant, een bouwt, een reviewt. Elk heeft een duidelijke scope en weet wanneer te stoppen.

# 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

De planner brengt het probleem in kaart en stelt wijzigingen voor zonder code te schrijven. De bouwer implementeert precies wat de planner voorstelde, binnen de grenzen van het contextpakket. De reviewer controleert de output tegen de contracten en signaleert alles wat afwijkt.

Deze scheiding is belangrijk omdat het weerspiegelt hoe engineeringteams in de praktijk werken. Een developer die zijn eigen code schrijft en reviewt, mist dingen. Dat geldt ook voor agenten. Een agent in "bouwmodus" optimaliseert voor het afronden van de taak. Een agent in "reviewmodus" optimaliseert voor het vinden van problemen. Door die rollen gescheiden te houden, vang je fouten op die een enkele agent zou missen.

Architecture First-werkstroom voor Claude Code

Dit is de volledige werkstroom, van contextpakket tot gemergte code:

Schrijf een contextpakket: stack, grenzen, contracten, beperkingen. Heb je al een CLAUDE.md of architectuurdocument, extraheer dan de relevante secties.
Verdeel agentbriefs: planner, bouwer, reviewer, en een optionele integrator voor wijzigingen die meerdere services raken. Elke brief bevat scope en een stopconditie.
Plan eerst: de planner stelt een wijzigingsset en testmatrix voor. Je reviewt dit voordat er code geschreven wordt. Hier vang je verkeerde aannames vroeg op.
Bouw parallel: de bouwer werkt binnen de grenzen van het contextpakket. Als een grens overschreden moet worden, meldt de agent dit in plaats van zelf te beslissen.
Review tegen het contract: de reviewer controleert types, afhankelijkheden en testdekking tegen het contextpakket. Niet "werkt deze code" maar "past deze code."
Integreer en draai gates: typecontrole, linting, tests. Als iets faalt, fixt de bouwer het binnen het bestaande plan.

Veelvoorkomende faalpatronen en hoe je ze voorkomt

Elke fout in multi-agent werkstromen is terug te leiden naar een gat in het contextpakket. Dit zijn de patronen die het vaakst voorkomen:

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

Conflicterende types komen het vaakst voor. Twee agenten bouwen services die data uitwisselen, maar definiëren InvoiceLine elk met andere velden. De een rekent btw mee, de ander niet. De code compileert prima tot runtime, wanneer het ontbrekende veld een stille rekenfout veroorzaakt.

Dependency drift is het sluipendst. Een agent besluit dat dayjs datumafhandeling makkelijker maakt en installeert het. Ondertussen gebruikt de codebase overal date-fns. Nu heb je twee datumbibliotheken die hetzelfde doen, en geen van beide agenten weet van de ander.

Grensoverschrijdingen ontstaan wanneer het contextpakket grenzen benoemt maar niet uitlegt waarom. Een agent ziet dat validatie in de API-handler sneller is dan via de domeinlaag routeren, en neemt de kortste weg. De volgende agent doet hetzelfde. Binnen een paar taken is je domeinlaag leeg en bevatten je API-routes businesslogica.

Testgaten ontstaan wanneer de bouwer alleen het pad test dat gebouwd is. Het happy path is klaar, dus het happy path wordt getest. Randgevallen als upgrades halverwege de cyclus, gedeeltelijke terugbetalingen of twee gebruikers die tegelijk dezelfde kortingscode invoeren worden volledig overgeslagen.

Minimaal benodigde context

Je hebt geen architectuurdocument van twintig pagina's nodig. Je hebt vier secties nodig:

Stack: frameworks, ORM, database, belangrijke bibliotheken. Genoeg zodat agenten niet hoeven te gokken.
Grenzen: wat hoort in domein, API, integraties. Waar logica thuishoort en waar niet.
Contracten: DTO's, events, fouttypes. De datastructuren die grenzen kruisen.
Beperkingen: regels voor afhankelijkheden, patronen, testverwachtingen. De vangrails.

Schrijf ze een keer. Werk ze bij als je architectuur verandert. Elke multi-agent taak begint met het lezen ervan.

Het verschil tussen multi-agent werkstromen die opleveren en werkstromen die alleen maar druk genereren is niet het gereedschap of het aantal agenten. Het is of die agenten een gedeeld begrip van je codebase hebben. Een kwartier besteden aan een contextpakket bespaart uren aan samenvoegwerk.

Probeer het contextpakket bij je volgende feature en kijk hoe de output verandert.

Lees de volledige les: Documentatie als Code →

Multi-agent Claude Code werkt alleen met Architecture First