에이전트 시스템 개요

에이전트 시스템이란

Claude Code의 에이전트 시스템은 복잡한 작업을 전문화된 서브에이전트 에 위임하는 메커니즘입니다. 부모 에이전트가 Task 도구를 사용해 자식 에이전트를 생성하고, 자식 에이전트는 독립적인 에이전틱 루프를 실행하여 결과를 반환합니다.

부모 에이전트 (메인 루프)
    ↓ Task 도구 호출
서브에이전트 1 (독립 루프)  ←→  서브에이전트 2 (독립 루프)
    ↓ 결과 반환                      ↓ 결과 반환
부모 에이전트 (결과 수집 및 통합)

Task 도구 (AgentTool)

Task 도구는 격리된 서브에이전트를 스폰하는 도구입니다. 각 서브에이전트는 별도의 에이전틱 루프 를 가집니다.

// Task 도구 파라미터
{
  description: "인증 모듈 보안 취약점 분석",  // 작업 설명 (로그/UI 표시용)
  prompt: `src/auth/ 디렉토리를 분석하여 보안 취약점을 찾아주세요.
    특히 다음을 확인하세요:
    - SQL 인젝션 가능성
    - 입력 검증 누락
    - 하드코딩된 자격 증명
    결과를 심각도별로 정리해 주세요.`,
  subagent_type: "general",     // 에이전트 유형
  run_in_background: false,     // 비동기 실행 여부
  isolation: "none"             // 격리 수준
}

서브에이전트 파라미터

파라미터	타입	기본값	설명
description	string	필수	작업 요약 (UI 표시용)
prompt	string	필수	서브에이전트에 전달할 전체 지시
subagent_type	string	"general"	에이전트 전문 유형
run_in_background	boolean	false	비동기 실행 여부
isolation	string	"none"	"none" 또는 "worktree"

서브에이전트의 격리 특성

서브에이전트는 부모와 완전히 격리된 컨텍스트 에서 실행됩니다.

부모 에이전트의 대화 히스토리:
  [메시지 1] [메시지 2] [메시지 3] ...

서브에이전트의 대화 히스토리:
  [빈 슬레이트] ← 부모 히스토리에 접근 불가
  [Task prompt만 전달받음]

이 격리로 인해 서브에이전트에 프롬프트를 작성할 때 모든 필요한 컨텍스트를 포함 해야 합니다. “앞서 논의한 방식으로”와 같은 표현은 서브에이전트에서 작동하지 않습니다.

제한된 도구 세트

서브에이전트는 부모 에이전트의 전체 도구 세트를 사용하지 않을 수 있습니다. subagent_type 에 따라 허용된 도구만 사용 가능합니다.

에이전트 유형	허용 도구	용도
general	모든 도구	일반 목적 작업
code-review	Read, Grep, Glob	읽기 전용 코드 검토
research	WebFetch, WebSearch, Read	정보 수집

에이전트 사용 판단 기준

사용해야 할 때

✓ 병렬 처리가 유리한 독립 작업
  예: 3개 라이브러리를 동시에 리서치

✓ 전문 분야 작업
  예: 보안 분석, 성능 프로파일링, 접근성 감사

✓ 장시간 작업 (메인 루프 차단 방지)
  예: 전체 코드베이스 분석, 대규모 마이그레이션

✓ 격리된 탐색 (실험적 변경)
  예: isolation: "worktree"로 안전한 실험

사용하지 않아야 할 때

✗ 단순 작업
  예: 파일 하나 읽기, 변수명 변경

✗ 소규모 파일 읽기
  예: 2-3개 파일 검토 (직접 Read가 더 빠름)

✗ 몇 번의 도구 호출로 완료 가능한 작업
  예: 설정 파일 수정, 단순 버그 수정

✗ 순차 의존성이 강한 작업
  예: A 결과를 보고 B를 결정해야 할 때

실용적인 에이전트 활용 예시

병렬 분석

부모: "세 가지 상태 관리 라이브러리를 비교해줘"

서브에이전트 1: "Zustand 공식 문서와 GitHub 분석"
서브에이전트 2: "Jotai 공식 문서와 GitHub 분석"
서브에이전트 3: "Recoil 공식 문서와 GitHub 분석"

← 세 에이전트 동시 실행 →

부모: 결과 수집 후 비교표 작성

전문 역할 분담

부모: "인증 기능을 구현하고 검토해줘"

에이전트 1 (구현): auth.ts 작성
에이전트 2 (보안 검토): 구현된 코드 보안 분석
에이전트 3 (테스트): 단위 테스트 작성

에이전트 시스템을 올바르게 활용하면 단일 에이전트로는 처리하기 어려운 대규모 작업을 효율적으로 수행할 수 있습니다.