> ## 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 # Come impedire a Claude Code e Cursor di rompere il tuo monorepo (con regole .ai e MCP) Superate le diecimila righe, gli agenti AI allucinano l'architettura: utility duplicate, controlli tenant aggirati, webhook rotti. Lo stack .ai/ + AGENTS.md + MCP + gate di test che fa rilasciare gli agenti in sicurezza. _Pubblicato 2026-11-08._ _Aggiornato il 2026-11-08._ > **Come si impedisce a Claude Code o Cursor di rompere l'architettura di un monorepo?** > Dipende dalla capacità di dare all'agente lo stesso contesto di un senior engineer: contratti di architettura leggibili dalle macchine (AGENTS.md più documenti specchio .ai/ che fissano i confini di ogni package), playbook di attività sotto .agents/skills/, un server MCP (@supastack/mcp) che lascia l'agente ispezionare il repo con tool strutturati invece di indovinare dai grep, e un gate di test deterministico da 693+ test — senza credenziali — obbligatorio prima della review. supastack pre-cabla tutti e quattro i livelli. ## Il muro delle diecimila righe che colpisce ogni utente di agenti Le prime 5.000 righe con Claude Code o Cursor sembrano magia. Poi il repo diventa troppo grande perché l'agente possa vederlo intero — e i fallimenti smettono di assomigliare a refusi: reimplementa una utility che esiste due package più in là; aggiunge una query che dimentica `workspaceId`; «sistema» un handler di webhook e cancella il controllo di idempotenza che ti è costato un weekend. È un fallimento di contesto, non di capacità. Un senior engineer non inciampa in quelle crepe perché porta l'architettura nella testa: quale package possiede cosa, quali invarianti sono portanti, cosa promettono i test. L'agente ci inciampa perché nessuno glielo ha scritto. ## Livello uno: un contratto scritto che l'agente può leggere supastack tratta il contesto per gli agenti come un artefatto di primo livello. `AGENTS.md` alla radice fissa il contratto di architettura: cosa possiede ogni package, cosa richiede il gate di test, quali pattern sono vietati. `.ai/PROJECT_CONTEXT.md` registra lo stato attuale e il perché delle decisioni, e i documenti specchio per file fanno viaggiare il contesto insieme al codice invece di lasciarlo marcire in un wiki. Sopra ci sono ~29 playbook di attività sotto `.agents/skills/` — aggiungere una feature web, cambiare lo schema del database, collegare un provider di pagamento, verificare una modifica — così l'agente esegue le procedure del repo invece di improvvisare. ``` 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 ``` ## Livello due: @supastack/mcp dà agli agenti accesso strutturato al repo Senza strumenti, l'unico modo in cui un agente esplora un monorepo da 700 file è: grep, leggere i file sbagliati, indovinare. `@supastack/mcp` è un vero server Model Context Protocol costruito su `@modelcontextprotocol/sdk` e sul runtime di tool `@supastack/agents` — espone il repo agli agenti compatibili MCP (Claude Code, Cursor, Devin, Windsurf) tramite tool strutturati, risorse documentali e prompt pronti. La differenza si vede nel tasso di errori. Un agente che può chiedere con tool tipizzati «cosa esporta questo package» o «cosa richiede il gate di test» smette di inventare risposte dal file che ha aperto per caso. Il nostro [articolo sullo starter kit per agenti di coding AI](https://supastack.dev/it/blog/ai-coding-saas-starter-kit.md) copre lo stesso workflow dal lato build. ## Livello tre: il gate di test deterministico che l'agente deve superare I guardrail senza enforcement sono solo suggerimenti. supastack include 693+ test automatizzati con provider finti senza credenziali per billing, auth, email e storage — l'intero percorso d'oro (signup, webhook di pagamento, concessione di entitlement, invito al team) si verifica in locale in pochi secondi. Il ciclo che rende sicuro un agente è semplice: l'agente scrive il diff, esegue il gate, legge il fallimento e si corregge — tutto prima della review umana. Lo skill `verify-changes` del repo gli dice quali check eseguire per tipo di modifica; «l'agente ha rotto il billing» diventa «l'agente lo ha scoperto da sé». | Modalità di fallimento | Repo senza guardrail | Con i guardrail supastack | |---|---|---| | L'agente reimplementa codice esistente | Scoperto in review — forse | I confini di package in AGENTS.md + specchi .ai/ lo prevengono | | Controllo tenant rimosso in silenzio | Esplode in produzione | Regole workspace scritte e coperte dai test | | Regressione di webhook | Si manifesta come outage di pagamenti | Ledger webhook idempotente fissato da test di replay | | Esplorazione del repo | Grep e supposizioni | Tool @supastack/mcp + risorse doc | | Verifica | L'agente dichiara «finito» | Gate di 693+ test obbligatorio prima della review | ## Perché i guardrail fruttano nel lavoro per clienti Per un'agenzia il conto è diretto: ogni repo cliente eredita lo stesso contratto, quindi un agente nuovo su un progetto nuovo è produttivo dalla prima ora invece di imparare i confini rompendoli. È la differenza tra vendere velocità dell'agente e vendere pulizia dopo l'agente. I tre livelli del kit rispecchiano come le agenzie comprano davvero — Starter da $199 per progetti a superficie singola, Full Bundle da $299 per tutte le superfici con 3 postazioni, Agency da $799 con 10 — e ogni livello consente progetti clienti commerciali illimitati. Confronta le opzioni nella [pagina dei prezzi](https://supastack.dev/#pricing). ## FAQ: agenti di coding AI su monorepo reali Le domande che i team fanno prima di affidare una codebase di produzione agli agenti: - Con quali agenti funzionano questi guardrail?, Con qualsiasi agente che sappia leggere Markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. I client compatibili MCP ottengono in più tool strutturati via `@supastack/mcp`; i doc .ai/ e gli skill sono agnostici. - AGENTS.md da solo non basta?, Aiuta, ma un file unico marcisce. La combinazione che regge è contratto (AGENTS.md) + memoria (specchi .ai/) + procedure (Agent Skills) + verifica (gate di test) — basta un livello mancante per avere fughe. - Quanto è grande davvero la suite di test?, 693+ test automatizzati su idempotenza del billing, auth di sessione, isolamento dei workspace, chiavi API e package orientati agli agenti — tutti eseguibili senza credenziali reali. - Si possono aggiungere questi guardrail a un repo esistente?, Sì — stima circa due settimane di scrittura accurata più un server MCP fatto in casa. Il kit è la scorciatoia: contratto, skill, server MCP e test sono già allineati tra loro.