Code-reviewer skill: gate post-write nel commit workflow

Code review fatto dall'LLM ha una reputazione mediocre: o è troppo verboso (commenta tutto, inclusi i micro-style), o troppo permissivo (approva quasi sempre). La skill code-reviewer di Superpowers risolve entrambi i problemi con due meccanismi: una classificazione di severità a quattro livelli e l'attivazione automatica post-write, sul diff appena prodotto, prima del commit.

Disclaimer di indipendenza: non sono affiliato a obra né ad Anthropic. Uso code-reviewer come gate pre-commit sul mio portfolio da otto mesi. Quanto leggi è quel che funziona davvero per me; ymmv.

Il problema con code review LLM "su richiesta"

Senza skill, una sessione tipica di review LLM si svolge così:

1. Scrivi codice (anche con AI).
2. Apri PR.
3. Chiedi al modello "review this PR".
4. Ricevi un commento per ogni piccola cosa: nomi variabili, indent, sezione mancante nel commento.

Risultato: noise. Il review umano successivo deve filtrare il noise per trovare i veri problemi. Net effect: il review LLM ti ha rubato dieci minuti senza darti valore.

La skill code-reviewer attacca due problemi separati: quando attivarsi (subito dopo write, non a PR) e cosa segnalare (issue classificate per severità, non tutto indiscriminatamente).

La classificazione a quattro livelli

La skill istruisce a usare quattro categorie esplicite:

• CRITICAL - bug certi che producono dati errati o crash, vulnerabilità di sicurezza note, secret in codice, regressioni funzionali. Esempio: SQL injection, hardcoded API key, validation bypassata. Blocca commit.
• HIGH - comportamenti dannosi probabili in produzione: race condition, error handling mancante in flow critico, performance regression misurabile, memory leak. Esempio: fetch senza try/catch nel pagamento. Richiede fix prima del merge.
• MEDIUM - qualità subottimale che peggiora la manutenibilità: naming poco chiaro, duplicazione di logica, mancanza test per business logic, accoppiamento eccessivo. Richiede fix se possibile, accept se costo alto.
• LOW - style preferences, micro-ottimizzazione, commento mancante in helper privato. Suggestion, non blocker.

L'output della skill è un report strutturato con conteggio per categoria e issue dettagliate. Esempio illustrativo:

## Code Review Report

CRITICAL: 0
HIGH: 1
MEDIUM: 3
LOW: 5

### HIGH-1 (file: src/payment/checkout.ts:42)
Missing error handling on stripe.charges.create - failed payment
could leak transient error to user as 500. Wrap in try/catch with
specific error mapping (CardError -> 4xx, NetworkError -> 503).

### MEDIUM-1 (file: src/payment/checkout.ts:67)
Duplicate validation logic with src/payment/refund.ts. Extract to
shared validatePaymentMethod() helper.

[... resto issue ...]

Attivazione automatica post-write

La parte che cambia di più il workflow non è la qualità del review (che pure è migliore), è il quando. La skill istruisce il modello a invocarsi automaticamente dopo aver scritto o modificato codice, prima del commit. Non aspetta il PR, non aspetta che chi lo chieda.

Workflow tipico con skill attiva:

1. Tu: "Implementa la feature X."
2. Modello: scrive codice in N file.
3. Modello (skill auto-invocata): "Code review report sul diff appena prodotto. CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 0."
4. Modello: discute la issue HIGH e propone fix.
5. Tu approvi il fix, modello applica.
6. Modello (skill re-invocata): re-review post-fix. HIGH: 0.
7. Commit.

Cost di una review post-write tipica: 10-20k token (sul diff). Tempo di latenza aggiunto al commit: 30-90 secondi. Vantaggio: il PR che apri non ha più issue HIGH/CRITICAL ovvie. Il review umano si concentra su ciò che la skill non può catturare (decisioni di design, domain knowledge, trade-off).

Setup pre-commit hook (illustrativo)

Per bloccare commit su CRITICAL non risolti, un pre-commit hook che invoca Claude Code con la skill attiva sul diff. Esempio illustrativo (non production-ready copy-paste, adattare al setup locale):

#!/usr/bin/env bash
# .git/hooks/pre-commit (illustrativo)

DIFF=$(git diff --cached)
if [ -z "$DIFF" ]; then exit 0; fi

REPORT=$(echo "$DIFF" | claude-code --skill code-reviewer --quick)

if echo "$REPORT" | grep -q "CRITICAL: [1-9]"; then
  echo "Commit bloccato: CRITICAL issue trovate."
  echo "$REPORT"
  exit 1
fi
exit 0

Setup richiede 20-30 minuti. Una volta installato, zero CRITICAL leakano in main branch. Effetto collaterale: paese in cui un secret hardcoded non arriva mai in git history.

Cosa la skill cerca specificamente

La skill ha un set di pattern noti che cerca in modo sistematico:

• OWASP Top 10: SQL injection, XSS, CSRF, broken auth, secret exposure.
• Error handling gaps: try/catch mancanti, error swallowing, generic catch-all.
• Resource leaks: file handle non chiusi, connection pool non rilasciate, listener non rimossi.
• Race conditions: shared state senza lock, async senza ordering garantito.
• Performance smell: N+1 query, loop over network call, sync I/O in async context.
• Code smell: duplicazione, complexity ciclomatica alta, naming opaco.
• Test gap: business logic senza test, edge case non coperti.

