Claude Code에서 서브에이전트를 fan out하고, 돌아온 결과를 검사하기

많은 사람이 Google에 "claude fan out subagents"라고 입력하고, 꽤 많은 사람이 끝에 "command"를 붙입니다. 마치 켜기만 하면 되는 스위치가 있는 것처럼요. 실제로는 기법이 있고, 명령어도 있습니다. 우리는 2026년 10월 16일에 Claude Code 2.1.301과 Anthropic 문서에서 둘 다 확인했습니다.

그리고 문서가 거의 다루지 않는 부분이 있습니다. 우리가 이 글을 쓰는 이유이기도 한, 결과를 어떻게 처리하느냐는 문제입니다. 우리는 매일 밤 fan out을 실행합니다. 서브에이전트 6개가 이 블로그의 새 글을 17개 언어로 번역하고, 메인 세션이 그 작업을 병합합니다. 모든 서브에이전트가 규칙을 지켰다고 보고합니다. 그런데도 실행 전에 작성해 둔 검사는 여전히 문제를 찾아냅니다.

짧은 답

fan out이란 하나의 세션이 작업을 서로 의존하지 않는 조각으로 나누고, 각 조각을 서브에이전트에 넘기고, 동시에 실행되게 한 뒤, 돌아온 것을 병합하는 것입니다. Claude Code에서는 세 가지 방법이 있습니다.

이 페이지의 나머지 부분에서는 각 방법을 차례로 살펴본 뒤, 우리 자신의 fan out에 적용하는 검사를 소개합니다.

서브에이전트가 볼 수 있는 것과 볼 수 없는 것

작업을 나누는 방식은 문서에 나오는 세 가지 사실로 정해집니다.

각 서브에이전트는 백지에서 시작합니다. 자기만의 컨텍스트 창에서, 자기만의 시스템 프롬프트, 도구, 권한을 갖고 실행됩니다. 대화 내용도, 이미 사용한 스킬도, Claude가 이미 읽은 파일도 보지 못합니다. 알아야 할 것은 모두 브리프에 들어 있어야 합니다.

결과는 메인 대화로 돌아옵니다. 서브에이전트 작업의 세부 내용은 그 서브에이전트의 컨텍스트에 남고, 결과만 돌아옵니다. 그래도 많은 서브에이전트가 긴 보고서를 돌려보내면 메인 컨텍스트가 가득 찰 수 있고, 각 서브에이전트는 실행되는 동안 자기 토큰을 씁니다.

한도가 있습니다. 기본적으로 한 세션에서 동시에 실행할 수 있는 서브에이전트는 20개입니다. 21번째는 Concurrent subagent limit reached로 실패하고, 이 오류는 Claude에게 다시 시도하지 말라고 알립니다. 한도는 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 높이거나 낮출 수 있습니다. 서브에이전트는 자기 서브에이전트를 시작할 수 있어 메인 대화에서 세 단계 아래까지 내려가며, 한 세션의 총수에는 제한이 없습니다.

방법 1: 평범한 말로 요청하기

가장 간단한 fan out은 문장 하나입니다. Anthropic 문서의 예시는 이렇습니다.

Research the authentication, database, and API modules in parallel using separate subagents

각 서브에이전트가 자기 영역을 탐색하고, 그다음 Claude가 하나의 종합을 작성합니다. 문서는 중요한 조건도 덧붙입니다. 조사 경로가 서로 의존하지 않을 때 가장 잘 작동한다는 것입니다. 데이터베이스에 관한 질문에 auth에 관한 답이 필요하다면, 그것은 세 조각이 아니라 하나의 순서입니다.

평범한 말로 요청하면 결정은 Claude에게 맡겨집니다. .claude/agents/에 커스텀 서브에이전트를 정의해 두었다면, @로 언급하면 그 작업에서 반드시 실행됩니다. 이 파일들이 어떻게 작동하는지는 Claude Code 서브에이전트 페이지에서 설명합니다.

방법 2: /batch, fan out 명령어에 가장 가까운 것

/batch는 Claude Code에 기본으로 포함된 스킬입니다. 지시를 하나 줍니다.

/batch migrate src/ from JavaScript to TypeScript

코드베이스를 조사하고, 작업을 5~30개의 독립된 단위로 나눈 뒤 계획을 보여줍니다. 승인하면 단위마다 백그라운드 서브에이전트를 하나씩 시작하고, 각각을 격리된 git worktree에서 실행합니다. 각 서브에이전트는 자기 단위를 구현하고, 테스트를 실행하고, 변경을 게시합니다. git 저장소가 필요하며, 다른 버전 관리 시스템이라면 worktree를 만들어 주는 WorktreeCreate 훅이 필요합니다.

속도를 늦춰야 할 순간은 계획 단계입니다. 분할이 거기서 정해지고, 분할이 전부입니다. 같은 파일을 건드리는 두 단위나 다른 단위의 출력이 필요한 단위는, 각 서브에이전트가 아무리 뛰어나도 깔끔하게 병합되지 않습니다. 단위 목록은 동료가 쓴 마이그레이션 계획을 읽듯이 읽으세요.

방법 3: claude -p 루프

