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.
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'harness | Cosa fa | Dove trovarla |
|---|---|---|
| Istruzioni di sistema | Claude Code le aggiunge al contesto prima del Suo primo messaggio: come lavorare, quali strumenti sono disponibili e in quale cartella si svolge la sessione | la riga System prompt nell'output di /context |
CLAUDE.md | regole del progetto che l'agente legge all'inizio della sessione | un file nella radice del progetto |
| Strumenti | lettura e modifica dei file, ricerca, comandi nel terminale | righe come Read(...) e Bash(...) durante il lavoro |
| Skill | istruzioni che il modello può scegliere per un compito o che Lei può richiamare esplicitamente | .claude/skills/, /skills |
| MCP | un ponte verso servizi esterni e dati aggiornati | /mcp |
| Subagent | un esecutore separato con il proprio contesto | .claude/agents/ |
| Richieste di autorizzazione | l'harness verifica se un'azione è consentita e, quando serve, chiede il Suo consenso | una domanda nel terminale prima di un comando o di una modifica |
| Hook | i Suoi comandi associati agli eventi della sessione, eseguiti senza una decisione del modello | /hooks |
| Contesto e sessione | cosa vede il modello in questo momento e a quale punto si può tornare | /context, /clear, /rewind |
| Ciclo dell'agente | restituisce al modello i risultati degli strumenti, così può scegliere il passo successivo | più 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.
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 inCLAUDE.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
Stoppuò 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
/modele confronti i risultati sullo stesso compito.
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.
GO TO FULL VERSION