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.

Chiedi informazioni su questa guida

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.

Lascia che l'agente esegua la configurazione per te

agent-setup.md, avvia il kit e distribuiscilo con un agente
pick-a-style.md, applica uno stile di design a tutto il prodotto
new-landing-page.md, componi una pagina marketing dai blocchi del kit
new-app-screen.md, aggiungi una schermata dentro la shell dell'app workspace
restyle-product.md, riporta una pagina esistente sui token del kit
ui-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.

Segui la configurazione guidata dall'agente

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/packages/web-core/src/reports.md spiega le decisioni dietro packages/web-core/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 API sk_ 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.

Gate di verifica e suite di test

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_ o EXPO_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.