multi-ai-roundtable

name	multi-ai-roundtable
description	Use when a project needs diverse expert perspectives before execution - launches a roundtable that calls the real codex CLI binary via Bash for a critical analysis (Claude agent fallback only on quota/missing-CLI/repeated-failure), pairs it with Claude's creative-alternative lens, synthesizes into a roadmap, then executes with parallel agents
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, Agent, WebSearch, AskUserQuestion
version	2.0.0

Multi-AI Roundtable: 토론 → 로드맵 → 병렬 실행

Overview

복잡한 프로젝트(책 집필, 아키텍처 설계, 콘텐츠 기획 등)에서 외부 AI CLI 바이너리(codex)의 실제 호출로 비판적 관점을 수집하고, 여기에 Claude의 창의적 대안 관점을 더해 다각도로 검토한 뒤, 합의된 로드맵을 기반으로 병렬 에이전트로 실행하는 워크플로우.

참고: 이 스킬은 이전에 두 번째 외부 CLI로 Google gemini를 호출했으나, gemini CLI가 종료되면서 제거되었다. 이제 외부 CLI는 codex 하나만 호출하고, 창의적 대안 제시 역할은 Claude(이 세션)가 맡는다.

Core principle: 한 AI의 편향을 진짜 다른 모델(codex)의 비판과 Claude의 대안 제시로 극복하고, 합의된 계획을 병렬 실행으로 빠르게 구현한다. Claude Agent 툴 폴백은 codex 미설치·quota 초과·반복 실패 시의 예외 경로일 뿐.

Announce at start: "multi-ai-roundtable 스킬을 사용하여 codex 분석 + Claude 합성 토론 → 로드맵 → 병렬 실행을 진행합니다."

When to Use

• 기존 콘텐츠/코드를 대규모로 재편성해야 할 때
• 설계 결정에 다양한 관점이 필요할 때
• "이게 최선인가?"라는 질문이 드는 복잡한 프로젝트
• 책 집필, 커리큘럼 설계, API 아키텍처, 프로젝트 구조 등 구조적 결정이 핵심인 작업

Don't use when:

• 단순 버그 수정이나 기능 추가
• 이미 합의된 계획이 있을 때
• 1~2개 파일 수정으로 끝나는 작업

---

The Process

Phase 1: 현황 분석 (Context Gathering)
    ↓
Phase 2: 토론 (codex 분석 + Claude 대안)
    ↓
Phase 3: 로드맵 합성 (Roadmap Synthesis)
    ↓
Phase 4: 병렬 실행 (Parallel Execution)
    ↓
Phase 5: 검증 및 정리 (Verification & Cleanup)

---

Phase 1: 현황 분석

대상 프로젝트의 현재 상태를 파악한다.

1-1. 파일 구조 파악

# 프로젝트 파일 목록
find . -name "*.md" -o -name "*.dart" -o -name "*.ts" | head -50

1-2. 핵심 파일 읽기

기존 콘텐츠/코드의 품질, 톤, 구조를 파악한다. 최소 3~5개 파일을 읽어 패턴을 이해한다.

1-3. 분석 요약 작성

다음 항목을 정리하여 Phase 2에 전달한다:

## 현황 요약
- **현재 구조**: 파일/챕터/모듈 목록
- **강점**: 잘 되어 있는 부분
- **약점/누락**: 빠져 있거나 보강이 필요한 부분
- **톤/스타일**: 기존 콘텐츠의 문체나 코드 컨벤션
- **파일 수**: N개 (규모 판단용)

---

Phase 2: 토론 (codex CLI 호출 + Claude 대안)

외부 AI CLI(codex)를 반드시 Bash 툴로 직접 실행하여 비판적 입장을 수집한다. Claude Agent 툴로의 codex 대체는 폴백 경로에서만 허용된다 (CLI 미설치 / quota 초과 / 반복 실패). 본 단계의 결정성은 이 플러그인의 핵심 가치이므로 절대 위반 금지. 창의적 대안 제시 입장은 Claude(이 세션)가 직접 작성한다.

자세한 호출 규약·재시도·quota 감지·폴백 표기는 ${CLAUDE_PLUGIN_ROOT}/rules/shared-rules.md의 "Phase 2 — 외부 CLI 호출 규약" 섹션을 단일 출처로 따른다.

역할 배정

주체	역할	핵심 지시
codex-cli (CLI 바이너리)	비판적 분석가	"문제점을 찾아라. 빠진 것은? 리스크는?"
Claude (이 세션)	창의적 대안 제시자 + 중재자 + 합성자	"다른 접근법은? 차별화 포인트는?" → 두 입장을 종합해 최종 합의안 도출

