Part I · CHAPTER 04

서브에이전트

컨텍스트를 위임하라

한 사람이 직접 모든 자료를 다 뒤지면 책상이 어지러워져요. 같은 일을 부하 직원에게 시키고 요약만 받으면, 책상은 깔끔한 채로 핵심 정보만 손에 쥘 수 있어요. 서브에이전트가 정확히 그 부하 직원이에요.

섹션 3에서 확인한 문제 — 동적 레이어는 정제 없이 쌓여요. 코드베이스를 탐색하면 파일 전체가, 테스트를 돌리면 반복 로그 전체가, 에러가 나면 스택 트레이스 전체가 메인 컨텍스트에 들어와요.

대규모 작업이라면 파일 탐색 수백 회, 테스트 수십 번 — 그것만으로 컨텍스트가 가득 차요. 관련 없는 정보로 오염된 컨텍스트는 LLM의 실효 집중력을 떨어뜨려요.

해법: 작업 위임, 요약 수신

서브에이전트(Sub-agent) 는 메인 에이전트가 생성하는 독립 에이전트예요. 별도의 컨텍스트 윈도우에서 작업을 수행하고, 완료 후 요약된 결과만 메인에게 반환해요.

sequenceDiagram participant Main as 메인 에이전트(Main Agent) participant Sub as 서브에이전트(Sub-agent)<br/>독립 컨텍스트 Main->>Sub: "src/ 전체에서 API 파일 찾아줘" Note over Sub: 파일 수백 개 탐색<br/>패턴 매칭 · 로그 처리 Sub->>Main: "routes/api.py, controllers/user.py" Note over Main: 컨텍스트에 추가된 것:<br/>요약 두 줄

메인 컨텍스트에 들어오는 것은 요약뿐이에요. 서브에이전트가 내부에서 얼마나 많은 파일을 읽고 로그를 처리했든, 메인은 결과만 받아요.

직접 수행 vs 위임 — 메인 책상에 쌓이는 것

같은 작업을 직접 처리할 때와 위임할 때, 메인 컨텍스트에 들어오는 토큰의 양이 얼마나 다른지 한눈에 보면 이래요.

flowchart LR subgraph Direct["직접 수행(DIRECT — no sub-agent)"] direction TB DR1["메인이 file_001.py 읽기 [+800 tok]"] DR2["메인이 file_002.py 읽기 [+650 tok]"] DR3["메인이 file_003.py 읽기 [+1200 tok]"] DR4["... 추가 47개 파일 ... [+30000 tok]"] DR5["grep 출력 [+5000 tok]"] DR6["메인 attention이 잡음에 희석"] DR7["합계: +37K tokens 원본 바이트"] DR1 --> DR2 --> DR3 --> DR4 --> DR5 --> DR6 --> DR7 end subgraph Delegated["위임(DELEGATED)"] direction TB DG1["메인: &quot;src/에서 API 파일 찾아줘&quot;"] DG2["서브에이전트(독립 컨텍스트)<br/>파일 50개 읽기, grep, 스캔<br/>내부에서 30K+ 토큰 소모 후 종료"] DG3["메인 수신: &quot;routes/api.py,<br/>controllers/user.py&quot; — 두 줄"] DG1 --> DG2 --> DG3 end

같은 작업, 같은 결론. 다만 메인 컨텍스트에는 한쪽이 37,000 토큰을 부어 넣고, 다른 한쪽은 두 줄만 받아요. 메인이 이후 작업에서 쓸 수 있는 책상 면적이 차이가 나요.

직접 수행서브에이전트 위임
메인 컨텍스트 증가파일 수백 개 내용 전부요약 단락 하나
컨텍스트 오염높음없음
LLM 집중력떨어짐유지됨

코딩 에이전트에서의 구현 — Claude Code 사례

Claude Code에서 서브에이전트는 Task 도구(또는 문서상 Agent 도구로 지칭되기도 함)로 호출해요. 작업을 위임하고 결과를 즉시 받거나, 시간이 오래 걸리는 일은 백그라운드로 돌릴 수도 있어요.

Task({
  description: "코드베이스 탐색",
  subagent_type: "Explore",        # 탐색에 특화된 서브에이전트 프리셋
  prompt: "src/ 디렉토리에서 API 관련 파일을 탐색하고 "
          "파일 경로와 핵심 역할만 요약해 반환해줘. 중간 로그 생략.",
  run_in_background: false         # true로 주면 비동기 백그라운드 실행
})

서브에이전트에 맞는 작업:

  • 코드베이스 탐색 (파일 수백 개 검색)
  • 반복 테스트 및 에러 로그 분석
  • 독립된 유틸리티 구현
  • 보안 검토, 의존성 분석

핵심: 서브에이전트 프롬프트에 출력 형식을 명시하세요.

"탐색 후 파일 경로와 핵심 내용만 반환해줘. 중간 과정은 생략."

결과를 통째로 받으면 메인 컨텍스트가 똑같이 오염돼요. 요약 형식을 프롬프트에서 강제하는 것이 서브에이전트 활용의 핵심이에요.

코딩 에이전트에서의 구현 — Codex 사례

Codex CLI 도 같은 위임 메커니즘을 갖고 있어요. 정의는 ~/.codex/config.toml 의 [agents] 테이블에 두고, 세션 안에서는 /agent 슬래시 커맨드로 활성 스레드를 전환해요. 별도 토글 없이 기본 활성이라 설정 파일에 에이전트만 등록하면 바로 써요. 큰 작업을 여러 갈래로 쪼개고 싶을 때는 spawn_agents_on_csv 같은 위임 도구로 분기해요.

# ~/.codex/config.toml

# 서브에이전트 1개 등록 (instructions 는 별도 파일로 분리)
[agents.explore]
description = "코드베이스 탐색 전용"
config_file = "./agents/explore.toml"   # 본문은 별도 TOML 파일에

# 분기 한도 — [agents] 글로벌 테이블 직속
[agents]
max_threads = 4                 # 동시 실행 스레드 수
max_depth = 2                   # 재귀 분기 한도
job_max_runtime_seconds = 600   # 한 서브에이전트 작업 시간 한도

./agents/explore.toml 같은 별도 파일에는 instructions 본문이 들어가요 — 예컨대 "src/ 디렉토리에서 요청한 파일을 탐색하고 파일 경로와 핵심 역할만 한 줄씩 요약해 반환해라. 중간 로그·grep 출력은 절대 본문에 넣지 마라" 같은 한 단락.

# 세션 안에서
/agent explore "src/ 에서 API 관련 파일만 골라줘"

호출 형식은 다르지만 자리는 정확히 같아요 — Claude Code 의 Task 도구가 함수 호출이라면 Codex 는 설정 파일 + 슬래시 커맨드의 짝이에요. 둘 다 별도 컨텍스트 윈도우에서 실행 → 요약만 메인으로 반환이라는 핵심 동작이 동일하고, 작업 시간 / 분기 한도를 잡는 토글이 있다는 점도 닮았어요. Codex 쪽 상세는 Codex 사용 가이드 §5 에서 다뤄요.

두 도구 공통의 핵심: 어느 쪽이든 서브에이전트 프롬프트에 출력 형식을 못박는 한 줄이 결과 품질을 결정해요. "탐색 후 파일 경로와 핵심 내용만 반환, 중간 과정 생략" — 이 한 줄이 빠지면 위임의 의미가 사라져요.