Costruisci con un agente di codice

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.

• Prima di iniziare
• Nozioni di base sul terminale
• Configurazione locale Web

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.

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