2-1. 작업 폴더 생성 및 사전 점검

mkdir -p .roundtable
# codex CLI 존재 확인
command -v codex >/dev/null 2>&1 || echo "MISSING:codex"

MISSING:codex가 출력되면 AskUserQuestion으로 사용자에게 (a) Claude 폴백으로 진행 / (b) 중단하고 설치 후 재시도 중 선택을 요청한다.

2-2. 프롬프트 파일 작성

Phase 1의 현황 요약을 포함하여 다음 파일을 Write 툴로 생성한다. codex-prompt.md는 codex CLI에 전달하고, 창의 프롬프트는 Claude가 자신의 대안 입장을 .roundtable/claude-alternative.md로 작성할 때 지침으로 쓴다.

.roundtable/codex-prompt.md:

당신은 비판적 분석가입니다. 다음 프로젝트의 현황을 분석하고 문제점을 지적하세요.

## 현황 요약
[Phase 1 결과를 그대로 붙여넣기]

## 분석 요청
1. 구조적 문제점 (순서, 누락, 중복)
2. 내용 품질 이슈 (깊이, 정확성, 실용성)
3. 타겟 독자/사용자 관점에서의 갭
4. 리스크 요소 (저작권, 기술적 한계, 시장성 등)
5. 구체적인 개선 우선순위 (상/중/하)

구체적인 근거와 함께 비판하세요. 마크다운 형식으로 응답하세요.

창의적 대안 프롬프트 (Claude가 .roundtable/claude-alternative.md 작성 시 지침):

당신은 창의적 대안 제시자입니다. 다음 프로젝트를 한 단계 격상시킬 전략적 제안을 하세요.

## 현황 요약
[Phase 1 결과를 그대로 붙여넣기]

## 제안 요청
1. 놓친 관점이나 기회
2. 구체적인 재편성/재구성 안 (표 형태)
3. 차별화 포인트 및 시장 포지셔닝
4. 단계별 실행 로드맵

파격적이되 실현 가능한 제안을 하세요. 마크다운 형식으로 응답하세요.

2-3. codex CLI 실행 (결정적, 재시도·폴백 포함)

codex 블록을 1회 호출(포그라운드)한다:

codex exec --skip-git-repo-check --sandbox read-only - \
  < .roundtable/codex-prompt.md \
  > .roundtable/codex-output.md \
  2> .roundtable/codex-stderr.log
echo "CODEX_EXIT=$?"

codex 결과를 수집하는 동안(또는 이후) Claude는 위 창의 프롬프트 지침에 따라 창의적 대안 입장을 .roundtable/claude-alternative.md로 직접 작성한다. (이 입장은 codex와 무관하게 항상 Claude가 생성하므로 폴백 대상이 아니다.)

codex 호출의 결과 분기 (shared-rules.md "재시도 정책" 단일 출처):

exit == 0
   └─ 결과 채택. .roundtable/codex-output.md를 입장으로 사용.

exit != 0
   └─ stderr 로그에 quota 패턴 매칭? (regex는 shared-rules.md 참조)
        ├─ Yes → 재시도 금지. 즉시 2-5 Claude 폴백.
        └─ No  → 2~3초 대기 후 1회 재시도.
                  ├─ 재시도 성공 → 결과 채택.
                  └─ 재시도 실패 → 2-5 Claude 폴백.

stderr 검사 명령:

grep -iE 'quota|rate.?limit|429|exceeded|RESOURCE_EXHAUSTED|too many requests|insufficient_quota' \
  .roundtable/codex-stderr.log >/dev/null 2>&1 && echo "QUOTA:codex"

2-4. 출력 정합성 점검

.roundtable/codex-output.md가 비어있지 않고 최소한의 분석 형태(헤더·항목 등)를 갖췄는지 Read로 확인. 비어있거나 에러 메시지만 있으면 일반 실패로 분류하여 폴백.

2-5. Claude 폴백 (예외 경로)

codex 미설치(사용자가 폴백 동의), quota 감지, 또는 반복 실패 시에만 발동. (창의적 대안 입장은 원래 Claude가 작성하므로 폴백 개념이 없다.)

Agent 툴을 사용해 codex의 비판적 분석 입장을 대체 생성한다:

• description: "codex 폴백 — 비판적 분석가 관점"
• prompt: 위 2-2의 codex 프롬프트 본문 + 다음 안내 1줄 추가

  "참고: 이는 codex CLI 사용 불가(사유: <quota|미설치|반복실패>)로 인한 Claude 폴백 분석입니다."

