Hoe voorkom je dat Claude Code of Cursor de architectuur van een monorepo breekt?
Het hangt af van of je de agent dezelfde context kunt geven als een senior engineer: machine-leesbare architectuurcontracten (AGENTS.md plus .ai/-spiegeldocs die de grenzen van elk package vastleggen), taakplaybooks onder .agents/skills/, een MCP-server (@supastack/mcp) die de agent de repo laat inspecteren via gestructureerde tools in plaats van grep-giswerk, en een deterministische testgate van 693+ tests — zonder credentials — die vóór review moet slagen. supastack verbindt alle vier lagen vooraf.
De tienduizend-regels-muur die elke agentgebruiker raakt
De eerste 5.000 regels met Claude Code of Cursor voelen als magie. Dan wordt de repo te groot voor de agent om nog te overzien — en de fouten zien er niet meer uit als typefouten: hij herimplementeert een utility die twee packages verder bestaat; hij voegt een query toe die workspaceId vergeet; hij 'fixt' een webhookhandler en verwijdert de idempotentiecheck die je een weekend kostte.
Dat is een contextfout, geen capaciteitsfout. Een senior engineer struikelt niet over die naden omdat hij de architectuur in zijn hoofd draagt: welk package wat bezit, welke invarianten dragend zijn, wat de tests beloven. De agent struikelt erover omdat niemand het voor hem heeft opgeschreven.
Laag één: een schriftelijk contract dat agents kunnen lezen
supastack behandelt agentcontext als een first-class artefact. AGENTS.md in de reporoot legt het architectuurcontract vast — wat elk package bezit, wat de testgate eist, welke patronen verboden zijn. .ai/PROJECT_CONTEXT.md legt de huidige staat en de redenering achter beslissingen vast, en spiegeldocs per bestand laten de context met de code meereizen in plaats van in een wiki te verrotten.
Daarboven liggen ~29 taakplaybooks onder .agents/skills/ — webfeature toevoegen, databaseschema wijzigen, betalingsprovider aansluiten, wijziging verifiëren — zodat agents de eigen procedures van de repo uitvoeren in plaats van te improviseren.
your-saas/
AGENTS.md architecture contract every agent reads first
.ai/
PROJECT_CONTEXT.md current state, decisions, ship status
apps/web/src/... per-file mirror docs that travel with code
.agents/skills/ ~29 task playbooks for agent workflows
packages/mcp/ MCP server: structured repo access for agentsLaag twee: @supastack/mcp geeft agents gestructureerde repo-toegang
Zonder tools kan een agent een monorepo van 700 bestanden maar op één manier verkennen: greppen, de verkeerde bestanden lezen en gokken. @supastack/mcp is een echte Model Context Protocol-server gebouwd op @modelcontextprotocol/sdk en de @supastack/agents-toolruntime — hij stelt de repo bloot aan MCP-compatibele agents (Claude Code, Cursor, Devin, Windsurf) via gestructureerde tools, documentatiebronnen en kant-en-klare prompts.
Het verschil toont zich in het faalpercentage. Een agent die via getypte tools kan vragen 'wat exporteert dit package' of 'wat eist de testgate' verzint geen antwoorden meer uit het bestand dat hij toevallig open heeft. Ons artikel over de AI-coding-agent starterkit behandelt dezelfde workflow vanaf de bouwkant.
Laag drie: de deterministische testgate die agents moeten halen
Guardrails zonder afdwinging zijn slechts suggesties. supastack levert 693+ geautomatiseerde tests met credential-vrije fake providers voor billing, auth, e-mail en storage; het complete gouden pad — signup, betalingswebhook, entitlementtoekenning, teamuitnodiging — verifieert lokaal in seconden.
De loop die een agent veilig maakt is onopvallend: de agent schrijft de diff, draait de gate, leest de failure en corrigeert zichzelf — allemaal vóór menselijke review. De verify-changes-skill van de repo vertelt hem welke checks bij welk type wijziging horen; zo wordt 'de agent brak billing' omgezet in 'de agent ving het zelf af'.
| Faalmodus | Repo zonder guardrails | Met supastack-guardrails |
|---|---|---|
| Agent herimplementeert bestaande code | Ontdekt in review — misschien | Packagegrenzen in AGENTS.md + .ai/-spiegels voorkomen het vooraf |
| Tenant-check stilletjes verwijderd | Ontploft in productie | Workspace-regels zijn geschreven en testgedekt |
| Webhook-regressie | Toont zich als betalingsuitval | Idempotent webhook-ledger vastgezet door replaytests |
| Repo-verkenning | Grep en giswerk | @supastack/mcp-tools + docbronnen |
| Verificatie | Agent zegt 'klaar' | 693+ testgate verplicht vóór review |
Waarom guardrails bij klantwerk rendement op rendement geven
Voor een agency is de som direct: elke klantrepo erft hetzelfde contract, dus een nieuwe agent op een nieuw project is vanaf uur één productief in plaats van de grenzen brekend te leren. Dat is het verschil tussen agentsnelheid verkopen en agent-opschoning verkopen.
De drie kitniveaus passen bij hoe agencies echt kopen — $199 Starter voor single-surfaceprojecten, $299 Full Bundle voor alle surfaces met 3 seats, $799 Agency met 10 seats — en elk niveau staat onbeperkte commerciële klantprojecten toe. Vergelijk opties op de prijspagina.
FAQ: AI-coding-agents op echte monorepo's
Vragen die teams stellen voordat ze een productiecodebase aan agents toevertrouwen:
- Met welke agents werken deze guardrails?, Met elke agent die Markdown kan lezen — Claude Code, Cursor, Windsurf, Copilot, Devin. MCP-compatibele clients krijgen bovendien gestructureerde tools via
@supastack/mcp; de .ai/-docs en skills zelf zijn tool-agnostisch. - Is AGENTS.md alleen niet genoeg?, Het helpt, maar een enkel bestand verrot. De combinatie die standhoudt is contract (AGENTS.md) + geheugen (.ai/-spiegels) + procedures (Agent Skills) + verificatie (testgate) — mis één laag en het lekt.
- Hoe groot is de testsuite echt?, 693+ geautomatiseerde tests over billing-idempotentie, sessie-auth, workspace-isolatie, API-keys en agentgerichte packages — allemaal draaibaar zonder echte credentials.
- Kun je deze guardrails aan een bestaande repo toevoegen?, Ja — reken op ongeveer twee weken zorgvuldig schrijfwerk plus een eigen MCP-server. De kit is de shortcut: contract, skills, MCP-server en tests zijn al op elkaar afgestemd.