ADHD: aggiungere ai Coding Agent un motore di ragionamento parallelo Tree-of-Thought

Quando una CLI chiama un LLM e ogni tanto resta bloccata per 90 secondi, come progetti retry e timeout? La risposta da manuale è: exponential backoff con jitter, un timeout assoluto e un retry automatico. Non è una risposta sbagliata, ma forse senti che manca una domanda: il problema è davvero la rete o è stato scelto il modello sbagliato? Più l’utente aspetta, il pulsante non dovrebbe diventare sempre più “caldo”, magari fino a permettere un clic che sposta la richiesta su un modello più veloce?

ADHD serve proprio a questo tipo di problema. Non è un prompt che dice all’Agent “pensaci ancora”, ma una struttura di ragionamento parallelo per AI coding agent: prima più rami isolati divergono simultaneamente da prospettive cognitive diverse, poi un critic separato valuta, raggruppa, taglia le trappole e approfondisce i sopravvissuti. Questa guida spiega meccanismo, confini e criteri d’uso dello skill.

Cos’è ADHD (non è una tecnica di prompt)

Il posizionamento di ADHD è chiaro: prova a correggere la convergenza prematura nel ragionamento autoregressivo, non ad aggiungere parole incoraggianti al prompt.

Un modello autoregressivo genera token uno dopo l’altro. Appena i primi passi scelgono una direzione, il resto del testo tende a svilupparsi attorno a quella direzione. È un meccanismo efficiente, ma nei problemi di ingegneria aperti ha un effetto collaterale: la prima risposta plausibile diventa un’ancora, e il modello scivola lungo il percorso più comune, più simile ai dati di addestramento. Quella risposta è spesso corretta da manuale, ma spesso manca anche opzioni non ovvie e più preziose.

Anche un prompt normale può chiedere “elenca più soluzioni e poi confrontale”, “ragiona da prospettive diverse”, “evita di concludere troppo presto”. Il problema è che quei rami si contaminano ancora nello stesso contesto. Il modello genera e valuta insieme; una volta scritto un primo orientamento, i rami successivi fanno fatica a liberarsene davvero.

ADHD usa una scelta più rigida: nella fase di divergenza divide il lavoro in N chiamate Agent SDK completamente isolate. Ogni ramo vede solo il problema originale, un frame cognitivo e un system prompt che vieta la valutazione. Tra i rami non c’è contesto condiviso. Solo nella fase di revisione un critic separato valuta, raggruppa, pota e approfondisce tutto.

In una frase: CoT fa pensare un cervello più lentamente, Tree-of-Thought fa cercare un cervello più in largo, ADHD fa pensare più cervelli in parallelo e in modo diverso, poi lascia scegliere a un revisore.

Meccanismo a due fasi: muro duro tra Diverge e Focus

Il nucleo di ADHD sono due fasi: Phase 1 Diverge e Phase 2 Focus. In mezzo c’è un muro duro. Durante la divergenza la valutazione è proibita; solo nella fase di valutazione è permesso convergere.

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

Inizia →Pubbl.

Phase 1 Diverge: N percorsi concorrenti e isolati

La prima fase sceglie N frame cognitivi, di default N=5, poi avvia in parallelo N query Agent SDK isolate. Ogni ramo riceve solo tre elementi:

1. Il problema originale.
2. Il prompt di prospettiva di un frame, per esempio per riporre il problema in termini di latenza, layout di memoria, regolamentazione, on-call o inversione.
3. Un system prompt che vieta valutazione, ranking ed esitazione.

I rami non possono vedersi. Il ramo con prospettiva da audit regolatorio non vede cosa ha scritto il ramo speedrunner; il ramo da ingegnere hardware non viene ancorato in anticipo dal ramo “bambino di 10 anni”. Ogni ramo è una sessione stateless indipendente. L’anchoring non viene represso dall’autodisciplina del modello: viene tagliato dalla struttura.

La concorrenza è controllata da un semaphore, con concurrency=4 di default. Il costo in token cresce linearmente con il numero di rami, O(N×costo per ramo), non N², perché i rami successivi non rileggono l’intero contenuto dei rami precedenti.

Phase 2 Focus: una chiamata critic separata

La seconda fase passa a una chiamata critic separata. Fa tre cose:

