Claude Code Task 기능 완벽 가이드: 서브에이전트로 개발 생산성 극대화
Claude Code Task 기능 완벽 가이드: 서브에이전트로 개발 생산성 극대화
AI 코딩 어시스턴트를 쓰면서 "한 번에 하나의 작업만 처리할 수 있다면 좋겠는데"라고 느껴본 적 있으신가요? Claude Code의 Task 기능은 이 한계를 정면으로 돌파합니다. 하나의 AI가 아니라, 전문화된 AI 팀을 구성해서 복잡한 작업을 병렬로 처리할 수 있거든요.
이 글에서는 Claude Code Task 기능의 핵심 개념부터 실전 활용법까지, 개발 생산성을 한 단계 끌어올리는 방법을 상세히 알아보겠습니다.
Claude Code Task란 무엇인가요?
Claude Code Task는 독립된 컨텍스트 윈도우에서 전문화된 서브에이전트를 생성(spawn)하여 병렬 작업을 수행하는 Claude Code의 핵심 실행 메커니즘입니다.
쉽게 말하면, 메인 Claude가 "팀장" 역할을 하면서 전문가 서브에이전트에게 특정 작업을 위임하는 구조입니다. 각 서브에이전트는 자신만의 컨텍스트를 가지고 독립적으로 작업하기 때문에 메인 대화의 문맥이 오염되지 않습니다.
Task 도구를 호출할 때는 다음 파라미터를 지정합니다:
| 파라미터 | 필수 | 설명 |
|---|---|---|
description | Yes | 3-5단어 짧은 작업 요약 |
prompt | Yes | 서브에이전트가 수행할 상세 지침 |
subagent_type | Yes | 에이전트 타입 (Explore, general-purpose, Plan, Bash) |
model | No | 모델 오버라이드 (sonnet, opus, haiku) |
run_in_background | No | 백그라운드 실행 여부 |
빌트인 서브에이전트 4종 비교
Claude Code에는 용도별로 최적화된 4가지 빌트인 서브에이전트가 내장되어 있습니다.
Explore: 빠른 코드베이스 탐색
Explore 에이전트는 Haiku 모델을 사용하여 빠르고 가볍게 코드베이스를 분석합니다. Read-only 접근만 가능하기 때문에 코드를 수정할 위험 없이 안전하게 탐색할 수 있어요. 호출 시 quick, medium, very thorough 중 탐색 깊이를 지정할 수 있습니다.
Plan: 전략 수립 전문가
Plan 에이전트는 메인 대화의 모델을 상속받아 코드베이스를 분석하고 실행 계획을 수립합니다. 역시 Read-only이며, Plan mode가 활성화되었을 때 컨텍스트 수집 역할을 합니다.
general-purpose: 만능 실행자
모든 도구에 접근 가능한 general-purpose 에이전트는 탐색부터 코드 수정, 복잡한 추론까지 처리합니다. 다단계 종속 작업이나 탐색과 수정이 함께 필요한 상황에서 위력을 발휘합니다.
Bash: 터미널 전문가
별도 컨텍스트에서 터미널 명령만 실행하는 가벼운 에이전트입니다. 빌드, 테스트, 배포 스크립트 실행 등을 격리해서 처리할 때 유용합니다.
| 타입 | 모델 | 도구 접근 | 최적 용도 |
|---|---|---|---|
| Explore | Haiku | Read-only | 코드 탐색, 분석 |
| Plan | 메인 상속 | Read-only | 계획 수립, 리서치 |
| general-purpose | 메인 상속 | 전체 | 복잡한 다단계 작업 |
| Bash | 메인 상속 | 터미널만 | 명령 격리 실행 |
커스텀 서브에이전트 만들기
빌트인 서브에이전트만으로 부족하다면 자신만의 전문가를 만들 수 있습니다. 프로젝트의 .claude/agents/ 디렉토리에 YAML frontmatter가 포함된 Markdown 파일을 추가하면 됩니다.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep, Bash
model: sonnet
maxTurns: 10
---
You are a senior code reviewer. Focus on:
- Code quality and readability
- Security vulnerabilities
- Performance bottlenecks
주요 설정 필드
| 필드 | 설명 | 예시 |
|---|---|---|
name | 고유 식별자 (소문자+하이픈) | code-reviewer |
description | 위임 판단 기준 | "코드 품질 검토" |
tools | 사용 가능한 도구 | Read, Write, Bash |
model | 사용 모델 | sonnet, opus, haiku |
skills | 시작 시 로드할 스킬 | 스킬 내용 자동 주입 |
mcpServers | MCP 서버 접근 | 외부 도구 연동 |
memory | 영구 메모리 스코프 | user, project, local |
파일 위치 우선순위
| 위치 | 범위 | 우선순위 |
|---|---|---|
--agents CLI 플래그 | 현재 세션 | 1 (최고) |
.claude/agents/ | 현재 프로젝트 | 2 |
~/.claude/agents/ | 모든 프로젝트 | 3 |
Plugin agents/ | 플러그인 활성 시 | 4 (최저) |
포그라운드 vs 백그라운드 실행
Task 기능의 또 다른 강점은 실행 모드를 선택할 수 있다는 점입니다.
포그라운드 실행은 서브에이전트가 완료될 때까지 메인 대화를 차단합니다. 권한 프롬프트와 질문이 사용자에게 직접 전달되기 때문에 세밀한 제어가 필요한 작업에 적합합니다.
백그라운드 실행은 run_in_background: true로 설정하면 즉시 반환됩니다. 여러 서브에이전트를 동시에 실행할 수 있어서 독립적인 작업들을 병렬 처리할 때 효율적이에요. 다만 백그라운드에서는 MCP 도구를 사용할 수 없다는 제약이 있습니다.
실행 중인 포그라운드 작업은 Ctrl+B를 눌러 백그라운드로 전환할 수도 있습니다.
Task vs Agent Teams: 언제 무엇을 쓸까?
Claude Code에는 Task(서브에이전트) 외에도 Agent Teams라는 고급 협업 기능이 있습니다. 둘의 핵심 차이는 통신 방식입니다.
| 항목 | Task (서브에이전트) | Agent Teams |
|---|---|---|
| 통신 | 메인에게만 결과 보고 | 팀원끼리 직접 메시지 |
| 조율 | 메인이 관리 | 공유 태스크 리스트로 자체 조율 |
| 비용 | 낮음 (결과 요약만 전달) | 높음 (팀원별 독립 컨텍스트) |
| 상태 | 안정 (GA) | 실험적 (환경 변수 활성화 필요) |
| 최적 용도 | 결과만 중요한 집중 작업 | 논의와 협업이 필요한 복잡한 작업 |
Task를 선택해야 할 때: 코드 분석, 파일 검색, 단순 수정처럼 결과만 반환하면 되는 경우
Agent Teams를 선택해야 할 때: 프론트엔드/백엔드 동시 개발, 코드 리뷰와 수정이 오가는 경우처럼 팀원 간 논의가 필요한 상황
실전 활용 베스트 프랙티스
Task 기능을 최대한 활용하기 위한 핵심 원칙을 정리했습니다.
-
집중된 역할 부여: 각 서브에이전트에 하나의 특정 작업만 맡기세요. "코드 분석하고 수정하고 테스트까지"보다 역할을 분리하는 게 품질이 높아집니다.
-
최소 권한 원칙: 필요한 도구만 부여하세요. 탐색만 필요한 에이전트에 Write 권한을 주면 의도치 않은 수정이 발생할 수 있습니다.
-
병렬 실행 극대화: 독립된 작업은 하나의 메시지에 여러 Task를 담아 동시에 실행하세요. 순차 실행 대비 시간이 크게 절약됩니다.
-
버전 관리:
.claude/agents/디렉토리를 Git에 커밋하면 팀 전체가 동일한 에이전트 구성을 공유할 수 있습니다. -
컨텍스트 보호: 대량 출력이 예상되는 작업은 반드시 서브에이전트로 격리하세요. 메인 컨텍스트의 품질을 유지하는 핵심 전략입니다.
알아두면 좋은 제한사항
Task 기능을 사용할 때 몇 가지 제약 사항을 미리 알아두면 좋습니다.
- 서브에이전트는 다른 서브에이전트를 생성할 수 없습니다 (중첩 불가)
- 부모 대화의 스킬을 자동 상속하지 않으므로
skills필드로 명시적 지정이 필요합니다 - 백그라운드 서브에이전트에서는 MCP 도구를 사용할 수 없습니다
- Agent Teams는 세션 재개 시 in-process 팀원 복원이 불가합니다
마무리
Claude Code Task 기능은 단일 AI 어시스턴트의 한계를 넘어 전문화된 AI 팀을 구성할 수 있게 해주는 핵심 기능입니다. 빌트인 서브에이전트로 빠르게 시작하고, 커스텀 에이전트로 팀의 워크플로우에 맞게 확장하세요. 프로젝트 복잡도가 높을수록 Task 기능의 가치는 더욱 커집니다.
지금 바로 .claude/agents/ 폴더에 첫 번째 커스텀 에이전트를 만들어보시는 건 어떨까요?
자주 묻는 질문 (FAQ)
Q: 서브에이전트를 몇 개까지 동시에 실행할 수 있나요?
공식적인 동시 실행 제한은 없지만, 각 서브에이전트가 별도 컨텍스트를 소비하므로 실용적으로 3-5개를 권장합니다. Agent Teams의 경우 리더 포함 최대 4명까지 동시 운영 가능합니다.
Q: 커스텀 에이전트에서 MCP 서버를 사용할 수 있나요?
네, frontmatter의 mcpServers 필드에 사용할 MCP 서버를 지정하면 됩니다. 단, 백그라운드 실행 시에는 MCP 도구 사용이 불가능하므로 포그라운드로 실행해야 합니다.
Q: Task와 Agent Teams 중 어떤 것을 먼저 배워야 하나요?
Task(서브에이전트)부터 시작하세요. GA 상태로 안정적이고 비용도 낮습니다. 팀원 간 협업이 필요한 복잡한 프로젝트에서만 Agent Teams로 확장하는 것을 권장합니다.
Q: 서브에이전트의 작업 기록은 어디에 저장되나요?
트랜스크립트가 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl 경로에 저장됩니다. resume 기능으로 이전 작업을 이어서 진행할 수도 있습니다.
