Claude Code 병렬 서브에이전트로 대규모 작업 처리하기 - fan-out·파이프라인을 직접 써본 기록

Claude Code 병렬 서브에이전트로 대규모 작업 처리하기 - fan-out·파이프라인을 직접 써본 기록

개발 도구 사용기

공식 문서와 실제 사용 경험을 기준으로 정리했습니다.

한 번에 다루기엔 너무 큰 작업이 있습니다. 파일 수백 개를 훑어야 하거나, 여러 갈래를 동시에 조사해야 하거나, 같은 내용을 여러 관점에서 교차 확인해야 할 때입니다. 이런 일을 하나의 대화창에서 순서대로 처리하면 금세 한계에 부딪힙니다. 이 글은 Claude Code의 서브에이전트(subagent)를 병렬로 나눠 큰 작업을 처리한 기록입니다. fan-out(갈래로 펼치기)과 파이프라인(단계로 잇기)이라는 두 가지 흐름을 중심으로 정리했고, 기능 설명은 공식 문서를 기준으로 했습니다. 명령과 화면은 버전에 따라 달라질 수 있으니 본문의 공식 문서를 함께 확인하시길 권합니다.

큰 작업이 막히는 지점

하나의 대화에는 한 번에 담을 수 있는 맥락의 양에 한계가 있습니다. 파일을 많이 열어 읽고, 긴 로그를 확인하고, 검색 결과를 잔뜩 받아 오면 정작 중요한 맥락이 뒤로 밀려납니다. 작업이 길어질수록 "방금 확인한 내용"이 흐려지고, 같은 것을 다시 읽는 일이 늘어납니다.

그래서 큰 작업은 잘게 나누는 편이 낫습니다. 핵심은 두 가지입니다. 첫째, 탐색처럼 양이 많은 일은 따로 떼어 내는 것. 둘째, 서로 독립적인 일은 동시에 굴리는 것. Claude Code의 서브에이전트가 이 두 가지를 맡습니다.

서브에이전트 — 따로 일하고 요약만 가져온다

서브에이전트는 자기만의 컨텍스트 창에서 독립적으로 일하는 보조 작업자입니다. 공식 문서에 따르면 각 서브에이전트는 별도의 컨텍스트와 지정된 도구 권한을 가지고 작업한 뒤, 결과를 메인 대화로 돌려줍니다. 중요한 점은 그 과정에서 읽은 파일, 검색 결과, 긴 출력 같은 자질구레한 내용은 서브에이전트 쪽에만 남고, 메인 대화에는 요약만 돌아온다는 것입니다.

덕분에 "테스트를 잔뜩 돌려 로그를 확인하는 일"이나 "문서 여러 개를 뒤져 답을 찾는 일"을 서브에이전트에 맡기면, 메인 대화는 그 verbose한 출력에 오염되지 않고 결론만 받습니다. 큰 작업에서 메인 대화의 맥락을 깨끗하게 유지하는 가장 기본적인 방법입니다.

병렬로 펼치기 — fan-out

서로 의존하지 않는 작업이라면 굳이 차례로 할 이유가 없습니다. 공식 문서는 독립적인 조사라면 여러 서브에이전트를 동시에 띄워 병렬로 진행할 수 있다고 설명합니다. 예를 들어 "프런트엔드·백엔드·인프라 세 영역을 각각 살펴봐"처럼 갈래가 분명한 일을 한꺼번에 펼쳐 두고, 각자의 결과를 모아 종합하는 식입니다. 이것을 fan-out이라 부르겠습니다.

방식	진행	어울리는 일
직렬	하나 끝나야 다음 시작	앞 결과가 뒤 작업의 입력이 될 때
병렬(fan-out)	여러 갈래를 동시에	서로 의존하지 않는 독립 조사·탐색

다만 병렬로 띄운 서브에이전트의 결과는 결국 메인 대화로 모입니다. 그래서 갈래가 너무 많으면 모이는 요약만으로도 부담이 될 수 있습니다. "독립적인가"와 "결과가 너무 길지 않은가"를 함께 따져 갈래 수를 정하는 편이 좋았습니다.

단계로 잇기 — 파이프라인

큰 작업은 보통 성격이 다른 단계로 나뉩니다. 탐색 → 처리 → 검증이 대표적입니다. 각 단계를 서브에이전트에 맡기되, 앞 단계의 결과를 다음 단계의 입력으로 넘기면 하나의 흐름이 됩니다. 저는 이렇게 단계를 잇는 구성을 파이프라인이라 부르며 썼습니다.

# 큰 작업을 단계로 나눈 예
1) 탐색 → 관련 파일·후보를 찾아 목록화 (서브에이전트)
2) 처리 → 목록을 항목별로 나눠 병렬 처리 (fan-out)
3) 검증 → 결과를 다른 관점에서 교차 확인

특히 마지막 검증 단계가 유용했습니다. 한 서브에이전트가 내놓은 결과를 다른 서브에이전트가 "정말 맞는지" 다시 보게 하면, 그럴듯하지만 틀린 답이 그대로 통과하는 일을 줄일 수 있었습니다. 처리와 검증을 같은 작업자에게 몰지 않고 나누는 것만으로도 결과의 신뢰도가 올라갔습니다.