1. score: assegna a ogni ramo un punteggio da 0 a 10 su novelty, feasibility e fit, e per ogni trappola scrive una ragione meccanicistica.
2. cluster: raggruppa per underlying angle, non per parole chiave superficiali.
3. deepen top-K: approfondisce i sopravvissuti, K=3 di default, aggiungendo schizzo, rischio portante, primo passo e 3-5 sotto-idee.

La scelta chiave è la separazione meccanica tra generator e critic. La fase generator vieta la valutazione; la fase critic deve valutare. Non sono due promesse verbali dentro la stessa sessione, ma due chiamate API diverse.

La forma di una chiamata a ramo isolato è più o meno questa:

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 ?? ""}`,
      }),
    ),
  ),
);

Tornando al problema retry/timeout iniziale, la baseline tende a dare l’ibrido standard: timeout del primo token a 15 secondi, timeout tra token a 30 secondi, limite assoluto a 90 secondi e un retry automatico. Il valore di ADHD non è scrivere questa risposta più lunga, ma far emergere anche opzioni come “un pulsante che diventa sempre più caldo mentre aspetti e, con un clic, annulla e sposta su un modello più veloce”, segnalando allo stesso tempo idee curiose ma insidiose come “streaming dei token al contrario” o “fatturare in base alla pazienza”.

Confronto strutturale con CoT/ToT

Tre differenze portanti

Prima: ADHD è isolamento, non ricerca. I rami di ToT si sviluppano comunque nello stesso albero e i nodi iniziali influenzano quelli successivi. I rami di ADHD non possono vedersi durante la divergenza, quindi l’anchoring viene eliminato per costruzione.

Seconda: ADHD usa frame, non varianti del next-step. ToT spesso espande le opzioni dentro “quale passo fare dopo”; ADHD ripone l’intero problema da un’altra posizione cognitiva. Non ritocca un parametro, ma fa guardare il problema al modello dalla latenza, dai vincoli fisici, dalla responsabilità regolatoria o dalla pressione di un on-call alle 3 di notte.

Terza: la separazione generator-critic è meccanica, non promissoria. Dire nella stessa sessione “prima non valutare” lascia comunque spazio a confronti sotterranei durante la generazione. ADHD divide la cosa con chiamate diverse, system prompt diversi e posture diverse.

Vale anche chiarire che frame non significa persona. Una persona dice “sei questo ruolo”; un frame dice “riponi l’intero problema con questi vincoli e questo vocabolario”. La prima cambia l’etichetta identitaria, il secondo cambia il quadro del problema.

15 frame cognitivi e come crearne uno custom

ADHD include 15 frame cognitivi per torcere lo stesso problema in direzioni diverse. codeMode tende di default verso prospettive di codice e design, e ogni esecuzione conserva un wild slot per evitare una divergenza troppo ordinata.

Esempi di frame integrati

Regole di selezione

• Lo stesso problema e lo stesso seed scelgono deterministicamente lo stesso gruppo di frame, utile per la riproducibilità.
• codeMode tende di default verso prospettive code/design, quindi non consegna un problema di ingegneria solo a metafore irrilevanti.
• Ogni esecuzione conserva un wild slot, così il sistema ha una possibilità di uscire da una cornice troppo regolare.

Frame custom

Un frame custom non deve essere lungo. Deve però cambiare davvero il problema. Un buon frame soddisfa almeno due condizioni su tre:

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

Testa ora →Pubbl.

1. Ha un vocabolario distintivo, non è solo “ragiona da più angoli”.
2. Ha una postura distintiva: avversaria, costruttiva, ingenua, a vincoli estremi.
3. Ha una distorsione riproducibile, cioè cambia stabilmente la direzione del ragionamento ogni volta che lo applichi.

Per esempio, per un prodotto in abbonamento puoi scrivere un frame così:

name: subscription_retention
vocabulary: ["subscription", "retention", "churn", "renewal", "lifecycle"]
stance: "Think in terms of subscription churn and lifetime value, not one-off transactions"
distortion: "Assume users will churn; design mechanisms that reduce churn"

Questo frame non si limita a chiamare il modello “responsabile crescita”; spinge il problema dentro i vincoli di retention, churn e lifetime value.

Quando usarlo e quando no

ADHD è uno strumento da punto decisionale, non da ogni battitura. Il criterio più semplice è questo: se un junior può trovarlo con Google, vince la baseline; quando un senior direbbe “fermiamoci un minuto e guardiamola da un’altra angolazione”, entra in scena ADHD.

Scenari adatti

Scenari non adatti

Installazione e attivazione

Prima di installarlo, fai una revisione di sicurezza dello skill di terze parti. Leggi almeno SKILL.md: cosa chiede all’Agent, se chiama comandi esterni, se legge o scrive directory che non vuoi toccare. Puoi usare come riferimento la guida pratica alla revisione di sicurezza degli skill OpenClaw.

Installazione universale

Il comando universale è:

npx skills add UditAkhourii/adhd

Rileva automaticamente circa 50 Agent, tra cui Claude Code, Cursor, Antigravity, Codex, Cline, Gemini CLI e Windsurf, e installa il file skill corretto.

Installazione specifica per Codex

Se il comando universale non registra lo skill in Codex, puoi forzare il target:

npx skills add UditAkhourii/adhd -a codex -g

Puoi anche installarlo a mano:

curl -o ~/.codex/skills/adhd/SKILL.md https://raw.githubusercontent.com/UditAkhourii/adhd/main/SKILL.md

Dopo l’installazione manuale, riavvia Codex per ricaricare la directory degli skill.

Modalità di attivazione

L’attivazione è:

/adhd "problema"

Per esempio:

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

Vedi prezzi →Pubbl.

/adhd "Una CLI che chiama un LLM ogni tanto resta bloccata per 90s: come progettare retry/timeout/UX?"

Non collegarlo a ogni completamento. L’uso più sensato è attivarlo esplicitamente su architettura, design di interfacce, naming e debugging sfocato.

Costo e valore

Dati di costo

Posizionamento del valore

Il posizionamento ufficiale è: spendere nell’ordine di 0,30 dollari per allargare una decisione architetturale da 50.000 dollari. Non significa far girare ADHD su ogni piccolo problema. Ricorda piuttosto che il costo di un errore in una decisione ingegneristica aperta può superare di molto una singola inferenza multi-ramo.

Nei progetti reali devi considerare anche il costo di contesto. Dentro Claude Code o sessioni Agent simili, ogni ramo può caricare contesto base di progetto, descrizioni degli strumenti e regole del repository. In teoria l’algoritmo è O(N×costo per ramo); in fattura somiglia di più a N×(base context + branch work). Per questo è adatto a “dovremmo progettare così?”, non a “come completo la prossima riga?”.

Interpretare i risultati eval

Il progetto ADHD presenta una serie di eval autodichiarate: 6 problemi di ingegneria aperti, stesso modello, giudice LLM indipendente, ordine A/B casuale. Questo perimetro va dichiarato: non è un benchmark accademico di terze parti e non è una valutazione umana.

Tabella comparativa a cinque dimensioni

Nota sul perimetro

Questi numeri sono utili per spiegare una direzione, non per citarli come punteggi autorevoli. Non dimostrano che “ADHD è sempre più forte di ogni strategia di ragionamento”. Sostengono una tesi più stretta: su problemi di ingegneria aperti, isolamento della divergenza più critic separato può cambiare in modo evidente ampiezza, novità e rilevamento delle trappole.

Nel testo, quindi, non conviene scrivere “leader nei benchmark di settore”. Una formula più solida è: “nelle eval autodichiarate del progetto, ADHD ha vinto 5 problemi aperti su 6, con uno scarto particolarmente grande in trap detection”. Tenere chiaro il confine dei fatti aiuta il lettore a usare bene questi dati.

Conclusione

La cosa interessante di ADHD non è che scrive risposte più lunghe, ma che trasforma il “pensare in modo diverso” in una struttura: i rami divergenti sono isolati, i frame ripongono il problema, il critic arriva separatamente a potare. Questa struttura colpisce esattamente una debolezza comune dei Coding Agent nei problemi di ingegneria aperti: convergere troppo presto sulla prima risposta che sembra buona.

Mettilo nei punti decisionali, non nel loop quotidiano a ogni battitura. Architettura, interfacce, naming, migrazioni e debugging sfocato valgono 30-90 secondi in più; cercare fatti, correggere bug con causa nota o scrivere una riga di boilerplate sono compiti più adatti alla baseline.

Se stai organizzando la tua toolchain di programmazione IA, puoi proseguire con il panorama degli strumenti di coding IA 2026 per collocarlo nella mappa degli strumenti, oppure leggere l’analisi dell’architettura DeepAgents per capire come sub-agent e strumenti di planning organizzano catene di ragionamento più lunghe.