| name | multi-agent-with-codex-gemini |
| description | gemini와 codex 두 agent를 parallel로 실행하여 편향 없는 다각도 분석. code review, documentation validation, architecture verification 등 프로젝트 전체 검증이 필요할 때 사용. 동일한 instruction을 두 agent에게 독립적으로 실행시켜 결과를 교차 검증. |
| version | 1.0.0 |
Multi-Agent with Codex & Gemini
gemini와 codex를 parallel로 실행하여 single-agent bias 제거 및 diverse perspective 확보
1. 전제조건
- gemini CLI 설치 및 인증
- codex CLI 설치 및 인증
- 두 agent를 foreground로 parallel 실행 (
& 사용 금지)
2. 핵심 기능
동일한 분석 작업을 gemini와 codex에 독립적으로 실행 후 결과 aggregation
2-1. 사용 시점
- Project-wide documentation consistency validation
- Code review (logic errors, inefficiencies, anti-patterns)
- Architectural decision verification
- Code vs documentation mismatch 찾기
- TODO 문서와 실제 구현 cross-reference
2-2. Parallel Execution 방법 (중요!)
절대 규칙: Task tool로 3개 subagent를 병렬 실행해야 한다.
Bash로 직접 CLI를 호출하면 순차 실행된다!
올바른 구조
main agent (Claude)
├─ Task 1 (parallel, run_in_background=true)
│ └─ Opus subagent: 직접 분석 수행
├─ Task 2 (parallel, run_in_background=true)
│ └─ subagent: Bash로 `codex exec "prompt"` 호출
└─ Task 3 (parallel, run_in_background=true)
└─ subagent: Bash로 `gemini -p "prompt"` 호출
→ 3개 완료 후, 필요시 main agent가 추가 검토
잘못된 구조 (순차 실행됨!)
main agent (Claude)
├─ Bash: codex exec "prompt" ← 완료까지 대기
└─ Bash: gemini -p "prompt" ← 그 다음 실행
실행 방법
하나의 응답에서 Task tool 3개를 동시 호출한다:
-
Task 1 (Opus): subagent_type="general-purpose", run_in_background=true
- prompt: "[review instruction]"
- Opus subagent가 직접 분석 수행
-
Task 2 (Codex): subagent_type="general-purpose", run_in_background=true
- prompt: "Run
codex exec with this prompt: [review instruction]"
-
Task 3 (Gemini): subagent_type="general-purpose", run_in_background=true
- prompt: "Run
gemini -p with this prompt: [review instruction]"
핵심: 3개 Task를 한 번의 응답에서 동시에 호출 → 병렬 실행 → 완료 후 main agent가 결과 aggregation (필요시 추가 검토)
3. Instruction Structure
세 agent 모두 동일한 instruction 제공
3-1. 기본 구조
[Task Description]
### 1. Context
- !git log --oneline -10
- !git diff --cached
- @README.md @todos/TODO_*.md
### 2. Exploration
- @component1/README.md @component2/README.md
- Explore beyond specified files to understand full project
### 3. Analysis Points
1. Issue Type A
2. Issue Type B
3. Issue Type C
### 4. Output
파일:라인 - 문제 유형 - 상세 설명
If no issues: "검토 완료: 이상 없음"
3-2. File Reference Syntax
@path/to/file.md - file content include@./ - current directory include!git diff - shell command 실행
4. Result Aggregation
세 agent의 결과를 비교하여 종합:
- Common findings (2개 이상 agent가 동일 지적): 신뢰도 높음, 수정 진행
- Unique findings (1개 agent만 지적): main agent가 직접 검증 후 사용자에게 보고
- 오탐 의심: 검증 결과 오탐으로 보이는 경우에도 사용자에게 보고하되, "검증 결과 오탐으로 판단됨" + 판단 근거를 함께 제시. 최종 판단은 사용자에게 맡김
5. 예시
5-1. Task tool 호출 예시 (Opus + Codex + Gemini 병렬)
main agent가 한 번의 응답에서 3개 Task를 동시 호출:
Task 1 - Opus:
- description: "Opus code review"
- subagent_type: "general-purpose"
- run_in_background: true
- prompt: "Review the shared_cache_dir implementation..."
Task 2 - Codex:
- description: "Codex code review"
- subagent_type: "general-purpose"
- run_in_background: true
- prompt: "Execute this command and return the result: codex exec 'Review the shared_cache_dir implementation...'"
Task 3 - Gemini:
- description: "Gemini code review"
- subagent_type: "general-purpose"
- run_in_background: true
- prompt: "Execute this command and return the result: gemini -p 'Review the shared_cache_dir implementation...'"
→ 3개 완료 후 main agent가 결과 aggregation, 필요시 추가 검토
5-2. Review Prompt 예시
Review the implementation for Issue #22.
### Context
@README.md
@operator/README.md
!git log --oneline -10
!git diff HEAD~3..HEAD
### Check
1. Logic errors
2. Performance issues
3. Code vs documentation mismatch
### Output
파일:라인 - 문제 - 설명
If no issues: "검토 완료: 이상 없음"
5-3. Documentation Review
gemini -p "Review README files for consistency.
### Check
1. Code vs doc mismatches
2. Broken links
3. 5W1H violations
### Files
@README.md @operator/README.md @client/README.md
Explore beyond these to understand full structure.
Output: 파일:라인 - 문제 - 설명"
codex exec "[... same prompt ...]"
5-4. Code Review
gemini -p "Review recent changes.
### Context
!git log --oneline -10
!git diff HEAD~3..HEAD
### Check
- Logic errors
- Performance issues
- Anti-patterns
- Missing error handling
Output: 파일:라인 - 문제 - 설명"
codex exec "[... same prompt ...]"
5-5. Architecture Verification
gemini -p "Verify TrialBatch implementation.
### Background
@docs/done_TODO_2025-11-06_trialbatch-refactor-unified.md
### Check
1. @operator/README.md: incorrect status markers
2. @operator/internal/controller/trialbatch_controller.go: actual logic
3. Code vs doc mismatch
Output: 파일:라인 - 문제 - 설명"
codex exec "[... same prompt ...]"
6. Best Practices
- Task tool 필수 - Bash 직접 호출 금지 (순차 실행됨)
- 3개 Task 동시 호출 - Opus/Codex/Gemini를 한 응답에서 병렬 실행
- run_in_background=true - 병렬 실행을 위해 필수
- 세 agent에 동일한 instruction 제공 (비교 가능한 결과)
- 명시된 파일 외에도 탐색하도록 명시적 지시
- 일관된 output format 요청 (aggregation 용이)
- 세 agent 모두 완료 대기 후 진행
- Result aggregation: common findings는 수정 진행, unique findings는 검증 후 보고, 오탐 의심도 판단 근거와 함께 보고
- TODO 문서 작성 시 agent findings를 background로 포함
- 필요시 main agent 추가 검토 - 3개 결과 확인 후 심층 분석 필요하면 main agent가 직접 수행
7. 결과 대기 방법 (중요!)
TaskOutput tool로 모든 task 완료 대기 → 1번만 취합
7-1. TaskOutput 사용법
block=true: task 완료까지 blocking 대기 (기본값)block=false: 즉시 현재 상태 반환 (non-blocking)timeout: 최대 대기 시간 (ms, 기본 30000, 최대 600000)
7-2. 올바른 대기 패턴
3개 Task 실행 후, 3개 TaskOutput을 동시 호출:
Step 1: Task 3개 동시 실행 (run_in_background=true)
├─ Task 1 (Opus) → task_id_1 반환
├─ Task 2 (Codex) → task_id_2 반환
└─ Task 3 (Gemini) → task_id_3 반환
Step 2: TaskOutput 3개 동시 호출 (block=true)
├─ TaskOutput(task_id_1, block=true, timeout=600000)
├─ TaskOutput(task_id_2, block=true, timeout=600000)
└─ TaskOutput(task_id_3, block=true, timeout=600000)
→ 3개 모두 완료될 때까지 대기
Step 3: 결과 취합 (딱 1번만!)
→ 3개 결과를 한꺼번에 받아서 aggregation
7-3. 잘못된 대기 패턴 (금지!)
# 잘못된 예시 1: sleep 사용
Bash: sleep 60 ← 불필요한 대기, 비효율적
# 잘못된 예시 2: 순차적 TaskOutput
TaskOutput(task_id_1) → 취합 ← 중간 취합 금지!
TaskOutput(task_id_2) → 취합 ← 중간 취합 금지!
TaskOutput(task_id_3) → 취합 ← 3번이나 취합함
# 올바른 예시: TaskOutput 3개 동시 호출
TaskOutput(task_id_1) ─┐
TaskOutput(task_id_2) ─┼→ 모두 완료 후 1번만 취합
TaskOutput(task_id_3) ─┘
7-4. timeout 권장 설정
- 코드 리뷰:
timeout=600000 (10분)
- 간단한 분석:
timeout=300000 (5분)
- timeout 발생 시 해당 agent 결과 없이 나머지로 취합
8. 주의사항
- Bash 직접 호출 절대 금지 - 순차 실행됨
- Task tool로 3개 subagent 생성 (Opus/Codex/Gemini)
- Codex/Gemini subagent는 내부에서 Bash로 CLI 호출
- sleep 사용 금지 - TaskOutput의 block=true 사용
- TaskOutput 3개 동시 호출 - 모든 agent 완료 대기
- 취합은 딱 1번만 - 3개 결과 수집 후 한꺼번에 aggregation
- 심층 분석 필요시 main agent가 추가 검토 수행
