> ## 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

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

[Prima di iniziare](https://supastack.dev/it/docs/web/before-you-start.md)

[Nozioni di base sul terminale](https://supastack.dev/it/docs/web/terminal-basics.md)

[Configurazione locale Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md)


## 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](https://supastack.dev/it/docs/web/agent-setup.md)

- `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](https://supastack.dev/it/docs/web/agent-setup.md)


## 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](https://supastack.dev/it/docs/web/testing.md)

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


Per continuare la configurazione, leggi [Crea i tuoi account esterni](https://supastack.dev/it/docs/web/external-accounts.md).


## Successivo

[Crea i tuoi account esterni](https://supastack.dev/it/docs/web/external-accounts.md)