Deliberation

Claude Code에서 GPT, Gemini, Grok으로부터 두 번째 의견을 받아보세요. OpenRouter를 통해 Qwen, Kimi, DeepSeek를 포함한 400개 이상의 모델도 활용할 수 있습니다. 일곱 명의 도메인 전문가(아키텍트, 코드 리뷰어, 보안 분석가 외 4명)가 여러분의 계획을 검토하고, 버그를 찾아내며, 합의에 도달할 때까지 엣지 케이스를 논쟁합니다.

최근 블로그 포스트: Deliberation 소개: 400개 이상의 모델은 쉽지만, 어떤 모델이 자리를 차지할 만한지 아는 것은 어렵습니다.

세 모델이 논쟁할 때, 진짜 버그가 드러납니다. 1라운드 = 독립적인 최상위 발견 사항. 2라운드 = 각 모델이 다른 모델의 선택을 비판합니다. 불일치 매트릭스는 어디에서 의견이 갈리는지 보여주고, 결론은 실제로 무엇을 먼저 고쳐야 하는지 보여줍니다.

Deliberation이란 무엇인가요?

Claude는 MCP를 통해 GPT, Gemini, Grok 또는 OpenRouter를 통한 모든 OpenAI 호환 모델에 도움을 요청할 수 있습니다. 플러그인이 각 제공자의 연결을 처리하므로 프롬프트만 작성하면 됩니다. 각 전문가는 고유한 전문 분야를 가지며 조언하거나 구현할 수 있습니다.

제공자의 일부만 사용할 수 있습니다. 플러그인은 구성된 제공자를 감지하고 그에 따라 라우팅합니다. OpenRouter는 조언 전용이며 구성 기반입니다: 모델은 ~/.config/deliberation/config.json(Windows: %APPDATA%\deliberation\config.json; DELIBERATION_CONFIG로 재정의)에 선언되며 Claude Code를 재시작하지 않고도 핫 리로드됩니다.

Related MCP server: Agents Council

설치

Claude Code 플러그인(권장):

1. 마켓플레이스 추가 - antonbabenko/agent-plugins

/plugin marketplace add antonbabenko/agent-plugins

2. 플러그인 설치

/plugin install deliberation@antonbabenko

3. 설정 실행

/deliberation:setup

이제 Claude이 복잡한 작업을 GPT, Gemini, Grok 및 OpenRouter 전문가에게 라우팅합니다(Grok과 OpenRouter는 조언하고, GPT와 Gemini는 구현도 가능).

설정은 일회성 단계입니다. MCP 서버는 플러그인 매니페스트에 등록되어 있으므로 자동으로 로드되고 업데이트 시 최신 상태를 유지합니다.

업데이트(Claude Code)

/plugin marketplace update antonbabenko  # pull the new version from the marketplace
/reload-plugins                          # reconnect the MCP servers (or just restart Claude Code)

비-Claude 호스트에서 업데이트: npx -y @antonbabenko/deliberation-mcp를 통해 독립형 서버를 실행하는 호스트는 각 새 resolve에서 최신 게시 버전을 가져옵니다. npx는 해결된 패키지를 캐시하므로, 호스트가 이전 빌드를 제공하는 경우 npx 캐시를 지우거나(rm -rf ~/.npm/_npx) 버전을 고정/새로 고침하세요.

대안: deliberation MCP 서버 사용(독립형, 모든 에이전트와 호환)

오케스트레이션 서버는 자체적으로도 게시됩니다 - npm @antonbabenko/deliberation-mcp, 공식 MCP 레지스트리 이름 io.github.antonbabenko/deliberation.

원클릭 설치:

호스트의 MCP 구성에 다음을 추가하세요(대부분의 호스트는 mcpServers 키를 사용합니다):

