> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Cómo evitar que Claude Code y Cursor rompan tu monorepo (con reglas .ai y MCP)

Pasadas unas diez mil líneas, los agentes IA alucinan arquitectura: utilidades duplicadas, checks de tenant esquivados, webhooks rotos. El stack .ai/ + AGENTS.md + MCP + gate de tests que hace que los agentes entreguen seguro.

_Publicado 2026-11-08._
_Actualizado el 2026-11-08._

> **¿Cómo evitar que Claude Code o Cursor rompa la arquitectura de un monorepo?**
> Depende de dar al agente el mismo contexto que a un ingeniero senior: contratos de arquitectura legibles por máquina (AGENTS.md más docs espejo .ai/ que fijan las fronteras de cada paquete), playbooks de tareas bajo .agents/skills/, un servidor MCP (@supastack/mcp) que le permite inspeccionar el repo con herramientas estructuradas en vez de adivinar greps, y un gate de tests determinista de 693+ tests — sin credenciales — que debe pasar antes del review. supastack pre-cablea las cuatro capas.

## El muro de las diez mil líneas que golpea a todo usuario de agentes

Las primeras 5.000 líneas con Claude Code o Cursor parecen magia. Luego el repo se vuelve demasiado grande para que el agente lo vea entero — y los fallos dejan de parecer erratas: reimplementa una utilidad que existe dos paquetes más allá; añade una query que olvida `workspaceId`; «arregla» un handler de webhook y borra el check de idempotencia que te costó un fin de semana.

Es un fallo de contexto, no de capacidad. Un ingeniero senior no pisa esas grietas porque lleva la arquitectura en la cabeza: qué paquete posee qué, qué invariantes soportan peso, qué prometen los tests. El agente las pisa porque nadie se lo escribió.


## Capa uno: un contrato escrito que el agente puede leer

supastack trata el contexto para agentes como un artefacto de primer nivel. `AGENTS.md` en la raíz consigna el contrato de arquitectura: qué posee cada paquete, qué exige el gate de tests y qué patrones están prohibidos. `.ai/PROJECT_CONTEXT.md` registra el estado actual y el porqué de las decisiones, y los docs espejo por archivo hacen que el contexto viaje con el código en vez de pudrirse en un wiki.

Encima hay ~29 playbooks de tareas bajo `.agents/skills/` — añadir una feature web, cambiar el esquema de la base, conectar un proveedor de pago, verificar un cambio — para que el agente ejecute los procedimientos del repo en vez de improvisar.

```
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 agents
```


## Capa dos: @supastack/mcp da a los agentes acceso estructurado al repo

Sin herramientas, la única forma en que un agente explora un monorepo de 700 archivos es grepear, leer los archivos equivocados y adivinar. `@supastack/mcp` es un servidor Model Context Protocol real construido sobre `@modelcontextprotocol/sdk` y el runtime de herramientas `@supastack/agents` — expone el repo a agentes con MCP (Claude Code, Cursor, Devin, Windsurf) mediante herramientas estructuradas, recursos de documentación y prompts listos.

La diferencia se nota en la tasa de fallos. Un agente que puede preguntar con herramientas tipadas «qué exporta este paquete» o «qué exige el gate de tests» deja de inventar respuestas a partir del archivo que abrió por casualidad. Nuestro [artículo del starter kit para agentes de coding IA](https://supastack.dev/es/blog/ai-coding-saas-starter-kit.md) cubre el mismo workflow desde el lado del build.


## Capa tres: el gate de tests determinista que el agente debe superar

Los guardarraíles sin enforcement son solo sugerencias. supastack incluye 693+ tests automatizados con providers falsos sin credenciales para billing, auth, email y storage — todo el camino dorado (signup, webhook de pago, concesión de entitlement, invitación de equipo) se verifica localmente en segundos.

El bucle que hace seguro a un agente es sencillo: escribe el diff, corre el gate, lee el fallo y se autocorrige — todo antes del review humano. El skill `verify-changes` del repo le dice qué checks correr según el tipo de cambio; «el agente rompió el billing» se convierte en «el agente lo pilló él mismo».

| Modo de fallo | Repo sin guardarraíles | Con guardarraíles supastack |
|---|---|---|
| El agente reimplementa código existente | Se descubre en review — si acaso | Las fronteras de paquetes en AGENTS.md + espejos .ai/ lo previenen |
| Check de tenant borrado en silencio | Estalla en producción | Reglas de workspace escritas y cubiertas por tests |
| Regresión de webhook | Aparece como caída de pagos | Ledger de webhooks idempotente fijado por tests de replay |
| Exploración del repo | Grep y adivinanza | Herramientas @supastack/mcp + recursos doc |
| Verificación | El agente dice «terminado» | Gate de 693+ tests obligatorio antes del review |


## Por qué los guardarraíles rinden interés compuesto en trabajo para clientes

Para una agencia el cálculo es directo: cada repo de cliente hereda el mismo contrato, así que un agente nuevo en un proyecto nuevo produce desde la hora uno en vez de aprender las fronteras rompiéndolas. Es la diferencia entre vender velocidad de agente y vender limpieza tras el agente.

Los tres niveles del kit corresponden a cómo compran las agencias — Starter de $199 para proyectos de una superficie, Full Bundle de $299 para todas con 3 asientos, Agency de $799 con 10 — y cada nivel permite proyectos comerciales de clientes ilimitados. Compara en la [página de precios](https://supastack.dev/#pricing).


## FAQ: agentes de coding IA en monorepos reales

Preguntas que hacen los equipos antes de entregar una codebase de producción a agentes:

- ¿Con qué agentes funcionan estos guardarraíles?, Con cualquier agente que lea Markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. Los clientes con MCP obtienen además herramientas estructuradas vía `@supastack/mcp`; los docs .ai/ y skills son agnósticos.
- ¿No basta con AGENTS.md?, Ayuda, pero un archivo único se pudre. La combinación que aguanta es contrato (AGENTS.md) + memoria (espejos .ai/) + procedimientos (Agent Skills) + verificación (gate de tests) — falta una capa y gotea.
- ¿Cuán grande es realmente la suite de tests?, 693+ tests automatizados sobre idempotencia de billing, auth de sesión, aislamiento de workspace, claves API y paquetes orientados a agentes — todos ejecutables sin credenciales reales.
- ¿Se pueden añadir estos guardarraíles a un repo existente?, Sí — calcula unas dos semanas de documentación cuidadosa más un servidor MCP propio. El kit es el atajo: contrato, skills, servidor MCP y tests ya están alineados entre sí.