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 agentsCamada 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 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.
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.