폴백으로 생성된 파일 최상단에 다음 헤더를 반드시 추가:

> ⚠️ 폴백: codex CLI 사용 불가 (사유: <quota|미설치|반복실패>) — Claude로 대체 분석

2-6. 토론 라운드

라운드	내용
1라운드	독립 분석 (codex 비판 입장 + Claude 대안 입장 수집 완료)
2라운드	필요 시 상대 입장에 대한 반론/보완 (codex에 추가 호출은 동일하게 결정적 흐름 적용, Claude 입장은 직접 갱신)
3라운드	최종 합의 시도 (필요 시)

최대 3라운드로 제한 — 그 이상은 수렴하지 않는다. 라운드를 추가할 때마다 .roundtable/codex-output-rN.md, .roundtable/claude-alternative-rN.md 식으로 파일 분리.

2-7. 합의 판단 기준

상황	처리
두 입장(codex·Claude) 동의	즉시 채택
한쪽만 동의	Claude가 근거를 평가하여 결정
양쪽 반대	제3의 절충안 도출 또는 사용자에게 판단 요청

---

Phase 3: 로드맵 합성

Claude가 중재자로서 토론 결과를 하나의 실행 가능한 로드맵으로 합성한다.

로드맵 문서 작성

${CLAUDE_PLUGIN_ROOT}/templates/roadmap-template.md 템플릿을 참조하여 작성한다.

핵심 구성요소:

1. 결론 — 한 문단 요약
2. 최종 구조 — 합의된 항목 목록 (표 형태)
3. 항목별 상세 — 유지/축소/보강/신설 구분
4. 기존→신규 매핑 — 어떤 것이 어디로 이동하는지
5. 차별화 포인트 — 합의된 강점
6. 토론 과정 요약 — 쟁점별 합의 결과 (표 형태). Phase 2에서 Claude 폴백이 발동된 입장은 해당 칸에 (Claude 폴백 — <사유>) 표기 필수. 사용자가 결과 출처를 명확히 알 수 있어야 함.

사용자 확인

반드시 사용자에게 로드맵을 보여주고 승인을 받는다:

• "이 로드맵으로 실행해도 될까요?"
• 수정 요청이 있으면 반영 후 재확인
• 승인 없이 Phase 4로 넘어가지 않는다

---

Phase 4: 병렬 실행

승인된 로드맵을 기반으로 병렬 에이전트를 실행한다.

4-1. 작업 분할 원칙

원칙	설명
독립성	각 에이전트가 서로 다른 파일을 수정한다
자족성	필요한 모든 정보를 프롬프트에 포함한다
일관성	톤, 포맷, 용어 기준을 프롬프트에 명시한다
적정 크기	에이전트 하나당 파일 1~2개가 적정

4-2. 에이전트 프롬프트 필수 포함 사항

[역할 설명]

## 작업 대상
파일 경로: [출력 파일 경로]
제목: [제목]
소속: [Part/Section 정보]

## 기존 콘텐츠 (있을 경우)
[기존 내용 전문 — 요약이나 생략 금지]

## 변경 사항
1. [구체적 변경 1]
2. [구체적 변경 2]

## 통일 포맷
[프로젝트 전체에 적용되는 포맷 규칙]

## 톤/스타일 가이드
[기존 콘텐츠의 문체나 코드 스타일 — 예시 포함]

## 교차 참조
[다른 항목과의 연결 관계]

## 출력 요구사항
- 전체 내용을 작성할 것 (요약/생략 금지)

4-3. 실행 배치 전략

배치 1: 독립 작업들 (최대 6~12개 에이전트, run_in_background=true)
    ↓ 완료 대기
배치 2: 배치 1 결과 참조 필요한 작업 (있을 경우)
    ↓ 완료 대기
배치 3: 통합 작업 (부록, 인덱스, 교차 참조 등)

4-4. 진행 상황 추적

에이전트 완료 알림이 올 때마다 표로 상태를 업데이트하고 사용자에게 보고한다:

| 항목 | 작업 내용 | 상태 |
|------|-----------|------|
| Item 1 | ... | ✅ 완료 |
| Item 2 | ... | ⏳ 실행 중 |

---

Phase 5: 검증 및 정리

5-1. 파일 정리

# 기존 파일을 _old/ 폴더로 이동 (삭제하지 않음!)
mkdir -p _old/
mv [기존파일들] _old/

절대 기존 파일을 삭제하지 않는다. 반드시 _old/로 백업한다.

5-2. 검증 체크리스트

