Ha cambiato modello con /model, ha ripetuto il compito e ha ottenuto una risposta diversa. Eppure l'agente ha letto CLAUDE.md nello stesso modo, ha chiesto di nuovo il permesso prima di eseguire un comando e l'hook è scattato come al solito. Quindi tutto questo non dipende dal modello.

Vediamo dove finisce il modello e dove comincia il programma che gli sta intorno. Così saprà cosa controllare quando l'agente sbaglia.

Il modello e l'harness

Il modello elabora il contesto che gli viene fornito e prepara una risposta oppure una richiesta a uno strumento. Per esempio, sceglie quale file leggere e quale comando eseguire. Per svolgere queste azioni serve un programma intorno al modello: accede ai file, esegue i comandi e restituisce i risultati al modello.

Nei testi in inglese questo programma si chiama harness. Alla lettera significa "finimenti" (sì, proprio quelli dei cavalli), e anche in italiano si dice semplicemente harness. La documentazione di Anthropic è chiara: Claude Code è l'harness, Claude è il modello al suo interno. Il termine compare anche negli articoli sugli agenti in generale, quindi vale la pena ricordarlo.

A sinistra la richiesta entra nell'harness. Al centro si trova il modello, circondato da tre gruppi: cosa vede, con cosa agisce e cosa può fermarlo. L'harness esegue la richiesta allo strumento e ne restituisce il risultato al modello, che sceglie il passo successivo. A destra è mostrato il risultato del lavoro nel progettoHarnesscicloLa richiestaModellosceglie il passoCosa vede il modelloistruzioni, CLAUDE.mdCon cosa agiscestrumenti, MCP, subagentCosa può fermare il modellopermessi, hookRisultatonel progetto
Il ciclo di lavoro: richiesta allo strumento, risultato, passo successivo

Nello schema, l'harness raccoglie il contesto, verifica i permessi ed esegue le richieste del modello agli strumenti. La freccia sotto il modello indica il ciclo: il risultato dello strumento torna nel contesto e il modello sceglie il passo successivo oppure conclude la risposta. Una risposta conclusa non dimostra ancora che il compito sia risolto: il risultato va verificato.

Cosa ha già configurato

Ecco come si presentano le parti dell'harness in Claude Code. I file e i comandi nella colonna di destra aiutano a trovare ogni meccanismo nel progetto o nella sessione.

Parte dell'harnessCosa faDove trovarla
Istruzioni di sistemaClaude Code le aggiunge al contesto prima del Suo primo messaggio: come lavorare, quali strumenti sono disponibili e in quale cartella si svolge la sessionela riga System prompt nell'output di /context
CLAUDE.mdregole del progetto che l'agente legge all'inizio della sessioneun file nella radice del progetto
Strumentilettura e modifica dei file, ricerca, comandi nel terminalerighe come Read(...) e Bash(...) durante il lavoro
Skillistruzioni che il modello può scegliere per un compito o che Lei può richiamare esplicitamente.claude/skills/, /skills
MCPun ponte verso servizi esterni e dati aggiornati/mcp
Subagentun esecutore separato con il proprio contesto.claude/agents/
Richieste di autorizzazionel'harness verifica se un'azione è consentita e, quando serve, chiede il Suo consensouna domanda nel terminale prima di un comando o di una modifica
Hooki Suoi comandi associati agli eventi della sessione, eseguiti senza una decisione del modello/hooks
Contesto e sessionecosa vede il modello in questo momento e a quale punto si può tornare/context, /clear, /rewind
Ciclo dell'agenterestituisce al modello i risultati degli strumenti, così può scegliere il passo successivopiù azioni consecutive in risposta a una richiesta

CLAUDE.md e le skill forniscono istruzioni al modello. Il modello può interpretare male una regola o saltarla. I controlli dei permessi e i comandi negli hook configurati vengono eseguiti dal programma: il risultato dipende dalle condizioni definite e dai comandi stessi.

I plugin non compaiono nella tabella perché non sono una parte separata, ma un pacchetto: più skill, comandi o hook installati con un'unica operazione.

Stesso modello, comportamento diverso

Prendiamo una chat web che non è collegata al Suo progetto né al terminale. Ha un proprio harness: cronologia della conversazione, interfaccia, a volte ricerca sul web o caricamento di file. In quella chat il modello può spiegare una modifica e mostrare il codice; Claude Code, avendo accesso al progetto, può applicarla direttamente al file. Il modello è lo stesso, ma le capacità cambiano perché cambia il programma che gli sta intorno.

Con /model succede il contrario. Cambia il modello, mentre l'harness resta lo stesso: regole, strumenti e richieste di autorizzazione rimangono.

Dal modello dipende come interpreta il compito, sceglie gli strumenti e valuta i risultati. L'harness raccoglie il contesto, mette a disposizione gli strumenti e verifica i permessi. Per esempio, il modello può chiedere un file che gli manca; l'harness lo legge e ne restituisce il contenuto.

Come si vede in Claude Code

L'agente ragiona con sicurezza su una funzione che nel progetto non esiste più da tempo? Per prima cosa controlli se il codice aggiornato è finito nel contesto. Può aggiungerlo con @ seguito dal percorso del file, incollarlo nel messaggio oppure recuperarlo con lo strumento di lettura. Nei primi due casi potrebbe non esserci una chiamata di lettura separata. Se lo strumento è stato chiamato, controlli cosa ha restituito: il contenuto del file oppure un errore di accesso o di percorso. Se il codice non è nel contesto, lo fornisca o chieda all'agente di leggere il file. Se invece il codice c'è ma la conclusione è sbagliata, verifichi il ragionamento confrontandolo con le righe di codice. Anche un altro modello può essere utile in questo caso.

Cosa modificare quando l'agente sbaglia

Un errore isolato si corregge facilmente con una risposta: "file sbagliato, guarda insrc/utils.js". Se invece l'errore si ripete da una sessione all'altra, conviene controllare le istruzioni e i dati disponibili. Forse ogni volta deve rispiegare la stessa regola.

In pratica, i casi possono essere questi:

  • in ogni sessione l'agente dimentica una regola del progetto, per esempio che i test si eseguono con npm test: la regola va scritta in CLAUDE.md. È più sicuro salvarla esplicitamente in quel file che affidarsi a un promemoria nella chat;
  • sta spiegando la stessa procedura per la terza volta: è il momento di spostarla in una skill. L'agente potrà caricare le istruzioni quando servono. Durante il lavoro controlli che la skill sia stata richiamata; altrimenti la richiami Lei con /skill-name, inserendo il suo vero nome;
  • l'agente fa supposizioni su dati che non ha: fornisca i dati necessari, aggiungendo il file al contesto con @ oppure collegando un servizio esterno tramite MCP. Con le insistenze non smetterà di tirare a indovinare;
  • l'agente scrive "fatto" senza aver eseguito una verifica: un hook sull'evento Stop può avviare i test automaticamente, senza una decisione del modello. Sarà comunque Lei a valutare il lavoro, basandosi sull'output del comando e non sul resoconto;
  • i dati necessari sono disponibili e sono stati letti, ma l'agente si perde in un ragionamento complesso: provi un altro modello con /model e confronti i risultati sullo stesso compito.
Verifichi la causa

Per prima cosa controlli che i dati e gli strumenti necessari siano disponibili. Se il problema è il ragionamento, può provare subito un altro modello. Confronti la qualità del risultato e il consumo indicato da /usage: anche i tentativi falliti ripetuti consumano il Suo limite e il Suo tempo.