> ## 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

# Como impedir que Claude Code e Cursor quebrem seu monorepo (com regras .ai e MCP)

Depois de umas dez mil linhas, agentes de IA alucinam arquitetura: utilities duplicadas, checks de tenant contornados, webhooks quebrados. A stack .ai/ + AGENTS.md + MCP + gate de testes que faz agentes entregarem com segurança.

_Publicado 2026-11-08._
_Atualizado em 2026-11-08._

> **Como impedir que Claude Code ou Cursor quebre a arquitetura de um monorepo?**
> Depende de dar ao agente o mesmo contexto de um engenheiro sênior: contratos de arquitetura legíveis por máquina (AGENTS.md mais docs-espelho .ai/ que registram as fronteiras de cada pacote), playbooks de tarefas sob .agents/skills/, um servidor MCP (@supastack/mcp) que deixa o agente inspecionar o repo por ferramentas estruturadas em vez de adivinhar greps, e um gate de testes determinístico de 693+ testes — sem credenciais — obrigatório antes do review. O supastack pré-conecta as quatro camadas.

## O muro das dez mil linhas que todo usuário de agente atinge

As primeiras 5.000 linhas com Claude Code ou Cursor parecem mágica. Aí o repo cresce além do que o agente consegue enxergar inteiro — e as falhas deixam de parecer gralhas: ele reimplementa uma utility que existe dois pacotes adiante; adiciona uma query que esquece `workspaceId`; «corrige» um handler de webhook e apaga o check de idempotência que custou seu fim de semana.

É uma falha de contexto, não de capacidade. Um engenheiro sênior não pisa nessas frestas porque carrega a arquitetura na cabeça: qual pacote é dono de quê, quais invariantes são estruturais, o que os testes prometem. O agente pisa porque ninguém escreveu isso para ele.


## Camada um: um contrato escrito que o agente consegue ler

O supastack trata contexto para agentes como artefato de primeira classe. O `AGENTS.md` na raiz registra o contrato de arquitetura — o que cada pacote possui, o que o gate de testes exige, quais padrões são proibidos. O `.ai/PROJECT_CONTEXT.md` registra o estado atual e o porquê das decisões, e docs-espelho por arquivo fazem o contexto viajar junto com o código em vez de apodrecer num wiki.

Acima ficam ~29 playbooks de tarefas sob `.agents/skills/` — adicionar feature web, mudar o schema do banco, plugar um provedor de pagamento, verificar uma alteração — para o agente executar os procedimentos do próprio repo em 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
```


## Camada dois: @supastack/mcp dá aos agentes acesso estruturado ao repo

Sem ferramentas, a única forma de um agente explorar um monorepo de 700 arquivos é: grepar, ler os arquivos errados e adivinhar. O `@supastack/mcp` é um servidor Model Context Protocol real construído sobre `@modelcontextprotocol/sdk` e o runtime de ferramentas `@supastack/agents` — expõe o repo a agentes compatíveis com MCP (Claude Code, Cursor, Devin, Windsurf) via ferramentas estruturadas, recursos de documentação e prompts prontos.

A diferença aparece na taxa de falhas. Um agente que pode perguntar por ferramentas tipadas «o que este pacote exporta» ou «o que o gate de testes exige» para de inventar respostas a partir do arquivo que abriu por acaso. Nosso [artigo sobre o starter kit para agentes de coding IA](https://supastack.dev/pt/blog/ai-coding-saas-starter-kit.md) cobre o mesmo workflow do lado do build.


## Camada três: o gate de testes determinístico que o agente deve passar

Guardrails sem enforcement são só sugestões. O supastack inclui 693+ testes automatizados com providers fake sem credenciais para billing, auth, e-mail e storage — todo o caminho dourado (signup, webhook de pagamento, concessão de entitlement, convite de equipe) se verifica localmente em segundos.

O loop que torna um agente seguro é simples: o agente escreve o diff, roda o gate, lê a falha e se autocorrige — tudo antes do review humano. O skill `verify-changes` do repo diz quais checks rodar por tipo de mudança; «o agente quebrou o billing» vira «o agente pegou sozinho».

| Modo de falha | Repo sem guardrails | Com guardrails supastack |
|---|---|---|
| Agente reimplementa código existente | Descoberto no review — se descoberto | Fronteiras de pacotes no AGENTS.md + espelhos .ai/ previnem antes |
| Check de tenant removido em silêncio | Explode em produção | Regras de workspace escritas e cobertas por testes |
| Regressão de webhook | Aparece como queda de pagamentos | Ledger de webhooks idempotente travado por testes de replay |
| Exploração do repo | Grep e adivinhação | Ferramentas @supastack/mcp + recursos doc |
| Verificação | Agente diz «terminado» | Gate de 693+ testes obrigatório antes do review |


## Por que guardrails viram juros compostos no trabalho para clientes

Para uma agência a conta é direta: cada repo de cliente herda o mesmo contrato, então um agente novo num projeto novo produz desde a primeira hora em vez de aprender as fronteiras quebrando-as. É a diferença entre vender velocidade de agente e vender limpeza pós-agente.

Os três níveis do kit correspondem ao que agências realmente compram — Starter de $199 para projetos de uma superfície, Full Bundle de $299 para todas com 3 assentos, Agency de $799 com 10 — e todo nível permite projetos comerciais de clientes ilimitados. Compare na [página de preços](https://supastack.dev/#pricing).


## FAQ: agentes de coding IA em monorepos reais

Perguntas que equipes fazem antes de confiar uma codebase de produção a agentes:

- Com quais agentes esses guardrails funcionam?, Com qualquer agente que leia Markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. Clientes com MCP ganham ainda ferramentas estruturadas via `@supastack/mcp`; os docs .ai/ e skills são agnósticos.
- Só o AGENTS.md não basta?, Ajuda, mas um arquivo único apodrece. A combinação que aguenta é contrato (AGENTS.md) + memória (espelhos .ai/) + procedimentos (Agent Skills) + verificação (gate de testes) — falta uma camada e vaza.
- Qual o tamanho real da suite de testes?, 693+ testes automatizados sobre idempotência de billing, auth de sessão, isolamento de workspace, chaves de API e pacotes voltados a agentes — todos rodáveis sem credenciais reais.
- Dá para adicionar esses guardrails a um repo existente?, Dá — estime umas duas semanas de escrita cuidadosa mais um servidor MCP caseiro. O kit é o atalho: contrato, skills, servidor MCP e testes já estão alinhados entre si.