Claude Code Workflow에서 복수 에이전트를 병렬로 실행하는 설계

서론

workflow라는 단어는 편리하지만, Claude Code에서는 이를 모호하게 사용하면 금방 파탄에 이릅니다. 실제로 수중에 있는 ~/.claude/를 다시 읽어보니, workflow는 '마법의 단일 기능'이 아니라 적어도 다음의 3개 계층으로 나뉘어 있었습니다.

• 기동을 허용하는 규칙
• 어떤 엔진에 무엇을 시킬 것인가에 대한 오케스트레이션 (Orchestration)
• 실제 태스크를 어떻게 단계화하고, 어디서 병렬화할 것인가에 대한 실행 절차

이 기사는 일반론이 아니라, 실제 파일로 확인한 ~/.claude/settings.json, ~/.claude/CLAUDE.md, ~/.claude/docs/workflow-orchestration.md, ~/.claude/agents/dev/SKILL.md, ~/.claude/agents/dev/references/workflow.md를 근거로 정리합니다.

우선 「workflow를 기동해도 좋은 상태」를 만든다

가장 먼저 작용하는 것은 ~/.claude/settings.json의 Hook입니다. TeamCreate에는 통상적으로 "Agent Team을 기동해도 되는지 확인하기 위한" prompt hook가 들어 있습니다. 즉, 복수 에이전트 실행은 기본적으로 자동 허용이 아닙니다.

한편 ~/.claude/CLAUDE.md에는 다음과 같은 예외 규칙이 있습니다.

• 프롬프트에 workflow / workflows를 포함하는 경우는 명시적 opt-in 취급 - 그 경우에는 Agent Team 기동 확인을 추가로 거치지 않고 진행해도 됨

이 부분이 중요합니다. 병렬화 그 자체보다 앞서, **"이것은 무거운 오케스트레이션 (Orchestration)을 돌려도 되는 의뢰인가"**를 명문화해 두었습니다. 실제 운용에서는 이 입구가 없으면 서브 에이전트(Sub-agent) 남발이 일어납니다.

workflow는 「누가 무엇을 담당할 것인가」의 배선도

다음으로 ~/.claude/docs/workflow-orchestration.md를 보면, workflow는 JavaScript의 DSL이라기보다 역할 분담 설계서로서 사용되고 있습니다. 정리하면 다음과 같습니다.

역할	주 담당
지휘·판단·통합·리뷰	Claude
...

게다가 이 분담은 추상론으로 끝나지 않습니다. 발동 조건까지 적혀 있습니다.

• 조사 대상 URL이 3개 이상
• 변경 대상 파일이 5개 이상
• 조사 → 분석 → 통합의 파이프라인 (Pipeline)형 태스크
• 대량의 텍스트 처리가 예상되는 경우

즉 workflow의 본체는 "병렬 실행을 하는 것"이 아니라, 어떤 일을 어떤 실행 계통으로 분리할지를 먼저 고정하는 것입니다.

문서 중의 플로우(Flow)도 상당히 실무적입니다.

Claude Code (사령탑)
├── 리서치 무거움 → Agent → gemini
├── 코드량 많음 → Agent → codex exec
...

이 구조라면 Claude를 coordinator로 고정한 채, 무거운 처리만 별도의 엔진으로 넘길 수 있습니다.

실제 dev agent는 「3회 병렬 리뷰 후 구현」에 치중되어 있다

더 구체적인 것이 ~/.claude/agents/dev/SKILL.md와 ~/.claude/agents/dev/references/workflow.md입니다. 여기서는 workflow가 구현 파이프라인 (Implementation Pipeline)으로 정의되어 있습니다.

흐름을 추출하면 다음 순서입니다.

• Planner가 서브 태스크 (Sub-task) 분해
• 3병렬 리뷰
• TEST PLAN 생성
• 3병렬의 테스트 망라성 리뷰
• worktree 생성
• codex-worker로 구현
• 테스트
• 최종 테스트 재실행
• 리뷰
• preview나 complete로 진행

특히 흥미로운 점은 병렬화의 위치입니다. 갑자기 구현을 fan-out 하는 것이 아니라, 먼저 리뷰 단계를 병렬화하고 있습니다.

workflow.md에서는 Plan 단계에서 다음 3가지 관점의 리뷰를 동시에 돌립니다.

• PM/Product 관점: 수락 조건과 스코프 (Scope)
• Technical/Architecture 관점: 입도(Granularity), 의존 관계, 타입이나 설계의 파탄
• Risk/Rollback 관점: 부작용, 위험도, 되돌리기 용이성

또한 TEST PLAN 이후에도 정상계(Normal case), 이상계(Abnormal case), E2E 통합의 3가지 관점에서 병렬 리뷰를 삽입합니다. 이는 구현을 앞당기기 위한 병렬화가 아니라, 되돌리기(Backtracking)를 줄이기 위한 병렬화입니다.

구현 담당은 Claude가 아니라 codex-worker에 집중시키고 있다

~/.claude/agents/dev/SKILL.md에서 명시되어 있었던 것은, 코드를 작성하는 작업을 상당히 강하게 codex-worker 쪽으로 몰아주고 있다는 점입니다.

• 구현 및 코드 생성
• 테스트 코드 생성
• 리팩터링 (Refactoring)
• 버그 수정

반대로 Claude 측은 Planner, 설계 판단, 리뷰, 게이트 관리(Gate management) 역할로 남겨두었습니다. 이 부분도 중요한데, 복수 에이전트 운용이 불안정해지는 원인은 "누가 최종 판단자인가"가 모호해지기 때문입니다. 역할을 고정해 두면 병렬화를 하더라도 책임 경계가 무너지기 어렵습니다.

이 설계에서 배운 점

가지고 있는 구성을 읽어본 결과, workflow의 가치는 "서브 에이전트(Sub-agent)를 동시에 돌릴 수 있다는 것" 그 자체에 있지 않습니다. 가치가 있는 것은 다음 3가지 지점입니다.

• 무거운 실행을 허용하는 진입 조건이 있다
• 사령탑, 구현, 조사의 담당이 나누어져 있다
• 구현 전 리뷰 단계에서 병렬화를 사용하고 있다

특히 3번째 지점이 효과적입니다. 구현을 병렬화하면 빨라 보이지만, 계획이나 테스트 관점이 허술하면 나중에 막히게 됩니다. 먼저 여러 관점에서 문제를 해결하는 것이 전체 Wall-clock time(실제 소요 시간)을 단축하는 경우가 상당히 많습니다.

Claude Code로 workflow를 구성한다면, 우선 "병렬 실행 API를 찾는 것"이 아니라, ~/.claude/에 있는 것과 같은 기동 조건, 역할 분담, 리뷰 단계의 병렬화를 먼저 설계하는 것이 더 안정적입니다. 제 환경에서 workflow는 코드가 아니라 운용 규칙으로서 먼저 존재하고 있었습니다.

관련 기사

Discussion