작업이 파일 목록이고 호출 하나하나를 통제하고 싶을 때를 위해, Anthropic의 모범 사례는 루프를 소개합니다. 먼저 Claude에게 목록을 쓰게 합니다(list all 2,000 Python files that need migrating and save the list to files.txt). 그다음:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

이 예시에는 따라 할 만한 세부 사항이 세 가지 있습니다.

• 답을 기계가 읽을 수 있습니다. "Return OK or FAIL" 덕분에 스크립트는 문장을 읽지 않고도 실패를 셀 수 있습니다.
• 권한은 미리 정해 둡니다. --allowedTools는 마이그레이션에 필요한 것만 정확히 허용하고, --permission-mode dontAsk는 그 밖의 모든 것을 거부합니다. 자리에 없는 사람을 기다리지 않습니다.
• 두세 개 파일로 시작합니다. 문서는 분명하게 말합니다. 처음 파일들에서 잘못된 부분을 보고 프롬프트를 다듬은 뒤, 전체 목록을 실행하라고요.

쓰인 그대로라면 루프는 파일을 하나씩 차례로 처리합니다. 여러 호출을 동시에 돌리는 것은 평범한 셸 작업이지만, 호출마다 내 머신과 쿼터를 쓰는 완전한 세션이 하나씩 돌아갑니다. 여러 에이전트가 같은 무거운 명령을 같은 분에 시작하면 무슨 일이 생기는지 이 글에서 측정했는데, 여기서도 이야기는 같습니다. 병렬 호출은 적은 수로 시작하세요.

CI에서는 문서가 --bare를 추가하라고 권합니다. 훅, 스킬, MCP 서버, CLAUDE.md를 건너뛰어 모든 머신이 같은 실행을 하게 됩니다. bare 모드는 구독 로그인을 쓰지 않으므로 ANTHROPIC_API_KEY가 필요합니다.

우리가 매일 밤 fan out하는 방법

이것이 우리가 실제로 돌리는 fan out입니다. 야간 SEO 팀은 새 글을 영어와 프랑스어로 직접 씁니다. 그다음 두 번째 에이전트가 Claude Code 서브에이전트로 17개 언어로 더 번역하고, 번체 중국어는 번역하지 않고 간체 중국어에서 스크립트로 생성합니다. 2026년 9월 13일 이후 글 11편이 이 과정을 거쳤고, 각 글은 파일 20개로 도착합니다.

조각

서브에이전트 6개가 각각 세 언어(마지막은 두 언어)를 맡습니다. 스페인어, 포르투갈어, 이탈리아어 / 독일어, 네덜란드어, 폴란드어 / 러시아어, 우크라이나어, 튀르키예어 / 일본어, 한국어, 중국어 / 태국어, 베트남어, 인도네시아어 / 아랍어, 힌디어. 어떤 언어도 다른 언어에 의존하지 않으며, 그래서 깔끔한 fan out이 됩니다.

각 브리프에는 같은 다섯 가지가 들어갑니다. 서브에이전트는 그 밖의 것을 아무것도 보지 못하기 때문입니다.

• 영어 원문, 그리고 어조와 제품 용어의 기준이 되는 프랑스어판
• 각 언어마다 그 언어로 사이트에 이미 게시된 문장. 서브에이전트가 새 단어를 만들어 내지 않고 사이트가 이미 쓰는 단어를 다시 쓰게 하기 위해서입니다
• 엄격한 규칙: 브랜드명과 제품명은 그대로, 코드는 바이트 하나까지 그대로, em 대시 금지
• 검사 스크립트, 그리고 OK가 나올 때까지 다시 실행하라는 지시
• 자기 조각 안이든 밖이든, 의심스러워 보인 것은 무엇이든 보고하라는 요청

검사는 실행 전에 작성합니다

검사는 스크립트이지, 서브에이전트의 의견이 아닙니다. 언어마다 파일을 영어 원문과 비교합니다.

• 같은 slug와 날짜, 제목은 H1과 동일
• 섹션, 하위 섹션, 이미지, 링크, 표 행의 수가 같고, 본문의 FAQ 답변 수가 메타데이터의 질문 수와 같음
• 링크는 바이트 단위로 동일, 코드 조각도 바이트 단위로 동일
• 브랜드명을 세고, 영어보다 적어서는 안 됨
• 길이가 언어별로 보정한 범위 안에 있을 것. 중국어는 영어에 필요한 글자 수의 약 36%로, 일본어는 약 절반으로 같은 내용을 말하기 때문입니다
• 그 언어에 발음 구별 기호가 있다면 들어 있을 것(폴란드어, 튀르키예어, 베트남어)

모든 서브에이전트는 "완료, 모든 검사 통과" 같은 말로 끝냅니다. 우리가 따르는 판정은 단 하나, 메인 세션이 같은 스크립트를 모든 파일에 한꺼번에 다시 실행한 결과입니다.

중앙 검사가 잡아내고 자체 보고는 놓친 것

