에이전트 시스템

Claude Code의 에이전트 시스템은 하나의 Claude 인스턴스가 다른 인스턴스에 작업을 위임할 수 있게 합니다. 에이전트는 독립적인 대화 컨텍스트와 도구 세트를 가지며, 부모 에이전트와 메시지를 주고받으면서 복잡한 작업을 분할 정복합니다.

에이전트 시스템은 세 가지 핵심 축으로 구성됩니다:

• 에이전트 타입: built-in, custom(플러그인), user/project 정의 에이전트
• 생명주기: 동기/비동기 실행, 포크 패스, 워크트리 격리
• 통신: SendMessageTool을 통한 메시지 교환과 결과 반환

에이전트는 세 가지 타입으로 분류되며, 동일한 이름의 에이전트가 여러 소스에서 정의될 경우 우선순위에 따라 하나만 활성화됩니다.

3가지 에이전트 타입

• Built-in 에이전트: Claude Code에 내장된 기본 에이전트 (General Purpose, Explore, Plan, Verification, Fork, StatuslineSetup)
• Custom/Plugin 에이전트: MCP 서버나 플러그인을 통해 등록된 에이전트
• User/Project 에이전트: 사용자 설정이나 프로젝트 설정에서 정의된 에이전트

우선순위 체계

동일한 agentType의 에이전트가 여러 소스에서 정의되면 다음 순서로 우선순위가 적용됩니다:

// 에이전트 우선순위 (높음 → 낮음)
// 뒤의 그룹이 앞의 그룹을 덮어쓰므로 policySettings가 최고 우선순위
// 1. built-in       — 시스템 내장, 가장 낮은 우선순위
// 2. plugin         — MCP/플러그인 제공
// 3. userSettings   — ~/.claude/settings.json
// 4. projectSettings — .claude/settings.json
// 5. flag           — CLI 플래그로 전달
// 6. policySettings — MDM/엔터프라이즈 정책, 최고 우선순위

Claude Code에는 여섯 개의 빌트인 에이전트가 내장되어 있으며, 각각 특화된 역할을 담당합니다.

• General Purpose: 범용 하위 에이전트. 부모의 도구 세트를 상속하며 대부분의 위임 작업에 사용됩니다.
• Explore: 코드베이스 탐색 전용. 읽기 전용 도구만 사용하며 변경을 가하지 않습니다.
• Plan: 계획 수립 전용. 동기 실행됩니다.
• Verification: 구현 결과 검증. 테스트 실행, 린트 체크 등을 수행합니다. background: true가 하드코딩된 유일한 빌트인 에이전트로, 항상 비동기 실행됩니다.
• Fork: 부모 대화의 컨텍스트를 포크하여 독립적인 분기를 생성합니다.
• StatuslineSetup: 상태줄 설정 에이전트 — 사용자의 Claude Code 상태줄 세팅을 구성합니다.

// 빌트인 에이전트 정의 예시
const verificationAgent = {
  name: 'Verification',
  type: 'built-in',
  background: true,   // 항상 비동기 — 유일한 빌트인
  description: '구현 결과 검증 에이전트',
}

에이전트는 동기 또는 비동기로 실행될 수 있습니다. 비동기 실행 여부는 shouldRunAsync 함수가 6가지 조건을 평가하여 결정합니다.

shouldRunAsync 6개 조건

1. 에이전트 정의에 background: true 하드코딩: Verification 에이전트처럼 항상 비동기
2. 호출 시 run_in_background: true 파라미터: 명시적 비동기 요청
3. 코디네이터 모드 활성화: 코디네이터는 워커를 비동기로 스폰
4. 팀 컨텍스트 내 실행: 팀 메이트 간 비동기 실행
5. 현재 에이전트 깊이 제한 초과: 중첩 깊이가 너무 깊으면 비동기 전환
6. 사용자 설정 오버라이드: 설정에서 특정 에이전트의 비동기 여부를 강제

포크 에이전트는 부모 대화의 컨텍스트를 복제하여 독립적인 분기를 생성합니다. 이때 핵심 최적화는 바이트 동일 접두사를 통한 프롬프트 캐시 공유입니다.

바이트 동일 접두사

포크 자식은 부모와 동일한 placeholder 텍스트를 사용합니다. 이 텍스트가 동일하면 Anthropic API의 서버 측 프롬프트 캐시에서 동일한 캐시 접두사를 공유하게 됩니다. 결과적으로 부모가 이미 캐시한 수만 토큰의 시스템 프롬프트와 도구 정의를 자식이 재활용할 수 있어, API 비용과 지연 시간이 크게 절감됩니다.

// 포크 에이전트 — 바이트 동일 접두사로 캐시 공유
// 부모와 자식이 동일한 도구 목록 + 시스템 프롬프트를 사용
// → API 서버에서 동일 캐시 히트
const forkChild = {
  systemPrompt: parentSystemPrompt,  // 바이트 동일
  tools: parentTools,                // 바이트 동일
  messages: [parentPrefix, ...forkSpecificMessages],
}

에이전트가 파일시스템 변경을 수반하는 작업을 수행할 때, git worktree를 사용하여 메인 작업 디렉토리와 격리된 환경에서 작업합니다.

워크트리 스마트 정리

에이전트가 완료되면 워크트리의 상태에 따라 정리 전략이 달라집니다:

• git 추적 변경이 없는 경우: 워크트리와 연결된 브랜치를 즉시 삭제합니다. 변경 사항이 없으므로 보존할 이유가 없습니다.
• git 추적 변경이 있는 경우: 워크트리를 유지하여 부모 에이전트나 사용자가 결과를 검사하고 병합할 수 있게 합니다.

// 워크트리 정리 로직
async function cleanupWorktree(worktreePath: string) {
  const hasChanges = await hasTrackedChanges(worktreePath)
  if (!hasChanges) {
    await removeWorktree(worktreePath)  // 워크트리 + 브랜치 삭제
  }
  // 변경 있으면 보존 — 부모/사용자가 검사
}

SendMessageTool은 실행 중인 에이전트에 메시지를 보내는 도구입니다. 비동기 에이전트의 상태를 조회하거나, 추가 지시를 전달하거나, 결과를 수집하는 데 사용됩니다.

에이전트 프론트매터 필드

에이전트 정의 파일에는 다음과 같은 프론트매터 필드가 포함됩니다:

• name — 에이전트 식별 이름
• description — 에이전트 역할 설명 (모델이 선택 시 참조)
• background — 비동기 실행 여부 (true/false)
• tools — 사용 가능한 도구 목록 또는 필터
• model — 사용할 모델 지정 (선택)
• systemPrompt — 커스텀 시스템 프롬프트 (선택)