Tutorial: Plandex per refactor multi-file con plan-then-apply

Studi Professionali & Consulenti

Consulenti e studi IT che intervengono su basi di codice legacy di clienti e hanno bisogno di strumenti che rendano ogni modifica reversibile e ispezionabile.

Scopri →

Note preliminari

Contenuto fornito “as-is”. Prima dell’uso in produzione:

• Lavorate su una copia o su un branch dedicato del repo.
• Backup prima di ogni sessione: anche se Plandex mantiene una propria sandbox dei cambiamenti, un errore di workflow può portare ad applicare diff non desiderati.
• Non inserite secrets nei prompt o nei file di configurazione. Plandex spedisce contesto al provider LLM configurato.
• Per codice sotto NDA o dati regolati, preferite un endpoint LLM locale o privato.
• Plandex è un progetto in evoluzione: sintassi dei comandi (new, tell, apply, diff) può cambiare tra versioni. Verificate la documentazione installata.

Cosa è Plandex

Plandex (plandex.ai, github.com/plandex-ai/plandex) è un agent da terminale per code editing multi-file rilasciato come open source nel 2024. La caratteristica distintiva rispetto ad Aider o ad altri pair-programming tool è il modello plan-then-apply: le modifiche proposte dall’agente non toccano il working tree immediatamente; vengono accumulate in un plan separato, ispezionabile via plandex diff, e scritte su disco solo dopo un plandex apply esplicito.

Operativamente questo significa che l’agente può iterare su decine di file di un piano (ad esempio estrarre un modulo attraversando 40 file di un monolite) senza mai lasciare il repo in uno stato intermedio incoerente. Per consulenti che intervengono su codice di terzi è un tratto di sicurezza utile.

Caso d’uso: migrazione naming da camelCase a snake_case in libreria Python legacy

Scenario: una libreria Python interna è stata scritta storicamente con funzioni in camelCase — in contrasto con PEP 8 e con la convenzione adottata dai nuovi moduli del cliente. Vogliamo rinominarle in snake_case e aggiornare ogni chiamata, su una cinquantina di file, mantenendo retrocompatibilità via alias deprecati.

1. Preparazione

cd ~/progetti/cliente/libX
git checkout -b refactor/snake_case
python -m pytest           # baseline verde

2. Installazione di Plandex

# Binario ufficiale (Go):
curl -sL https://plandex.ai/install.sh | bash
plandex --version

# Provider cloud o locale: usate la configurazione che preferite.
# Esempio via env (evita di committare chiavi):
read -rs OPENROUTER_API_KEY && export OPENROUTER_API_KEY

3. Nuovo plan nel working tree

plandex new
# Plandex crea uno stato associato alla directory corrente.
# Il working tree git resta intatto.

4. Fornire contesto mirato

Plandex usa un meccanismo di contesto esplicito: dichiarate quali file sono rilevanti per il plan. Evitare di caricare tutto il repo tiene bassi costi e rumore.

plandex load src/libX/*.py tests/*.py
plandex ls                  # verifica cosa è nel contesto

5. Istruzione al plan

plandex tell "Rinomina tutte le funzioni pubbliche da camelCase a snake_case. \
Aggiorna ogni chiamata dentro src/libX/ e tests/. \
Mantieni un alias deprecato con DeprecationWarning per ogni nome precedente. \
Non toccare le docstring. \
Procedi file per file."

Plandex avvia il modello e inizia a produrre modifiche. Le modifiche finiscono nella sandbox del plan, non sul disco. Durante l’esecuzione potete:

plandex diff                # vedere i diff accumulati
plandex diff src/libX/core.py   # solo un file
plandex log                 # i passi del plan

6. Revisione e rollback per-task

Se un passo produce un diff non corretto, si può rollback selettivo senza perdere il resto del plan:

plandex log
# output tipo:
#   [step 7]  aggiornamento test_core.py
#   [step 8]  aggiornamento core.py
plandex rewind 7            # annulla step 7 e successivi, tieni 1..6

Questo è il tratto più utile di Plandex in un contesto di consulenza: se lo step 12 introduce un errore, non buttate via gli 11 passi precedenti approvati.

7. Applicazione finale

Quando la sandbox è coerente:

plandex diff                 # revisione completa
plandex apply                # scrive sul working tree git
pytest                       # verifica regressioni
git status
git add -p                   # stage granulare, non tutto in blocco
git commit -m "refactor: migrate public API to snake_case with deprecated aliases"

Se i test falliscono, l’istanza git è comunque recuperabile con git restore perché lo stage selettivo ha limitato cosa è entrato nell’index.

Limiti e avvertenze

• Il plan non è un sostituto di un branch git: alla fine plandex apply riversa i cambiamenti sul working tree. Lavorare su un branch dedicato resta la rete di sicurezza principale.
• Il contesto caricato influenza fortemente la qualità: se load è troppo ristretto, l’agente rinominerà funzioni in un file ignorando chiamate in altri moduli. Se è troppo esteso, esplodono costi e rumore. Il punto di equilibrio dipende dal refactor.
• Il modello può inventare nomi non presenti: su codebase con metaprogrammazione pesante (getattr dinamico, factory string-based) un puro refactor di rinomina può sfuggire. I test di regressione sono la verifica obbligata.
• Costi token su plan lunghi: 50 file in un plan significa molte chiamate al modello. Monitorate il consumo, spezzate in plan più piccoli quando possibile, e per task ripetitivi valutate l’uso di modelli più economici (DeepSeek Coder, CodeLlama locale).
• Usare plan paralleli con attenzione: Plandex supporta plan multipli nella stessa directory. Lavorare su due plan concorrenti su stesse aree del codice produce conflitti — comportatevi come fareste con branch git incrociati.

Link: plandex.ai — github.com/plandex-ai/plandex

Stefano Noferi — Founder e CEO/CTO di noze
Tech Entrepreneur — AI Governance & Security Architect