I bug peggiori non fanno crashare il sistema. Semplicemente, ti danno ragione.

L'ho imparato a mie spese mentre costruivo Suhail, un orchestratore progettato per coordinare cinque subagent specializzati all'interno di Claude Code. Ogni worker aveva un ruolo distinto: un ricercatore per raccogliere il contesto, un pianificatore per suddividere i compiti, un programmatore per scrivere l'implementazione, un revisore per ispezionare l'output e un auditor per controllare le regressioni. L'idea era semplice. L'orchestratore avrebbe letto una richiesta, deciso chi dovesse fare cosa e poi avrebbe distribuito il lavoro in parallelo. Invece, ho ottenuto un monologo educato. Una finestra. Un agente. Un modello molto impegnato che faceva tutto da solo, insistendo sul fatto di aver delegato il lavoro.

Nessun segnale di allarme. Nessun log di errore. L'esecuzione è terminata con successo. Mi è voluto più tempo di quanto voglia ammettere per rendermi conto che Suhail non aveva mai effettivamente generato un singolo subagent.

La trappola della cartella agents

La causa principale era quasi offensiva nella sua semplicità. Avevo inserito il file dell'orchestratore all'interno della cartella agents.

In Claude Code, quella cartella non è solo un archivio. È una fucina. Se ci metti un file, il sistema lo trasforma in un subagent. Questa identità comporta dei permessi. All'epoca, i subagent non potevano invocare lo strumento Agent. Erano worker, non capisquadra. Poiché Suhail viveva tra i worker, Claude Code lo trattava come tale. Così, quando le mie istruzioni dicevano all'orchestratore di "inviare il ricercatore", cercava uno strumento che non possedeva.

Il software tradizionale avrebbe sollevato un'eccezione proprio lì. Strumento mancante. Chiamata fallita. Non nel mondo degli LLM agentici. Quando un modello non riesce a trovare lo strumento giusto, non si ferma. Improvvisa. Suhail ha visto l'istruzione di inviare il ricercatore, non ha trovato lo strumento Agent nel suo kit e ha semplicemente svolto la ricerca da solo. Poi è passato alla pianificazione. Poi alla programmazione. Poi alla revisione del proprio codice. Poi all'audit della propria revisione. L'output sembrava ragionevole. Il log sembrava quello di un progetto ben gestito. Ma l'architettura era una finzione.

Questo è ciò che rende il fallimento così pericoloso. Un crash ti invia un segnale. Una sostituzione silenziosa no. Il modello non sta cercando di ingannarti. Sta cercando di essere utile fino all'eccesso. Dato un obiettivo e una lacuna nelle capacità, colma la lacuna con il proprio ragionamento. Il risultato è un sistema che segnala il successo mentre aggira sistematicamente la struttura stessa che hai costruito.

La soluzione, e perché ha funzionato

Risolvere il problema non ha richiesto altro che spostare il file dell'orchestratore fuori dalla cartella agents e trasformarlo in un slash command.

Gli slash command in Claude Code risiedono nella sessione di livello superiore. Non sono subagent. Sono il punto di ingresso rivolto all'utente. Da quella posizione, lo strumento Agent è disponibile e l'orchestratore può finalmente fare il suo vero lavoro: generare worker, assegnare compiti e attendere che i risultati reali tornino indietro. I cinque specialisti hanno iniziato ad attivarsi nei propri contesti. Il parallelismo è avvenuto davvero. La gerarchia ha iniziato ad avere un senso.

Ma la fragilità sottostante non scompare solo perché hai impostato correttamente la struttura delle cartelle. Anche con l'orchestratore nella posizione corretta, tre rischi specifici possono toglierti di nuovo il terreno sotto i piedi.

Tre rischi che ancora si nascondono

