Cheat sheet

Cheatsheet harness dell'agente AI: componenti, file, problemi e checklist di avvio

Aggiornato: 12.10.2026 · Skillaria.Top

L'harness di un agente AI è composto da cinque componenti: istruzioni, strumenti, ambiente, stato e feedback. Il set minimo di file comprende AGENTS.md come router breve, gli script di verifica (make check, verify.sh), un file di avanzamento e un elenco di funzionalità con stati. Il segno di completamento lo mette lo script, non l'agente.

I cinque componenti dell'harness di un agente AI

Componente	Che cos'è	Artefatti	Sintomo di rottura
Istruzioni	Ciò che l'agente deve sapere del progetto	AGENTS.md / CLAUDE.md, skills, docs/, ADR	Viola convenzioni note
Strumenti	Ciò che l'agente può fare	shell, test, linter, browser, server MCP	"Vuole ma non può"
Ambiente	Dove lavora l'agente	file di lock, Docker/devcontainer, git worktree, sandbox, init.sh	La sessione inizia riparando l'ambiente
Stato	Ciò che sopravvive al riavvio	PROGRESS.md, DECISIONS.md, feature_list.json, commit	La nuova sessione non sa dove si era fermata
Feedback	Come l'agente scopre i propri errori	make check, E2E, hook, arch-check, valutatore	"Fatto", ma non funziona

Ordine di costruzione da zero: feedback → istruzioni → stato → ambiente → strumenti.

File dell'harness

File	Funzione	Regola
AGENTS.md / CLAUDE.md	Punto d'ingresso: che cos'è il progetto, come si avvia, come si verifica	Router breve (circa 80 righe), link ai documenti con la condizione "quando leggere"
docs/*.md	Dettagli per tema	Si leggono su richiesta, non per intero
.claude/skills/*/SKILL.md	Procedure ricorrenti (deploy, revisione)	Si caricano quando la descrizione del compito corrisponde
PROGRESS.md	Stato, lavoro svolto, blocchi, prossimi passi	Aggiornare alla fine di ogni sessione
DECISIONS.md	Decisione, motivazione, alternative scartate	Registrare il percorso, non solo l'esito
feature_list.json	Funzionalità: behavior, verification, state	Esattamente una funzionalità active (WIP=1)
scripts/verify.sh	Verifica una funzionalità e la porta a passing	L'unico che mette passing, con lo SHA del commit
scripts/arch-check.sh	Confini architetturali	Codice d'uscita 1 + WHY e FIX nell'output
scripts/init.sh	Controllo dell'ambiente prima del lavoro	Ambiente, git pulito, make check verde, funzionalità attiva
sprint contract	Contratto della funzionalità prima del codice	Nel perimetro / fuori perimetro / domande aperte
.claude/settings.json	Permessi e hook di Claude Code	Le verifiche girano sugli eventi, non nella memoria dell'agente

Scheletro di AGENTS.md

# Progetto: backend dei pagamenti (FastAPI, PostgreSQL)

## Avvio
docker compose up -d && ./scripts/init.sh

## Verifica
make check   # lint, tipi, unit, arch-check
make e2e     # scenari end-to-end

## Definition of Done
- make check e make e2e — codice 0
- funzionalità portata a passing con scripts/verify.sh
- PROGRESS.md aggiornato

## MUST
- Le richieste al database solo tramite i repository
- I segreti solo dalle variabili d'ambiente

## Documenti
- docs/payments.md — quando il compito riguarda pagamenti e rimborsi
- docs/migrations.md — quando cambia lo schema del database

Stati di una funzionalità

Stato	Significato	Chi lo cambia
pending	In coda	Pianificatore
active	In lavorazione (una sola)	L'agente all'avvio
passing	Verifica superata	Solo verify.sh
blocked	Serve una decisione umana	L'agente, con la motivazione

Livelli di verifica

Livello	Cosa	Quando
1	Lint, tipi	Sempre
2	Unit e integration test	Sempre
3	E2E	Quando cambia più di uno strato; prima di dire "fatto"
4	arch-check	Nuovi import tra strati

Il diritto di dire "fatto" arriva solo dopo il livello più alto. Gli unit test verdi non sono completamento.

Meccanizzare le regole

Livello	Strumento	Costo
grep-guard	Script che cerca un pattern e stampa un messaggio WHY/FIX	Minuti
Regola del linter	import-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)	Un'ora
Test architetturale	Test in CI che fallisce se si violano gli strati	Di più, ma visibile in make check

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: i servizi non parlano direttamente con il database"
  echo "FIX: usa il repository in app/repositories/"
  fail=1
fi
exit $fail

Problemi tipici e soluzioni

