멀티 에이전트 워크플로 — Claude Code + Codex CLI 협업 패턴

AI 에이전트 1개로 일하던 사람이 2개 이상을 조합하기 시작하면 가장 먼저 깨지는 건 "같은 컨텍스트를 공유한다"는 가정이다. 사람끼리 일할 때는 슬랙·미팅·옆자리로 빈틈을 메우지만, 에이전트들은 그러지 못한다. 위임은 약속이 아니라 코드로 강제된 게이트로 표현되어야 한다.

이 가이드는 Claude Code (메인 에이전트) + Codex CLI (서브 에이전트) 조합으로 1주일 이상 일해 본 경험에서 정리한 패턴이다. 다른 조합(Cursor + Claude Code, Aider + Claude Code 등)에도 동일하게 적용된다.

TL;DR

1. 역할 분담 — 분석/계획/지시는 Opus(메인) · 실행은 Sonnet/Codex(서브). 같은 일을 두 번 시키면 결과가 갈린다.
2. 위임서를 만든다 — 사람용 슬랙 메시지가 아니라, 다른 에이전트가 단독으로 읽고 실행 가능한 자기완결 문서.
3. 검증 게이트를 코드로 묶는다 — npm run verify:{phase} 같은 스크립트 + CI 통과 없으면 머지 불가. 약속만으로 격차는 누적된다.
4. One Task Per Agent — 서브에이전트 결과는 맹목적으로 신뢰하지 않는다. 머지 전 메인이 직접 재실행.

왜 멀티 에이전트인가

에이전트 1개로 충분한 일도 많다. 단일 파일 수정, 짧은 리팩토링, 코드 리뷰. 그러나 다음 상황에서는 멀티 에이전트가 빠르다:

• 병렬화 가능한 독립 작업 — 프론트 + 백엔드 + 마이그레이션을 동시에 진행
• 모델 특성을 살리는 분할 — 추론(Opus)과 실행(Sonnet/GPT)을 분리해 비용·속도 최적화
• 컨텍스트 격리 — 큰 코드베이스에서 메인 에이전트의 컨텍스트가 오염되지 않도록 서브에 위임
• 검증의 독립성 — 작성자와 검증자가 분리되어야 객관성이 생긴다

반대로 멀티 에이전트가 손해인 경우:

• 작업이 한 파일에 모이는 경우 — 충돌·머지 비용이 협업 이득을 잡아먹는다
• 컨텍스트가 매우 좁고 짧은 경우 — 위임서 만드는 시간이 작업 시간보다 길다
• 변경 명세가 모호한 경우 — 모호한 채로 위임하면 두 에이전트가 다른 해석으로 가버린다

1. 역할 분담 — 누구에게 무엇을

가장 흔한 실수는 "둘 다 똑같이 일 시키기". 결과가 갈리고 어느 쪽도 책임지지 않는다.

권장 분담:

같은 사람이 메인과 서브 모두를 운영하더라도 세션을 분리한다. 메인이 자기 컨텍스트로 자기 결과를 검증하면 객관성이 사라진다.

메인이 직접 할 일

• 계획 수립 + 트레이드오프 평가 + 대안 검토
• "왜 이 방향인가"의 근거 정리
• 위임서 작성
• 서브의 결과 머지 전 검증 (재실행, 게이트 raw output 확인)

서브에게만 시킬 일

• 명확히 정의된 작업 — 입력·출력·acceptance가 위임서에 떨어진 것
• 반복적 CLI 작업 (빌드, 테스트, 마이그레이션 실행)
• 큰 코드베이스 grep/find — 메인 컨텍스트 보호

절대 둘 다 시키지 말 것

• "이거 어떻게 할지 정해서 알려줘" — 둘이 다른 답을 가져와서 다시 통합해야 함
• "코드 짜고 검증도 해줘" — 자기가 짠 코드를 자기가 검증하면 같은 사각지대를 놓침

2. 위임서(Handoff Document) 패턴

위임서는 다른 에이전트가 이 메시지만 읽고 작업을 끝낼 수 있는 자기완결 문서다. 슬랙 메시지나 짧은 프롬프트가 아니다.

필수 섹션

# Phase X — {작업 제목}
 
## 목표
{한 문장으로 무엇을 끝내는가}
 
## 컨텍스트
- 관련 파일: `src/foo.ts:42`, `tests/foo.test.ts`
- 선행 작업: PR #123 머지됨, RFC-005 채택됨
- 외부 의존: API 스펙 `docs/api.md` v2
 
