Concetti fondamentali

Dropstone è uno strumento di codifica agentico che gira nel tuo terminale. Può leggere codice, eseguire comandi, pianificare modifiche, modificare file e verificare il risultato. Questa pagina copre le idee fondamentali che devi imparare una sola volta: il loop in cui gira l'agente, a cosa può accedere, come funzionano le sessioni, come viene gestito il contesto e come le autorizzazioni ti mantengono al controllo.

Il loop agentico

Quando dai a Dropstone un compito, lavora attraverso tre fasi: raccogliere contesto, agire e verificare i risultati. Le fasi si fondono tra loro. Dropstone usa strumenti in tutto il processo, sia che legga file per capire il tuo codice, sia che modifichi per apportare cambiamenti, sia che esegua test per controllare il suo lavoro.

Il loop si adatta a ciò che chiedi. Una domanda sul tuo codebase potrebbe richiedere solo la raccolta di contesto. Una correzione di bug attraversa tutte e tre le fasi. Un grande refactoring potrebbe comportare una verifica pesante. Dropstone decide cosa richiede ogni passaggio in base a ciò che ha imparato dal passaggio precedente, concatenando dozzine di azioni e correggendo la rotta lungo il percorso.

Anche tu fai parte di questo loop. Puoi interrompere in qualsiasi momento per reindirizzare, aggiungere contesto o chiedere un approccio diverso. Dropstone lavora in modo autonomo ma rimane reattivo al tuo input.

Il loop agentico è alimentato da due componenti: il modello che ragiona e gli strumenti che agiscono.

Modelli

Dropstone usa modelli di codifica costruiti su misura. Ci sono tre livelli, ciascuno ottimizzato per un diverso tipo di lavoro:

Cambia livello con /effort low, /effort medium, /effort high o /effort xhigh durante una sessione, oppure con Ctrl+T per scorrere tra di essi. Quando questa guida dice "Dropstone decide" o "Dropstone sceglie", è il modello che sta ragionando.

Strumenti

Gli strumenti sono ciò che rende Dropstone agentico. Senza strumenti, il modello può solo produrre testo. Con gli strumenti, può agire: leggere il tuo codice, modificare file, eseguire comandi, cercare sul web e interagire con servizi esterni. Ogni risultato dello strumento viene reimmesso nel loop, informando la decisione successiva.

Gli strumenti integrati rientrano in cinque categorie:

Dropstone sceglie quali strumenti usare in base al tuo prompt e a ciò che impara lungo il percorso. Quando dici "correggi i test che falliscono", potrebbe:

1. Eseguire la suite di test per vedere cosa fallisce
2. Leggere l'output degli errori
3. Cercare i file sorgente pertinenti
4. Leggere quei file per capire il codice
5. Modificarli per risolvere il problema
6. Eseguire di nuovo i test per verificare

Ogni uso di uno strumento restituisce informazioni che informano il passaggio successivo. Questo è il loop agentico in pratica.

Gli strumenti integrati sono la base. Puoi estendere ciò che Dropstone conosce con skills, connetterti a servizi esterni con server MCP e delegare lavoro a subagent. Per l'elenco completo degli strumenti integrati, vedi Strumenti integrati.

A cosa può accedere Dropstone

Quando esegui dropstone in una directory, l'agente ottiene accesso a:

• Il tuo progetto. File nella tua directory di lavoro e nelle sottodirectory, più altri file con la tua autorizzazione.
• Il tuo terminale. Qualsiasi comando che potresti eseguire tu stesso: strumenti di build, git, gestori di pacchetti, utilità di sistema, script. Se puoi farlo dalla riga di comando, Dropstone può farlo anche lui.
• Il tuo stato git. Branch corrente, modifiche non committate, file in stage e cronologia dei commit recenti.
• Il tuo AGENTS.md. Un file markdown nella radice del repository dove scrivi convenzioni specifiche del progetto, comandi di build, insidie e qualsiasi cosa Dropstone dovrebbe sapere in ogni sessione.
• Estensioni che configuri. Server MCP per servizi esterni, skills per flussi di lavoro e subagent per lavoro delegato.

Poiché Dropstone vede l'intero progetto, può lavorare su di esso in modo trasversale. Quando gli chiedi di "correggere il bug di autenticazione", cerca i file pertinenti, ne legge diversi per capire il contesto, apporta modifiche coordinate su di essi, esegue test per verificare e committa se glielo chiedi. Questo è diverso dagli assistenti di codice inline che vedono solo il file corrente.

Sessioni

Ogni sessione interattiva viene salvata localmente. Ogni messaggio, uso di strumento e risultato viene scritto in un record di sessione, il che rende possibile annullare, riprendere e biforcare lavori passati.

Le sessioni sono indipendenti. Una nuova sessione inizia con una finestra di contesto fresca, senza memoria delle conversazioni precedenti. La conoscenza persistente appartiene a AGENTS.md, non alla cronologia della conversazione.

Riprendi o biforca le sessioni

Riprendere con dropstone --continue (o dropstone -c) riapre la sessione più recente nella directory corrente e vi aggiunge nuovi messaggi. Riprendere una sessione specifica per id usa dropstone --session <id>.

# Continua l'ultima sessione in questa directory
dropstone -c

# Riprendi una sessione specifica
dropstone --session 7f3a82b1

# Biforca una sessione esistente in una nuova conversazione
dropstone --session 7f3a82b1 --fork

La biforcazione copia la cronologia in un nuovo id di sessione, lasciando l'originale intatto. Utile quando vuoi esplorare una direzione alternativa senza perdere il filo originale.

La finestra di contesto

