하나의 두뇌, 여러 개의 손: AI 에이전트를 위한 병렬 작업 오케스트레이터 (Parallel Task Orchestrator) 구축하기

아무도 말하지 않는 문제
AI 코딩 어시스턴트(AI coding assistants)는 빠릅니다. 터무니없이 빠르죠. 제가 커피 한 잔을 다 마시는 시간 동안 서비스를 스캐폴딩(scaffold)하고, 테스트를 작성하며, 모듈을 리팩터링(refactor)할 수 있습니다. 하지만 그들은 한 번에 한 가지 일만 합니다.

저는 마이크로서비스 감사 로깅(microservices audit logging) 시스템을 작업하고 있었습니다. 네 가지 작업이 있었고, 모두 독립적이며 범위가 명확했습니다: 이벤트 스키마(event schema) 구현, 인제스션 엔드포인트(ingestion endpoint) 구축, 쿼리 API(query API) 추가, 통합 테스트(integration tests) 작성.

시작부터 결승선이 보였습니다. 하지만 저는 마치 세탁기에 양말을 한 짝씩 손으로 집어넣는 것처럼, Claude Code 세션에 작업을 하나씩 차례대로 입력하며 앉아 있었습니다. 각 작업에는 에이전트 시간이 10~15분 정도 소요되었습니다. 네 가지 작업을 순차적으로 실행하면 한 시간이 걸립니다. 하지만 이 작업들은 순차적일 필요가 없었습니다. 서로 다른 파일, 서로 다른 관심사, 코드베이스의 서로 다른 부분을 다루고 있었기 때문입니다. 만약 저에게 네 명의 개발자가 있었다면, 네 가지 작업을 한꺼번에 할당하고 점심을 먹으러 갔을 것입니다. 그런데 왜 AI 에이전트로는 그렇게 할 수 없는 걸까요?

Stripe의 영감
2026년 3월 초, Stripe는 'Minions'라고 불리는 내부 시스템에 대한 블로그 포스트를 게시했습니다. 이는 작업을 병렬로 처리하는 원샷(one-shot), 엔드 투 엔드(end-to-end) 코딩 에이전트입니다. 핵심적인 통찰이 즉시 머릿속을 스쳤습니다: 더 똑똑한 에이전트가 필요한 것이 아닙니다. 약간은 멍청한 에이전트들을 궤도(rails) 위에 유지하는 방법을 아는 오케스트레이터(orchestrator)가 필요한 것입니다.

Stripe의 청사진 패턴은 우아했습니다: 에이전트 단계(코드를 작성하고 버그를 수정하는 창의적이고 예측 불가능한 부분)를 결정론적인 가드레일(deterministic guardrails, git 작업, 린팅(linting), 테스트) 안에 가두는 것입니다. 에이전트는 구현 과정에서 얼마든지 환각(hallucinate)을 일으킬 수 있지만, 테스트를 통과하지 못하면 다시 루프를 돕니다. 린트(lint)가 실패하면 수정합니다. 그리고 이 모든 과정은 제한됩니다: 최대 두 번의 시도 후 중단됩니다.

저는 AGI(인공 일반 지능)를 만들려고 했던 것이 아닙니다. 저는 건설 현장의 작업 반장(foreman)을 만들고 있었던 것입니다.

아키텍처: 전부 마크다운(Markdown)으로
여기서부터 조금 제정신이 아닌 부분이 나옵니다. 전체 오케스트레이터는 순수 마크다운(markdown)입니다. TypeScript 런타임도 없습니다. Python 글루(glue) 코드도 없습니다. 유지 관리하거나, 컴파일하거나, 디버깅할 코드가 전혀 없습니다.

Claude Code가 지침으로 불러오는 단 세 개의 마크다운 (markdown) 파일만 있으면 됩니다:

• 오케스트레이터 (Orchestrator, commands/minion.md): 두뇌입니다. 작업 목록을 파싱(parse)하고, 의존성 순서(dependency order)를 파악하며, 병렬 웨이브(parallel waves)를 계산하고, 워커(worker)를 생성합니다.
• 워커 (Worker, agents/minion-worker.md): 손입니다. 각 워커는 작업(task), git 워크트리 (git worktree), 그리고 따라야 할 청사진 (blueprint)을 할당받습니다.
• 청사진 (Blueprint, skills/minion-blueprint/SKILL.md): 레일입니다. 브랜치 생성, 구현, 린트 (lint), 테스트, 커밋 (commit), 보고로 이어지는 단계별 실행 패턴입니다.