표 안에서 번역된 코드. 9월 13일, 서브에이전트의 약 절반이 표 안에서 명령어와 같은 백틱 안에 이어진 단어들을 번역했습니다. 저마다 이해한 대로 브리프를 따른 것이었습니다. 수정은 서브에이전트가 아니라 브리프에 들어갔습니다. 코드 조각에는 명령어만 넣고, 그 뒤의 단어는 백틱 밖에 둡니다.

우리 자신의 검사가 틀렸습니다. 9월 6일, 교체 대상이던 옛 문장을 기준으로 보정한 길이 검사가 서브에이전트 17개 중 11개를 경고했습니다. 11개 모두 옳았습니다. 새 텍스트는 원래 더 길어야 했습니다. 수정된 프랑스어를 기준으로 다시 보정하자 경고는 하나도 없었습니다. 중앙 검사도 틀릴 수 있으며, 그것을 알아보는 방법은 이미 좋다고 알고 있는 결과물에 먼저 실행해 보는 것입니다.

조각 사이의 일관성. 10월 15일, 같은 방식으로 번역한 새 기능 페이지에서 병합 검사는 90개 파일에서 예상한 문장만 바뀌었음을 확인했습니다. 하지만 일본어, 한국어, 중국어 서브에이전트는 각각 "You may also like"에 대해, 그 언어가 이웃 페이지에서 이미 쓰던 것과 다른 제목을 골랐습니다. 각 선택은 올바른 번역이었습니다. 하지만 어느 것도 사이트와 일관되지 않았습니다. 어떤 서브에이전트도 자기 조각 안에서는 그것을 볼 수 없었습니다. 병합된 결과를 한 번 훑는 과정만이 볼 수 있습니다.

틀린 단어는 모든 구조 검사를 통과합니다. 사이트의 한 언어는 한때 AI 에이전트를 자동차 대리점이라고 불렀고, 그것이 몇 달 동안 온라인에 남아 있었습니다. 길이도 같고, 구두점도 같고, 브랜드명도 있었습니다. 모든 수치가 초록색이었습니다. 그것을 잡아내는 유일한 것은 알려진 오역을 이름으로 적어 둔 목록입니다. 이 목록은 모든 배포를 막고, 새 오역을 찾을 때마다 한 줄씩 늘어납니다.

조각 밖에 대한 보고. 10월 15일, 튀르키예어를 맡은 서브에이전트가 사이트의 기존 문장 97개에서 "agent"가 "ajans", 즉 대행사로 쓰여 있다고 보고했습니다. 브리프가 금지했기 때문에 그 서브에이전트는 손대지 않았습니다. 우리는 티켓을 열었고 수정은 다음 날 배포되었습니다. 서브에이전트에게 무엇을 했는지뿐 아니라 무엇을 봤는지 묻는 일은 비용이 적고 효과가 있습니다.

병합은 한곳에서 합니다

서브에이전트는 저장소에 직접 쓰지 않습니다. 각자 자기 파일을 돌려주면 스크립트가 병합하고, 결과를 이전 버전과 문장 단위로 비교합니다. 바뀌어도 되는 것은 요청한 문장뿐입니다. 그다음 저장소의 검사와 사이트 빌드가 병합된 결과에 대해 한 번만 실행됩니다. 서브에이전트마다 빌드를 돌리면 더 느리고, 절대 배포되지 않을 반쯤 병합된 상태를 테스트하게 됩니다.

fan out하지 말아야 할 때

• 조각들이 서로 의존합니다. 조각 B에 조각 A의 출력이 필요하다면 순서대로 실행하세요.
• 작업이 작습니다. 각 서브에이전트는 백지에서 시작해 필요한 것을 다시 읽습니다. 10분짜리 작업에서는 새로 시작하는 비용이 아끼는 것보다 큽니다.
• 검사를 작성할 수 없습니다. 전부 직접 읽지 않고는 좋은 조각과 나쁜 조각을 구별할 방법이 없다면, 시간은 병합에서 다 쓰게 됩니다.
• 쿼터가 빠듯합니다. 각 서브에이전트는 자기 토큰을 씁니다. fan out으로 얻는 것은 시간과 깔끔한 메인 컨텍스트이지, 더 적은 청구액이 아닙니다.

AgentsRoom의 자리

서브에이전트는 하나의 Claude Code 세션 안에서 삽니다. 보이는 것은 결과이지 작업 과정이 아니며, 도중에 그중 하나의 방향을 바꿀 수도 없습니다. 각 조각을 따로 지켜보고, 답하고, 검토할 수 있는 에이전트로 만들고 싶다면 대신 별도의 세션을 실행하세요. 티켓마다 자기 git worktree를 쓰고, 조각들이 서로 작업을 넘겨줄 때는 Agent Teams를 씁니다. 팀 단계에는 검사 명령을 붙일 수 있고, 실행을 다음으로 넘길지는 에이전트 자신의 주장이 아니라 그 명령의 종료 코드가 정합니다. 위와 같은 규칙을 러너가 강제하는 것입니다. Claude Code, Codex, 그리고 AgentsRoom이 지원하는 다른 에이전트 CLI에서 작동합니다.

서브에이전트와 Agent Teams 사이에서 아직 고민 중이라면, 이 비교 글에서 각각의 용도를 설명합니다.