ADHD: curare la convergenza prematura dei coding agent con ragionamento divergente parallelo

Dai a un agent un problema aperto e ha un difetto prevedibile: si ferma al primo piano che sembra plausibile e poi continua a scrivere lungo quell’unica strada. Il README ha un esempio reale. Una CLI chiama un LLM e a volte si blocca per 90 secondi, e all’agent si chiede di progettare una strategia di retry e timeout. Un agent a colpo singolo dà una risposta molto standard: timeout del primo token a 15 secondi, timeout tra token a 30 secondi, tetto assoluto a 90 secondi, più un retry automatico, citando il capitolo 22 del libro Google SRE. Niente da ridire, ma non chiede nemmeno una volta se per questo problema sia stato scelto il modello sbagliato, dove la chiamata lenta non andrebbe ritentata affatto, ma rilanciata su un modello più veloce.

È questa la lacuna che ADHD vuole colmare. È il pacchetto npm adhd-agent, con licenza MIT, costruito sull’Agent SDK di Claude e Codex. Apre un problema in parallelo attraverso più frame cognitivi isolati in decine di idee, poi usa una singola chiamata critic separata per valutare, raggruppare, potare le trappole e approfondire le migliori. In questa serie sui LLM locali gioca un ruolo insolito: non risolve «dove gira il tuo modello», risolve «se il tuo agent pensa abbastanza ampio a un punto decisionale chiave».

Il verdetto prima di tutto: cura la convergenza prematura

La convergenza prematura (premature convergence) è un problema strutturale dei modelli autoregressivi. Il modello genera token per token, e ogni nuovo token è trascinato da ciò che è già stato scritto. Il suo primo piano tende quindi a essere il più tipico, il più «da manuale» dei dati di addestramento. Quella risposta di solito è corretta, ma di solito poco originale e, peggio, spesso è una trappola che sembra giusta proprio perché è familiare.

Quando ti morde davvero? Nelle decisioni architetturali come storage a livelli, sharding, modelli di auth e topologia di code; nel dare nomi a funzioni, prodotti e variabili d’ambiente; e davanti a un bug sfocato senza causa radice chiara, dove prima devi elencare alcune classi di ipotesi. Ciò che hanno in comune è che non c’è una risposta standard, e mancare l’opzione non ovvia ma praticabile può costarti una riscrittura mesi dopo.

All’opposto, tutto ciò che ha una risposta chiara non dovrebbe usarlo. Cercare come chiamare un’API, correggere un bug di cui hai già trovato la causa, qualsiasi cosa a una ricerca di distanza: qui spreca soldi e tempo. Un test in una riga: ciò che un junior risolverebbe con Google, lascialo rispondere alla baseline; il momento in cui un senior si fermerebbe a dire «su questo devo pensarci in modo diverso per un minuto» è quando ADHD si guadagna il suo posto.

Il meccanismo: un muro duro tra due fasi

ADHD è un loop a due fasi con una partizione dura tra le fasi. L’autore insiste che mescolare divergenza e revisione è esattamente ciò che distrugge la qualità delle idee, perché il critic strozza il generator sul posto.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

Divergenza: N rami che non si vedono tra loro

La prima fase sceglie N frame cognitivi e lancia N chiamate Agent SDK concorrenti, ognuna una sessione nuova e senza stato. Ogni ramo vede solo tre cose: il problema originale, il prompt di prospettiva di un frame e un system prompt che vieta valutazione e ranking. La chiave: i rami non possono vedersi tra loro. Il ramo con la prospettiva del «regolatore» non legge mai cosa ha scritto il ramo «speedrunner». Senza contesto condiviso, l’anchoring non viene represso col prompt; semplicemente non esiste per costruzione.

Focus: una singola chiamata critic separata

Il critic entra in gioco solo nella seconda fase e fa tre cose. Prima valuta ogni idea da 0 a 10 su novità, fattibilità e aderenza, e marca ogni trappola con una ragione meccanicistica, per esempio «shelve non è thread-safe sotto carico multi-writer» invece di un vago «è rischioso». Poi raggruppa per angolo di fondo invece che per parole chiave di superficie, così vedi la forma di tutto lo spazio di design. Infine approfondisce i top-K, 3 di default, con uno schizzo, il rischio portante, il primo passo concreto e 3-5 idee figlie.

