Planning with Files è una skill per agenti di Ahmad Adi che conserva piano, risultati e avanzamento di un'attività nei file del progetto. Usala quando un lavoro di sviluppo o ricerca dura abbastanza da richiedere, in una nuova conversazione, la ricostruzione delle decisioni precedenti. I file offrono all'agente un registro da leggere e aggiornare; la loro utilità dipende dalla precisione con cui vengono mantenuti.
Il punto di partenza pratico sono tre file Markdown: task_plan.md, findings.md e progress.md. Assegna a ciascuno un ruolo distinto. Il piano indica che cosa resta da fare, i risultati spiegano che cosa si è appreso e il registro di avanzamento racconta ciò che è effettivamente successo. Ripetere lo stesso paragrafo in tutti e tre rende più difficile riprendere il lavoro.
Esempio fittizio di pianificazione Apple: i commenti citati e le percentuali hanno solo scopo illustrativo. Apri l'illustrazione a dimensione intera.
Installa la cartella completa della skill
La pagina Thrive della skill Planning with Files riporta la fonte dell'autore verificata. Installala nel progetto:
npx usethrive add planning-with-files --agent claudePer Codex, cambia --agent claude in --agent codex. L'installer copia la cartella completa della skill alla revisione indicata, compresi modelli e script. Lascia intatta un'installazione esistente, quindi esamina la copia installata prima di sostituirla.
Installare una skill e installare un plugin nell'ambiente dell'agente sono operazioni diverse. L'autore fornisce anche collegamenti per gli hook del ciclo di vita e il recupero delle attività. Copiare una cartella non registra automaticamente tutti gli hook dei plugin di ciascun ambiente. Se vuoi questi collegamenti, segui la documentazione di installazione dell'autore per l'agente e il sistema operativo che usi.
Tieni la skill installata separata dai file di pianificazione del progetto. La cartella installata contiene script e modelli riutilizzabili. La cartella dell'attività contiene i registri del lavoro in corso. La procedura attuale dell'autore può selezionare una cartella per l'attività: quando questa modalità è attiva, usa il suo inizializzatore e l'identificativo dell'attività riportato nell'output, senza presumere che tutte le attività scrivano nella radice del progetto.
Assegna a ogni file uno scopo utile
File | Che cosa inserire | Che cosa evitare |
|---|---|---|
| Obiettivo, fasi, criteri di accettazione e prossima azione | La trascrizione di ogni chiamata agli strumenti |
| Prove, link alle fonti, vincoli e motivi delle decisioni | Una conclusione priva di prove presentata come un fatto |
| Passaggi completati, risultati effettivi dei test ed errori irrisolti | Verifiche pianificate descritte come già completate |
Per una modifica breve, questi file possono richiedere più lavoro di quanto ne risparmino. Correggere un titolo raramente richiede un sistema per riprendere il lavoro. Una migrazione, una ricerca su più fonti o una funzionalità con diverse dipendenze si prestano meglio, perché l'azione successiva dipende dalle prove raccolte prima.
Esempio: pianificare una piccola migrazione di contenuti
Supponiamo che tu stia trasferendo un archivio di newsletter in un CMS. Devi mappare titoli, date, tag e corpo del testo senza pubblicare bozze private. Parti da un piano che definisca il risultato e le verifiche:
# Newsletter archive migration
## Objective
Import the approved public archive and preserve draft visibility.
## Phases
- [ ] Inventory source records and classify their visibility.
- [ ] Map source fields to the target content model.
- [ ] Import a small sample and check formatting.
- [ ] Import the approved remaining records.
- [ ] Verify counts, visibility, and representative links.
## Acceptance criteria
- Source and imported approved-record counts match.
- Draft records have no public snapshot.
- Sample links, headings, and publication dates are preserved.
## Next step
Inspect five representative source records before writing the mapper.L'esempio è un modello di pianificazione, non una dichiarazione che una migrazione sia stata completata. Sostituisci le verifiche con quelle richieste dai sistemi di origine e destinazione. Se una mappatura richiede una decisione di chi gestisce i contenuti, registra la dipendenza invece di lasciare che l'agente indovini.
In findings.md, spiega una decisione di mappatura con le prove a sostegno. Per esempio, «L'esportazione contiene published_at solo per le voci pubblicate; conserva il valore mancante per le bozze» è utile se lo hai osservato nell'esportazione. Registra il file esaminato e i campi pertinenti. Non scrivere questa conclusione solo perché sembra plausibile per un CMS.
In progress.md, registra il risultato effettivo del campione. «Importati cinque record; un video incorporato richiede una regola di conversione separata» indica alla sessione successiva che cosa resta da fare. «La migrazione sembra a posto» non fornisce informazioni sufficienti per proseguire in sicurezza.
Riprendi il lavoro dopo un azzeramento del contesto
Prima di modificare qualcosa, chiedi all'agente di leggere i tre file dell'attività selezionata e riportare la fase attuale, le decisioni irrisolte e la prossima azione. Confronta questa descrizione con il repository e gli eventuali sistemi esterni usati. Una casella spuntata in Markdown può essere obsoleta: l'agente dovrebbe verificare il file o il risultato pertinente prima di basarsi su di essa.
Se il piano dice che i test sono passati, il registro di avanzamento deve indicare il comando e il risultato. Se indica che un deploy è completo, conserva l'identificativo o l'URL del deploy. Non inserire segreti in questi file, soprattutto se il repository è condiviso. Registra i nomi delle credenziali e i requisiti di accesso anziché copiare i token.
L'autore include strumenti per recuperare le sessioni con modalità esplicite. Usa quella adatta all'attività e all'ambiente. L'accesso alla cartella di un progetto non autorizza a raccogliere registri di conversazioni locali estranei al compito. Spesso basta il piano del progetto per ripristinare il contesto utile dell'attività.
Evita piani obsoleti e modifiche in conflitto
Aggiorna il piano quando cambia una fase e formula il passo successivo con un verbo concreto: esaminare, confrontare, implementare o verificare. Un'istruzione vaga come «continua lo sviluppo» costringe una nuova sessione a ricostruire di nuovo la decisione.
Quando contribuiscono più agenti, assegna a uno solo la responsabilità del piano condiviso. Gli altri possono riferire tramite i file assegnati o i messaggi. Così è più facile conciliare un'attività completata con un errore appena scoperto. Agenti indipendenti che riscrivono lo stesso documento di stato possono nascondere per errore il lavoro degli altri.
Prima di chiudere l'attività, verifica il risultato rispetto ai criteri di accettazione. Lascia visibili gli elementi irrisolti. Planning with Files rende più continuo il lavoro dell'agente; il fatto che il suo script di completamento accetti un piano non ne dimostra la correttezza.
Che cosa provare per prima cosa
Installa la skill per un'attività che prevedi già di svolgere in più sessioni. Parti da un obiettivo breve, poche fasi e una prossima azione verificabile. Dopo la prima sessione, apri personalmente i file e controlla se un'altra persona potrebbe proseguire il lavoro da lì. Decisioni mancanti o stati vaghi mostrano che cosa migliorare prima che l'attività diventi più grande.
Per le procedure che producono anche note di ricerca, consulta la skill Obsidian Markdown. Tieni separati i registri di esecuzione del progetto e le note personali di riferimento quando hanno responsabili o requisiti di riservatezza diversi.