{
  "mcpServers": {
    "deliberation": {
      "command": "npx",
      "args": ["-y", "@antonbabenko/deliberation-mcp"],
      "env": {
        "XAI_API_KEY": "xai-...",
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

env 블록은 Claude Code 외부에서 제공자 키를 설정하는 방법입니다. GPT와 Gemini은 여기서 키를 읽지 않습니다 - 별도로 로그인된 codex 및 agy CLI를 사용하므로, GPT/Gemini만 사용하는 경우 해당 줄을 제거하세요. XAI_API_KEY는 Grok을 활성화하고, OPENROUTER_API_KEY는 OpenRouter를 활성화합니다(OpenRouter는 ~/.config/deliberation/config.json - 표준 XDG 경로, Windows %APPDATA%\deliberation\config.json - 또는 DELIBERATION_CONFIG로 다른 위치를 지정해야 합니다). 위의 원클릭 버튼은 비밀을 전달할 수 없으므로 설치 후 env 블록을 직접 추가하세요.

호스트별 구성 위치 및 예상 키:

제공자 사전 요구 사항은 플러그인과 동일합니다(요구 사항 참조): GPT용 Codex CLI, Gemini용 agy, Grok용 XAI_API_KEY, OpenRouter용 OPENROUTER_API_KEY 및 ~/.config/deliberation/config.json(Windows: %APPDATA%\deliberation\config.json; DELIBERATION_CONFIG로 구성 경로 재정의).

노출된 도구: ask-all, consensus(전체 수렴 루프를 한 번의 호출로 실행하거나 synthesizeAlways:true로 단일 종합 패스 실행), consensus-step(루프를 직접 제어, 호출당 하나의 작업), ask-gpt / ask-gemini / ask-grok / ask-openrouter, panel + ask-one(활성 제공자 집합을 발견한 다음 개별적으로 호출 - 병렬로 실행하여 제공자별 진행 상황을 표시), analyze(디버그 로그 + 세션에 대한 읽기 전용 실행 분석: 모델별 지연 시간 / 토큰 + 결론 일치, 조언적 튜닝 제안 포함; configuredOnly 및 since는 보고서를 현재 실행 중인 모델과 선택한 기간으로 제한), 일곱 전문가(architect, plan-reviewer, scope-analyst, code-reviewer, security-analyst, researcher, debugger), 세션 도구(session-get / session-revisit / session-annotate). 모든 결과는 ms 및 유효 reasoningEffort를 포함합니다(HTTP 제공자는 토큰 usage 추가). 선택적 디버그 로그("debug": { "enabled": true })는 지연 시간 / 토큰 / 투표를 기록합니다 - 프롬프트나 응답은 절대 기록하지 않습니다. 이들은 서버 측이므로 Claude Code뿐만 아니라 모든 MCP 호스트에서 작동합니다(AGENTS.md 참조).

패키지에는 deliberation-setup bin도 포함되어 있습니다. npx -y --package @antonbabenko/deliberation-mcp deliberation-setup으로 한 번 실행하여 시작용 ~/.config/deliberation/config.json을 작성합니다(기존 파일은 절대 덮어쓰지 않습니다). 일반 npx -y @antonbabenko/deliberation-mcp 형식은 기본 bin(서버)을 실행하며, 이는 MCP 호스트가 시작하는 것입니다. 호스트 규칙 연결은 AGENTS.md 및 examples/의 호스트별 스니펫을 참조하세요.

호스트별 네이티브 플러그인(Cursor / Codex / Kiro / OpenCode)

위의 원시 MCP 구성 외에도, deliberation은 네 호스트에 대한 네이티브 플러그인 아티팩트를 제공하여 Claude Code 플러그인과 동일한 경험(페르소나를 가진 전문가 + 위임 시점에 대한 지침, 단순한 도구가 아닌)을 제공합니다. 이 모든 것은 node scripts/sync-hosts.js에 의해 정식 소스에서 생성되어 커밋되므로, 결코 표류하지 않습니다(CI 드리프트 테스트가 이를 강제합니다). 각 호스트는 리포지토리에서 자체 파일을 스캔합니다:

프로바이더 자격 증명은 독립 실행형 서버와 동일하게 작동합니다(Codex CLI를 통한 GPT, agy를 통한 Gemini, Grok용 XAI_API_KEY, OpenRouter용 OPENROUTER_API_KEY) - 사용하는 프로바이더만 설정하세요. MCP 서버는 이미 각 전문가 페르소나를 서버 측에서 주입하므로, 이러한 네이티브 파일은 호스트의 명령/스티어링 표면을 추가할 뿐 로직을 중복하지 않습니다.

호스트별 전체 설치 가이드: docs/hosts/ - Cursor, Codex CLI, Kiro, OpenCode.

요구 사항

최소한 하나의 프로바이더가 필요합니다:

• Codex CLI (GPT): npm install -g @openai/codex 실행 후 codex login을 실행하세요.

• Antigravity CLI: Antigravity CLI 시작하기 및 Gemini CLI에서 마이그레이션을 참조한 후 agy를 실행하고 로그인하세요.

• Grok (xAI): 설치할 CLI가 없습니다. 브리지는 플러그인과 함께 제공됩니다(Node 18+ 필요). XAI_API_KEY를 설정하세요(https://console.x.ai에서 키를 받으세요).

• OpenRouter: CLI가 없습니다. 브리지는 플러그인과 함께 제공됩니다(Node 18+ 필요). OPENROUTER_API_KEY를 설정하고(https://openrouter.ai/keys에서 키를 받으세요), ~/.config/deliberation/config.json에서 모델을 선언하세요(Windows: %APPDATA%\deliberation\config.json; DELIBERATION_CONFIG로 재정의 가능). 모든 OpenAI 호환 엔드포인트(Ollama, vLLM, LM Studio, HuggingFace Inference)에서 작동합니다 - 키 환경 변수가 비어 있으면 인증이 자동으로 건너뜁니다.

Windows 참고 사항(CLI 프로바이더). Windows에서 npm install -g는 실행 파일이 아닌 codex.cmd 셸(shim)을 설치하며, Node는 .cmd 파일을 직접 실행할 수 없습니다 - 그래서 GPT 호출은 spawn 오류만 발생하고 실패하곤 했습니다. deliberation은 이제 CLI 자체를 직접 해석합니다(PATHEXT, 실패 시 패키지 자체의 진입점으로 폴백) 그리고 셸을 거치지 않습니다. 사용자 머신에서 해석이 실패하는 경우, CODEX_BIN(GPT) 또는 AGY_BIN(Gemini)을 실제 실행 파일로 지정하세요. Grok과 OpenRouter는 영향을 받지 않습니다 - HTTP 브리지이며 아무것도 spawn하지 않습니다.

명령어

플러그인에 포함되어 제공됩니다(설치 후 사용 가능):

/setup은 짧은 별칭(/ask-gpt, /ask-gemini, /ask-grok, /ask-openrouter, /ask-all, /consensus)을 ~/.claude/commands/에 설치할 수도 있습니다. 이는 선택 사항입니다. 동일한 이름의 기존 명령어는 기본적으로 유지되며, setup은 덮어쓰기 전에 확인을 요청합니다. /deliberation:uninstall은 별칭이 번들 복사본과 바이트 단위로 동일한 경우에만 제거합니다.

analyze는 의도적으로 제외되었습니다: /analyze는 흔한 이름이며, 단순 복사본은 해당 명령어를 제공하는 다른 플러그인과 충돌합니다. 항상 사용 가능한 /deliberation:analyze를 사용하세요. 이전 setup이 ~/.claude/commands/analyze.md를 설치한 경우, setup은 삭제할 수 있도록 경로를 알려줍니다. /deliberation:uninstall도 analyze를 나열하지만, 바이트 동일성 가드는 현재 번들 파일의 복사본에만 적용됩니다 - 이전 릴리스에서 복사된 별칭은 다르므로 추측으로 삭제하지 않고 의도적으로 남겨둡니다.

전문가

전문가가 가장 도움이 되는 경우

• 아키텍처 결정 - "Redis를 사용해야 할까요, 아니면 인메모리 캐싱을 사용해야 할까요?"

• 디버깅에 막혔을 때 - 두 번 이상 실패한 후, 새로운 시각을 얻으세요

• 구현 전 - 코드를 작성하기 전에 계획을 검증하세요

• 보안 우려 - "이 인증 흐름이 안전한가요?"

• 코드 품질 - 구현에 대한 세컨드 오피니언

전문가를 사용하지 말아야 할 경우

• 단순한 파일 작업(Claude가 직접 처리)

• 모든 수정의 첫 시도(먼저 직접 시도하세요)

• 사소한 질문(위임할 필요 없음)

사용 방법

작업을 설명하세요. Claude는 전문가가 도움이 되는 시점을 감지하고 자동으로 위임합니다:

You: "Is this authentication flow secure?"
Claude: routes to the Security Analyst, then synthesizes the findings.

명시적으로 요청할 수도 있습니다: "Ask GPT to review this architecture", "Ask Gemini to...", 또는 "Ask Grok to...". 각 전문가는 분석을 위해 읽기 전용으로 실행되거나 수정 사항을 적용하기 위해 쓰기 권한으로 실행되며, Claude는 요청에 따라 모드를 선택합니다.

또는 슬래시 명령어를 직접 호출하세요 - 위의 명령어 섹션을 참조하세요.

/consensus 및 /ask-*가 모델의 정직성을 유지하는 방법

/ask-gpt, /ask-gemini, /ask-grok, /ask-all은 빠른 명령어입니다: 각각 하나 또는 세 개의 외부 모델을 디스패치하고, Claude가 출력을 읽고, 하나의 종합된 답변을 받습니다. 단일 실행, 루프 없음, 동료 검토 라운드 없음.

/consensus는 무거운 명령어입니다. 동일한 병렬 디스패치이지만, 동료 검토 라운드와 모델들이 동의할 때까지 계속되는 다중 라운드 루프가 있습니다. 비용: 오케스트레이터(Claude)가 검토 프롬프트를 작성하고, 투표하고, 어떤 이의가 실제인지 결정하고, 루프를 실행합니다. 방치하면 이 설정은 조용히 자신의 계획을 승인할 수 있습니다. 네 가지 가드가 이를 막습니다.

편향 가드 및 모델별 흐름이 포함된 상세 다이어그램 보기

네 가지 가드:

• 블라인드 평결. Claude는 패널을 호출하는 메시지 이전에 전송된 메시지에서 자신의 평결(APPROVE / REQUEST CHANGES / REJECT)을 게시합니다. 사전 약속은 대화 기록에 남으므로, Claude는 다른 모델의 의견을 본 후 자신의 의견을 바꿀 수 없습니다. 엔진이 이를 강제합니다: 블라인드 평결이 기록될 때까지 패널은 공개되지 않습니다.

• 동료 검토. 각 외부 모델은 계획을 독립적으로 검토하고 평결과 분류된 중요 이슈를 반환합니다. Claude는 중재자로서 이를 평가합니다. 모델들이 투표하고, Claude가 판정합니다.

• 자기 승인 없음. 응답한 모든 외부 모델이 승인하고 최소한 하나의 외부 모델이 실제로 응답한 경우에만 라운드가 수렴합니다. Claude 자신의 승인만으로는 라운드가 성립하지 않습니다. 오류가 발생한 프로바이더(예: 구성되지 않은 Grok이 missing-auth를 반환하는 경우)는 루프를 막는 대신 카운트에서 제외됩니다.

• 조용한 기각 없음. 기각되거나 연기된 모든 중요 이슈는 최종 보고서에 한 줄 이유와 함께 포함되며, Claude가 자신의 블라인드 이의 중 하나를 철회하는 경우도 포함됩니다. 엔진은 이유 없이 이슈를 기각하는 판정을 거부합니다.

/ask-* 명령어는 동일한 규칙의 더 가벼운 버전을 수행합니다. 외부 모델은 자문만 제공합니다: Claude가 출력을 읽고, 자신의 판단을 적용하고, 종합된 답변에 대한 책임을 집니다. 모델들이 동의하는 경우, 그것은 입력일 뿐 평결이 아닙니다.

/consensus는 핵심 수렴 엔진(core/consensus-loop.js) 위의 얇은 드라이버입니다. 루프 메커니즘 - 라운드 카운팅, 수렴 규칙, 구성 가능한 최대 라운드 상한, 기록, 신뢰도 라벨 - 은 명령어가 아닌 엔진에 있습니다. 각 라운드:

1. 블라인드 평결. Claude는 패널이 공개되기 전에 자신의 평결(대화록에 표시됨)을 먼저 제출하며, 엔진은 이 평결이 있을 때만 공개를 진행합니다.

2. 패널 검토. GPT, Gemini, Grok(및 구성된 모든 OpenRouter 위임 모델)이 계획을 병렬로 검토하고 APPROVE / REQUEST CHANGES / REJECT 및 분류된 주요 이슈를 제출합니다. 서버는 각 평결을 파싱합니다.

3. 중재자 판정 + 수정. Claude는 패널 평결과 자신의 블라인드 평결을 조정하며, 각 주요 이슈에 대해 수용, 기각(사유 필요), 또는 보류를 선택한 후 다음 라운드를 위해 계획을 수정합니다.

루프는 응답한 외부 모델 중 최소 하나가 승인하고, 거부가 없으며, 수용된 주요 이슈가 없고, Claude가 APPROVE로 판정할 때 수렴합니다 - 즉 Claude는 스스로 승인할 수 없습니다. 그 외에는 consensus.maxRounds(기본 5, 설정 가능)에서 unresolved로 중단됩니다. 신뢰도 라벨은 얼마나 빨리 수렴했는지를 반영합니다(1라운드 = 높음, 2-3 = 중간, 4-5 = 낮음).

동일한 엔진이 다른 호스트가 사용하는 진입점들도 지원합니다: consensus 도구(공급자 중재자와 함께 단일 호출로 전체 루프를 서버 측에서 실행하거나, synthesizeAlways:true로 단일 합성 패스를 실행) 및 consensus-step(직접 구동, 호출당 하나의 작업). 분류 체계와 엔진 계약에 대한 자세한 내용은 TECHNICAL.md를 참조하세요.

이전 버전에서는 추가 "2단계" 익명 피어 교차 검토(각 모델이 다른 모델의 답변을 블라인드로 평가, karpathy/llm-council에서 각색)를 실행했습니다. 엔진 기반 재작성에서 단일 진실 소스를 유지하기 위해 이를 제거했으며, 엔진 기능으로 돌아올 수 있습니다.

구성

전체 설정 및 구성 참조는 **SETUP.md**에 있습니다. 다음 내용을 다룹니다:

• 전문가 모드 - 자문(read-only) vs 구현(workspace-write), 요청에 따라 자동 선택

• 구성 파일 - 위치(~/.config/deliberation/config.json), DELIBERATION_CONFIG 재정의, 핫 리로드

• 6개 구성 섹션 - providers, models, routing, consensus, sessions, debug - 최소 예시 포함

• OpenRouter 모델 - 레코드 선언, askAll / consensus 자격, 팬아웃, reasoningEffort, 중재자 선택; consensus는 라운드 상한(maxRounds)과 벽시계 시간 예산(maxWallMs, 기본 20분)도 구성

• 타임아웃 - providers.defaults.timeout는 모든 공급자의 호출당 상한을 한 번에 높이고, providers.<name>.timeout은 하나를 재정의하며, 고정 모델의 models.<id>.timeout이 여전히 우선합니다. 비율 제한(HTTP 429) 호출은 업스트림의 Retry-After를 존중하여 한 번 재시도됩니다

• 디버그 로그 - 옵트인 지연 시간 / 토큰 / 투표 추적

• 세션 영속화 - 옵트인 디스크 기반 실행 기록(호스트 기반 /consensus 루프 포함) 및 session-* 도구; sessions.captureText(기본 꺼짐)는 추가로 공급자 응답 본문을 저장합니다(정리됨)

공급자 내부 구조, 환경 변수 및 수동 MCP 설정에 대해서는 **TECHNICAL.md**를 참조하세요.

작성자

Anton Babenko가 유지 관리합니다 - LinkedIn, X/Twitter.

기여

기여를 환영합니다. 워크플로, 커밋 규칙 및 자동화된 릴리스 프로세스는 CONTRIBUTING.md를 참조하세요.

라이선스

MIT