Problema	Componente	Soluzione
Una regola in CLAUDE.md non viene rispettata	Istruzioni	Accorciare il file, trasformare la regola in verifica o hook
L'agente non riesce a eseguire i test	Strumenti	Consentire il comando, installare le dipendenze nell'immagine
Comportamenti diversi su macchine diverse	Ambiente	File di lock, Docker/devcontainer, versioni del runtime fissate
Amnesia tra le sessioni	Stato	PROGRESS.md, session handoff, lettura all'inizio della sessione
Tre funzionalità avviate, nessuna finita	Stato	WIP=1 in feature_list.json
"Fatto", ma non funziona	Feedback	DoD, E2E, verify.sh, valutatore indipendente
Test verdi, funzionalità rotta	Feedback	E2E con database e configurazione reali
L'agente copia pattern cattivi	Feedback	arch-check fin dal primo giorno
Non si capisce che cosa abbia fatto l'agente	Stato	Commit piccoli, report in PROGRESS.md e DECISIONS.md
L'agente ha rovinato l'ambiente di notte	Ambiente	Sandbox, git worktree, checkpoint, ripristino con init.sh
Lo stesso commento di revisione è arrivato due volte	Intero harness	Trasformarlo in verifica in make check, togliere il testo dalle istruzioni

Ruoli nei compiti lunghi

Ruolo	Fa	Non fa
Pianificatore	Funzionalità con criteri di accettazione	Non scrive codice
Generatore	Implementa una funzionalità, esegue i test	Non decide se è completa
Valutatore	Verdetto con rubrica, citando file, riga, log	Non vede il ragionamento del generatore
Merge	Commit quando review == pass	È codice, non un agente

Budget del lavoro autonomo

Obiettivo in una sola frase (per esempio portare tutte le funzionalità a passing).
WIP=1, limiti di tempo e di tentativi per funzionalità.
La metrica cresce soltanto; una regressione comporta rollback immediato.
Migrazioni, infrastruttura, denaro: escalation a una persona.
Dopo diverse revisioni fallite la funzionalità riparte da un contesto pulito.

Checklist di avvio dell'agente

Esiste AGENTS.md: stack, avvio, comando di verifica, DoD.
make check passa su un clone pulito.
L'ambiente è riproducibile: file di lock, Docker o devcontainer.
L'agente ha accesso ai comandi necessari, quelli pericolosi sono bloccati o in sandbox.
C'è almeno un E2E per lo scenario principale.
Esiste PROGRESS.md e la regola di leggerlo all'inizio di ogni sessione.
Le funzionalità sono in lista con i loro stati, una sola attiva.
Il segno di passing lo mette lo script.
I messaggi di verifica contengono WHY e FIX.
Il compito è formulato con criteri di accettazione e confini del perimetro.
È definito che cosa richiede una decisione umana.
È stato misurato il verification gap prima delle modifiche, come riferimento.

Metriche dell'harness

Metrica	Come si calcola
Verification gap	Quota di "fatto" non confermati dalla verifica su 10 compiti
MTTR	Tempo dal guasto al ripristino dello stato funzionante
Avvio a freddo	La nuova sessione sa rispondere a "dove siamo, che cosa viene dopo" senza tirare a indovinare?
Ablation	Calo quando si disattiva un componente su un insieme fisso di compiti

Sintesi

L'harness non è un file, ma un ciclo: istruzioni, strumenti, ambiente, stato e feedback. Parti dalla verifica, mantieni AGENTS.md breve, affida il segno di completamento allo script e rivedi regolarmente l'harness. Tutto questo viene insegnato in pratica in un corso su un progetto reale, dove i componenti si assemblano in un unico harness.

Domande frequenti

Qual è la differenza tra AGENTS.md e CLAUDE.md?

Lo scopo è lo stesso: un file di istruzioni per l'agente. CLAUDE.md è letto da Claude Code, AGENTS.md è un formato comune a più agenti. In CLAUDE.md puoi limitarti a scrivere <code>@AGENTS.md</code> per collegarli.

Quante righe deve avere AGENTS.md?

Non c'è un limite rigido, ma il file d'ingresso va tenuto breve, come un indice: circa un centinaio di righe. I dettagli vanno in documenti separati.

Serve un feature_list.json anche in un progetto piccolo?

Per modifiche occasionali e isolate no. Diventa utile quando l'agente lavora su più funzionalità di seguito o in più sessioni.

Dove conservo i segreti a cui deve accedere l'agente?

Nelle variabili d'ambiente o in un gestore di segreti, non nei file di istruzioni né nel codice. All'agente dai accesso all'ambiente, non i valori scritti nel testo.

Impara l’argomento in video

Questo argomento è trattato in modo approfondito, con pratica, nel corso «Harness Engineering: инженерия надёжности AI-агентов».

Vai al corso