에이전트 워크플로 설계: 일회성 대화에서 다단계 자동화로 · 1 / 6강

레슨 1: 대화에서 워크플로로: 오케스트레이션이 존재하는 이유

학습 목표:

단일 대화와 워크플로의 근본적인 차이 이해하기

워크플로에 맞는 작업이 어떤 특징을 갖는지 알아보기

워크플로 오케스트레이션의 핵심 가치 파악하기

전제: Claude Code나 비슷한 AI 도구를 사용해 본 적이 있다 | 다음: 레슨 2 >>

에이전트가 벽에 부딪힌다

Claude Code에게 큰 코드베이스의 리팩터링을 맡깁니다. "이 5,000줄짜리 모놀리스를 마이크로서비스로 쪼개 주세요."

Claude가 작업을 시작합니다. 파일을 읽고, 모듈 경계를 찾아내고, 의존 관계를 뽑아냅니다. 그러다 47번째 파일 언저리에서 컨텍스트 윈도가 가득 찹니다. 앞에서 무엇을 했는지 잊어버리고, 처음부터 다시 시작하고, 루프에 빠집니다.¹

또는 "열려 있는 PR을 전부 리뷰하고 이번 주 릴리스 노트를 써 주세요"라고 요청합니다. Claude는 한 번에 PR 하나씩만 처리할 수 있으므로, 여러분은 손으로 20번을 돌리면서 매번 형식 규칙을 다시 설명하게 됩니다.

이것이 단일 대화의 한계입니다. 하나의 대화, 하나의 컨텍스트 윈도, 하나의 추론 사슬. 복잡한 작업 앞에서 이 방식은 무너집니다.²

워크플로란 무엇인가

워크플로는 복잡한 작업을 여러 단계로 쪼개고, 각 단계를 새 에이전트에게 위임하고, 그 전체를 스스로 조율하는 실행 가능한 스크립트입니다.³

핵심적인 차이는 이렇습니다.

구분	단일 대화	워크플로
제어 흐름	다음에 무엇을 할지 에이전트가 정한다	다음에 무엇을 할지 스크립트가 정한다
컨텍스트	모든 이력이 하나의 윈도에 쌓인다	각 단계가 자기만의 컨텍스트를 갖는다
병렬성	순차적으로 실행된다	여러 에이전트를 한꺼번에 띄울 수 있다
재현성	실행할 때마다 달라질 수 있다	스크립트가 고정되어 결정론적으로 실행된다
맞는 규모	작은 작업(파일 몇 개)	큰 작업(수백 개 파일, 여러 단계의 검증)

예를 들어 리팩터링 워크플로는 이런 모습일 수 있습니다.

JAVASCRIPT

// 의사 코드 예시
async function refactorWorkflow(codebase) {
  // 1단계: 모든 모듈을 병렬로 분석
  const modules = await Promise.all(
    codebase.files.map(file => 
      agent({ task: `${file}의 책임과 의존 관계를 분석` })
    )
  );
  
  // 2단계: 마이크로서비스 경계를 제안
  const plan = await agent({ 
    task: '분석 결과를 바탕으로 마이크로서비스 경계를 설계',
    context: modules 
  });
  
  // 3단계: 각 서비스를 병렬로 추출
  const services = await Promise.all(
    plan.services.map(svc => 
      agent({ task: `${svc.name} 서비스의 코드를 추출` })
    )
  );
  
  // 4단계: 모든 서비스의 테스트가 통과하는지 검증
  return await agent({ 
    task: '모든 서비스의 테스트 스위트를 실행',
    context: services 
  });
}

루프와 분기와 중간 결과는 스크립트가 쥐고 있고, Claude의 컨텍스트에는 최종 답만 들어옵니다. 오케스트레이션은 결정론적이고, 모델이 주도하는 것은 각 단계 안의 작업뿐입니다.³

언제 워크플로가 맞는가

워크플로에 맞는 작업에는 네 가지 특징이 있습니다.

