FAQ
Domande frequenti
Risposte brevi alle domande più comuni su Deep Work Plan, ciascuna con un link alla pagina che approfondisce.
01
Che cos’è Deep Work Plan
Cosa fa esattamente Deep Work Plan?
Deep Work Plan trasforma un repository in un ambiente strutturato in cui un agente di coding può eseguire con affidabilità lavoro di lunga durata. Si installa come skill per agenti, fa l’onboarding del repository una sola volta (un indice `AGENTS.md`, un albero `docs/`, un kit `.agents/` di skill e comandi, un’area di output `.dwp/` esclusa da git) e da quel momento qualsiasi obiettivo diventa un piano: task atomici, ciascuno con criteri di accettazione e un validation gate, eseguiti uno alla volta, sottoposti a commit man mano che passano e ripristinabili da disco da qualsiasi agente. Il piano si chiude con un Final Review che verifica la sicurezza e valida lo stato finale. La metodologia è con licenza MIT e funziona con qualsiasi agente di coding che legge un repository.
A chi è destinato?
Sviluppatori e team che affidano lavoro reale e multi-step ad agenti di coding e vogliono che venga portato a termine. È adatto quando un’attività copre più di una sessione, più di una famiglia di file o più di un agente; quando un collega deve poter riprendere da dove un agente si è fermato; o quando “fatto” deve significare “validato”, non “lo dice l’agente”. Una correzione di una riga non ha bisogno di un piano, e la metodologia lo dice chiaramente: la sua regola di rigore proporzionale raccomanda al suo posto un obiettivo inline, con criteri e gate.
Qual è la differenza tra un piano Lite e uno Full?
Una scelta di rappresentazione, non un compromesso sul rigore. I piani sono Lite per impostazione predefinita: un README compatto con record di task ancorati che è già eseguibile, non una bozza parziale. Se si chiede un piano Full fin dall’inizio, `create` scrive direttamente i file di task Full; ed espande un piano a Full quando il dettaglio delle istruzioni, le dipendenze o i contratti di un task non rientrano più in un record compatto e revisionabile. La promozione successiva conserva ogni task completato. Entrambi i formati portano gli stessi criteri di accettazione, validation gate, evidenze e il Final Review obbligatorio.
È uno strumento, un framework o una metodologia?
Una metodologia distribuita come skill installabile. Non c’è server, né account, né formato proprietario, né runtime al di fuori dell’agente di coding che già utilizza. Ciò che viene installato sono istruzioni che l’agente legge, un piccolo insieme di script shell per il rilevamento del contesto e la verifica di conformità, e le convenzioni che il Suo repository adotta. Tutto ciò che il piano produce è Markdown e JSON nel Suo repository, leggibile senza alcuno strumento.
Con quali agenti di coding funziona?
Qualsiasi agente che legge i file del repository. La skill segue lo standard aperto Agent Skills e la convenzione `AGENTS.md`, quindi Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot e altri la acquisiscono attraverso il normale caricamento di skill e istruzioni. La valutazione interna della metodologia mostra un piano avviato dall’agente di un fornitore e ripreso da quello di un altro in entrambe le direzioni. La copertura di installazione e le evidenze comportamentali sono elencate per agente nella matrice di compatibilità, e le due non vengono mai confuse.
Come si usa?
Tre passaggi. Per prima cosa, installa la skill Deep Work Plan nel tuo agente di coding — la via più rapida è `npx skills add DailybotHQ/deepworkplan-skill` (oppure clona il repository della skill ed esegui `./setup.sh`). In secondo luogo, fai l’onboarding del repository una volta, così l’agente adatta `AGENTS.md`, `docs/`, il kit `.agents/` e un’area `.dwp/` ignorata da git al tuo stack: punta a https://deepworkplan.com/init.md, oppure esegui `/deepworkplan-onboard`. In terzo luogo, pianifica ed esegui il lavoro con i comandi leggeri: `/dwp-create <goal>` costruisce un piano; `/dwp-execute` lo esegue task per task contro ogni gate; `/dwp-refine` modifica un piano in corso (ambito, task, o la promozione di un piano Lite a Full); `/dwp-resume` continua dopo un’interruzione; `/dwp-status` riporta l’avanzamento senza eseguire; `/dwp-verify` produce un rapporto oggettivo di conformità; `/dwp-upgrade` sposta una skill installata a una versione più recente senza toccare i piani esistenti. Gli agenti che intercettano `/` usano spesso `#` invece (per esempio `#dwp-execute`). Il punto di adozione e l’avvio rapido percorrono lo stesso cammino con più dettaglio.
Cosa viene installato esattamente, e dove?
La skill dell’agente viene installata ovunque il Suo agente carichi le skill di progetto o utente. L’onboarding adatta poi il repository stesso: crea o riconcilia `AGENTS.md`, `docs/`, `.agents/` e l’area di lavoro `.dwp/` esclusa da git. La skill insegna il metodo all’agente; il repository conserva il contesto, il kit e le evidenze del piano di cui gli altri agenti hanno bisogno per proseguire.
Deep Work Plan richiede Git?
Git è consigliato per i repository perché la sua cronologia fa parte della superficie di recupero e revisione, ma la metodologia può funzionare anche in uno spazio di lavoro dell’agente senza un repository Git. In tal caso è richiesto lo strato di stato leggibile dalle macchine, inclusi i checkpoint di `state.json` e i record dei gate, così il recupero non dipende da una trascrizione della chat.
Qual è la differenza tra una skill, un piano e una specifica di prodotto?
Una skill descrive come un agente esegue una procedura ripetibile. Un piano DWP descrive una modifica concreta attraverso ambito, criteri di accettazione, validation gate ed evidenze. Una specifica di prodotto descrive il comportamento attuale del prodotto ed evolve tramite delta dopo l’implementazione; anche le skill e i piani sono specifiche, ma descrivono procedure e modifiche anziché mantenere quel contratto di prodotto canonico.
02
Come viene eseguito un piano
Come sono implementati i validation gate? Richiedono un’approvazione umana?
Sono asserzioni eseguibili che l’agente esegue da sé. L’approvazione umana delimita l’esecuzione all’inizio e alla fine: una persona approva il piano prima dell’esecuzione e rivede il diff finale in fase di pull request; l’esecuzione nel mezzo è autonoma. Ogni task indica comandi concreti, in genere il quality gate del repository stesso, selezionati dalla superficie toccata dal task: i test del comportamento modificato e dei suoi consumer, ampliati alla suite completa quando la modifica è condivisa o non delimitabile. Un task viene marcato come fatto solo quando quei comandi terminano con successo, e i task che modificano il comportamento devono estendere i test. In caso di fallimento l’agente ripara prima ciò che ricade nell’ambito proprio della task e riesegue il gate; un fallimento non riparabile in quell’ambito lascia il task marcato come bloccato e ferma l’esecuzione.
Come evita il piano di diventare obsoleto quando il codice viene modificato tra un’esecuzione e l’altra?
Su tre fronti. I task sono scritti come comportamento, non come modifiche: un criterio di accettazione dice cosa il sistema deve fare, quindi un file rinominato o un’implementazione sostituita non lo invalida. Ogni gate viene rieseguito sul repository così com’è in quel momento, quindi un’assunzione non più valida fallisce rumorosamente all’esecuzione successiva invece di derivare in silenzio, e quel fallimento è l’indicazione per rifinire. E mantenere la documentazione sincronizzata è parte del lavoro: un task che modifica il comportamento aggiorna anche i documenti e il kit agent-facing che lo descrivono, dentro il proprio gate. Ogni esecuzione dovrebbe lasciare il repository più pronto per gli agenti di come lo ha trovato.
Posso modificare il piano durante l’esecuzione senza perdere il lavoro completato?
Sì; rifinire un piano eseguito parzialmente è un’operazione di prima classe. Le definizioni dei task e lo stato di esecuzione sono tenute separate: il piano è una checklist su disco più un piccolo file di stato, quindi ciò che è fatto resta registrato in modo indipendente dal testo dei task. Quando un task si rivela sbagliato, l’agente lo marca come bloccato e si ferma invece di insistere. Lei può allora modificare, riordinare, dividere o eliminare i task non ancora eseguiti, mentre i task completati restano completati. La ripresa ricostruisce lo stato dal disco e dal repository reale e riesegue i gate che contano, così nulla di ciò che è cambiato sotto passa inosservato.
Il lavoro viene controllato continuamente rispetto al piano, oppure il piano è solo qualcosa di definito all’inizio?
Il piano è un controllo continuo. L’agente lavora un piccolo task alla volta e deve validare prima di proseguire, quindi può deviare di un passo, non di tre. Ogni task porta criteri di accettazione più i comandi esatti che li provano, e i progressi vengono scritti nel repository man mano, con uno stato per task, così la deriva diventa visibile a Lei, alla prossima sessione e al prossimo agente. Un piano non è finito finché tutto non valida, Final Review compreso. L’avvertenza onesta: la metodologia non può impedire a un agente di scrivere in partenza un criterio di accettazione debole; rende la deriva rumorosa invece che silenziosa.
Il piano viene generato una volta e mantenuto a mano, o evolve con il codice?
Né l’uno né l’altro. Viene generato una volta a partire da un obiettivo e poi mantenuto come parte del lavoro. Il piano non viene deliberatamente riscritto a partire dai diff del codice, perché una specifica che insegue il codice diventa uno specchio in ritardo, che è proprio la deriva che la metodologia esiste per eliminare. Evolve di proposito: i gate vengono rieseguiti sul repository attuale, un gate che fallisce innesca una rifinitura e l’agente esegue quella rifinitura durante l’esecuzione, mentre Lei approva in anticipo e rivede alla fine. Documentazione e test evolvono insieme al codice per costruzione, perché aggiornarli è dentro il gate di ogni task.
Cosa succede se la sessione si interrompe a metà?
I progressi vivono su disco, non nella chat. Le checkbox del README, il log di ogni task, un indice di lavoro delimitato e un file di stato leggibile dalle macchine vengono aggiornati a ogni confine di task, e il file di stato registra un checkpoint prima di ogni pausa pianificata. Una sessione nuova, o un agente diverso, legge quell’indice compatto, lo riconcilia con il repository e la cronologia di git e prosegue dal primo task incompleto senza rifare il lavoro concluso. Anche una creazione del piano interrotta è recuperabile: l’identità del piano e l’elenco dei task previsti vengono scritti prima di qualsiasi file di task, quindi un piano creato a metà può essere completato o scartato anziché dover essere intuito.
Che cos’è il Final Review?
L’unico task di chiusura obbligatorio di ogni piano. In ordine: un passaggio di sicurezza sull’intero insieme di modifiche accumulato dal piano, inclusa una revisione locale obbligatoria del diff da parte della skill AI Diff Reviewer, con i rilievi critical che bloccano il completamento finché non vengono corretti o accettati esplicitamente; la validazione dello stato finale, ossia le suite complete applicabili di test, lint, type-check e format del repository sul codice finale; e la riconciliazione delle decisioni sulle skill registrate da ogni task. L’agente riporta poi deliverable, evidenze e limitazioni, e offre un Executive Report una sola volta, generandolo solo su richiesta.
Cosa succede quando un validation gate fallisce?
Un gate fallito è prima di tutto un segnale di riparazione: l’agente corregge ciò che ricade nell’ambito proprio della task e riesegue il gate. Un fallimento che eccede quell’ambito lascia il task registrato come bloccato, e l’agente si ferma prima di dichiarare il completamento. Lei può ispezionare le evidenze, riparare il codice o rifinire il task, quindi riprendere; un comando fallito è un segnale per risolvere la discrepanza, non un permesso per indebolire il gate.
Cosa succede quando il verificatore di conformità non può eseguire i suoi controlli?
Lo dice chiaramente. Il verificatore termina con codice di uscita 2 e un verdetto `UNVERIFIED` esplicito — non stampa mai un esito positivo che non abbia effettivamente verificato. Se l’ambiente manca di un interprete capace o un controllo non può girare, l’esito onesto è «non verificato», non «conforme»; un risultato verde significa sempre che ogni controllo è stato eseguito ed è passato. La stessa disciplina attraversa tutta la metodologia: nessun flusso indebolisce o falsifica un gate per dichiarare il lavoro completato.
Un piano può essere eseguito senza supervisione, di notte o in CI?
Sì, quando il piano è stato approvato in anticipo, porta lo strato di stato richiesto e conferisce all’agente un’autorità delimitata. Un’esecuzione senza supervisione deve fermarsi e registrare un blocco quando la realtà diverge, un gate fallisce al di fuori del suo ambito di riparazione pianificato, oppure serve una nuova approvazione o una credenziale.
03
Come si confronta
Un piano può estendersi su più repository?
Sì — l’archetipo dell’hub orchestratore esiste esattamente per questo. Un repository hub tiene il piano che coordina, e ogni repository figlio esegue il proprio piano dentro la propria area `.dwp/` isolata, quindi un figlio non scrive mai nello stato dei piani dell’hub. Il completamento del figlio si legge dallo stato di livello superiore del piano stesso, non cercando stringhe al suo interno, e l’hub registra dove si trova prima di navigare da qualsiasi parte. Ogni figlio resta un repository DWP ordinario, che può essere pilotato anche da solo.
In cosa differisce dagli strumenti spec-driven come Spec Kit, OpenSpec o Kiro?
Risolvono problemi adiacenti. Gli strumenti spec-driven sono eccellenti nel catturare cosa dovrebbe cambiare: specifiche, requisiti e proposte di modifica in una forma ripetibile. Deep Work Plan riguarda come un agente esegue per ore senza derivare: la harness installata dall’onboarding, i validation gate per task selezionati dalla superficie toccata, lo stato ripristinabile su disco, un Final Review obbligatorio con passaggio di sicurezza e un verificatore di conformità per il repository stesso. I due si possono combinare, con una specifica o una proposta di modifica che alimenta un piano. La pagina di confronto mette le capacità fianco a fianco, nei termini di ciascuno strumento.
In cosa differisce da strumenti di workflow per agenti come BMAD, Superpowers, Get Shit Done o Gentle-AI?
I framework di workflow per agenti come BMAD, Superpowers e Get Shit Done portano stili di lavoro solidi: ruoli, principi, passaggi test-first, abitudini di verifica. Gentle-AI si colloca in una categoria affine, come configuratore dell'ecosistema di agenti: equipaggia gli agenti di codice che già usi con memoria persistente tra le sessioni (Engram), skill curate, persona, server MCP, Spec-Driven Development opzionale e revisione opzionale basata su evidenze (Receipt-Driven Development), scrivendo nelle directory di configurazione di ciascun agente. Deep Work Plan si differenzia da entrambi: si concentra su ciò che resta nel repository e su ciò che può essere verificato — un harness che qualsiasi agente legge a freddo, file di task con criteri di accettazione e gate, stato che sopravvive a una sessione, un verificatore di conformità con un codice di uscita adatto alla CI e una misurazione pubblicata di quanti byte di istruzioni carica ciascun flusso. È agnostico rispetto allo strumento per costruzione e non aggiunge alcun servizio, provider o segreto al ciclo principale. I livelli possono coesistere: i framework e Gentle-AI plasmano il modo in cui l'agente lavora; Deep Work Plan rende il lavoro lungo duraturo e verificabile all'interno del repository. La pagina di confronto mostra dove ciascun approccio è integrato, opzionale o fuori ambito.
Perché non usare semplicemente la modalità plan integrata nel mio agente?
Le modalità plan integrate sono utili e Deep Work Plan si basa sullo stesso substrato, la convenzione `AGENTS.md` e lo standard aperto Agent Skills. La differenza è dove vive il piano e cosa lo fa rispettare. I piani nativi in genere vivono fuori dal repository e scadono con la sessione; Deep Work Plan scrive il piano, il suo stato e le sue evidenze nel repository, quindi un altro agente o un collega può proseguirlo, e ogni task porta un gate eseguibile e un log registrato. Lei continua a usare la modalità plan del Suo agente per riflettere; la metodologia aggiunge il ciclo di esecuzione duraturo e verificabile.
04
Adottarlo
Cosa scrive l’onboarding nel mio repository e tocca i file esistenti?
L’onboarding è non distruttivo: rileva un `AGENTS.md`, un `docs/`, un `.agents/` o un `CLAUDE.md` esistente, riconcilia anziché sovrascrivere e chiede prima di sostituire qualsiasi cosa. Scrive l’indice `AGENTS.md` con i comandi reali, un albero `docs/` ragionato, documentazione per modulo, il kit `.agents/` con i sottili comandi `dwp-*`, un’area di output `.dwp/` esclusa da git, una mappa dei test verificata e la revisione locale del codice obbligatoria (la skill AI Diff Reviewer più un’estensione di revisione adattata al repository). Esegue poi un self-check e il verificatore di conformità, così può vedere cosa è stato prodotto. Un repository sottoposto a onboarding con uno standard precedente riceve un aggiornamento mirato dell’harness che riconcilia solo ciò che manca o è obsoleto.
Come aggiorno la skill in un repository già sottoposto a onboarding?
Sono due aggiornamenti diversi, e il flusso li tiene separati. L’harness del repository — `AGENTS.md`, `docs/`, il kit `.agents/` — si riconcilia rieseguendo l’onboarding, che colma solo ciò che manca o è obsoleto. La skill stessa avanza con `/dwp-upgrade`: un controllo in sola lettura dell’ultima versione pubblicata, l’installazione del tag esatto che hai accettato, verificata, e poi l’onboarding di nuovo come una passata fresca. Il flusso è subordinato al consenso esplicito in ogni passo, le adattazioni locali vengono confrontate e preservate invece di sovrascritte, e `.dwp/` non viene mai migrato — i piani esistenti mantengono la loro forma registrata e continuano a girare.
Posso usare la metodologia core senza installare gli add-on?
Sì. Gli add-on sono livelli opzionali e un repository senza nessuno di essi è pienamente conforme a DWP. I devcontainer, la rendicontazione Dailybot, gli aggiornamenti delle dipendenze, il supporto al design system e la revisione CI opzionale vengono offerti solo quando si adattano al Suo repository e Lei li accetta esplicitamente.
Cosa succede se il mio repository non ha ancora test o linting?
DWP non tratta l’assenza di una toolchain come un lasciapassare. Durante l’onboarding l’agente propone una configurazione di validazione adeguata allo stack, registra i comandi nella documentazione del repository e usa quei comandi come obiettivo per i gate futuri; la proposta resta visibile perché Lei la riveda.
Quanto costa e come si misura l’efficienza?
La metodologia e la skill sono con licenza MIT e gratuite; nei flussi principali non c’è servizio, né chiave API, né telemetria. L’efficienza è riportata come numero di byte di istruzioni caricati da ogni flusso **all’ingresso** — il suo pacchetto all’avvio di una sessione — pubblicato insieme a **percorsi end-to-end** nominati che aggiungono ciò che i trigger reali del flusso caricano quando il lavoro prosegue davvero (per esempio, una ripresa che prosegue fino all’esecuzione carica in genere diverse volte il proprio pacchetto d’ingresso). Nessuna delle due cifre limita una sessione: un’esecuzione reale legge anche i file del repository, l’output degli strumenti e i file di lavoro del piano, nessuno dei quali è conteggiato in questo registro. Entrambi i numeri sono misurati da uno script sottoposto a commit insieme alla skill, rimisurato su ogni baseline di rilascio e pubblicato in un registro di valutazione, con gli aumenti riportati con la stessa evidenza delle diminuzioni. Non è riportata come percentuali di token o risparmi, perché un inventario di byte non li stabilisce. Una valutazione pubblica con agenti freschi è ormai stata eseguita sotto un protocollo congelato: le stesse due funzionalità costruite da clone puliti senza harness, con la versione maggiore precedente e con quella attuale. Ha rilevato che gli agenti su un albero con harness leggevano meno byte in entrambi i task e che le sessioni di funzionalità della versione attuale consumavano meno input e output di modello di quelle della versione maggiore precedente in entrambi i task — come riportato dall’harness, su un singolo carico di lavoro. Ha anche rilevato i limiti onesti: l’onboarding è un costo una tantum che si ripaga solo quando i flussi vengono usati, la direzione netta dei token per carico di lavoro è stata mista, non si rivendica alcun vantaggio di tempo di clock e un agente fresco non entra nei flussi da solo — i flussi sono comandi che invocate voi o un agente che sa chiamarli.
Ha ancora una domanda?
Ha ancora una domanda?
Apra una discussione o una issue su GitHub. Le domande che ricorrono vengono aggiunte a questa pagina.