Plan-on-roids: il mio agente Copilot per pianificare scrupolsamente

Ho costruito un agente GitHub Copilot personale che ha un unico obiettivo: non lasciarmi implementare nulla finché il piano non è solido.

Link GitHub: mfse-plan-on-roids.agent.md

Si chiama mfse-plan-on-roids (plan sotto steroidi) perché potenzia l’agent “Plan” di GitHub Copilot con un processo di domande più meticoloso finché il modello non ritiene di avere abbastanza informazioni per produrre un piano strutturato e affidabile.

Il problema che volevo risolvere

Quando si usa un coding agent, la tentazione è sempre la stessa: dare un’idea vaga e aspettarsi che l’agente si arrangi. Questo sarebbe hope-vibe-coding. Ma quando il task è complesso il rischio che l’agente prenda la tangente per una direzione che non vogliamo è alta.

Il vero problema non è l’agente (si sa che si comportano così): è non investire abbastanza in un piano ben specifico.

Plan due volte, implementa una volta: ci ho scritto un articolo sopra, ma trasformarlo in abitudine richiede uno strumento che mi obblighi a farlo.

Come funziona

L’agente segue tre fasi obbligatorie, nell’ordine. Non si salta niente.

1. Interview

Fa domande. Una alla volta. Non tutte insieme, non in modo generico: domande mirate, con la risposta consigliata già inclusa, per non bloccarsi su falsi dilemmi.

Ogni ramo della decisione viene esplorato fino in fondo. Se può risolvere una domanda guardando la codebase — struttura dei file, pattern esistenti, dipendenze — lo fa in autonomia delegando all’agente Explore, senza disturbarmi.

La fase di intervista non finisce finché non ci sono ambiguità aperte.

2. Design

Solo quando l’intervista è completata, l’agente produce un piano strutturato. Non una lista generica: include dipendenze esplicite tra i passi, indica quali attività possono correre in parallelo e quali invece bloccano le successive, elenca i file critici da modificare, e definisce i passi di verifica — sia automatici che manuali.

Il piano viene salvato in /memories/session/plan.md per persistere durante la conversazione, ma viene anche mostrato direttamente in chat. Il file è solo un backup: il piano lo vedo io.

3. Finalize

L’agente non si dichiara soddisfatto da solo. La fase di finalizzazione include le domande ancora aperte e le assunzioni prese. Se ci sono nodi irrisolti, si torna indietro alla fase di intervista.

Come l’ho strutturato

L’agente è un file .agent.md con frontmatter YAML. Definisce i tool disponibili, i sub-agenti che può invocare, e due possibili handoff al termine:

• Implement — passa il controllo all’agente di implementazione
• Write plan to file — salva il piano su file per usarlo in una sessione successiva

I tool a disposizione sono volutamente limitati: memoria, domande all’utente, ricerca, lettura di file, e la possibilità di lanciare sub-agenti. Nessun tool di scrittura: l’agente non può toccare il codice, solo pianificare.

name: mfse-plan-on-roids
tools: [vscode/memory, vscode/askQuestions, vscode/toolSearch, read, agent, search]
agents: ['Explore']
handoffs:
  - label: Implement
    agent: agent
    prompt: Start implementation
    send: false
  - label: Write plan to file
    agent: agent
    prompt: Write plan to file for later use
    send: true

Perché funziona

La cosa più utile non è l’agente in sé: è il vincolo che impone.

Avere uno strumento che ti dice esplicitamente “non si va avanti finché il piano non è chiaro” cambia il comportamento.

Ho già scritto di quanto il contesto sia determinante per la qualità dell’output di un coding agent: Context is king. Un piano solido è una forma strutturata di contesto. Meno ambiguità nel piano, meno sorprese nell’implementazione.

In aggiunta, il fatto che le domande vengano poste una alla volta — con una risposta consigliata — elimina la paralisi da scelta. Non mi trovo davanti a una lista di dilemmi tutti insieme: risolvo un nodo alla volta, con una direzione già suggerita da valutare.

Quando lo uso

Non lo uso sempre. Per task piccoli e ben definiti è overkill. Lo uso quando il task è complesso, quando non ho idee chiarissime, quando ci sono dipendenze non ovvie, o quando ho la sensazione che “implementare subito” sarebbe un errore.

In pratica: ogni volta che la mia istintiva voglia di fare prevale sulla prudenza, apro mfse-plan-on-roids e lascio che mi interroghi.

Altro

Se vuoi approfondire come costruire agenti personalizzati per Copilot, parti da Scrivere un buon AGENTS.md e da Come usare i sub-agenti nel modo giusto.