• 모든 에이전트가 파일을 정상 생성했는가
• 항목 간 교차 참조가 올바른가 (다음/이전 링크)
• 용어가 전체적으로 일관되는가
• 통일 포맷이 모든 항목에 적용되었는가
• 기존 파일이 _old/에 백업되었는가

5-3. 최종 보고

## 실행 완료 보고

### 파일 구조
[최종 파일 트리]

### 주요 변경 요약
- 신설: [새로 만든 항목]
- 재배치: [순서가 바뀐 항목]
- 보강: [내용이 추가된 항목]
- 수정: [수정된 사항]

### 차별화 포인트
[로드맵에서 합의된 차별화 포인트 재확인]

---

Customization Points

AI 역할 변경

프로젝트 유형에 따라 역할을 조정할 수 있다:

프로젝트 유형	codex-cli 역할	Claude 역할
책/콘텐츠	구조 비평가	차별화 전략가
API 설계	보안/성능 감사	DX/UX 제안자
코드 아키텍처	기술 부채 분석	확장성 설계자
커리큘럼	교육학 비평	학습 경험 설계

규모 조절

프로젝트 규모	토론 라운드	병렬 에이전트 수
소 (파일 5개 이하)	1라운드	3~5개
중 (파일 10~15개)	2라운드	6~10개
대 (파일 20개 이상)	2~3라운드	배치별 8~12개

codex 없이 사용 (자동 폴백)

codex가 설치되지 않았거나 quota가 소진된 경우, Phase 2의 폴백 경로(2-5)가 자동으로 발동한다:

• 사전 점검에서 MISSING:codex 감지 시 사용자에게 폴백/중단 선택 요청
• 실행 중 quota 패턴 감지 시 재시도 없이 즉시 Claude Agent 툴로 대체
• 일반 에러 시 1회 재시도 후 실패하면 Claude Agent 툴로 대체
• 모든 폴백 결과에는 > ⚠️ 폴백: ... 헤더와 토론 요약 표 (Claude 폴백) 표기가 붙음

중요: 폴백은 예외 경로다. codex가 설치·작동 가능한 환경에서는 절대 폴백을 기본값으로 쓰지 않는다 (사용자가 codex라는 진짜 다른 모델의 관점을 받지 못하게 됨).

---

Red Flags

Never:

• 토론 없이 바로 실행하지 않는다 — 편향된 결과가 나온다
• 에이전트 프롬프트에 기존 콘텐츠를 생략하지 않는다 — 톤/스타일 불일치가 생긴다
• 기존 파일을 삭제하지 않는다 — 반드시 _old/로 백업한다
• 3라운드 이상 토론하지 않는다 — 수렴하지 않으면 사용자 판단을 받는다
• 한 에이전트에 3개 이상 파일을 맡기지 않는다 — 품질이 떨어진다
• 사용자 승인 없이 Phase 4를 시작하지 않는다
• Phase 2에서 codex가 작동 가능한데 Agent 툴(Claude 역할극)로 우회하지 않는다 — codex의 비판 입장까지 Claude가 대신하면 사실상 단일 모델 결과가 된다 (폴백은 미설치/quota/반복실패 시에만)
• quota 에러를 만나도 재시도하지 않는다 — 같은 에러가 반복되며 시간만 낭비된다. 즉시 폴백

Always:

• Phase 1에서 기존 콘텐츠를 충분히 읽는다
• Phase 2에서 codex CLI 바이너리를 Bash 툴로 직접 호출하고, 창의적 대안 입장은 Claude가 작성한다
• codex 호출 전 command -v codex로 존재를 확인한다
• 폴백이 발동되면 결과 파일과 로드맵 토론 요약에 폴백 사유를 명시한다
• 토론 결과에서 합의/비합의 사항을 명확히 구분한다
• 로드맵을 사용자에게 확인받은 후 실행한다
• 에이전트 프롬프트에 톤/스타일/포맷 가이드를 포함한다
• 실행 진행 상황을 실시간으로 사용자에게 보고한다

---

Example: 아카펠라 책 12챕터 재편성

Phase 1: 기존 10챕터 초안 + 외래어 기준표 분석 Phase 2: codex-cli(구조 비판) + Claude(차별화 전략) → 2라운드 토론 Phase 3: 12챕터 + 부록 로드맵 합성, 사용자 확인 Phase 4: 13개 에이전트 병렬 실행 (Ch1~Ch12 + 부록) Phase 5: 기존 파일 _old/ 이동, 외래어 기준표 업데이트, 최종 보고

결과: 10챕터 → 12챕터 재편성, 신설 2챕터, 전 챕터 보강, 부록 추가 — 약 30분 소요