Claude Code subagents는 언제 켜고 언제 메인 세션으로 끝내야 할까 2026 – context bloat·병렬작업 기준표

Posted on by

Claude Code subagents를 처음 보면 꽤 유혹적이다.

뭔가 팀이 생긴 느낌이 난다.

메인 Claude가 있고, 옆에서 코드 읽는 agent, 리뷰하는 agent, 테스트 보는 agent가 돌아가면 갑자기 내 터미널이 작은 개발 조직처럼 보인다.

좋다.

그런데 바로 여기서 사고가 난다.

모든 일을 subagent에 던지면 context가 절약되는 게 아니라 결과 요약을 다시 해석하느라 메인 세션이 더 피곤해진다.

반대로 모든 일을 메인 세션에서만 하면 검색 결과, 로그, 파일 내용, 실패한 실험이 대화창을 가득 채운다.

이게 Claude Code subagents의 핵심이다.

켜야 할 때 켜면 context bloat를 줄인다.

아무 때나 켜면 의사결정 bloat를 만든다.

결론 먼저

Claude Code subagents는 옆길 탐색, read-only 조사, 병렬 검토, 대량 로그/파일 읽기에 쓸 때 가장 깔끔하다.

반대로 최종 설계 결정, 사용자 의도 확인, 작은 단일 수정, 이미 메인 세션이 모든 맥락을 가진 작업은 메인 세션에서 끝내는 편이 낫다.

상황 subagent 사용 이유
코드베이스에서 함수 위치만 찾아야 함 예 read-only 탐색 결과만 요약받으면 됨
긴 로그와 테스트 출력 분석 예 메인 context를 로그로 더럽히지 않음
보안 리뷰, 성능 리뷰, 문서 리뷰를 동시에 돌림 예 병렬 관점이 의미 있음
사용자의 모호한 요구사항을 해석해야 함 아니오 메인 세션이 직접 질문해야 함
파일 1개, 수정 5줄짜리 작업 아니오 위임 오버헤드가 더 큼
최종 아키텍처 결정을 내려야 함 보조만 subagent는 근거 수집, 결정은 메인 세션

왜 subagents가 context를 아끼나

Claude Code 공식 문서는 subagents를 task-specific workflow와 context management를 위한 특화 assistant로 설명한다.

핵심은 각 subagent가 자기 context window에서 작업한다는 점이다.

subagent가 검색하고, 파일을 읽고, 로그를 훑고, 실패한 가설을 몇 번 버려도 메인 대화에는 최종 요약만 돌아온다.

이건 꽤 큰 차이다.

AI 코딩에서 context가 망가지는 순간은 보통 코드가 길어서가 아니다.

필요 없는 탐색 흔적이 너무 많이 남아서다.

예를 들어 이런 흐름이 있다.

  1. auth 관련 파일을 찾아본다.
  2. 비슷한 파일 12개를 읽는다.
  3. 오래된 구현 3개를 버린다.
  4. 테스트 로그 500줄을 본다.
  5. 이제 진짜 수정 파일 2개만 남는다.

메인 세션에서 이걸 다 하면 대화창은 똑똑해지는 대신 무거워진다.

subagent에 맡기면 메인 세션은 이렇게 받으면 된다.

수정 대상은 A와 B입니다. C는 오래된 경로라 제외했습니다. 실패 테스트는 D 조건 때문입니다.

이 정도면 충분하다.

subagent를 켜야 하는 순간

subagent를 켜는 기준은 “어려운가”가 아니다.

“메인 세션이 이 중간 과정을 계속 기억해야 하는가”다.

중간 과정이 나중에 필요 없으면 subagent가 어울린다.

중간 과정 자체가 의사결정 근거라면 메인 세션에 남겨야 한다.

트리거 예시 권장 방식
대량 탐색 이 코드베이스에서 결제 흐름 찾아줘 read-only Explore
대량 로그 CI 실패 로그 1,000줄 분석 subagent 분석 후 원인만 회수
병렬 비교 접근법 A/B/C 장단점 비교 subagents 2~3개 병렬
독립 리뷰 보안, 성능, 문서 품질 점검 각각 다른 subagent
반복 역할 매번 같은 릴리즈 체크 custom subagent 정의

Claude Code에는 built-in subagents도 있다.

공식 문서 기준으로 Explore는 read-only agent이고, 파일 검색과 코드베이스 이해에 맞다.

Plan은 plan mode에서 코드베이스 research를 담당한다.

General-purpose는 탐색과 수정이 섞인 복잡한 작업에 쓰인다.

이 구조만 봐도 힌트가 나온다.

먼저 읽고 찾는 일은 subagent가 잘한다.

최종 방향을 고르는 일은 메인 세션이 쥐고 있어야 한다.

메인 세션에 남겨야 하는 순간

subagent가 능숙해 보여도 메인 세션이 붙잡아야 하는 일이 있다.

첫째, 요구사항 해석이다.