Il body della skill ha section dettagliate per ogni categoria, lazy-load via references/ quando il review ne incontra una rilevante.

Anti-pattern: review che non blocca mai

Una skill code-reviewer che produce solo "tutto OK" è inutile. Causa tipica: il body è troppo permissivo o il description spinge a "be encouraging" invece di "find issues". Sintomo: nessun PR del progetto ha mai un HIGH segnalato.

Soluzione: il description deve impostare il tono ("be strict, flag any issue that would slow a senior reviewer"). Il body deve avere section esplicite tipo "if you can't find issues, recheck - most code has at least one MEDIUM". La skill upstream di Superpowers è ben tarata, ma se la senti permissiva su un tuo dominio specifico, una variante custom con tono più severo aiuta.

Anti-pattern: review che blocca tutto

L'opposto: una skill che segnala 30 LOW per PR. Sintomo: la team smette di leggere il report.

Soluzione: configura severity threshold. Sul portfolio mostro solo HIGH e MEDIUM nel report pre-commit; LOW finisce in un file .code-review-low-suggestions.md ignorato di default, consultabile su richiesta. CRITICAL blocca sempre.

Integrazione con altre skill

code-reviewer si combina bene con due altre skill:

• security-reviewer: deep-dive su pattern OWASP, ha threshold più severa. Lo invoco esplicitamente sui flow di autenticazione, pagamento, upload file.
• refactor-cleaner: dopo code-reviewer ha segnalato duplicazione MEDIUM, refactor-cleaner propone il refactor concreto. Chain: code-reviewer trova → refactor-cleaner risolve.

Quando la skill sbaglia

Ci sono casi in cui la skill segnala issue che non sono issue, o manca issue reali. Casi tipici:

1. False positive su domain-specific patterns: il review segnala "duplicazione" su due funzioni che sembrano simili ma operano su domini distinti. Esempio personale: computeTaxIt e computeTaxFr non sono duplicazione, sono due funzioni separate per giurisdizione. La skill upstream non lo sa. Risposta: documenta nel CLAUDE.md di progetto i domain pattern che non sono duplicazione.
2. False negative su business rule: la skill non vede una violazione di business rule perché non conosce la rule. Esempio: una funzione che calcola IVA al 22% senza considerare regime forfettario. Tecnicamente il codice è corretto; semanticamente è sbagliato. Solo un umano con domain knowledge lo coglie.
3. Race condition sottile: la skill cattura race su shared state ovvi, ma race su ordering distribuito (es. webhook ordering Stripe) le sfugge. Per quelli serve security-reviewer o review umano specializzato.

Sessione tipica: metriche

• Diff medio: 200-500 righe modificate.
• Tempo review skill: 30-90 secondi.
• Token consumati: 10-25k.
• Issue catturate medie: 0 CRITICAL, 0-2 HIGH, 1-4 MEDIUM, 2-8 LOW.
• Issue HIGH/MEDIUM che il review umano avrebbe trovato: ~80%.
• Issue HIGH/MEDIUM solo trovate dalla skill: ~20% (di solito edge case che l'occhio umano scrolla).

Pattern: review batch su PR grosse

Sul portfolio, PR grosse (>30 file modificati) richiedono variante di pattern: la skill review-batch.

1. Splitta il diff per dominio (es. backend / frontend / migration).
2. Invoca code-reviewer separatamente per ogni gruppo.
3. Aggrega report finale con priorità CRITICAL → HIGH → MEDIUM.

Senza splitting, sui diff oltre 1000 righe il modello tende a fare review superficiale (skip di interi file). Splitting forza attenzione granulare.

Cosa ho imparato scrivendo questo articolo

La lezione principale è sul tempo. Il valore della skill non è tanto cosa cattura (un umano farebbe lo stesso review con tempo sufficiente), è quando lo cattura: 30 secondi dopo aver scritto il codice, non 30 minuti dopo il PR. Trovare un HIGH al PR significa back-and-forth con l'autore. Trovarlo al commit significa fix immediato con tutto il context fresco in mente.

Secondo insight: la skill mi ha fatto notare quanto scorrei il mio codice quando ne scrivo molto in una sessione. Casi in cui la skill catturava typo o error handling mancante che io stesso avrei catturato rivedendo lentamente - ma non li avrei catturati perché stavo pensando alla feature successiva. La skill compensa esattamente questa modalità di "writing fast, reviewing inattentively".

Anti-pattern evitati

• Review LLM come sostituto del review umano. La skill cattura tipi specifici di issue, non sostituisce il giudizio architettonico. Tenere il review umano sui design decision, lasciare il review LLM sull'esecuzione.
• Skill troppo silenziosa. Se la skill non blocca mai, non sta funzionando. Tarare verso strictness, non verso encouragement.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai integrato code-reviewer in workflow di team, scrivimi a federico@federicocalo.dev. Sono particolarmente interessato a setup multi-developer dove il gate pre-commit ha cambiato la dinamica del review umano.

← Cluster precedente: TDD enforcement skill Prossimo cluster: Refactor-cleaner skill →