verify-agent

verify-agent è una skill per Claude Code che ti permette di verificare il lavoro prodotto da un agente AI — codice, documenti, dati, configurazioni — contro la richiesta originale. La differenza con un "controlla il tuo lavoro" è che il modello che ha prodotto il lavoro non si corregge da solo: un modello di famiglia diversa cerca di dimostrare che il lavoro NON rispetta la richiesta, e Claude verifica ogni obiezione con prove meccaniche prima di accettarla o respingerla.

I due ruoli

lavoro + brief ──▶ ⚔️ reviewer attacca ──▶ findings ──▶ ⚖️ Claude li verifica ──▶ 📋 verdetto
                          ▲                                     │
                          └────────── stessa sessione, ─────────┘
                                        max 3 round

⚔️ Reviewer — un modello esterno (Codex CLI di default; in alternativa Gemini, OpenRouter o Ollama) riceve il lavoro e il suo brief con un solo compito: trovare dove il lavoro non rispetta il brief. Lavora in sandbox read-only — legge il repo, non modifica nulla.

⚖️ Arbitro — Claude esegue il passo di verifica di ogni finding del reviewer: se si conferma, corregge il lavoro; se non si conferma, lo confuta e mette a verbale la controprova. Un finding è un claim, non una verità — anche i reviewer sbagliano.

I due si scambiano il lavoro finché il reviewer non ha più obiezioni, con un tetto di 3 round. Se un disaccordo resta aperto, compare esplicitamente nel verdetto.

Le cinque fasi

1. 📌 Pin — si fissano su disco l'artefatto (cosa si verifica: un diff, dei file, un documento) e il brief (il contratto contro cui verificarlo). La skill cerca il brief in quest'ordine: spec o PRD nel progetto, issue GitHub referenziata, documento di handoff, ricostruzione dalla conversazione da farti confermare, oppure te lo chiede direttamente.

2. 🔧 Check meccanici — tutto ciò che si può verificare oggettivamente viene verificato con strumenti reali, prima di chiedere qualsiasi parere a un LLM: test, lint, build ed esecuzione reale per il codice; link, numeri e claim fattuali per i documenti; conteggi e invarianti per i dati. Ogni check fallito è già un finding bloccante.

3. ⚔️ Review adversariale — il reviewer riceve solo brief, artefatto ed esiti dei check, mai il ragionamento di Claude. Attacca su tre assi: requisiti mancanti o fuori scope, errori dimostrabili, effetti collaterali fuori perimetro. Ogni finding deve indicare severità, evidenza esatta e un passo di verifica riproducibile. Se non trova nulla deve elencare cosa ha attaccato e perché ha retto — un "va tutto bene" senza lista non è valido.

4. ⚖️ Verifica dei findings — ogni finding viene verificato e marcato ACCETTATO (con correzione) o CONFUTATO (con controprova), poi il lavoro aggiornato torna al reviewer nella stessa sessione: il reviewer ricorda i round precedenti e può insistere su un punto confutato solo portando evidenza nuova.

5. 📋 Verdetto — ✅ VERIFICATO (check verdi e reviewer senza obiezioni), ⚠️ VERIFICATO CON RISERVE (nessun bloccante aperto, riserve elencate), oppure ❌ BOCCIATO (almeno un bloccante confermato e non corretto, con indicato cosa rifare).

Cosa vedi durante la verifica

Ogni passaggio è salvato in ./tmp/verify/<nome-task>/ dentro il progetto, e la skill ti dice in chat cosa sta succedendo e quale file lo documenta.

BRIEF.md — il contratto congelato e l'elenco di cosa si verifica. REVIEW-LOG.md — il log completo, round per round: findings, esiti dell'arbitrato, evidenze. reviewer-prompt.md — il prompt esatto inviato al reviewer. roundN-codex.md — il report del reviewer a ogni round. roundN-codex.jsonl — lo stream grezzo di Codex; con tail -f lo segui in diretta mentre lavora. arbitration-roundN.md — gli esiti della verifica dei findings rimandati al reviewer.

Installazione

1. Clona la repo — git clone https://github.com/DarioFontanel/verify-agent.git
2. Copia la skill nella cartella delle skill utente di Claude Code:

# macOS / Linux
cp -r verify-agent/skills/* ~/.claude/skills/

# Windows (PowerShell)
Copy-Item -Recurse verify-agent\skills\* $env:USERPROFILE\.claude\skills\

Verifica: in Claude Code digita /verify-agent — la skill compare tra quelle disponibili. Funziona anche in linguaggio naturale: "verifica il lavoro che ha fatto l'agente", "controlla che il task sia stato fatto bene".

Per aggiornare: git pull e ri-copia.

Prerequisiti

Codex CLI ≥ 0.130 — il reviewer di default. Installa con npm install -g @openai/codex@latest, poi codex login una volta (basta un account ChatGPT, nessuna API key). Non serve configurare un modello: la skill usa quello di default della tua config.

Backend alternativi — opzionali. Gemini richiede GEMINI_API_KEY nel .env del progetto, OpenRouter richiede OPENROUTER_API_KEY, Ollama richiede un modello locale. Con modelli locali piccoli il verdetto pesa poco: un reviewer vale solo se è paragonabile in capacità al modello che ha prodotto il lavoro. Comandi e dettagli per ogni backend sono in skills/verify-agent/references/backends.md.

Puoi anche usare più reviewer insieme ("verifica con codex e gemini"): i findings vengono deduplicati prima della verifica.

Sicurezza

Il reviewer è read-only a ogni round. La skill forza la sandbox anche quando riprende una sessione Codex esistente — caso in cui la CLI erediterebbe la configurazione locale, che può essere scrivibile — e gestisce gli altri dettagli non ovvi della CLI: lo stdin che può bloccare la run, i timeout, la ripresa della sessione per id esplicito. L'unico che modifica i file, durante la verifica dei findings, è Claude.

Designed by Dario Fontanel, PhD

Aiuto PMI italiane ad integrare l'intelligenza artificiale per automatizzare i lavori ripetitivi, abbattere i costi e guadagnare tempo per crescere.

Licenza MIT.