사용자가 “대충 깔끔하게 해줘”라고 했을 때 그 “깔끔”이 디자인인지, 성능인지, 파일 구조인지, 비용인지 묻는 일은 메인 세션이 해야 한다.

둘째, 최종 trade-off 결정이다.

subagent는 근거를 모을 수 있다.

하지만 “이번 릴리즈에서 보안 리팩터를 미룰지 말지” 같은 결정은 메인 세션이 사용자와 함께 해야 한다.

셋째, 아주 작은 작업이다.

파일 하나 열고 import 하나 고치는 데 subagent를 부르면 작업이 아니라 회의가 생긴다.

넷째, 이미 메인 세션이 충분한 맥락을 가진 작업이다.

방금 사용자가 설명했고, 방금 테스트도 봤고, 수정 범위도 선명하다면 굳이 옆방에 보내지 말자.

병렬 작업 기준표

병렬 subagents가 진짜 유용한 순간은 작업이 독립적일 때다.

서로 같은 파일을 수정하거나, 한 agent의 결과가 다른 agent의 입력이 되면 병렬처럼 보이는 순차 작업이 된다.

그때는 그냥 메인 세션에서 차례로 하는 편이 낫다.

병렬로 좋은 작업 병렬로 위험한 작업
서로 다른 모듈 조사 같은 파일을 동시에 수정
보안/성능/문서 관점 리뷰 한 설계를 모두가 각자 고쳐버림
여러 후보 라이브러리 비교 첫 결과를 알아야 다음 판단 가능
read-only 리서치 DB 마이그레이션 실행
테스트 실패 원인 후보 수집 production 설정 변경

내 기준은 간단하다.

결과를 합쳐도 충돌이 없으면 병렬이다.

결과를 합치려면 중재가 필요하면 병렬이 아니다.

이 기준을 안 세우면 subagents는 context 절약 도구가 아니라 작업 충돌 생성기가 된다.

tools와 permission은 먼저 줄인다

Claude Code 공식 문서는 subagent의 tool access를 조절할 수 있다고 설명한다.

기본적으로 subagent가 메인 conversation의 tool을 상속할 수 있지만, tools allowlist나 disallowedTools로 제한할 수 있다.

이건 귀찮은 설정이 아니다.

subagent 운영의 안전벨트다.

코드 검색만 시킬 agent라면 Read, Grep, Glob 정도면 충분하다.

문서 리뷰라면 Write와 Edit를 굳이 줄 필요가 없다.

보안 리뷰라면 네트워크나 MCP 접근을 제한하는 게 더 낫다.

역할 권장 tool 범위 이유
explorer Read, Grep, Glob 파일 발견과 요약만 필요
reviewer Read, Grep, Glob, Bash test 정도 수정 없이 증거 수집
worker Edit/Write 허용 가능 파일 책임 범위가 명확할 때만
docs checker Read 중심 문서 품질 확인은 수정 권한 없이도 가능
release checker Bash 제한 포함 배포 명령과 읽기 명령을 분리

MCP도 마찬가지다.

Claude Code MCP 문서는 외부 도구, 데이터베이스, API를 연결할 수 있다고 설명한다.

동시에 third-party MCP 서버는 신뢰와 prompt injection 위험을 조심하라고 안내한다.

그러니 subagent에 MCP를 다 열어두는 건 편해 보이지만 위험하다.

subagent가 Slack, DB, GitHub, Sentry를 전부 볼 수 있으면 조사 범위가 넓어지는 만큼 사고 범위도 넓어진다.

작업마다 필요한 MCP만 열자.

이게 재미는 덜해도 잠은 더 잘 온다.

hooks와 subagents는 역할이 다르다

subagents와 hooks를 헷갈리면 운영이 꼬인다.

subagent는 판단하고 요약하는 작은 agent다.

hook은 이벤트에 반응하는 자동화 지점이다.

예를 들어 코드 리뷰를 해야 하면 subagent가 맞다.

커밋 전에 포맷터를 돌리거나, 특정 명령을 막거나, 작업 종료 알림을 보내는 건 hook이 맞다.

Claude Code hooks 문서는 hook events, JSON 입출력, exit code, async hook 등을 다룬다.

즉 hook은 “반복되는 자동 반응”에 가깝다.

subagent는 “작업 단위 판단”에 가깝다.

하고 싶은 일 subagent hook
코드베이스 구조 조사 예 아니오
저장 전 포맷팅 아니오 예
보안 리뷰 의견 작성 예 조건부
위험 명령 차단 아니오 예
긴 로그 요약 예 아니오
작업 완료 알림 아니오 예

subagent로 자동화를 만들려고 하면 대화가 늘어난다.

hook으로 판단을 시키려고 하면 예외 처리가 늘어난다.

각자 자리가 있다.

custom subagent를 만들 기준

매번 직접 “이거 읽고 요약해줘”라고 시키면 custom subagent까지는 필요 없다.

custom subagent는 반복될 때 만든다.

공식 문서에서 subagent는 Markdown file과 YAML frontmatter로 정의할 수 있고, name과 description이 필수다.

