For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /it/docs/web/agents.md (or send Accept: text/markdown).
Costruisci con un agente di codice
Affida attività a un agente di codice: i file che legge, la libreria di prompt pronti da incollare, la configurazione automatica e la revisione che ti lascia il controllo.
Procedura guidata per principianti
Prerequisiti: leggi le due guide per principianti qui sotto, completa la configurazione locale Web e apri questo repository alla radice nel tuo editor. Un agente di codice è uno strumento AI — Cursor, Claude Code, Devin o un assistente simile — che legge il tuo progetto, modifica file ed esegue comandi. Tutto ciò che trovi in questa pagina vale per qualsiasi strumento tu usi.
Termini rapidi: un prompt è il testo di istruzioni che incolli nell'agente. Un diff è l'elenco delle modifiche ai file che propone. La radice del repository è la cartella più in alto che contiene package.json — l'agente dovrebbe sempre partire da lì.
1. Apri la cartella prompts/ nella radice del repository e copia il prompt più vicino alla tua attività. new-landing-page.md è un buon primo tentativo.
2. Incollalo nel tuo agente e compila i <placeholders>: la route che vuoi, cosa deve fare la pagina o la schermata, chi può usarla e che aspetto ha il risultato atteso. Poi aggiungi una riga: leggi llms.txt, poi AGENTS.md, poi .ai/PROJECT_CONTEXT.md prima di toccare il codice.
3. Fai elencare all'agente i file che modificherà e i controlli che eseguirà prima di intervenire. Quando ha finito, esamina il diff — stai approvando modifiche reali al tuo prodotto.
4. Pubblicazione, deployment e chiamate a provider a pagamento non fanno mai parte di un prompt di attività. Tienili come passaggi separati che approvi esplicitamente.
I file che il tuo agente legge
Il repository include un piccolo insieme di file scritti per gli agenti, non solo per le persone. Non devi mai incollare questo contesto a mano — punta l'agente su llms.txt e leggerà il resto da solo.
L'ordine di lettura conta: llms.txt è la mappa, AGENTS.md fissa i confini e .ai/PROJECT_CONTEXT.md conserva ciò che le sessioni precedenti hanno imparato. Un agente che salta i confini produce codice che non puoi pubblicare.
| Percorso | Cosa offre all'agente |
|---|---|
| `llms.txt` | La mappa di ingresso del repository — tutti i documenti che vale la pena leggere più i protocolli di sicurezza, in ordine di lettura |
| `AGENTS.md` | I confini non negoziabili: solo lavoro locale finché non approvi di più, scope per workspaceId, segreti solo lato server |
| `.ai/PROJECT_CONTEXT.md` | Memoria tra sessioni — cosa è cambiato di recente e perché; da leggere prima delle modifiche al codice |
| Documenti mirror `.ai/` | Una nota `.ai/<path>.md` corrispondente accanto ai file importanti, che registra decisioni e discussioni aperte per file |
| `docs/agent-setup.md` | Il runbook automatico — fasi di installazione, migrazione e deployment con un checkpoint di verifica dopo ciascuna |
| `prompts/` | Prompt di attività pronti da incollare per i lavori che i proprietari chiedono più spesso |
| `docs/agent-security.md` | La checklist di accettazione — autenticazione, controlli su workspace e RLS, log oscurati, prove del deployment |
| `.env.example` | L'inventario completo dell'ambiente — l'agente non inventa mai un nome di variabile assente da questo file |
La libreria dei prompt
prompts/README.md è l'indice. Ogni file è un brief completo: incollalo, compila i <placeholders> e le regole del kit — design token al posto di colori fissati nel codice, blocchi del kit al posto di pattern inventati — viaggiano con esso.
Per il percorso da zero all'esecuzione, incolla invece prompts/agent-setup.md — guida la configurazione automatica descritta qui sotto.
agent-setup.md— avvia il kit e distribuiscilo con un agentepick-a-style.md— applica uno stile di design a tutto il prodottonew-landing-page.md— componi una pagina marketing dai blocchi del kitnew-app-screen.md— aggiungi una schermata dentro la shell dell'app workspacerestyle-product.md— riporta una pagina esistente sui token del kitui-audit.md— esegui l'audit visivo e di accessibilità su una route
Lasciare installare e distribuire all'agente
Il kit può in gran parte configurarsi da solo. Incollare prompts/agent-setup.md fa eseguire all'agente docs/agent-setup.md — il runbook incluso — fase per fase: controlli preliminari, file di ambiente, installazione, avvio del database, migrazioni, avvio dell'app e, facoltativamente, un deploy su VPS. Dopo ogni fase esegue il relativo checkpoint di verifica e riporta l'output reale, non una dichiarazione.
Due script di supporto mantengono tutto sicuro. scripts/setup-env.mjs prepara i file env da .env.example: crea solo i file mancanti, genera solo i segreti mancanti o segnaposto e la sua modalità --check valida senza scrivere. docker-compose.dev.yml è un ambiente di sviluppo completamente in container — Postgres più un dev container Node 22 — quindi l'agente non ha bisogno di Node.js installato sul tuo computer.
Quale repository hai ricevuto conta qui. Il repository Web e il monorepo All Platforms includono il runbook, i file compose, scripts/setup-env.mjs e prompts/. I repository Mobile e Desktop standalone includono un llms.txt dedicato, AGENTS.md, i documenti mirror .ai/ e documenti selezionati tra cui docs/agent-security.md — ma non il runbook di configurazione né i file compose, perché il backend con cui quelle app comunicano vive nel repository Web.
Come l'agente ricorda tra le sessioni
Gli agenti non hanno memoria tra le sessioni — la cartella .ai/ è la memoria. .ai/PROJECT_CONTEXT.md registra cosa è cambiato di recente e perché. Accanto, un documento mirror come .ai/apps/web/src/reports.md spiega le decisioni dietro apps/web/src/reports.ts che il codice da solo non mostra.
Il contratto è semplice: leggi il mirror di un file prima di modificarlo e aggiorna il mirror quando la modifica arriva. Le voci Open Threads registrano il lavoro non finito così la sessione successiva riprende invece di ricominciare. Un mirror obsoleto è peggio di nessuno — quando esamini il diff dell'agente, controlla che i mirror dei file modificati si siano mossi insieme al codice.
La superficie per gli agenti dell'app in esecuzione
Anche il tuo prodotto distribuito risponde agli agenti — questi endpoint esistono sull'app in esecuzione, non solo nel repository.
GET /llms.txt— l'app serve il proprio indice llmstxt.org: guide, pagine pubbliche ed endpoint pubblici, con URL assoluti.POST /api/mcp— un endpoint MCP stateless che espone gli strumenti dell'app. Accetta solo chiavi APIsk_come bearer token — le sessioni cookie del browser non valgono mai. Crea le chiavi in Impostazioni → Sviluppatori.GET /api/v1/openapi— la specifica OpenAPI dell'API REST pubblica, per generatori di client e strumenti per agenti.GET /api/health— la sonda di disponibilità e dipendenze che chiamano load balancer e controlli di uptime; riporta i tipi di configurazione dei provider, mai i segreti./status— una pagina leggibile che riporta lo stato di salute di ogni sottosistema.
Esamina onestamente il lavoro dell'agente
Un'attività finita è una prova, non un riepilogo. Prima di tenere il lavoro dell'agente, controllalo nel modo in cui docs/agent-security.md controlla un deployment:
Quando qualcosa non va, rispedisci il diff indietro — l'agente corregge il proprio lavoro più in fretta quando nomini il controllo fallito. Per qualsiasi cosa non avrebbe mai dovuto tentare da solo, dillo esplicitamente una volta; il confine vale per il resto della sessione.
- Ha eseguito i test che dichiara — chiedi il comando e il suo output, non una conclusione.
- I segreti sono rimasti solo lato server — niente di nuovo porta il prefisso
NEXT_PUBLIC_oEXPO_PUBLIC_e nessuna chiave è finita in un report o in un commit. - Ogni lettura e scrittura di dati dell'utente è rimasta delimitata da
workspaceId— nessuna query si fida di un id inviato dal browser. - Il mirror
.ai/di ogni file modificato si è mosso insieme al codice. - Pubblicazione, deployment e chiamate a provider a pagamento sono rimasti passaggi separati che hai approvato — l'agente non ha mai fatto merge, push o deploy da solo.
- Se un passaggio è fallito due volte, si è fermato e ha riportato il comando fallito invece di improvvisare.