저는 이것을 제로 코드 프롬프트 엔지니어링 (zero-code prompt engineering)이라고 부릅니다. 여기서 "코드"는 바로 프롬프트 (prompt)입니다. Claude Code는 마크다운 지침을 해석하고 내장된 도구들 (bash, 파일 편집, git)을 사용하여 이를 실행합니다. SDK도, API 호출도, 인프라 (infrastructure)도 필요 없습니다.

사용자 (인간)
└── Claude Code 세션 (오케스트레이터)
├── 워커-1 (워크트리: .worktrees/task-1)
├── 워커-2 (워크트리: .worktrees/task-2)
└── 워커-3 (워크트리: .worktrees/task-3)

각 워커는 격리된 git 워크트리 (git worktree)에서 실행됩니다. 이것이 핵심입니다. 워크트리는 저장소 (repo)를 병렬로 체크아웃 (checkout)하는 것과 같습니다. 즉, 동일한 git 히스토리를 가지되 작업 디렉토리 (working directory)는 서로 다릅니다. 워커-1이 src/api/events.ts를 편집하는 동안 워커-2가 src/api/queries.ts를 편집할 수 있으며, 이들은 서로의 영역을 침범하지 않습니다.

실제 작동 방식

작업 목록과 함께 오케스트레이터를 호출합니다:
/minion Tasks:
1. src/events/schema.ts에 Zod 검증을 포함한 이벤트 스키마 구현 (Implement event schema with Zod validation in src/events/schema.ts)
2. /api/events에 인제스션 (ingestion) POST 엔드포인트 구축 (depends on: 1)
3. 필터링 기능이 포함된 /api/events 쿼리 GET 엔드포인트 추가 (depends on: 1)
4. 두 엔드포인트 모두에 대한 통합 테스트 작성 (depends on: 2, 3)

오케스트레이터는 이를 읽고 의존성 그래프 (dependency graph)를 구축한 뒤 웨이브 (waves)를 계산합니다:

• 웨이브 1: 작업 1 (의존성 없음)
• 웨이브 2: 작업 2와 3 (둘 다 1에 의존하지만, 서로에게는 의존하지 않으므로 병렬로 실행됨)
• 웨이브 3: 작업 4 (2와 3에 의존함)

무언가를 생성하기 전에, 각 작업이 건드릴 가능성이 있는 파일 경로를 스캔하여 충돌 감지 (conflict detection)를 수행합니다. 만약 동일한 웨이브 내의 두 작업이 같은 파일을 편집하려 한다면, 충돌을 표시하고 이를 직렬화 (serialize)합니다. 그 후에 워커를 생성합니다.

각 워커는 다음을 할당받습니다:

• 현재 HEAD에서 분기된 새로운 워크트리 (worktree)
• 전체 컨텍스트가 포함된 작업 설명
• 키워드에 의해 자동 선택된 도메인 에이전트 오버레이 (domain agent overlay). "Endpoint"와 "API"는 backend-architect가 담당합니다. "React component"는 frontend-architect가 담당합니다. "Dockerfile"은 devops-engineer가 담당합니다.
• 현재 단계에 따른 역할 오버레이 (role overlay). 계획 (Planning) 단계인가요? researcher가 할당됩니다. 구현 (Implementing) 단계인가요? tdd-developer가 할당됩니다. 리뷰 (Reviewing) 단계인가요? code-reviewer가 할당됩니다.
• 자동 감지된 프로젝트 도구: package.json을 읽어 린트 (lint) 명령, 테스트 러너 (test runner), 빌드 스크립트를 찾아냅니다.

다음은 웨이브 기반의 병렬 실행 (wave-based parallel execution)을 통해 실제 12개의 작업을 수행하는 HAL 리팩토링의 실제 사례입니다. 각 워커가 따르는 청사진은 다음과 같습니다:

1. 베이스에서 브랜치 생성
2. 작업 구현 (에이전트 방식 — 여기서 창의성이 발휘됩니다)
3. 린트 실행. 실패 시 수정 (1회 시도)
4. 테스트 실행. 실패 시 수정 (1회 시도)
5. 수정 후에도 여전히 실패할 경우, 중단(STOP)하고 부분적인 진행 상황을 보고
6. 관습적인 커밋 메시지 (conventional commit message)로 커밋
7. 브랜치 푸시 및 PR 생성

