서브 에이전트

Claude Code는 자율적인 서브 에이전트에게 작업을 위임할 수 있어요. 각 서브 에이전트는 독립된 컨텍스트에서 실행되어 메인 스레드를 보호하고 여러 작업을 동시에 처리할 수 있습니다.

서브 에이전트란?

서브 에이전트는 메인 스레드가 특정 작업을 처리하기 위해 호출하는 보조 Claude Code 인스턴스예요. 자체 컨텍스트를 가지고 있어서 부모 대화 내역을 볼 수 없고, 서브 에이전트의 작업(파일 읽기, 명령어 실행 등)이 메인 컨텍스트를 오염시키지 않습니다.

구체적인 장점 두 가지:

• 격리: 탐색 작업(아키텍처 파악을 위해 파일 50개 읽기 등)은 컨텍스트 창을 많이 소모해요. 서브 에이전트에게 위임하면 이후 작업을 위해 메인 스레드의 컨텍스트를 아낄 수 있습니다.
• 전문화: 각 서브 에이전트에게 역할을 부여할 수 있어요. 탐색, 리팩토링, 테스트 작성, 문서 작성 등. 메인 스레드는 조율하고 서브 에이전트가 실행합니다.

즉석 서브 에이전트 실행하기

서브 에이전트를 사용하기 위해 사전 설정이 필요하지 않아요. 프롬프트에서 바로 요청하면 됩니다.

서브 에이전트를 실행해서 src/ 폴더를 탐색하고 아키텍처 요약을 알려줘. 아무것도 수정하지 마.

Claude Code가 서브 에이전트를 생성하고 작업을 넘긴 뒤, 결과를 메인 스레드로 돌려줍니다. 작업이 끝나면 서브 에이전트는 사라집니다.

한 번의 요청으로 여러 작업을 병렬로 실행할 수도 있어요.

서브 에이전트 두 개를 동시에 실행해줘. 첫 번째는 package.json의 직접 의존성과 버전 목록을 만들고, 두 번째는 프로젝트에서 TODO가 있는 파일을 찾아줘.

/agents 메뉴

/agents 슬래시 명령어는 현재 세션에서 사용 가능한 모든 서브 에이전트를 보여줘요. 직접 설정한 에이전트도 여기에 나타납니다 (다음 섹션 참고).

$/agents

이 메뉴에서 사용 가능한 에이전트, 설명, 그리고 접근 가능한 도구 목록을 확인할 수 있어요. 커스텀 에이전트가 세션 시작 시 제대로 로드되었는지 확인할 때 유용합니다.

커스텀 서브 에이전트 설정하기

테스트 작성, SQL 검증, 문서 검토처럼 반복적인 작업에는 영구적인 서브 에이전트를 정의할 수 있어요. .claude/agents/ 폴더에 마크다운 파일을 만들면 됩니다.

에이전트 파일 구조

.claude/agents/test-writer.md 파일을 아래 형식으로 만드세요.

---
name: test-writer
description: 입력으로 받은 TypeScript 함수에 대한 유닛 테스트를 작성합니다. 사용자가 함수나 모듈을 테스트하고 싶을 때 사용하세요.
tools:
  - Read
  - Write
  - Bash
model: sonnet
---

당신은 Vitest를 사용하는 TypeScript 유닛 테스트 전문가입니다.
받은 함수마다 아래 절차를 따르세요.
1. 일반 케이스와 엣지 케이스를 파악합니다.
2. 소스 파일과 같은 위치에 `*.test.ts` 파일에 테스트를 작성합니다.
3. `pnpm test --run`을 실행해서 테스트가 통과하는지 확인합니다.

프론트매터 필드:

• name: 케밥 케이스 식별자. 에이전트를 호출할 때 사용합니다 (test-writer로 이 함수 테스트해줘).
• description: 이 에이전트를 언제 사용하는지 설명합니다. Claude가 이 설명을 읽고 관련 상황에서 자동으로 에이전트를 호출할지 결정해요.
• tools: 허용된 도구 목록. 도구를 제한하면 위험 범위를 줄일 수 있습니다.
• model (선택): 사용할 모델. 대부분의 보조 에이전트에는 sonnet이 적합합니다.

파일 본문

프론트매터 이후의 내용이 에이전트의 시스템 프롬프트예요. 에이전트의 행동 방식, 제약 조건, 응답 스타일을 여기서 정의합니다.