La finestra di contesto contiene la cronologia della conversazione, i contenuti dei file, gli output dei comandi, AGENTS.md, le skills caricate e le istruzioni di sistema. Mentre lavori, la finestra si riempie. Dropstone compatta automaticamente i contenuti più vecchi, ma le istruzioni dell'inizio della conversazione possono andare perse.

Alcune regole pratiche:

• Metti le regole persistenti in AGENTS.md, non nei messaggi di chat. La versione nel messaggio di chat viene compattata; la versione in AGENTS.md viene ricaricata in ogni sessione.
• Le skills si caricano su richiesta. Dropstone vede le descrizioni delle skills all'inizio della sessione ma carica solo il contenuto completo quando una skill viene invocata.
• I subagent hanno il proprio contesto fresco. Il loro lavoro non appesantisce la conversazione principale; quando finiscono, restituiscono un riepilogo.

Sicurezza: checkpoint e autorizzazioni

Dropstone ha due meccanismi di sicurezza. I checkpoint ti permettono di annullare le modifiche apportate dall'agente. Le autorizzazioni controllano cosa può fare l'agente senza chiedere.

Annulla con checkpoint

Ogni modifica ai file è reversibile. Prima che Dropstone modifichi un file, cattura un'istantanea del contenuto corrente. Se qualcosa va storto, usa /undo per tornare indietro di un ciclo di modifica alla volta, oppure /redo per riprodurre un passaggio annullato.

/undo            # ripristina l'ultimo ciclo di modifica
/redo            # riproduce il passaggio annullato più recente

I checkpoint sono locali alla tua sessione, separati da git. Coprono solo le modifiche ai file. Le azioni che toccano sistemi remoti (database, servizi distribuiti, API di rete) non possono essere checkpointate, motivo per cui Dropstone chiede prima di eseguire comandi con effetti collaterali esterni.

Controlla cosa può fare Dropstone

Dropstone chiede approvazione la prima volta che vuole eseguire un'azione sensibile: modificare un file, eseguire un comando shell, chiamare la rete. Approva una volta e la stessa operazione viene eseguita senza richiedere di nuovo per il resto della sessione.

Usa Tab per passare tra due modalità operative durante una sessione:

• Modalità Build. La predefinita. Dropstone può modificare file ed eseguire comandi (soggetto ad approvazione). Usala quando vuoi consegnare la modifica.
• Modalità Plan. Sola lettura. Dropstone può investigare il codebase, raccogliere contesto e produrre un piano, ma non può modificare o eseguire nulla. Usala quando vuoi studiare il sistema prima di modificarlo.

Per pre-approvare i comandi e saltare del tutto il prompt, elencali nella configurazione delle autorizzazioni del tuo progetto. Per esempio:

{
  "permissions": {
    "allow": ["git status", "git diff", "npm test", "npm run lint"]
  }
}

Per politiche a livello di organizzazione, pattern più granulari e come funziona la risoluzione dell'ambito, vedi la Guida alle autorizzazioni.

Lavorare efficacemente con Dropstone

Alcuni pattern che tendono a produrre risultati migliori.

È una conversazione

Non hai bisogno di un prompt iniziale perfetto. Inizia con ciò che vuoi, osserva cosa fa l'agente, poi correggilo:

correggi il bug del login

no, il problema è nella gestione delle sessioni, non nella validazione del form

Non stai ricominciando da zero. Stai iterando. Ogni turno affina la comprensione dell'agente.

Interrompi e guida

Puoi reindirizzare Dropstone in qualsiasi momento:

• Premi Esc per fermarti immediatamente. La chiamata allo strumento corrente viene annullata e Dropstone attende la tua prossima istruzione.
• Scrivi una correzione e premi Enter senza aspettare. Dropstone la legge appena l'azione corrente termina e si adatta prima di decidere il passaggio successivo.

Sii specifico fin dall'inizio

Più preciso è il tuo prompt iniziale, meno correzioni ti serviranno. Fai riferimento ai file, menziona i vincoli, indica i pattern di esempio:

il flusso di checkout è rotto per gli utenti con carte scadute.
cerca il problema in src/payments/, soprattutto nel token refresh.
scrivi prima un test che fallisce, poi correggilo.

I prompt vaghi funzionano, ma passerai più tempo a guidare. I prompt specifici come quello sopra spesso riescono al primo tentativo.

Dai a Dropstone qualcosa su cui verificare

L'agente lavora meglio quando può controllare il proprio lavoro. Includi casi di test, output attesi o criteri di accettazione:

implementa validateEmail. casi di test:
  'user@example.com' -> true
  'invalid'           -> false
  'user@.com'         -> false
esegui i test dopo.

Esplora prima di implementare

Per problemi complessi, separa la ricerca dalla codifica. Passa alla modalità plan (Tab), fai studiare a Dropstone il codice pertinente, perfeziona il piano attraverso la conversazione, poi torna alla modalità build per eseguire:

leggi src/auth/ e spiega come gestiamo le sessioni oggi.
poi proponi un piano per aggiungere il supporto OAuth.

Rivedi il piano, opponi resistenza su qualsiasi cosa con cui non sei d'accordo, poi lascia che Dropstone implementi. Questo approccio in due fasi produce risultati costantemente migliori rispetto ad andare direttamente al codice.

Delega, non dettare

Tratta Dropstone come un collega capace. Dai contesto e direzione, poi fidati che l'agente capisca i dettagli:

il flusso di checkout è rotto per gli utenti con carte scadute.
il codice pertinente è in src/payments/.
investiga e correggilo.

Non devi specificare quali file leggere, quali comandi eseguire o in quale ordine fare le cose. Dropstone lo capisce dal prompt.

Cosa c'è dopo