최대 2회의 반복 (two-iteration maximum) 규칙은 신성불가침입니다. 이 규칙이 없다면, 에이전트는 연쇄적인 린트 에러를 수정하려고 영원히 루프를 돌 수 있습니다. 이 규칙이 있다면, 최악의 경우라도 명확한 상태 보고서가 포함된 부분적으로 완료된 PR이 남게 됩니다. 그리고 제가 배운 점이 하나 있습니다. 불완전한 실행이라도 여전히 훌륭한 시작점이 될 수 있다는 것입니다. "X 때문에 테스트가 실패함"이라는 명확한 메모와 함께 80% 완료된 PR은, 에이전트가 20분 동안 헛바퀴를 돌고 있는 것보다 무한히 낫습니다.

계획, 구현, 리뷰 단계로 전체 워크플로가 실행될 때의 모습은 다음과 같습니다:

첫 번째 실제 테스트 (그리고 첫 번째 실제 충돌)
저는 traza-microservicios라는 마이크로서비스 트레이싱 시스템이라는 실제 프로젝트에서 minion-toolkit을 테스트했습니다. 두 개의 작업, 두 개의 병렬 워커를 사용했습니다. Worker-2는 완벽하게 해냈습니다. 깨끗한 브랜치, 통과된 테스트, PR 준비 완료. Worker-1은... git이 손상되었습니다. 알고 보니 macOS에서 동시적인 git worktree 작업을 실행하면 SIGBUS 신호 — 즉 저수준 메모리 버스 에러 (low-level memory bus error)를 유발할 수 있었습니다. 두 프로세스가 동시에 refs를 업데이트하려고 할 때 git 인덱스 파일이 손상되는 것입니다. 이는 프롬프트 엔지니어링 (prompt engineering)이나 AI와는 전혀 상관없는 문제였습니다.

그것은 인간 개발자라면 거의 겪을 일이 없는 파일 시스템 동시성 (filesystem concurrency) 문제였습니다. 인간은 같은 초에 세 개의 워크트리 (worktree)를 생성하지 않기 때문입니다. 해결 방법은 별로 화려하지 않았습니다. 워크트리 생성 사이에 짧은 지연 시간을 추가하고, git 작업 시 --no-optional-locks 옵션을 사용하며, 최후의 수단으로 /tmp에 새로 클론 (clone)하여 그곳에서 작업하는 것이었습니다. 이것은 실제로 제품을 출시해 봐야만 배울 수 있는 종류의 교훈입니다. 그 어떤 설계 문서도 "macOS git worktrees는 병렬 에이전트 생성 시 레이스 컨디션 (race condition)이 발생한다"는 사실을 예측하지 못했을 것입니다.

고난을 통해 얻은 교훈들

머지 충돌 (Merge conflicts)이 1순위 문제입니다. AI 환각 (hallucination)도 아니고, 잘못된 코드도 아니며, 테스트 실패도 아닙니다. 가장 흔한 실패 모드는 두 명의 작업자 (worker)가 동일한 파일을 편집하는 것입니다. 에이전트를 생성하기 전에 충돌을 감지하는 기능이 제가 추가한 기능 중 가장 영향력이 컸습니다.

작업자들은 추가적인 파일들을 생성합니다. "엔드포인트를 추가하라"는 명령을 받은 에이전트는 유틸리티 모듈을 생성하거나, 배럴 익스포트 (barrel export)를 업데이트하거나, 타입 파일을 추가할 수도 있습니다. 이러한 범위를 벗어난 변경 사항들이 나중에 머지 충돌을 일으킵니다. 해결책은 전체 브랜치를 머지 (merge)하는 대신 특정 커밋 (commit)을 git cherry-pick 하는 것입니다.

gh pr checks는 거짓말을 합니다. GitHub CLI는 결론 (conclusion)이 아닌 버킷 (bucket) 필드를 사용하여 체크 상태를 보고합니다. 저는 왜 "통과 (passing)"된 PR이 실패로 표시되는지 궁금해하며 매우 창피할 정도로 많은 시간을 허비했습니다.

