멀티에이전트 파이프라인 — 슬래시 커맨드로 페이즈 묶기 | Claude한테 짜게 시키고 Codex한테 까게 시키기

이 챕터를 끝내면 "한 번 부르면 알아서 진행되는" 다단계 작업 흐름을 슬래시 커맨드로 정의할 수 있어요.

왜 파이프라인인가

같은 작업을 매번 손으로 진행하면 다음 문제가 쌓여요.

매번 빠뜨리는 단계가 생겨요 (스펙 동기화, 타입 생성, 린트…)
단계 순서가 흔들려요
advisory 리뷰를 까먹어요
사람마다 다르게 일해요

해결: 페이즈를 정의한 슬래시 커맨드 하나로 묶어서 매번 같은 흐름으로 진행해요.

페이즈 설계 원칙

각 페이즈는 다음 중 하나여야 해요.

블로킹 게이트 — 실패하면 전체 중단 (예: 린트, 빌드, 사용자 승인)
advisory 페이즈 — 실패해도 다음 페이즈 진행 (예: Codex 교차 리뷰)
사용자 승인 게이트 — 자동 진행 금지, 멈추고 사람 입력 대기 (예: 스펙 확정)

이 셋을 섞을 때 핵심은 advisory를 블로킹으로 만들지 않는 것이에요. advisory가 한 번이라도 다음 단계를 막으면 전체 워크플로우가 advisory 의존이 돼요.

슬래시 커맨드 한 벌 예시

.claude/commands/ship.md에 다음 같은 파이프라인을 정의한다고 가정해요.

# /ship — Implementation Pipeline

Run the full implementation flow for an approved spec.

Usage: /ship <spec-id>

## Pipeline

### Phase 0: 사전 동기화 (블로킹)
- 외부 스펙 sync 실행
- 실패 시 중단

### Phase 1: 기획 (사용자 승인 게이트)
- 기획 서브에이전트 호출 → 작업 계약서 생성
- **사용자 승인 대기** — 승인 없이 진행 금지

### Phase 2: 구현 (블로킹)
- 로직 서브에이전트 → API/훅/스키마
- 페이지 서브에이전트 → 위 결과를 조립

### Phase 3: 검증 (블로킹)
- 린트·타입 체크·테스트
- 자동 수정 시도 후 재실행 (최대 2회)

### Phase 3.5: 교차 리뷰 (advisory)
- 베이스 브랜치 결정 (`CODEX_BASE_BRANCH` env var 또는 fallback)
- `bash scripts/codex-review.sh --base "$BASE"` 호출 (JSON envelope 반환)
- `jq -r '.body'`로 본문 추출해 보고에 첨부
- CRITICAL 발견해도 **다음 페이즈 진행**

### Phase 4: 보고
- 페이즈별 결과 요약 출력
- Codex 결과는 advisory 섹션으로 분리해서 보여주기

Task: $ARGUMENTS

서브에이전트로 책임 분리

한 슬래시 커맨드 안에서 여러 서브에이전트를 부를 수 있어요. 분담하는 이유:

컨텍스트 격리 — 기획 페이즈가 잘못된 가정으로 길게 추론해도 구현 페이즈에 오염되지 않음
역할 강제 — 구현 에이전트는 새 훅을 짜지 못하게 시스템 프롬프트로 막아두기
재실행 단위 — 한 페이즈만 실패해도 그 페이즈만 다시 돌릴 수 있음

분담 예시:

기획자 — 스펙 읽고 작업 계약서 작성 (코드 X)
로직 빌더 — API 모듈, 훅, 스키마, 폼 검증
페이지 어셈블러 — 위 결과 조립만 (훅 재구현 금지)
검증자 — 토큰 준수, 인터랙션 상태, 타입, 린트
QA — 기능 정합성, 엣지 케이스

다섯 명을 한 슬래시 커맨드가 순서대로 부르는 셈이에요.

advisory 페이즈를 어디에 끼울지

검증(블로킹) 직후, 보고 직전이 가장 자연스러운 위치예요.

너무 이르면 — 아직 안정화 안 된 코드를 리뷰해서 노이즈가 많아져요
너무 늦으면 — 사용자가 결과를 안 봐요

순서: 구현 → 자체 검증 → advisory 교차 리뷰 → 보고

사용자 승인 게이트 패턴

기획 단계처럼 사람의 판단이 필요한 지점에는 자동 진행을 막는 명시적 게이트를 둬요. 슬래시 커맨드 본문에 다음 같은 룰을 박아둬요.

STOP HERE and wait for user approval. Do NOT proceed without explicit approval.

이 게이트가 없으면 에이전트가 본인 추론으로 다음 단계를 진행해버리는데, 잘못된 기획 위에 코드가 쌓여 회복 비용이 커져요.

안티패턴

하나의 거대한 페이즈 — 페이즈 사이 명시적 경계가 없으면 실패 지점을 못 찾아요
advisory를 게이트로 승격 — Codex 결과로 자동 차단하는 순간 전체 워크플로우가 advisory 의존
서브에이전트가 다른 서브에이전트의 작업을 덮어씀 — 시스템 프롬프트로 명시적 금지
사용자 승인 게이트 없이 기획 자동 통과 — 잘못된 가정 위에 구현 쌓임

다음 챕터 예고

슬래시 커맨드는 사람이 호출해야 동작해요. 다음 챕터에서 사람이 까먹어도 자동으로 advisory 리뷰가 돌게 만드는 pre-push hook을 붙여요.