Claude Code Sub-agent 병렬 실행으로 빌드 시간 61% 줄이는 법

모노레포 환경에서 테스트, 린트, 타입체크를 매번 순서대로 기다리고 있다면 이 글이 정확히 필요한 글이다. Claude Code의 Agent 툴을 병렬로 설계하면 실행 구조 자체가 바뀐다.

---

1. 왜 지금 이걸 봐야 하나

Claude Code로 자동화를 한다고 해도 대부분의 세션은 암묵적으로 직렬이다. 테스트가 끝나야 린트를 돌리고, 린트가 끝나야 타입체크를 돌린다. 이 순서가 너무 당연하게 굳어져 있어서, 실제로 이 세 작업 사이에 의존성이 전혀 없다는 사실을 인식하지 못한다.

문제는 시간이다. 세 작업을 직렬로 묶으면 각각 소요 시간의 합만큼 기다려야 한다. 모노레포 규모가 커질수록 이 대기 시간은 선형으로 늘어난다. 코드 한 줄 고치고 PR을 올리기 전에 3분씩 멍하니 기다리는 구조다.

Claude Code의 Agent 툴은 단순히 서브태스크를 위임하는 용도가 아니다. 하나의 응답 안에 여러 Agent 호출을 동시에 담으면 그것들이 병렬로 실행된다. 설계만 바꾸면 대기 시간이 최장 작업 하나의 시간으로 수렴한다.

---

2. 핵심 아이디어

병렬화의 핵심은 하나다. 의존성 그래프를 먼저 그리고, 독립적인 작업을 한 번에 발화한다.

어떤 작업이 어떤 작업의 결과를 필요로 하는지 먼저 파악해야 병렬화 경계가 보인다. 이 경계를 Agent 툴 호출 타이밍으로 변환하는 것이 전부다.

작업 분류 기준을 표로 정리하면 이렇다.

구분	조건	예시
병렬화 가능	읽기 전용, 파일 겹침 없음, 결과 독립적	패키지별 테스트, Explore 에이전트, 서로 다른 서비스 빌드
병렬화 금지	같은 파일 수정, 앞 단계 결과 의존, 공유 상태 변경	동일 파일 리팩터링, DB 마이그레이션, 순서 있는 배포

직렬과 병렬의 시간 구조 차이를 먼저 이해하면 이후 패턴들이 훨씬 명확하게 읽힌다.

---

3. 바로 따라하는 방법

패턴 1: 독립 작업 병렬 위임

모노레포에서 패키지별 작업을 동시에 돌리는 가장 기본적인 패턴이다. Claude Code에 다음처럼 지시한다.

"packages/auth, packages/api, packages/ui 각각에서
테스트를 동시에 실행하고 결과를 취합해줘"

이 지시를 받은 Claude Code 내부에서는 세 개의 Agent 툴 호출이 단일 메시지에 담겨 동시에 발화된다. 직렬로 기다릴 이유가 없는 패키지들은 처음부터 이렇게 설계해야 한다.

패턴 2: Explore + Implement 분리

코드베이스 분석 단계와 수정 단계를 분리하면 조사 속도가 확연히 달라진다.

step_1_parallel:
  - agent: Explore
    task: "AuthService의 토큰 갱신 로직 위치 파악"
  - agent: Explore
    task: "UserRepository의 세션 관리 코드 파악"

step_2_sequential:  # step_1 완료 후
  - agent: general-purpose
    task: "위 두 결과를 바탕으로 JWT 갱신 버그 수정"

Explore 에이전트는 읽기 전용이라 동시에 몇 개를 돌려도 충돌이 없다. 두 곳을 각각 조사하는 시간이 두 배가 아니라 한 번으로 줄어든다.

패턴 3: 결과 취합 에이전트

병렬 작업이 끝난 뒤 결과를 모으는 단계를 반드시 명시적으로 설계해야 한다. 이 단계 없이 병렬로만 돌리면 결과 해석이 뒤엉킨다.

# 취합 에이전트 프롬프트 템플릿

다음 세 에이전트의 출력을 받았음:
- Agent A: [패키지 auth 테스트 결과]
- Agent B: [패키지 api 타입체크 결과]
- Agent C: [패키지 ui 린트 결과]

규칙:
1. 실패가 하나라도 있으면 전체 실패로 판정
2. 각 실패 원인을 파일명:라인 형식으로 정리
3. 수정 우선순위를 블로킹/논블로킹으로 분류

취합 에이전트에게 넘기는 출력은 반드시 요약 형태로 제한한다. 원본 전체를 그대로 넘기면 컨텍스트 비용이 급등한다.

패턴 4: Worktree 격리로 안전한 병렬 수정

여러 에이전트가 동시에 서로 다른 파일을 수정해야 할 때는 git worktree로 격리한다.

# 병렬 수정 전 worktree 준비
git worktree add ../feature-auth-fix feature/auth-fix
git worktree add ../feature-api-fix feature/api-fix

# 각 에이전트가 별도 worktree에서 작업
# Agent 1 → ../feature-auth-fix
# Agent 2 → ../feature-api-fix

# 작업 완료 후 병합
git merge feature/auth-fix
git merge feature/api-fix
git worktree remove ../feature-auth-fix
git worktree remove ../feature-api-fix

Claude Code의 isolation: "worktree" 옵션을 쓰면 이 준비와 정리 과정이 자동화된다. 병합 충돌 위험도 수동으로 관리할 필요가 없다.

---

4. 운영할 때 조심할 점

에이전트 수는 3~5개가 상한선이다. 에이전트를 무한정 늘리면 오케스트레이터의 컨텍스트 윈도우가 포화된다. 각 에이전트의 결과가 오케스트레이터로 돌아오기 때문에, 에이전트 수가 많아질수록 취합 단계에서 비용이 급증한다.

작업 유형	권장 최대 병렬 수
읽기 전용 탐색	5개
코드 수정	3개
결과 취합	항상 1개 (직렬)

같은 파일을 건드리는 두 에이전트는 절대 병렬로 돌리면 안 된다. worktree 격리를 써도 같은 파일을 동시에 수정하면 병합 충돌이 생긴다. 병렬화 설계 전에 파일 단위 의존성을 먼저 파악해야 한다.

실측 기준을 잡아두면 판단이 쉬워진다. Next.js + NestJS 모노레포에서 직접 측정한 결과다.

구성	방식	소요 시간
타입체크 38초 + 린트 19초 + 유닛 테스트 52초 + E2E 71초	직렬	180초
타입체크·린트 병렬 / 유닛 테스트 / E2E 테스트	병렬 3그룹	71초

단축률 61%, 병렬화 설계에 쓴 10분이 실행할 때마다 109초를 돌려준다.

---

마무리

의존성 그래프를 먼저 그리고 독립적인 경계를 찾는 것, 그게 병렬 에이전트 설계의 전부다. 경계가 명확하면 Agent 툴 호출 타이밍으로 바로 변환할 수 있고, 직렬 워크플로우와 같은 신뢰성을 유지하면서 실행 시간만 대폭 줄어든다.

다음 편에서는 병렬 에이전트 결과를 구조화된 JSON으로 취합해서 후속 에이전트에게 안전하게 넘기는 데이터 계약 패턴을 다룬다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 실전
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독