하나의 대화가 조율할 수 있는 것보다 에이전트가 많다. 단일 대화는 서브에이전트를 3~5개까지 다룰 수 있고, 그 이상은 워크플로가 필요합니다.
오케스트레이션을 읽고 재사용할 수 있는 스크립트로 굳히고 싶다. 한 번 써 두고 언제든 다시 돌립니다.
작업이 명확한 단계로 나뉜다. 분석, 계획, 구현, 검증.
병렬 실행이나 교차 검증이 필요하다. 독립적인 하위 작업, 적대적 검증, 토너먼트식 비교.

공식 문서는 이를 분명하게 말합니다. "Reach for a workflow when a task needs more agents than one conversation can coordinate, or when you want the orchestration codified as a script you can read and rerun."(하나의 대화가 조율할 수 있는 것보다 많은 에이전트가 필요하거나, 오케스트레이션을 읽고 다시 돌릴 수 있는 스크립트로 굳히고 싶을 때 워크플로를 꺼내라)²

전형적인 시나리오는 이렇습니다.

코드베이스 감사. 500개 파일을 훑으면서 파일당 에이전트 하나가 보안 문제를 점검하고, 그 결과를 취합합니다.
대규모 마이그레이션. 200개 컴포넌트를 Vue 2에서 Vue 3로 병렬 업그레이드하고, 마지막에 통합을 검증합니다.
교차 검증 리서치. 에이전트 5개가 같은 질문을 독립적으로 조사하고, 사실을 교차 확인해 일관성 보고서를 냅니다.
다각도 설계 리뷰. 하나의 설계를 세 관점(아키텍처, 성능, 비용)에서 독립적으로 평가한 뒤 합칩니다.²

워크플로가 맞지 않는 경우도 있습니다.

단순한 단일 파일 수정이나 코드 리뷰처럼 직접 대화하면 충분한 일.
창작 글쓰기나 브레인스토밍처럼 끝이 열려 있는 일.
사람의 판단이 많이 필요해 단계로 환원되지 않는 일.

워크플로는 어떻게 진화했는가

워크플로는 난데없이 나타나지 않았습니다. Claude Code 오케스트레이션 능력의 네 번째 단계입니다.¹

1단계: 모놀리식 에이전트

┌─────────┐│ Claude  │  하나의 컨텍스트 윈도가 모든 것을 처리한다:└─────────┘  읽기, 계획, 편집, 테스트

┌─────────┐│ Claude  │  하나의 컨텍스트 윈도가 모든 것을 처리한다:└─────────┘  읽기, 계획, 편집, 테스트

2단계: 서브에이전트 팬아웃(Agent 도구)

┌─────────┐│ Claude  │──→ agent: "코드베이스 검색"│ (main)  │──→ agent: "이 40개 파일 읽기"└─────────┘  결과가 부모 에이전트로 돌아간다

┌─────────┐│ Claude  │──→ agent: "코드베이스 검색"│ (main)  │──→ agent: "이 40개 파일 읽기"└─────────┘  결과가 부모 에이전트로 돌아간다

3단계: 에이전트 팀

┌─────────┐    ┌─────────┐    ┌─────────┐│ Planner │───→│ Coder   │───→│ Tester  │└─────────┘    └─────────┘    └─────────┘     각 에이전트가 자기 역할과 컨텍스트를 유지한다

┌─────────┐    ┌─────────┐    ┌─────────┐│ Planner │───→│ Coder   │───→│ Tester  │└─────────┘    └─────────┘    └─────────┘     각 에이전트가 자기 역할과 컨텍스트를 유지한다