Qui c’è una scelta di design facile da non notare: la separazione tra generator e critic è meccanica, fatta di due chiamate API diverse con due system prompt opposti, non una promessa fatta alla stessa sessione di «prima divergere, poi convergere». La chiamata di un ramo isolato è più o meno così:

const branches = await Promise.all(
  frames.map(frame => withSemaphore(concurrency, () => callLLM({
    systemPrompt: `${frame.vantage}\n\nFORBIDDEN: evaluation, ranking, hedging. JSON array out.`,
    userPrompt:   `${problem}\n\n${context ?? ""}`,
  })))
);

Il costo in token cresce linearmente col numero di rami, non in modo quadratico, perché i rami successivi non rileggono mai cosa hanno scritto i precedenti. La concorrenza è governata da un semaforo, 4 di default.

Da una esecuzione non ottieni un muro di testo, ma un risultato strutturato: l’insieme completo di idee raggruppate, una rosa di 2-4 candidati, un’opzione «non ovvia ma praticabile» segnalata esplicitamente, un elenco di trappole con una ragione per ciascuna, i rami approfonditi e una provocazione jolly. Tornando al problema del retry, il colpo singolo dava solo l’ibrido da manuale; l’opzione che ADHD ha tirato fuori tra oltre 30 idee era «un pulsante che scotta sempre di più man mano che aspetti, un clic annulla e reinvia a un modello più veloce della famiglia Haiku», mentre segnalava in anticipo idee che suonano divertenti ma sono trappole, come «trasmettere i token al contrario» e «fatturare in base alla pazienza», prima che costassero tempo di ingegneria.

In cosa differisce da Chain-of-Thought e Tree-of-Thought

Questi tre sono i più facili da confondere, ma sono strutturalmente diversi.

Tre differenze portanti vanno isolate. Prima, è isolamento, non ricerca. I rami di CoT e ToT condividono una finestra di contesto, così al passo quattro il modello è ancorato ai suoi primi tre passi; i rami di ADHD non possono vedersi durante la divergenza, quindi l’anchoring è eliminato per costruzione. Seconda, varia il frame, non il passo successivo. I rami di ToT di solito variano la prossima mossa (prova questo numero, prova quello), mentre ADHD varia la prospettiva sull’intero problema, chiedendo in pratica al modello di «riporre questo come un problema hardware», il che produce idee strutturalmente diverse invece di ritocchi vicini. Terza, la separazione generator-critic è meccanica invece che promessa.

Una precisazione: ADHD è esso stesso una variante di Tree-of-Thought, e la fase di approfondimento espande davvero nodi top-K. La novità è che la ramificazione è guidata da frame e che la separazione della revisione poggia su due chiamate davvero distinte.

🔥 Non sprecare mesi su prodotti senza domanda! Valida i punti di forza del tuo SaaS con Adsterra e un piccolo budget ➡️

Testa ora →Pubbl.

Cos’è un frame: cambiare la prospettiva sull’intero problema

Un frame non è gioco di ruolo. È un «operatore di prospettiva», un system prompt che ripone l’intero problema da una particolare posizione cognitiva. A differenza della ricerca sui prompt di persona con il suo «sei un ingegnere di 34 anni di nome Alex», un frame non fa interpretare un personaggio al modello; lo spinge in un angolo di pensiero verso cui non andrebbe da solo.

Il progetto include 15 frame, e con codeMode attivo (di default) tende a prospettive di ingegneria. Qualcuno concreto: l’ingegnere hardware pensa in latenza, layout di memoria e vincoli fisici; il reperibile delle 3 di notte pensa «quale design eviterebbe di farmi svegliare»; il frame «rimuovi l’assunzione portante» chiede «cosa è possibile se framework, database e rete sono tutti spariti». Ogni esecuzione sceglie i frame in modo deterministico in base a un seed e riserva sempre un wild slot, così la divergenza resta un po’ strana.

