클로드 코드에 백그라운드 서브에이전트가 들어왔습니다. 무거운 작업을 걸어두고 끝날 때까지 손 놓고 기다릴 필요가 없습니다. 동시에 20개까지 돌아갑니다.
1. 앞이냐 뒤냐 — 여기서 갈립니다
서브에이전트는 두 가지로 돌아갑니다. 공식 문서가 이렇게 나눕니다.
| 어디서 돌리나 | 메인 대화는 |
|---|---|
| 포그라운드 (앞) | 끝날 때까지 멈춥니다 |
| 백그라운드 (뒤) | 내가 일하는 동안 같이 굴러갑니다 |
원문 그대로: "Foreground subagents block the main conversation until complete. … Background subagents run concurrently while you continue working."
그래서 뒤로 넘기기 좋은 건 오래 걸리면서 내 손이 안 가도 되는 일입니다 — 대형 리포 조사, 정기 유지관리, 오래 걸리는 검증 같은 것들이죠.
이런 소식, 남들보다 먼저 받으실 분?
직접 돌려보고 되는 것만 골라 매주 보내드립니다. 광고성 하이프는 거릅니다.
2. 동시에 몇 개까지 — 기본 20개
무제한이 아닙니다. 한 세션에서 동시에 돌릴 수 있는 수가 정해져 있습니다.
| 항목 | 값 |
|---|---|
| 기본 동시 실행 한도 | 20개 |
| 넘겼을 때 뜨는 말 | Concurrent subagent limit reached |
한도를 넘기면 그냥 실패하는 게 아니라 재시도하지 말라고 같이 알려줍니다.
원문: "…spawning another with the Agent tool fails with Concurrent subagent limit reached, and the error tells Claude not to retry."
3. 그 숫자를 바꾸는 법
환경변수 하나면 됩니다. 양의 정수를 넣으면 그대로 적용됩니다.
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=30원문: "To change the limit, set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to any positive whole number."
4. 그런데 많이 띄우면 손해입니다
숫자를 올릴 수 있다고 올리는 게 답은 아닙니다. 공식 문서가 직접 경고합니다.
⚠ "Running many subagents that each return detailed results can consume significant context."
결과를 길게 물고 오는 서브에이전트를 여러 개 돌리면 컨텍스트를 크게 먹습니다.
그래서 실무에서 갈리는 건 개수가 아니라 무엇을 맡기느냐입니다. 결과가 짧게 떨어지는 일(찾기·확인·요약)은 뒤로 넘기기 좋고, 긴 산출물을 그대로 물고 오는 일은 개수를 늘릴수록 본 작업이 좁아집니다.
5. 그대로 복붙하세요
① 한도를 30개로 올리기
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=30② 뒤로 넘기기 좋은 일 — 그대로 시켜보세요
이 저장소에서 인증·DB·API 모듈을 각각 서브에이전트로 나눠서
동시에 조사하고, 끝나면 요약만 가져와줘먼저 하나만 뒤로 넘겨보세요. 몇 개까지 늘릴지는 그다음에 정해도 늦지 않습니다 — 컨텍스트가 얼마나 줄어드는지는 일에 따라 다릅니다.
6. 이어지는 글
클로드 코드에서 한도에 부딪히는 이야기는 처음이 아닙니다. 사용량 한도가 언제 풀리는지 재본 편에서는 기다리는 쪽을 다뤘는데, 이번 편은 기다리는 동안 다른 일이 굴러가게 만드는 쪽입니다.
카드뉴스로도 정리했습니다
인스타그램에 올린 5장입니다.
