How do you stop Claude Code or Cursor from breaking a monorepo?
It depends on giving the agent the same context a senior engineer holds: machine-readable architecture contracts (AGENTS.md and .ai/ mirror docs that state each package's boundaries), task playbooks under .agents/skills/, an MCP server (@supastack/mcp) that lets the agent inspect the repo through structured tools instead of grep guesses, and a deterministic credential-free test gate of 693+ tests it must run before you review. supastack ships all four layers pre-wired.
The 10,000-Line Wall Every Agent User Hits
The first 5,000 lines with Claude Code or Cursor feel like magic. Then the repo gets big enough that the agent can no longer see it whole — and the failures stop looking like typos. It re-implements a utility that already exists two packages away. It adds a query that forgets workspaceId. It 'fixes' a webhook handler by removing the idempotency check that took you a weekend to get right.
This is a context failure, not a capability failure. A senior engineer doesn't break those seams because they carry the architecture in their head: which package owns what, which invariants are load-bearing, what the tests promise. Agents break them because nobody wrote that down for them.
Layer One: A Written Contract the Agent Can Read
supastack treats agent context as a first-class deliverable. AGENTS.md at the repo root states the architecture contract — what each package owns, what the test gate requires, which patterns are forbidden. .ai/PROJECT_CONTEXT.md records current state and the reasoning behind decisions, with per-file mirror docs so the context travels with the code instead of rotting in a wiki.
On top sit ~29 task playbooks in .agents/skills/ — add a web feature, change the database schema, add a payment provider, verify changes — so an agent executes the repo's own procedure instead of improvising one.
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 agentsLayer Two: @supastack/mcp Gives Agents Structured Repo Access
Without tooling, an agent explores a 700-file monorepo the only way it can: grepping, reading the wrong file, and guessing. @supastack/mcp is a real Model Context Protocol server built on @modelcontextprotocol/sdk and the @supastack/agents tool runtime — it exposes the repo to MCP-capable agents (Claude Code, Cursor, Devin, Windsurf) through structured tools, document resources and ready-made prompts.
The difference shows up in failure rates. An agent that can query 'what does this package export' or 'what does the test gate require' through a typed tool stops inventing answers from whichever file it happened to open. Our AI coding agent starter kit post covers the workflow from the build side.
Layer Three: A Deterministic Test Gate Agents Must Pass
Guardrails without enforcement are suggestions. supastack ships 693+ automated tests with fake, credential-free providers for billing, auth, email and storage, so the entire golden path — signup, checkout webhook, entitlement, team invite — verifies locally in seconds.
The loop that makes agents safe is unglamorous: the agent writes the diff, runs the gate, reads the failure, self-corrects — before a human ever reviews it. The repo's verify-changes skill tells the agent exactly which checks to run for the kind of change it made, so 'the agent broke billing' becomes 'the agent caught it.'
| Failure mode | Unguarded repo | With supastack guardrails |
|---|---|---|
| Agent re-implements existing code | Discovered in review, if ever | Package boundaries in AGENTS.md + .ai/ mirrors prevent it |
| Tenant check silently dropped | Surfaces in production | Workspace rules are written down and covered by tests |
| Webhook regression | Found when payments break | Idempotent webhook ledger is pinned by replay tests |
| Repo exploration | Greps and guesses | @supastack/mcp tools + document resources |
| Verification | Agent says 'done' | 693+ test gate must pass before review |
Why Guardrails Compound for Client Work
For an agency, the arithmetic is direct: every client repo inherits the same contract, so a new agent on a new engagement starts productive on hour one instead of learning boundaries by breaking them. That is the difference between selling agent speed and selling agent cleanup.
The kit's three tiers map to how agencies actually buy — Starter at $199 for a single-platform engagement, Full Bundle at $299 for all surfaces with 3 seats, Agency at $799 with 10 seats — each permitting unlimited client commercial projects. Compare options on the pricing page.
FAQ: AI Coding Agents on a Real Monorepo
Questions teams ask before trusting agents with a production codebase:
- Which agents do these guardrails work with?, Any agent that reads markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. MCP-capable clients additionally get structured tools through
@supastack/mcp; the .ai/ docs and skills are tool-agnostic. - Isn't AGENTS.md enough on its own?, It helps, but a single file rots. The pattern that holds is contract (AGENTS.md) + memory (.ai/ mirrors) + procedure (Agent Skills) + verification (test gate) — any layer alone leaks.
- How big is the test suite really?, 693+ automated tests covering billing idempotency, auth sessions, workspace isolation, API keys and the agent-facing packages — all runnable without live credentials.
- Can I add these guardrails to an existing repo?, You can, and that is roughly two weeks of careful writing plus an MCP server build. The kit is the shortcut: the contract, skills, MCP server and tests already agree with each other.