Alcuni frame interdisciplinari sono particolarmente bravi a far emergere idee trasferibili: la biologia attinge a sistema immunitario, plasticità neuronale e segnalazione cellulare; la logistica pensa in code, batch, consegna just-in-time e hub-and-spoke; il game design pensa in loop, ricompense, attrito, punti di salvataggio e trucchi da speedrun. La risposta davvero buona a un problema aperto spesso vive fuori dal manuale di un singolo dominio e va trapiantata da altrove, ed è proprio la ragione d’essere dei frame interdisciplinari.

Scrivere un tuo frame costa circa 5 righe di codice. Un buon frame soddisfa almeno due criteri su tre: un vocabolario che nessun altro frame usa, una postura distinta dalle altre (avversaria, costruttiva, ingenua, massimalista) e una distorsione riproducibile che fa emergere idee che gli altri frame mancano. Limitarsi a rinominare il dominio dicendo la stessa cosa non basta.

Quando usarlo e quando no

Trattalo come uno strumento da punto decisionale, non da ogni battitura. La tabella qui sotto si può applicare direttamente.

Tieni chiaro il costo. Una esecuzione di default sono circa 10 chiamate LLM: 5 chiamate di divergenza di default, più 1 di valutazione, 1 di clustering e 3 di approfondimento, che fanno all’incirca 5-10 volte un colpo singolo, con 30-90 secondi di tempo reale. L’inquadramento dell’autore è pratico: spendere circa 0,30 dollari per allargare una decisione architetturale da 50.000 dollari, non eseguirlo a ogni battitura, eseguirlo nei punti decisionali. Un avvertimento onesto: dentro una sessione di Claude Code che porta un CLAUDE.md grande e contesto di strumenti, ogni ramo ricarica quel substrato di base, quindi il costo reale in token è più vicino a «rami per base più ramo», superiore al puro costo algoritmico.

Come installarlo e attivarlo

L’installazione è un comando che rileva automaticamente il tuo agent tra Claude Code, Cursor, Antigravity, Codex, Cline, Gemini CLI, Windsurf e una cinquantina di altri.

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

npx skills add UditAkhourii/adhd

Una volta installato, attivalo esplicitamente con /adhd "il tuo problema", oppure lascialo attivare automaticamente su intenti di ideazione. Codex ha un proprio percorso di scoperta; quando il comando universale non si registra, forza il target:

npx skills add UditAkhourii/adhd -a codex -g

Puoi anche copiare SKILL.md a mano nella directory degli skill di Codex, ~/.codex/skills/adhd/; dopo un riavvio, /adhd "design a rate limiter" passa per questo skill. Esistono anche gli usi da CLI e da libreria: npm install -g adhd-agent per la CLI, npm install adhd-agent per usarlo come libreria.

Prima di installare uno skill di terze parti, leggi il suo SKILL.md per vedere cosa chiede all’agent, soprattutto se chiama comandi esterni. La guida pratica alla revisione di sicurezza degli skill OpenClaw è un riferimento utile qui; 5 minuti sui confini dei permessi convengono più che rimediare dopo.

Sui modelli locali, per essere franchi: ADHD è costruito sull’Agent SDK e usa di default modelli della famiglia Claude, quindi non è uno strumento locale pronto all’uso. Collegare un modello locale, per esempio servito da Ollama, significa scrivere tu stesso un adattatore al livello di chiamata, e il progetto non promette che questa strada sia liscia. Il suo posto in questa serie sui LLM locali riguarda il suo pensiero al livello del ragionamento degli agent, non l’idea di poterlo dare così com’è a un piccolo modello locale.

Conclusione

Tratta ADHD come uno strumento che tiri fuori a un punto decisionale, non come qualcosa che prende in carico tutto il tuo flusso di lavoro. Il suo valore non è «pensare di più» ma «pensare in modo diverso», più una passata di revisione separata che segnala le trappole. Eseguilo una volta su una decisione architetturale per cui hai già una risposta, confronta l’opzione non ovvia che restituisce con il tuo piano, e poi decidi se collegarlo al tuo loop di agent.

Per continuare, vedi il panorama degli strumenti di coding IA 2026 per collocarlo nel paesaggio degli strumenti, oppure l’analisi dell’architettura DeepAgents per capire come i sub-agent e gli strumenti di pianificazione organizzano il ragionamento.