서브에이전트 정의하는 법

자주 쓰는 역할은 파일로 정의해 두면 매번 설명할 필요가 없습니다. 공식 문서 기준으로, 서브에이전트는 프로젝트의 .claude/agents/ 또는 사용자 홈의 ~/.claude/agents/ 아래에 마크다운 파일로 둡니다. 파일 맨 위 frontmatter에 기본 정보를 적고, 그 아래 본문에 그 에이전트의 역할(시스템 프롬프트)을 적습니다.

# .claude/agents/researcher.md
---
name: researcher
description: 언제 이 에이전트를 쓰는지
tools: Read, Grep, Glob
model: haiku
---

# 여기에 이 에이전트의 역할을 자유롭게 서술

description는 "이 에이전트를 언제 부를지"를 적는 칸으로, 작업과 맞으면 자동으로 위임되는 기준이 됩니다. tools를 적으면 그 도구만 쓰게 권한을 좁힐 수 있고, 생략하면 상속됩니다. model로 사용할 모델을 따로 지정할 수도 있습니다.

비용과 맥락을 같이 아끼기

병렬로 여러 작업자를 굴리면 그만큼 토큰을 더 씁니다. 그래서 공식 문서는 가벼운 작업은 더 빠르고 저렴한 모델로 라우팅하는 방법을 권합니다. 단순 탐색·정리 같은 일은 가벼운 모델(예: Haiku)에 맡기고, 판단이 중요한 단계만 상위 모델을 쓰는 식으로 나누면 비용을 눌러 가며 병렬의 이점을 가져갈 수 있었습니다.

맥락 절약과 비용 절약은 사실 같은 이야기입니다. verbose한 출력을 서브에이전트 쪽에 가두고 요약만 받으면, 메인 대화가 짧게 유지되고 그만큼 토큰도 덜 듭니다. "따로 일하게 하고 결론만 받는다"는 원칙 하나가 두 가지를 동시에 해결해 줬습니다.

써보며 걸렸던 점

• 나누지 않아도 될 일까지 나눔 — 작은 작업은 그냥 메인 대화에서 하는 게 빨랐습니다. 서브에이전트는 출력이 많거나 독립적인 일에 쓸 때 효과가 컸습니다.
• 갈래를 과하게 펼침 — 병렬 갈래가 많아지자 돌아오는 요약을 합치는 일이 또 다른 부담이 됐습니다. 꼭 필요한 갈래만 두는 편이 나았습니다.
• 검증을 생략함 — 처리 결과를 바로 믿었다가 틀린 곳을 늦게 발견한 적이 있었습니다. 교차 확인 단계를 두니 이런 일이 줄었습니다.
• 역할 설명이 모호함 — description이 두루뭉술하면 위임이 엉뚱하게 됐습니다. "언제 쓰는지"를 구체적으로 적을수록 정확해졌습니다.

자주 묻는 질문

Q. 서브에이전트는 메인 대화와 무엇이 다른가요?

서브에이전트는 별도의 컨텍스트 창에서 독립적으로 일하고 결과만 돌려줍니다. 그래서 양이 많은 탐색·검증을 맡겨도 메인 대화의 맥락이 그 출력으로 채워지지 않습니다.

Q. 항상 병렬로 나누는 게 좋나요?

아닙니다. 앞 결과가 뒤 작업의 입력이 되는 일은 직렬이 맞고, 작은 일은 나누지 않는 편이 빠릅니다. 서로 독립적이고 출력이 많은 일에 병렬이 어울립니다.

Q. 비용이 더 들지 않나요?

병렬은 토큰을 더 쓸 수 있습니다. 가벼운 단계는 더 저렴한 모델로 돌리고, 출력을 서브에이전트에 가둬 요약만 받으면 비용과 맥락을 함께 아낄 수 있습니다.

마무리

큰 작업을 다루는 요령은 결국 "잘게 나눠, 독립적인 건 동시에, 결과는 교차로 확인한다"로 모였습니다. 탐색처럼 양이 많은 일은 서브에이전트에 맡겨 메인 대화를 비워 두고, 갈래가 분명한 일은 fan-out으로 펼치고, 성격이 다른 단계는 파이프라인으로 이어 붙이는 흐름입니다. 처음에는 "긴 탐색 한 건을 서브에이전트에 떼어 내 보기"부터 시작하시길 권합니다. 그 작은 분리만으로도 메인 대화가 한결 가벼워지는 걸 느낄 수 있습니다.

이 글의 기능 설명은 Claude Code 공식 문서를 기준으로 정리했습니다. 세부 구성과 명령은 버전에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.

• 서브에이전트 문서: code.claude.com/docs/en/sub-agents
• 에이전트 개요 문서: code.claude.com/docs/en/agents

※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. 도구의 기능·화면·명령은 버전에 따라 달라질 수 있으며, 특정 결과를 보장하지 않습니다.