## 작업 범위
1. {파일 A} 에서 {함수 B} 시그니처 변경
2. {파일 C} 에 신규 함수 D 추가
3. {파일 E} 의 테스트 4개 갱신
 
## 비-목표
- {유혹받기 쉬운 확장} 하지 말 것 (다음 phase 작업)
- {리팩토링 유혹} 하지 말 것 (별도 PR)
 
## Acceptance
- [ ] `npm run verify:phase-X` 통과
- [ ] `npm run typecheck` clean
- [ ] PR diff 라인 수 < 300 (큰 수정은 더 작게 쪼개기)
 
## 검증 명령
\`\`\`bash
npm run verify:phase-X  # 본 phase 전용 게이트
npm test src/foo        # 단위 테스트
\`\`\`
 
## 막히면
- 3번 같은 에러로 막히면 메인에게 보고 (자체 무한 루프 금지)
- 외부 의존 API 응답이 다르면 즉시 보고 (가짜 응답으로 우회 금지)
 
## 작성자 / 일자
csmarch · 2026-05-12

핵심 원칙

1. 자기완결 — 위임서만 보고 작업 가능해야 함. "그건 슬랙에서 얘기했잖아"는 무효
2. 범위와 비-범위를 함께 명시 — 서브가 좋은 의도로 확장하는 사고 차단
3. acceptance는 코드 — "잘 동작하면 OK" 대신 npm run verify:phase-X 같이 자동 게이트
4. 막히면 보고 규칙 — 무한 루프 자체 디버깅 시간 제한 명시

위임서의 길이는 작업 크기에 비례한다. 1줄짜리 작업에 100줄짜리 위임서를 쓰면 손해다. 5+파일 또는 새 모듈은 위임서 필수, 1~2파일 버그 수정은 채팅 한 줄로 OK.

3. 검증 게이트 — 약속을 코드로 강제

가장 흔하고 가장 비싼 실수: "검증은 머지 후에 할게요".

작업이 끝났다고 보고하면 결과를 받은 메인은 그걸 신뢰하고 다음 phase로 넘어간다. 다음 phase에서 무언가 깨지면 이전 phase로 거슬러 올라가야 한다. 격차가 누적되면 결국 큰 catch-up 작업으로 폭발한다.

원칙: 위임서를 만들 때 검증 스크립트와 머지 게이트를 같은 PR에 묶는다.

게이트 3종

1. 로컬 검증 스크립트 — npm run verify:phase-X 또는 npm run verify:auth 등 작업별 전용 잡
2. CI gate — GitHub Actions / GitLab CI에서 verify:phase-X 자동 실행. 통과 못하면 머지 차단
3. 메인의 재실행 — 서브가 보낸 결과를 메인이 자기 환경에서 한 번 더 재현. 같은 결과 나와야 머지

예시 — verify:phase-X 스크립트

// package.json
{
  "scripts": {
    "verify:phase-A": "tsc --noEmit && eslint src/phase-a && jest src/phase-a --coverage",
    "verify:phase-B": "...",
    "verify:assets": "node scripts/check-asset-sha256.mjs"
  }
}

GitHub Actions 게이트 예시

# .github/workflows/ci.yml
name: CI
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
      - run: pnpm verify:assets   # phase별 verify도 동일 패턴

위임 완료 보고 형식

서브가 작업 끝났다고 보고할 때 다음을 첨부:

[Phase X 완료]
- 변경 파일: 5개 (src/foo.ts, ...)
- verify raw output:
  $ npm run verify:phase-X
  ✓ tsc clean
  ✓ eslint clean
  ✓ jest 23 passed
- PR: #234

raw output이 없는 보고는 다시 요청한다. "잘 됐어요"라는 텍스트는 신뢰하지 않는다.

4. One Task Per Agent — 결과를 그대로 믿지 말 것

서브가 보낸 결과를 메인이 받자마자 다음 작업으로 진행하면 안 된다. 다음 3가지를 메인이 직접 한다:

1. 재실행 — 서브가 보낸 verify raw output을 신뢰하지 않고 메인이 자기 머신에서 같은 명령 실행. 결과가 다르면 추적 (환경 차이? race condition? 캐시?)
2. Diff 리뷰 — PR diff를 사람 코드 리뷰 수준으로 직접 확인. 범위 외 변경, 주석 누락, 테스트 부재 등
3. 반례 시도 — acceptance 외에 "이게 깨지면 안 되는데?" 케이스 1~2개 직접 실행

이 단계는 서브의 능력을 의심해서가 아니라, 에이전트가 자기 컨텍스트의 사각지대를 못 본다는 본질적 한계 때문이다. 사람도 자기 코드 리뷰는 못 한다.

5. 실패 사례에서 배운 교훈

사례 — 위임서만 있고 게이트 없던 phase

상황: UI 재설계 phase D 위임. 위임서에 acceptance 8개 명시. 서브가 "다 됐어요" 보고. 메인이 머지. 다음 phase 작업 시작.

문제: phase D의 4번째 acceptance가 실제로는 통과하지 않은 상태였다 (서브가 부분 구현 후 자체 OK 판단). 다음 phase E에서 phase D 기능 사용 시 깨졌고, phase E 디버깅 도중 phase D로 거슬러 올라가야 했다. 추가로 phase F까지 동일한 패턴 누적.

복구: phase D~F catch-up 작업 별도 phase로 만들고 verify:phase-D 스크립트를 사후 작성. 게이트가 있었다면 처음에 통과 못 했을 것.

교훈: 위임서에 acceptance만 적고 검증 스크립트를 만들지 않으면 약속이 떠다닌다. 위임서 + 검증 스크립트 + CI 게이트는 같은 PR에 묶는다.

사례 — 자체 무한 루프

상황: 서브에게 "테스트 깨지면 고쳐" 위임. 서브가 자기 코드 보고 안 보이는 버그를 5번 시도. 매번 새 에러. 1시간 후 보고: "여러 가지 시도했는데 안 됩니다"

문제: 막힘 보고 시간 규칙이 없었다. 서브는 도움 요청 시점을 정할 기준이 없어서 끝없이 시도.

복구: 위임서에 "3회 같은 에러로 막히면 즉시 보고" 명시. 메인이 컨텍스트 보고 다른 가설 제시.

교훈: 막힘 규칙을 위임서에 명시. "끝까지 해봐" 대신 "3회 실패 시 보고".

6. 시작 체크리스트

처음 멀티 에이전트로 넘어가는 1주일:

1. 메인 에이전트의 페르소나/규칙 정리 — CLAUDE.md 또는 동등 파일에 역할, 자율 권한, 금지 사항, 코드 스타일 명시
2. 서브 에이전트 1개로 시작 — Codex CLI 또는 Sonnet 서브에이전트. 처음부터 3~4개 띄우지 말 것
3. 첫 위임서를 짧게 만들기 — 12파일 작업, acceptance 23개, verify 스크립트 1개
4. GitHub Actions에 verify gate 1개 등록 — phase 늘어날수록 추가
5. 막힘 규칙 적용 — 3회 실패 시 보고 + 메인 재검토
6. 회고 — 매 phase 끝에 무엇이 누락됐는지 1줄 메모. 위임서 템플릿이 점진적으로 진화

트러블슈팅

"위임서가 너무 길어서 작업할 의욕이 안 난다"

작업이 너무 크다는 신호다. phase를 더 작게 쪼개라. 위임서가 100줄을 넘어가면 작업이 1주일 이상 걸린다는 뜻이다.

"서브가 자꾸 범위 외 작업을 한다"

"비-목표(Non-goals)" 섹션 누락이거나 너무 추상적이다. "리팩토링하지 말 것"이 아니라 "src/legacy/ 디렉토리는 건드리지 말 것" 같이 구체적으로.

"검증 스크립트 만들 시간이 없다"

검증 스크립트는 코드 작성 후가 아니라 위임서 작성 시점에 같이 만든다. 위임서 acceptance를 그대로 verify:phase-X 스크립트의 assert 라인으로 옮긴다.

"두 에이전트 결과가 자꾸 충돌한다"

컨텍스트 격리가 안 됐다. 위임 범위가 서로 겹친다는 뜻이다. 위임서의 "작업 범위 — 파일 목록"이 명확히 분리되어야 한다. 같은 파일을 두 명이 동시에 만지면 사람이라도 충돌한다.

"메인이 너무 바빠진다"

서브에게 권한을 더 주는 게 답이 아니다. 검증·머지 결정은 메인이 유지해야 한다. 대신 위임서·게이트 자동화에 투자하고, 작업 자체를 줄이는 방향(범위 축소, 계획 단순화)을 우선 시도.

참고

• Claude Code 셋업 — 메인 에이전트 셋업이 먼저
• Anthropic 공식 — Claude Code subagents (서브에이전트 운영 모범사례)
• OpenAI Codex CLI — openai-codex GitHub

변경 이력

• 2026-05-12: 첫 작성. 1주일 이상 운영 경험을 6장 + 트러블슈팅 5종으로 정리.