description은 Claude가 언제 위임할지 판단하는 신호다.

그러니 description이 흐리면 자동 위임도 흐려진다.

좋은 description은 이렇다.

Use this agent when you need read-only exploration of billing-related code paths. Return exact file paths, key functions, and uncertainty. Do not edit files.

나쁜 description은 이렇다.

Helpful coding assistant.

두 번째는 멋있지만 쓸모가 없다.

custom subagent를 만들 기준은 세 가지다.

  1. 같은 역할을 3번 이상 반복했다.
  2. tool 제한이 매번 중요하다.
  3. 결과물 포맷이 고정되어야 한다.

이 셋 중 하나도 없으면 그냥 메인 세션에서 명시적으로 시키는 편이 낫다.

context bloat를 막는 운영 루틴

subagents를 켜기 전에 메인 세션이 해야 할 일이 있다.

작업 목표를 작게 써야 한다.

결과 포맷을 정해야 한다.

subagent가 읽어도 되는 범위를 정해야 한다.

마지막으로 “내가 지금 이 결과를 어떻게 합칠지”를 미리 생각해야 한다.

이걸 안 하면 subagent가 장문의 보고서를 가져온다.

보고서는 열심히 썼는데 메인 세션은 다시 요약해야 한다.

그럼 context를 아낀 게 아니라 요약 노동을 미룬 셈이다.

내가 쓰는 간단한 프롬프트는 이런 식이다.

Explore only. Do not edit files.
Find the files involved in login token refresh.
Return:
1. exact file paths
2. key functions
3. likely bug location
4. what you did not verify
Keep it under 15 bullets.

이 정도면 subagent 결과가 메인 세션에 바로 붙는다.

반대로 “전체 구조 분석해줘”라고 던지면 전체 구조 분석이 돌아온다.

무섭게 성실한 답이 온다.

그리고 우리는 다시 커피를 찾는다.

실무 판단표

질문 예면 아니오면
중간 탐색 결과를 나중에 다시 볼 필요가 적나 subagent 메인 세션
작업이 read-only인가 subagent 우선 권한 범위 먼저 제한
병렬로 돌려도 충돌이 없나 subagents 병렬 순차 처리
결과 포맷이 명확한가 위임 가능 먼저 포맷 정의
사용자의 의도를 다시 확인해야 하나 메인 세션 subagent 가능
수정 파일 범위가 겹치나 메인 세션 조율 worker 분리 가능

운영 기준은 결국 하나다.

subagent는 메인 세션을 대신하는 상사가 아니다.

메인 세션의 기억을 보호하는 조사원이다.

이 관점을 잡으면 훨씬 덜 꼬인다.

함께 보면 좋은 글

FAQ

Q1. Claude Code subagents는 무조건 context 절약에 좋나?

아니다.

대량 탐색이나 독립 리뷰에는 좋지만, 작은 작업에 쓰면 위임 오버헤드가 더 크다.

결과를 다시 해석해야 하면 오히려 메인 세션이 피곤해진다.

Q2. subagent가 메인 세션의 전체 맥락을 다 아나?

그렇게 보면 위험하다.

공식 문서 기준 subagent는 자체 context와 system prompt를 가진다.

필요한 배경은 프롬프트에 명시해서 넘겨야 한다.

Q3. 병렬 subagents를 많이 돌리면 무조건 빠른가?

독립 작업이면 빠르다.

하지만 같은 파일을 수정하거나, 한 결과가 다음 결과의 입력이면 병렬이 아니라 충돌이다.

그때는 메인 세션에서 순서를 잡는 편이 낫다.

Q4. custom subagent는 언제 만들면 되나?

같은 역할을 반복하고, tool 제한이 중요하고, 결과 포맷을 고정하고 싶을 때 만든다.

한 번 쓸 작업이면 명시 프롬프트가 더 간단하다.

Q5. hooks와 subagents 중 무엇부터 배워야 하나?

처음에는 subagents보다 context 관리 기준부터 잡는 게 낫다.

그다음 read-only 탐색용 subagent를 쓰고, 반복 이벤트가 보이면 hooks를 붙이면 된다.

자동화는 마지막에 붙여도 늦지 않다.

공식 출처

마무리

Claude Code subagents는 많이 켜는 기능이 아니라 잘 나누는 기능이다.

메인 세션은 목표와 결정권을 잡고, subagent는 대량 탐색과 독립 리뷰를 맡는다.

이렇게 나누면 context bloat가 줄고, 대화는 덜 지저분해지고, 작업 결과도 더 검토하기 쉬워진다.

반대로 subagent를 만능 팀원처럼 쓰면 작업은 병렬화되는 듯하지만 결정은 더 느려질 수 있다.

기준은 간단하다.

메인 세션이 계속 기억해야 하는 일은 남긴다.

한 번 보고 버릴 탐색은 보낸다.

그 정도만 지켜도 Claude Code subagents는 훨씬 덜 부담스럽고 훨씬 더 쓸 만해진다.