query() 호출로 앵커링을 구조적으로 제거한다.
UditAkhourii/adhd · npm 패키지 adhd-agent v0.1.4 · TypeScript 5.6 + Node.js ≥18 + ESM · 핵심 의존성 @anthropic-ai/claude-agent-sdk · p-limit · zod · 인지 프레임 15종 · 라이선스 MIT · 저자 Udit Akhouri · 프리프린트 adhdstack.github.io · 클론 소스 직접 분석)
보통의 AI는 문제를 받으면 가장 그럴듯한 첫 답을 잡고 거기서부터 다듬는다. 이걸 조기 수렴(premature convergence)이라 부른다. 결과는 "맞긴 한데 잊혀지는" 답 — 시니어 엔지니어가 30초 만에 줄 법한 정석이다.
ADHD는 정반대다. 하드웨어 엔지니어, 규제 감사관, 10살 아이, 스피드러너 같은 15가지 인지 프레임 중 몇 개를 골라 각자 독립된 프로세스로 아이디어를 뿜게 하고(발산), 그 다음 별개의 비평가 호출이 30여 개를 점수화·군집화·함정 제거·심화한다(수렴).
이 도구는 두 가지 얼굴을 가진다. 하나는 설치형 스킬(skills/adhd/SKILL.md) — npx skills add UditAkhourii/adhd 한 줄이면 Claude Code·Cursor·Codex 등 ~50개 에이전트에 붙고, /adhd "문제"로 부른다. 다른 하나는 독립 Node/TS 라이브러리 + CLI(adhd-agent) — 에이전트 밖이나 배치 작업에서 같은 루프를 구조화 JSON으로 돌린다.
# A) 설치형 스킬 — 에이전트에 붙여 /adhd 로 호출
npx skills add UditAkhourii/adhd
# B) CLI — 터미널에서 바로
npm install -g adhd-agent
adhd "리더 선출에도 살아남는 rate limiter를 설계해줘"
adhd "이 함수 이름 지어줘" --frames 3 --ideas 8 --top 2라이브러리로 쓰면 자기 에이전트 루프의 결정 지점에 그대로 끼워 넣을 수 있다. 반환값 하나에 발산·수렴 결과가 전부 담긴다:
import { run, renderText } from "adhd-agent";
const result = await run({
problem: "버스트 트래픽에서 이 큐를 어떻게 샤딩하지?",
framesPerRun: 5, topK: 3,
});
console.log(renderText(result));
// result.shortlist · result.nonObviousPick · result.traps · result.deepened · result.clusters정리하면 ADHD의 정체는 "프롬프트 트릭"이 아니라 "오케스트레이션 엔진"이다. ① 프레임을 골라 ② 서로 격리된 N개의 LLM 호출을 병렬로 띄우고(발산) ③ 반대 성향의 비평가 호출로 점수·군집·함정·심화를 처리한다(수렴). 값은 Claude Agent SDK의 query()가 내지만, 이 레포의 진짜 가치는 발산과 수렴 사이에 세운 "하드 월(hard wall)" 그 자체에 있다.
ADHD가 트렌딩에 오른 이유는 단순한 프롬프트 모음이 아니라 하나의 주장을 코드·논문·실측으로 밀어붙이기 때문이다. 그 주장은: "자기회귀 추론의 조기 수렴은 프롬프트로 못 고친다. 아키텍처로 고쳐야 한다."
선형 CoT는 맨 처음 뱉은 문장에 닻을 내린다. ToT는 탐색을 넓히지만 여전히 하나의 공유 문맥을 걸어서, 앵커링이 가지 전체에 번진다. "대안도 생각해봐", "5개 옵션 먼저 나열해" 같은 프롬프트도 결국 한 문맥 안에서 순차 생성이라 첫 답에 끌려간다 — 번호만 붙은 CoT다.
ADHD의 N개 가지는 발산 중 서로의 문맥을 절대 못 본다. 각 가지는 남이 뭘 썼는지 볼 수 없는 별도 query()라, 닻 내릴 "첫 답"이 존재하지 않는다. 다양성이 프롬프트로 "요청"되는 게 아니라 격리 + 프레임으로 구조적으로 보장(by construction)된다.
저자는 이걸 말로만 하지 않고 재현 가능한 평가 스위트로 못박았다. 6개의 열린 엔지니어링 문제에서, 같은 모델의 단발(single-shot) 베이스라인과 ADHD를 붙여 놓고, 회의적인 스태프 엔지니어 시스템 프롬프트를 쓴 독립 LLM 심판이 A/B 순서를 무작위로 섞어 채점한 결과다(실행일 2026-05-25):
| 평가 축 | ADHD | 베이스라인 | 차이 | 배수 |
|---|---|---|---|---|
| breadth (폭) | 9.00 | 4.83 | +4.17 | 1.9× |
| novelty (참신성) | 7.83 | 2.67 | +5.17 | 2.9× |
| trap detection (함정 감지) | 9.50 | 1.83 | +7.67 | 5.2× |
| actionability (실행성) | 9.50 | 6.50 | +3.00 | 1.5× |
| builder usefulness (유용성) | 7.67 | 6.83 | +0.83 | 1.1× |
6문제 중 5문제에서 ADHD 승. 가장 큰 격차는 함정 감지(5.2배) — 단발 베이스라인은 "그럴듯하지만 망가지는" 아이디어를 거의 이름 붙이지 못하는데, ADHD의 별도 비평가 패스는 매번 15~20개를 기계적 이유와 함께 걸러낸다. 반대로 builder usefulness는 1.1배로 거의 차이가 없다 — 이건 정직한 신호다. 정석 답이 이미 충분한 상황에선 ADHD의 이점이 작다는 뜻이고, 저자도 이를 숨기지 않는다.
CoT는 한 사람이 소리 내어 천천히 추론하는 것. ToT는 한 사람이 체스판에서 N수 앞을 내다보며 탐색하는 것. ADHD는 하드웨어 엔지니어·규제 감사관·10살 아이·스피드러너가 한 방에 모인 브레인스토밍 룸 — 단, 서로 칸막이로 막아 남의 아이디어를 못 보게 한 뒤, 옆방의 편집자가 결과를 모아 고르는 것이다.
여기에 실제 채택 사례가 트렌딩을 뒷받침한다. 오케스트레이터 프레임워크 repowire가 ADHD를 정식 이식(PR #313 머지)해 프레임을 "프레임 시프트된 임시 피어"로 매핑했고, mstack은 think 플러그인으로 벤더링했으며, zk-flow-oss는 리뷰 전 앵커링 완화 패스로 프레임을 차용했다. 기술 매체 The New Stack이 "ADHD for Claude Code" 피처 기사를 냈고, testdouble/han 진영은 11개 출처·8라운드 검증의 근거 기반 리뷰를 공개(이슈 #16~#18로 추적)하기도 했다. 즉 "아이디어 → 논문 → 코드 → 외부 채택·검증"의 고리가 다 돌고 있다는 점이 이 레포의 무게다.
한 번 돌리면 대략 10회의 에이전트 호출, 30~90초, 단발 답의 5~10배 비용이 든다. 저자 스스로 SKILL.md에 사전 게이트(pre-flight)를 넣어 "정답이 하나거나 구글 한 번이면 나오는 문제"에는 쓰지 말라고 못박는다. 강점은 어디까지나 설계·네이밍·API 표면·모호한 디버깅 같은 열린 문제에 한정된다.
ADHD의 스택은 프레임워크가 아니라 "얇은 오케스트레이션 레이어"다. 무거운 값(LLM 추론)은 Claude Agent SDK에 위임하고, 자기 코드는 호출을 어떻게 배치·격리·검증하느냐에만 집중한다. 런타임 의존성이 딱 3개인 게 이 철학을 웅변한다.
| 계층 | 기술 | 왜 이걸 썼나 |
|---|---|---|
| 언어 | TypeScript 5.6 · ESM | "type":"module" 순수 ESM. 타입으로 Idea·Score·RunResult 등 도메인 모델을 못박아 LLM 출력의 형태를 강제한다. |
| 런타임 | Node.js ≥ 18 | node:crypto의 randomUUID()로 아이디어 ID 부여, node --test + tsx로 테스트. |
| LLM 게이트웨이 | @anthropic-ai/claude-agent-sdk ^0.1.0 | 핵심. query() 하나를 stateless 원샷으로 써서 각 발산 가지를 독립 세션으로 띄운다. |
| 동시성 제어 | p-limit ^5.0.0 | 병렬 호출 수를 세마포어로 제한(concurrency 기본 4). API 레이트리밋·비용 폭주 방지. |
| 구조화 파싱 | zod ^3.23.0 | LLM이 뱉은 JSON을 스키마로 검증. 형식이 어긋나면 그 가지를 빈 배열로 우아하게 실패(graceful degrade). |
| 빌드·개발 | tsc · tsx ^4.19 | tsc로 dist/ 산출, tsx로 트랜스파일 없이 src/cli.ts 즉시 실행(npm run dev). |
query()는 프롬프트를 넣으면 어시스턴트 메시지·결과를 비동기 스트림으로 돌려주는 함수다. ADHD는 이걸 stateless(무상태)로 쓴다 — 매 호출이 이전 대화 기억이 전혀 없는 새 세션이라는 뜻. 바로 이 "기억 없음"이 발산 가지 사이의 앵커링을 원천 차단한다.ADHD는 UI가 없는 CLI/라이브러리 도구라 전통적 프론트엔드가 없다. 대신 두 가지가 그 자리를 채운다. ① 터미널 렌더러 src/render.ts — ANSI 컬러 이스케이프로 발산·수렴 결과를 들여쓰기·강조·점수 칩으로 구조화해 출력한다("평평한 산문 벽"을 피하는 게 설계 철학의 일부다). ② 문서 사이트 adhdstack.github.io(GitHub Pages, docs/index.html)가 프리프린트를 호스팅한다. 인프라 측은 GitHub Actions 워크플로 5종(ci·codeql·dependency-review·stale·summary)으로 타입체크·보안 스캔·의존성 리뷰를 자동화한다. 평가 스위트(bench/)는 로컬 전용이라 CI에는 없다 — 재현 수치는 각자 npm run evals로 만든다.
ADHD의 스택은 레스토랑 주방장이 아니라 "홀 매니저"에 가깝다. 요리(추론)는 Agent SDK라는 주방이 하고, ADHD는 몇 명의 요리사에게(프레임) 서로 안 보이게(격리) 주문을 배분하고(p-limit), 접시가 규격대로 나왔는지 검수하고(zod), 손님상에 예쁘게 담아내는(render) 일만 한다. 그래서 코드가 얇다.
전체는 2단계 루프다. 그리고 두 단계 사이엔 넘을 수 없는 벽이 있다. 저자의 말: "두 단계를 섞는 것이 아이디어 품질을 죽인다. 비평가가 생성기의 목을 조르기 때문(the critic strangles the generator)." 발산은 "그래, 그리고(yes, and)"의 자세, 수렴은 "아니, 왜냐하면(no, because)"의 자세 — 둘을 동시에 하면 둘 다 망친다.
ToT는 모델이 진행하며 스스로 평가한다. ADHD는 발산을 자기만의 LLM 호출로 만들고 그 시스템 프롬프트가 평가를 금지한다. 수렴은 반대 자세의 별도 호출이다. 두 자세, 두 패스, 상호 배타 — 한 프롬프트 안의 약속이 아니라 서로 다른 API 호출로 물리적으로 분리된 게 이 레포의 가장 중요한 설계 결정이다.
// engine.ts — 발산 시스템 프롬프트(요약): 평가 금지
const DIVERGE_SYSTEM = `You are in DIVERGENT mode. You are a generator, not a critic.
- 첫 3개(뻔한 답)는 금지. 어색한 중간지대를 노려라.
- 나쁘고 이상하고 황당한 아이디어 환영 — 더 나은 걸 씨 뿌린다.
- 평가·헤지·랭킹 하지 마라. 그냥 생성만.`;
// 반대로 수렴 시스템 프롬프트(요약): 평가 필수
const SCORE_SYSTEM = `You are in CONVERGENT mode. You are now the critic.
- novelty / viability / fit 을 0-10로 채점.
- 매력적이지만 함정이면(hidden cost, false economy...) trap 사유 한 줄.`;발산은 Promise.all로 N개 가지를 동시에 띄우되, p-limit 세마포어(concurrency 기본 4)로 동시 호출 수를 묶는다. 토큰 비용은 가지 수에 선형(O(N))으로만 늘고, 이전 가지를 나중 가지에 뿌리지 않아 제곱으로 폭발하지 않는다.
// engine.ts — PHASE 1: 순수 병렬 팬아웃. 어떤 가지도 남을 못 본다.
const limit = pLimit(concurrency);
const branches = await Promise.all(
frames.map((f) => limit(async () => {
onEvent?.({ kind: "frame:start", frameId: f.id, ... });
const b = await divergeBranch(problem, context, f, ideasPerFrame, model);
return b; // b 는 오직 자기 프레임의 아이디어만 담는다
})),
);
const allIdeas = branches.flatMap((b) => b.ideas);LLM은 ```json 펜스나 서두를 자꾸 붙인다. parseJSON()은 펜스를 벗기고 첫 {/[를 찾아 잘라낸 뒤, zod 스키마로 검증한다. 파싱이 실패하면 예외로 죽지 않고 그 가지만 빈 채로 넘어간다 — 5개 중 1개가 깨져도 나머지 4개로 결과가 나온다.
공식 문서(how-it-works.md)는 src/diverge.ts·score.ts·cluster.ts·deepen.ts처럼 패스마다 파일이 나뉜 것처럼 설명한다. 하지만 실제 클론한 소스에선 이 네 함수(divergeBranch·scoreIdeas·clusterIdeas·deepenIdea)가 전부 src/engine.ts 한 파일 안에 있다. 문서는 개념적 분리를 말하고, 배포 코드는 한 엔진으로 합쳤다는 것 — README만 믿지 말고 소스를 봐야 하는 이유다.
구조가 말해 주는 것: 같은 루프가 두 번 표현돼 있다. src/는 실행 가능한 코드(라이브러리·CLI), skills/adhd/SKILL.md는 에이전트가 코드 없이 직접 수행하는 지시문이다. SKILL.md는 프레임 표·시스템 프롬프트·출력 형식을 자연어로 담아, Claude가 Task 도구로 병렬 격리 호출을 스스로 흉내 내게 한다 — 설치 없이 같은 방법론을 쓰는 길이다.
"여러 관점에서 봐줘"라고 부탁하는 대신, 물리적으로 격리된 병렬 호출을 만든다. 앵커링을 없애는 가장 확실한 방법은 닻 내릴 대상 자체를 없애는 것. 이 발상은 ADHD 밖에서도 쓸 수 있다 — 리뷰, 리서치, 브레인스토밍 파이프라인 어디든.
llm.ts는 query()를 for await로 소비해 assistant 텍스트 블록만 모으고, result가 실패면 예외를 던진다. 대화형이 아니라 함수 호출처럼 SDK를 쓰는 깔끔한 최소 예제다. 도구는 빈 배열(tools:[]) — "도구 = 수렴 압력"이라 발산 단계에선 일부러 뺀다.
모델은 ```json과 서두를 붙인다는 전제로 parseJSON()이 짜여 있다. 스키마 검증 실패 = 예외 대신 빈 결과. 프로덕션 LLM 파이프라인에서 "한 호출이 깨져도 전체는 산다"를 구현하는 표준 패턴.
프레임은 페르소나("너는 34살 엔지니어 존이야")가 아니다. "너는 지연시간·메모리 배치·물리 제약으로 사고한다"처럼 문제를 다시 던지게 하는 왜곡 장치다. 좋은 프레임의 조건: 고유 어휘 · 고유 자세 · 재현 가능한 왜곡. 페르소나 연구 결과가 그대로 적용되지 않는 이유이기도 하다.
--critic-model 플래그로 채점·군집 패스만 다른 모델 계열로 돌릴 수 있다. 생성기와 비평가가 같은 모델이면 같은 실수를 공유한다 — 다른 계열을 쓰면 오류가 서로 상쇄된다. 앙상블·자기검증 설계의 핵심 아이디어.
bench/run-evals.ts를 읽고 LLM-as-judge가 어떻게 A/B 순서를 섞는지 확인해 보라. frames.ts의 selectFrames()가 왜 Fisher–Yates 셔플을 쓰고 sort(() => Math.random()-0.5)를 피하는지(분포 편향) 주석을 따라가 보라. 이 둘만 봐도 "작지만 신중한" 엔지니어링의 결이 보인다.
| 항목 | 요구사항 / 수치 |
|---|---|
| 런타임 | Node.js ≥ 18 (ESM). 설치형 스킬은 대상 에이전트(Claude Code·Cursor·Codex 등)만 있으면 됨 |
| 인증 | ANTHROPIC_API_KEY 또는 Claude Code 세션(Agent SDK가 사용). 네트워크 필요 |
| 호출 수 | N(발산) + 1(점수) + 1(군집) + K(심화) ≈ 기본값에서 약 10회 |
| 지연시간 | 대략 30~90초 (병렬이지만 심판·심화가 순차 구간) |
| 비용 배수 | 단발 답의 5~10배. 정직한 공식: N × (base_context + branch_output) |
저자가 when-to-use.md에서 특히 강조하는 통찰: "호출 수는 잘못된 단위"다. 각 발산 가지는 격리된 새 문맥이라, 세션의 기반 문맥(CLAUDE.md·상태 파일·도구 컨텍스트)이 가지마다 통째로 다시 로딩된다. 기반이 ~26K 토큰이면 5개 가지가 발산 한 토큰 나오기 전에 ~130K를 재로딩한다. 그래서:
adhd "..."): 기반 문맥이 작아 비용 프리미엄이 낮다 — 순진한 5~10배에 가깝다.CLAUDE.md+도구 컨텍스트를 재로딩 → 프리미엄이 의미 있게 더 높다. 1 × base가 아니라 N × base로 예산을 잡아라.회의실 5개를 동시에 빌려 각각 브레인스토밍을 시킨다고 하자. 아이디어(출력 토큰)는 몇 줄 안 되지만, 각 방마다 프로젝트 배경 자료 26쪽을 새로 복사해 나눠준다(기반 문맥). 종이값은 아이디어 양이 아니라 방 개수 × 배경자료로 정해진다. ADHD 비용의 진짜 바닥이 여기다.
npm i -g adhd-agent 후 adhd "블로그 댓글 스팸을 막는 방법"을 돌려라. 출력의 다섯 부분 — Wide set(군집별), Converge(shortlist + ★non-obvious pick), Traps, Focus(심화), Provocation — 을 각각 찾아 표시해 보라. 어떤 아이디어가 왜 trap으로 분류됐는지 사유를 읽어 본다.
src/frames.ts의 FRAMES 배열에 프레임을 하나 더한다(예: "고고학자 — 이 시스템을 100년 뒤 발굴한 고고학자의 눈"). 고유 어휘·고유 자세·재현 가능한 왜곡 세 조건을 만족하는지 자문하고, tags를 붙인 뒤 같은 문제를 여러 번 돌려 그 프레임이 다른 프레임이 안 내는 아이디어를 내는지 확인하라.
adhd "..." --critic-model <다른-계열-모델>로 생성기와 비평가를 다른 모델로 분리해 본다. 같은 모델일 때와 trap 감지 개수·shortlist 구성이 어떻게 달라지는지 비교하라. "오류 탈상관"이 실제로 관찰되는가?
bench/problems.json에 열린 엔지니어링 문제를 4줄로 추가하고 npm run evals -- --problem <id>로 돌려라. judge.ts가 만든 판정을 읽고, ADHD가 이긴/진 축을 분석한다. builder usefulness가 낮게 나오는 문제 유형이 있는가?
라이브러리로 run()을 임포트해, 자기 에이전트가 설계 결정 지점에 도달했을 때만(SKILL.md의 pre-flight 게이트 로직 참고) ADHD를 호출하도록 감싸라. result.nonObviousPick을 후보로 채택하는 라우팅을 붙여 본다.
| 주차 | 주제 | 무엇을 · 왜 |
|---|---|---|
| 1주차 | 추론 전략 기초 | Chain-of-Thought · Tree-of-Thought · 발산/수렴 이론. 앵커링과 조기 수렴이 왜 생기는지. vs-cot-and-tot.md를 정독하고 세 가지 결정적 차이를 설명할 수 있게. |
| 2주차 | Claude Agent SDK | query()의 메시지 스트림 구조, 시스템 프롬프트 프리셋·append, stateless 사용법. llm.ts를 한 줄씩 재현해 보기. |
| 3주차 | 동시성 + 타입 안전 | Promise.all + p-limit 세마포어로 팬아웃 제어. zod 스키마 검증과 방어적 파싱. LLM I/O를 타입으로 못박는 법. |
| 4주차 | LLM-as-judge 평가 | A/B 순서 무작위화, 회의적 심판 프롬프트, 다축(breadth·novelty·trap…) 채점. bench/를 뜯어 재현 가능한 벤치마크 설계를 배운다. |
| 5주차 | 멀티에이전트 오케스트레이션 | 격리된 병렬 에이전트, 생성기·비평가 분리, 결정 지점 라우팅. ADHD를 자기 파이프라인의 서브루틴으로 통합. |