# 클로드 코드 백그라운드 서브에이전트 — 치트시트

출처: https://code.claude.com/docs/en/sub-agents (「Create custom subagents」)
아래는 전부 그 문서에서 확인한 것만 적었습니다. 발표일은 문서에 표시가 없어 확인하지 못했습니다.

## 앞이냐 뒤냐

| 어디서 돌리나 | 메인 대화는 |
|---|---|
| 포그라운드 (앞) | 끝날 때까지 멈춥니다 |
| 백그라운드 (뒤) | 내가 일하는 동안 같이 굴러갑니다 |

> "Foreground subagents block the main conversation until complete."
> "Background subagents run concurrently while you continue working."

## 동시 실행 한도

기본값은 **20개**입니다.

> "By default, when 20 subagents are running in a session, spawning another with the
> Agent tool fails with `Concurrent subagent limit reached`, and the error tells Claude not to retry."

한도를 넘기면 그냥 실패하는 게 아니라 **재시도하지 말라고 같이 알려줍니다.**

## 한도 바꾸기

```bash
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=30
```

> "To change the limit, set `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` to any positive whole number."

양의 정수면 됩니다.

## ⚠ 많이 띄운다고 좋은 게 아닙니다

문서가 직접 경고합니다.

> "Running many subagents that each return detailed results can consume significant context."

결과를 길게 물고 오는 서브에이전트를 여러 개 돌리면 **컨텍스트를 크게 먹습니다.**
개수를 늘리는 것보다 **무엇을 맡기느냐**가 먼저입니다.

- 뒤로 넘기기 좋은 일: 결과가 짧게 떨어지는 것 (찾기·확인·요약)
- 뒤로 넘기면 손해인 일: 긴 산출물을 그대로 물고 오는 것

## 바로 시켜보기

```
이 저장소에서 인증·DB·API 모듈을 각각 서브에이전트로 나눠서
동시에 조사하고, 끝나면 요약만 가져와줘
```

---

성능이 얼마나 좋아지는지는 적지 않았습니다 — 모델·사양·설치 상태가 저마다 달라서
한 곳에서 잰 값이 다른 환경에 그대로 맞지 않기 때문입니다. 문서에 있는 구조와 숫자만 담았습니다.

자비스스튜디오 · https://jarvisstudio-blog.web.app/blog/claude-code-subagent/