> ## 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 codifica: i file che legge, gli skill inclusi e la revisione che ti mantiene in controllo.

## Procedura dettagliata per principianti

Prerequisiti: leggi le due guide per principianti qui sotto e completa la configurazione locale Desktop. Un agente di codifica è uno strumento AI — Cursor, Claude Code, Devin o un assistente simile — che legge il tuo progetto, modifica file ed esegue comandi. Tutto in questa pagina si applica a qualunque 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 `.agents/skills/` nella radice del repository e copia lo skill più vicino alla tua attività — `add-a-desktop-capability` è un buon primo tentativo.

2. Incollalo nel tuo agente e descrivi la tua modifica, 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, rilascio di installer 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/desktop/before-you-start.md)

[Nozioni di base sui terminali](https://supastack.dev/it/docs/desktop/terminal-basics.md)

[Configurazione locale del desktop](https://supastack.dev/it/docs/desktop/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, generata per elencare solo ciò che questo checkout effettivamente include |
| `AGENTS.md` | I confini non negoziabili: solo lavoro locale finché non approvi di più, la shell non fork mai la UI di prodotto |
| `.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 |
| `.agents/skills/` | Runbook di attività scritti per gli agenti — i cinque skill Desktop elencati qui sotto |
| `docs/agent-security.md` | La checklist di accettazione — autenticazione, controlli di workspace e permessi, log redatti |
| `docs/desktop-updates.md` | Il runbook del canale di aggiornamento — chiavi di firma, endpoint e canali di rilascio |
| `.env.example` | L'inventario completo dell'ambiente — l'agente non inventa mai un nome di variabile assente da questo file |


## Gli skill inclusi

Ogni file sotto `.agents/skills/` è un brief completo: incollalo o lascia che l'agente lo legga, e le regole del kit viaggiano con esso — la UI di prodotto resta nell'app web, solo il comportamento SO va in Rust.

La libreria `prompts/` incollabile è inclusa solo nel repository Web; questo checkout porta invece gli skill. Per una configurazione non presidiata, usa il prompt già pronto nella guida agent-setup.

[Lascia che l'agente esegua la configurazione](https://supastack.dev/it/docs/desktop/agent-setup.md)

- `add-a-desktop-capability` — modifiche di finestra, tray, scorciatoia, aggiornamento o build
- `adding-a-dependency` — aggiungere, aggiornare o spostare una dipendenza npm in sicurezza
- `reviewing-a-pr` — revisionare un diff per correttezza, isolamento del workspace e segreti
- `upgrading-from-upstream` — portare una release più recente del kit nella tua shell
- `verify-changes` — scegliere ed eseguire i controlli giusti prima della consegna


## 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 specchio come `.ai/apps/desktop/src-tauri/src/lib.md` spiega le decisioni dietro `apps/desktop/src-tauri/src/lib.rs` 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.


## 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/desktop/testing.md)

- Ha eseguito i controlli che afferma — cargo test, cargo check o il preflight di rilascio — chiedi il comando e il suo output, non una conclusione.
- I segreti sono rimasti solo sul server — nessuna chiave di firma o certificato è stato stampato in un report o commit, e la shell non porta ancora credenziali di provider.
- Il comportamento di prodotto è rimasto nell'app web — il diff non aggiunge UI, autenticazione o logica di chat parallela in Rust.
- Il mirror `.ai/` di ogni file modificato si è mosso insieme al codice.
- Pubblicazione, rilascio di installer e chiamate a provider a pagamento sono rimasti passaggi separati che hai approvato — l'agente non ha mai fatto merge, push o rilascio 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 gli account di rilascio desktop](https://supastack.dev/it/docs/desktop/external-accounts.md).


## Successivo

[Crea gli account di rilascio desktop](https://supastack.dev/it/docs/desktop/external-accounts.md)