Wie verhindert man, dass Claude Code oder Cursor die Monorepo-Architektur zerstört?
Es kommt darauf an, ob der Agent denselben Kontext wie ein Senior Engineer erhält: maschinenlesbare Architekturverträge (AGENTS.md plus .ai/-Mirror-Docs mit Paketgrenzen), Aufgaben-Playbooks unter .agents/skills/, einen MCP-Server (@supastack/mcp), über den Agenten das Repo per strukturierter Tools statt per Grep-Rateerei inspizieren, und ein deterministisches Test-Gate aus 693+ Tests, das vor dem Review bestanden sein muss. supastack liefert alle vier Schichten vorverdrahtet.
Die Zehntausend-Zeilen-Mauer, die jeder Agenten-Nutzer trifft
Die ersten 5.000 Zeilen mit Claude Code oder Cursor fühlen sich wie Magie an. Dann wird das Repo zu groß, als dass der Agent es noch überblicken könnte – und die Fehler hören auf, wie Tippfehler auszusehen: Er implementiert eine Utility neu, die zwei Packages weiter existiert; er fügt eine Query ohne workspaceId hinzu; er »repariert« einen Webhook-Handler und löscht den Idempotenz-Check, für den Sie ein Wochenende gebraucht haben.
Das ist ein Kontextversagen, kein Fähigkeitsversagen. Senior Engineers treten nicht in diese Ritzen, weil sie die Architektur im Kopf tragen: welches Package was besitzt, welche Invarianten tragend sind, was die Tests versprechen. Agenten treten hinein, weil es niemand für sie aufgeschrieben hat.
Schicht eins: ein schriftlicher Vertrag, den Agenten lesen können
supastack behandelt Agenten-Kontext als First-Class-Artefakt. AGENTS.md im Repo-Root hält den Architekturvertrag fest – was jedes Package besitzt, was das Test-Gate verlangt, welche Muster verboten sind. .ai/PROJECT_CONTEXT.md dokumentiert den aktuellen Stand und die Gründe hinter Entscheidungen; Mirror-Docs pro Datei sorgen dafür, dass Kontext mit dem Code wandert statt in einem Wiki zu verrotten.
Darüber liegen ~29 Aufgaben-Playbooks unter .agents/skills/ – Web-Feature hinzufügen, Datenbankschema ändern, Zahlungsprovider einbinden, Änderung verifizieren – damit Agenten die Prozeduren des Repos ausführen statt zu improvisieren.
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 agentsSchicht zwei: @supastack/mcp für strukturierten Repo-Zugang
Ohne Werkzeuge kann ein Agent in einem 700-Dateien-Monorepo nur eines: greppen, die falschen Dateien lesen und raten. @supastack/mcp ist ein echter Model-Context-Protocol-Server auf Basis von @modelcontextprotocol/sdk und der @supastack/agents-Tool-Runtime – er exponiert das Repo für MCP-fähige Agenten (Claude Code, Cursor, Devin, Windsurf) über strukturierte Tools, Dokumentations-Ressourcen und fertige Prompts.
Der Unterschied zeigt sich in der Fehlerrate. Ein Agent, der per typisiertem Tool fragen kann »was exportiert dieses Package« oder »was verlangt das Test-Gate«, erfindet keine Antworten mehr aus der Datei, die er zufällig offen hat. Unser Artikel zu AI-Coding-Agenten im Starter-Kit behandelt denselben Workflow aus Builder-Sicht.
Schicht drei: das deterministische Test-Gate, das Agenten passieren müssen
Guardrails ohne Durchsetzung sind nur Vorschläge. supastack liefert 693+ automatisierte Tests mit credential-freien Fake-Providern für Billing, Auth, E-Mail und Storage; der komplette Golden Path – Signup, Zahlungs-Webhook, Entitlement-Vergabe, Team-Einladung – verifiziert sich lokal in Sekunden.
Die Schleife, die Agenten sicher macht, ist unauffällig: Der Agent schreibt den Diff, läuft das Gate, liest die Fehler und korrigiert sich – alles vor menschlichem Review. Der verify-changes-Skill sagt ihm, welche Checks zu welchem Änderungstyp gehören; aus »der Agent hat Billing kaputtgemacht« wird »der Agent hat es selbst gefangen«.
| Fehlermodus | Repo ohne Guardrails | Mit supastack-Guardrails |
|---|---|---|
| Agent implementiert Vorhandenes neu | Im Review entdeckt – falls überhaupt | Paketgrenzen in AGENTS.md + .ai/-Mirrors verhindern es vorab |
| Tenant-Check still entfernt | Fällt in Production auf | Workspace-Regeln sind dokumentiert und testabgesichert |
| Webhook-Regression | Zeigt sich als Zahlungsausfall | Idempotentes Webhook-Ledger durch Replay-Tests fixiert |
| Repo-Exploration | Grep und Raterei | @supastack/mcp-Tools + Doku-Ressourcen |
| Verifikation | Agent behauptet »fertig« | 693+ Test-Gate Pflicht vor Review |
Warum sich Guardrails bei Kundenarbeit verzinsen
Für eine Agentur ist die Rechnung direkt: Jede Kunden-Codebase erbt denselben Vertrag, also ist ein neuer Agent auf einem neuen Projekt in Stunde eins produktiv statt die Grenzen durch Bruch zu lernen. Das ist der Unterschied zwischen »Agenten-Speed verkaufen« und »Agenten-Cleanup verkaufen«.
Die drei Kit-Stufen spiegeln, wie Agenturen kaufen – $199 Starter für Ein-Oberflächen-Projekte, $299 Full Bundle für alle Oberflächen mit 3 Seats, $799 Agency mit 10 Seats – und jede Stufe erlaubt unbegrenzte kommerzielle Kundenprojekte. Optionen auf der Pricing-Seite vergleichen.
FAQ: AI-Coding-Agenten auf echten Monorepos
Fragen, die Teams stellen, bevor sie Agenten eine Produktions-Codebasis anvertrauen:
- Mit welchen Agenten funktionieren diese Guardrails?, Mit jedem Agenten, der Markdown lesen kann – Claude Code, Cursor, Windsurf, Copilot, Devin. MCP-fähige Clients erhalten zusätzlich strukturierte Tools über
@supastack/mcp; die .ai/-Docs und Skills selbst sind tool-agnostisch. - Reicht AGENTS.md allein?, Es hilft, aber eine Einzeldatei verrottet. Was hält, ist die Kombination aus Vertrag (AGENTS.md) + Gedächtnis (.ai/-Mirrors) + Prozeduren (Agent Skills) + Verifikation (Test-Gate) – fehlt eine Schicht, tropft es durch.
- Wie groß ist die Test-Suite wirklich?, 693+ automatisierte Tests über Billing-Idempotenz, Session-Auth, Workspace-Isolation, API-Keys und agentenbezogene Packages – alle ohne echte Credentials lauffähig.
- Kann man diese Guardrails in ein bestehendes Repo nachrüsten?, Ja – überschlagen Sie etwa zwei Wochen sorgfältige Doku-Arbeit plus einen eigenen MCP-Server. Das Kit ist die Abkürzung: Vertrag, Skills, MCP-Server und Tests sind bereits aufeinander abgestimmt.