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