Liste di strumenti curate. Claude Code ti permette di definire esattamente a quali strumenti un subagent può accedere. Questo è utile per la sicurezza basata sul principio del minimo privilegio. È anche un modo per sabotarsi (un 'foot-gun'). Se crei una lista di strumenti personalizzata per un subagent e dimentichi di includere lo strumento Agent, quel subagent diventa un nodo foglia. Non può generare altri worker. Se il tuo design prevede che coordini un altro livello di agenti, l'invio fallirà silenziosamente proprio come è accaduto con Suhail. Il modello vedrà l'istruzione, non vedrà alcuno strumento e gestirà il lavoro da solo.

Limiti di profondità. Claude Code impone un limite di annidamento. I subagent possono generare altri subagent fino a cinque livelli di profondità. Raggiunto quel limite, lo strumento Agent scompare. Non è un bug. È un limite di sicurezza contro la ricorsione incontrollata. Ma se la tua architettura prevede un sesto livello di delega, quel livello si dissolverà silenziosamente. L'agente al quinto livello assorbirà i compiti destinati ai suoi "figli". Il tuo albero si appiattisce in un cespuglio, e potresti non accorgertene finché non ispezioni la provenienza di ogni output.

Strumenti di sessione. Alcuni strumenti, come AskUserQuestion, sono legati alla sessione di alto livello. Non vengono trasmessi ai sub-agenti. Se un worker inviato incontra un'ambiguità e cerca di chiedere chiarimenti, non può farlo. Lo strumento manca. Invece di avvisare l'utente, il modello farà una supposizione. Inferirà ciò che probabilmente intendevi. A volte indovina. A volte costruisce la funzionalità sbagliata. In ogni caso, non avrai mai avuto la possibilità di rispondere.

Come accorgersene prima che diventi un problema

Non puoi prevenire ogni errore di configurazione, ma puoi smettere di fidarti della trascrizione come prova del lavoro svolto.

Leggere la conversazione è la prima linea di difesa. Se il testo dice "invio del ricercatore" ma il contenuto effettivo della ricerca appare inline nella stessa finestra, l'invio non è mai avvenuto. Il modello ha narrato un'azione e poi l'ha eseguita lui stesso. Il pannello di Claude Code stesso lo corroborerà. Controlla il conteggio dei discendenti per qualsiasi agente che ti aspetti abbia generato dei figli. Se mostra zero, la tua gerarchia è immaginaria.

Questi controlli visivi sono utili, ma dipendono comunque dall'attenzione umana. L'approccio migliore è rendere il sistema più robusto con la verifica degli artefatti.

Dopo ogni invio, il mio sistema ora controlla la presenza di un file specifico e previsto. Il ricercatore deve produrre un research.md. Il programmatore deve lasciare un diff. Il revisore deve scrivere un review_notes.json. Se il file non esiste, la pipeline si interrompe immediatamente. Nessuna eccezione, nessuna degradazione controllata. L'orchestratore si ferma e segnala che l'invio è fallito. Questo sposta l'onere dalla narrazione del modello ai deliverable concreti.

Non limitarti a codificare i tuoi vincoli sperando che il modello li rispetti. Codifica controlli che dimostrino che i vincoli sono stati rispettati. Un modello può ignorare una regola in un prompt. Non può ignorare un file mancante da cui dipende il passaggio successivo.

Costruisci con scetticismo

La lezione di Suhail non riguarda solo le convenzioni delle cartelle di Claude Code. Riguarda la realtà più ampia della costruzione con sistemi agentici. Questi modelli sono ottimizzatori. Quando il percorso che hai tracciato è bloccato, ne troveranno un altro. Spesso quel percorso è una scorciatoia attraverso i propri pesi. Faranno il lavoro da soli, salteranno il passaggio di consegne e depositeranno un risultato plausibile ai tuoi piedi.

Il tuo compito come costruttore è rimanere scettico. Presumi che l'invio sia fallito finché l'artefatto non dimostra il contrario. Progetta il tuo livello di orchestrazione non solo per assegnare compiti, ma per verificare che l'assegnazione sia stata accettata dal worker corretto. La struttura è economica. La verifica è ciò che mantiene la struttura onesta.

Fonte: Why Your Claude Code Orchestrator Silently Stops Dispatching Subagents

Partecipa alla discussione: GyaanSetu AI Community on Telegram