4단계: 워크플로 오케스트레이션

    ┌─────────────────┐    │ Workflow Script │  루프, 분기, 상태를 담는다    └────────┬────────┘         ┌───┴───┬───────┬───────┐         ↓       ↓       ↓       ↓    agent()  agent() agent() agent()    각 호출이 독립적인 서브에이전트를 띄운다

    ┌─────────────────┐    │ Workflow Script │  루프, 분기, 상태를 담는다    └────────┬────────┘         ┌───┴───┬───────┬───────┐         ↓       ↓       ↓       ↓    agent()  agent() agent() agent()    각 호출이 독립적인 서브에이전트를 띄운다

워크플로의 핵심 혁신은 제어 흐름의 반전입니다. 에이전트가 "다음에 무엇을 할까"를 정하게 두는 대신, 스크립트가 "다음에 어떤 에이전트를 부를까"를 정합니다.³

오케스트레이션의 본질

오케스트레이션은 말 그대로의 뜻입니다. "one score, many musicians. A script deciding it — for loop, if statement — is orchestration."(하나의 악보, 여러 연주자. 스크립트가 그것을 정하는 것 — for 루프, if 문 — 이 오케스트레이션이다)¹

워크플로에서는 이렇습니다.

악보 = 여러분이 쓰는 JavaScript/TypeScript 스크립트, 그 안의 for 루프와 if 문과 Promise.all 호출.
연주자 = 각 agent() 호출이 띄우는 서브에이전트.
지휘자 = 악보에 따라 에이전트를 조율하는 스크립트의 실행 엔진.

그 구분을, 이 개념에 이름을 붙인 가이드의 말로 옮기면 이렇습니다. "A normal agent decides the control flow as it goes. A workflow inverts that. You write the control flow as plain code, and each individual step is delegated to a fresh subagent."(보통의 에이전트는 진행하면서 제어 흐름을 정한다. 워크플로는 그것을 뒤집는다. 제어 흐름을 평범한 코드로 쓰고, 각각의 단계는 새 서브에이전트에게 위임한다)

보통의 에이전트는 실행 중에 즉흥적으로 움직입니다. "먼저 A를 하고, 그다음 B를 할지 C를 할지 정한다." 워크플로는 제어 흐름을 코드에 못 박습니다. "A1~A10을 병렬로 돌리고, 전부 끝나면 B를 한다. B가 score > 0.8을 반환하면 C를, 아니면 D를 한다."

결정론적 오케스트레이션이 가져다주는 것은 이렇습니다.

예측 가능하다. 같은 입력이면 같은 실행 경로.
디버그하기 쉽다. 어느 단계가 실패했는지 훤히 보인다.
다시 돌릴 수 있다. 스크립트는 .claude/workflows/에 있고 이름으로 부를 수 있다.
확장된다. 에이전트를 10개에서 100개로 늘리는 일은 루프 횟수를 바꾸는 것뿐이다.³

첫 워크플로 시나리오: 코드 리뷰 파이프라인

실제 사례를 하나 봅시다. 팀에 리뷰를 기다리는 PR이 15개 있고, PR마다 네 가지를 점검해야 합니다.

코드가 스타일 가이드를 따르는가?
눈에 띄는 버그가 있는가?
테스트 커버리지가 충분한가?
관련 문서가 갱신되었는가?

단일 대화로 하면 15번을 돌리면서 매번 손으로 PR을 바꿔 줘야 합니다.

워크플로로 하면 이렇습니다.

JAVASCRIPT

async function reviewPRsWorkflow(prList) {
  // 1단계: 모든 PR을 병렬로 리뷰
  const reviews = await Promise.all(
    prList.map(pr => 
      agent({
        task: `PR #${pr.number} 리뷰`,
        prompt: `코드 스타일, 잠재적 버그, 테스트, 문서를 점검.
                 JSON 출력: { style: score, bugs: [], 
                 coverage: number, docs: boolean }`
      })
    )
  );
  
  // 2단계: 보고서 취합
  return await agent({
    task: '주간 보고서 생성',
    prompt: `PR ${reviews.length}건의 리뷰 결과를 바탕으로
             이번 주 코드 품질 보고서를 작성하고,
             문제를 심각도 순으로 정렬`
  });
}