드라이 런 (Dry-run) 모드는 정신 건강을 지켜줍니다. 각각 토큰을 소모하는 4개의 병렬 작업자를 생성하기 전에, 어떤 파동 (waves)이 일어날지, 어떤 에이전트가 사용될지, 어떤 파일이 수정될지 미리 확인하십시오. --dry-run은 나중에 덧붙인 기능이었지만 일상적인 습관이 되었습니다.

비용 추적은 중요합니다. 병렬 작업자는 API 사용량을 배가시킵니다. 4개의 작업을 병렬로 실행하는 비용이 약 $2.50인 반면, 단일 순차 실행 비용이 약 $1.80라는 것을 아는 것은 언제 병렬 처리를 사용할 가치가 있는지 결정하는 데 도움이 됩니다.

(스포일러: 토큰보다 시간이 더 중요할 때, 거의 항상 그렇습니다.)

진화 과정

3월 4일에 200줄짜리 마크다운 (Markdown) 파일로 시작된 것이 3월 8일에는 제대로 된 오픈 소스 (Open-source) 도구로 성장했습니다.

버전	변경 사항
1.0	기본적인 오케스트레이터 (Orchestrator), 수동 작업 파싱 (Task parsing)
2.0	교차 단계 메모리 (Cross-phase memory), 드라이 런 (Dry-run), 워커 상태 모니터링 (Worker health monitoring)
2.1	충돌 방지 (Conflict prevention), 스마트 컨텍스트 수집 (Smart context gathering), 비용 추적 (Cost tracking)
2.2	MCP 선택적 위임 (Optional delegation), CLI 설치 프로그램 ( npx minion-toolkit install )
2.3	워크플로 (Workflows), 도메인 에이전트 (Domain agents), 역할 오버레이 (Role overlays), 의도 포착 (Intent capture), 정체 감지 (Stall detection)

CLI 설치 프로그램은 마크다운 자산들을 사용자의 ~/.claude/ 디렉토리로 복사하고 플러그인을 구성합니다. 단 한 번의 명령으로, 당신의 Claude Code 세션은 병렬 오케스트레이터 (Parallel orchestrator)가 됩니다:
npx minion-toolkit install

그 이후에는 모든 Claude Code 세션에서 /minion을 사용할 수 있습니다.

누구를 위한 도구인가?

만약 당신이 Claude Code를 사용 중이거나 사용할 계획이며, 병렬화가 가능한 작업들—여러 파일에 걸친 기능 개발, 다중 서비스 변경, 테스트 스위트 (Test suites), 문서화 배치 작업—을 정기적으로 수행한다면, 이 도구는 당신의 단일 스레드 (Single-threaded) AI 세션을 조율된 팀으로 바꿔줍니다. 특히 다음과 같은 경우에 유용합니다:

• 소규모 팀을 시뮬레이션하고 싶은 1인 개발자
• 범위가 잘 지정된 일련의 작업들을 위임하고 싶은 테크 리드 (Tech leads)
• AI 세션에 작업을 하나씩 입력하는 것에 지친 모든 사람

이 도구는 모든 파일이 서로에게 의존하는, 즉 매우 밀접하게 얽혀 있는 작업에는 적합하지 않습니다. 오케스트레이터는 웨이브 (Wave) 간의 의존성은 처리할 수 있지만, 하나의 웨이브 내에서 작업들은 반드시 독립적이어야 합니다. 만약 작업들을 병렬화할 수 없다면, 단일 세션을 사용하는 것이 여전히 올바른 방법입니다.

직접 시도해보기

전체 프로젝트는 오픈 소스입니다:

• GitHub: pablocalofatti/minion-toolkit
• npm: npx minion-toolkit install

아이디어가 마음에 든다면 별 (Star)을 눌러주세요. 무언가 고장 난다면 이슈 (Issue)를 열어주세요 (무언가는 반드시 고장 날 것입니다. 그것이 재미있는 부분이죠). 그리고 이 도구로 멋진 것을 만드셨다면, 꼭 알려주세요.

Claude Code는 이미 놀라울 정도로 유능한 개발자입니다. 하지만 최고의 개발자라 할지라도 단 하나의 키보드로만 타이핑할 수 있습니다. minion-toolkit은 그들에게 팀원을 제공합니다.

하나의 두뇌. 여러 개의 손. 그것이 이 모든 아이디어의 핵심입니다.