Tutorial: Aider con DeepSeek Coder via OpenRouter per refactor su branch dedicato

Piccole e Medie Imprese

Team di sviluppo di PMI che affrontano refactor su codice esistente e cercano strumenti con tracciabilità git integrata.

Scopri →

Note preliminari

Contenuto fornito “as-is”. Prima dell’uso su codice reale:

• Lavorate su un branch dedicato, mai direttamente su main.
• Backup (o push remoto) del branch di partenza prima di avviare la sessione.
• Non inserite secrets nei prompt, nei file di config o nei messaggi di commit generati.
• Se usate un provider cloud (OpenRouter, Anthropic, OpenAI), il contenuto dei file aperti viene trasmesso. Per codice sotto NDA preferite un endpoint locale (Ollama) o un accordo contrattuale verificato con il provider.
• La suite di test del progetto deve essere eseguibile e idealmente affidabile: è la principale difesa contro refactor “plausibili” ma incorretti.

Aider + DeepSeek Coder: perché

Aider (aider.chat) — CLI Python per AI pair programming di Paul Gauthier, prima release su PyPI (v0.10.0) il 22 luglio 2023, Apache 2.0 — è tra i pochi strumenti che trasformano ogni interazione con il modello in un commit git. Questa scelta ha una conseguenza pratica diretta: la cronologia git di una sessione Aider è un audit trail completo del lavoro dell’agente, e git revert basta a tornare indietro su qualsiasi singolo passo.

A metà 2024, DeepSeek pubblica DeepSeek Coder V2: un modello focalizzato sul code editing, con prestazioni competitive sui benchmark di refactoring della stessa Aider Leaderboard, a costo sensibilmente inferiore rispetto ai modelli frontier generalisti. La combinazione Aider + DeepSeek Coder V2 via OpenRouter è un compromesso utile per PMI che vogliono integrare AI nel workflow di refactor senza subire il costo di un modello frontier su ogni iterazione.

Caso d’uso: estrarre un modulo di validazione in un’app Flask

Scenario: un’app Flask di media complessità ha la logica di validazione degli input sparsa in tre blueprint (orders, invoices, customers). Vogliamo estrarla in un modulo validators/ con funzioni testate, senza cambiare il comportamento osservabile.

1. Branch dedicato e suite di test verde

cd ~/progetti/appX
git checkout -b refactor/validators
pytest                     # deve essere verde prima di iniziare
git log --oneline -5       # ancoraggio per il revert in caso di disastro

Se i test falliscono già prima dell’avvio, fermatevi: Aider non serve a risolvere test rotti, e un refactor su codice non testato è un salto al buio.

2. Installazione di Aider

python3 -m venv ~/.venvs/aider
source ~/.venvs/aider/bin/activate
pip install aider-chat
aider --version

3. Chiave OpenRouter in env

OpenRouter (openrouter.ai) fa da router verso molti modelli con un’unica API. La chiave viene letta dalla env; non inseritela in file committati.

read -rs OPENROUTER_API_KEY && export OPENROUTER_API_KEY
# Variante con chiave in $HOME/.config/ (solo se la macchina non è condivisa):
#   echo "OPENROUTER_API_KEY=..." > ~/.config/aider.env
#   chmod 600 ~/.config/aider.env

4. Avvio con DeepSeek Coder via OpenRouter

aider \
  --model openrouter/deepseek/deepseek-coder-v2 \
  --auto-commits \
  --no-stream \
  src/blueprints/orders.py \
  src/blueprints/invoices.py \
  src/blueprints/customers.py

Note:

• Solo i file rilevanti sono passati all’agente: limita il contesto e il blast radius.
• --auto-commits crea un commit per ogni modifica accettata. I messaggi sono generati da Aider; controllateli e riformulateli se servono in forma più aziendale.
• --no-stream rende l’output più leggibile su terminale condiviso o registrato.

5. Prompt di refactor

Nel REPL di Aider:

“Estrai tutte le funzioni di validazione input (i decoratori @validate_* e le funzioni di supporto) dai tre blueprint in un modulo src/validators/__init__.py con funzioni pure. I blueprint devono continuare a usarle via import. Non cambiare i messaggi di errore restituiti. Aggiungi test in tests/test_validators.py.”

Aider propone modifiche multiple (può creare il modulo, aggiornare i blueprint, aggiungere test). Ogni modifica approvata diventa un commit con diff visibile. Per operazioni rischiose, chiedete esplicitamente solo il diff senza applicare:

“Prima di scrivere, mostrami i diff proposti. Non applicare nulla.”

6. Verifica continua con i test

Dopo ogni commit, eseguire:

pytest tests/

Se un test fallisce, l’ordine consigliato è:

1. git log --oneline → ultimo commit dell’agente.
2. Leggere il diff: git show HEAD.
3. Revert o fix mirato: git revert HEAD (ripulisce) o fix manuale con commit successivo.

7. Merge e pulizia

Quando il refactor è completo:

pytest                     # verde
git log --oneline main..HEAD  # lista commit dell'agente, da revisionare
git rebase -i main        # facoltativo: squash o riscrittura messaggi
git checkout main
git merge --no-ff refactor/validators

La presenza di molti commit “minimali” dell’agente è normale. Uno squash in rebase interattivo o un merge --squash sono entrambe opzioni legittime: la scelta dipende dalla vostra policy sulla cronologia.

Limiti e avvertenze

• Il modello può “rompere silenziosamente” comportamenti non coperti da test: se una funzione non ha test che catturano un effetto secondario (es. un log, una metrica), l’agente può cambiarlo senza rendersene conto. La copertura dei test è il limite pratico del refactor sicuro.
• Il repo map non è magico: Aider costruisce una rappresentazione sintetica del repo con tree-sitter. Su codice molto dinamico (metaprogrammazione Python, dispatcher a runtime) l’agente può ignorare dipendenze non statiche. Verificate sempre a mano gli impatti non ovvi.
• Auto-commits vs review: l’auto-commit è una comodità, non un’autorizzazione a fidarsi. Il fatto che una modifica sia committata non ne certifica la correttezza: resta necessaria la PR review.
• Costi token con modelli frontier: se passate a un modello frontier per task complessi, una singola sessione di refactor può costare in token quanto un’ora-uomo. Monitorate il consumo (OpenRouter espone dashboard per credito residuo).

Link: aider.chat — openrouter.ai — github.com/paul-gauthier/aider

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