이 워크플로가 가져다주는 것은 이렇습니다.

PR 15개를 병렬로 리뷰해 순차 실행보다 15배 빠릅니다.
리뷰 기준이 일정합니다(모든 PR이 같은 프롬프트를 씁니다).
매주 자동으로 돌 수 있고, 손이 갈 일이 없습니다.
스크립트를 Git에 커밋해 팀 전체가 공유합니다.

다음: 레슨 2 >> — 워크플로의 구성 요소: 단계, 상태, 분기, 루프

ClaudeWorld: What Is a Workflow? Multi-Agent Orchestration Explained — https://claude-world.com/articles/what-is-a-workflow-multi-agent-orchestration/ ↩ ↩² ↩³
Claude Code 문서: Workflows — https://code.claude.com/docs/en/workflows ↩ ↩² ↩³
Alex Op: Claude Code Workflows and Deterministic Orchestration — https://alexop.dev/posts/claude-code-workflows-deterministic-orchestration/ ↩ ↩² ↩³ ↩⁴

연습

지난 한 주의 업무를 돌아보며 반복적인 작업을 하나 찾고, 그것이 워크플로에 맞는지 판단해 보세요.

레벨 1: 첫 워크플로 시나리오 찾기

판단 기준:

비슷한 입력을 여러 개 처리해야 한다(파일 여러 개, 데이터 소스 여러 개, 서비스 여러 개)
명확한 단계가 있다(추출, 변환, 검증, 출력)
그 과정이 매번 똑같이 실행되기를 바란다
일부 또는 전부를 병렬로 돌릴 수 있다

적어 볼 것:

그 작업을 한 문장으로
지금은 어떻게 하고 있는지
워크플로로 만든다면 어떤 단계로 나뉘는지
시간이 얼마나 절약될 것 같은지

완료 기준 · 로컬에서 확인

시나리오가 분명하게 서술되어 있고, 단계 구분이 타당하며(3~5개), 병렬 실행이 도움이 되는 지점을 짚어냈고, 시간 추정에 근거가 있다(예: "지금은 파일 10개를 순차로 처리해 30분이 걸리고, 병렬로 하면 5분이 될 것으로 본다").

아래 두 시나리오 중 하나를 골라, 왜 하나는 단일 대화에 맞고 다른 하나는 워크플로에 맞는지 설명해 보세요.

레벨 2: 단일 대화와 워크플로 비교하기

시나리오 A: 로직이 명확한 50줄짜리 함수의 버그를 고친다.

시나리오 B: 컴포넌트 30개짜리 UI 라이브러리를 Material-UI v4에서 v5로 업그레이드한다.

판단과 근거를 적어 보세요(시나리오당 2~3문장).

완료 기준 · 로컬에서 확인

시나리오 A가 단일 대화에 맞고(작업 규모가 작고, 컨텍스트를 감당할 수 있고, 병렬성이 필요 없다) 시나리오 B가 워크플로에 맞는다는 것을(규모가 크고, 분해할 수 있고, 병렬화할 수 있다) 올바르게 짚어냈다. 정의를 되풀이하는 대신 "왜"를 설명했고, 워크플로의 구체적인 이점(병렬성, 일관성, 재현성)을 하나 이상 짚었다.

레슨 1: 대화에서 워크플로로: 오케스트레이션이 존재하는 이유

에이전트가 벽에 부딪힌다

워크플로란 무엇인가

언제 워크플로가 맞는가

워크플로는 어떻게 진화했는가

오케스트레이션의 본질

첫 워크플로 시나리오: 코드 리뷰 파이프라인

Footnotes

연습

지난 한 주의 업무를 돌아보며 반복적인 작업을 하나 찾고, 그것이 워크플로에 맞는지 판단해 보세요.

아래 두 시나리오 중 하나를 골라, 왜 하나는 단일 대화에 맞고 다른 하나는 워크플로에 맞는지 설명해 보세요.