Claude Code Agent 서브에이전트 병렬 작업 가이드 2026

리서치 에이전트 3개를 병렬로 돌리니 코드베이스 분석이 10분에서 3분으로 줄었다. 혼자 개발하는데 팀이 생긴 기분이었다.

Claude Code Agent(서브에이전트)란, 메인 Claude 세션 안에서 독립적인 컨텍스트 윈도우를 가지고 특화된 작업을 수행하는 AI 보조 시스템이다. 각 에이전트는 자기만의 시스템 프롬프트, 도구 접근 권한, 모델 설정을 갖는다. 최대 10개의 서브에이전트가 동시에 실행된다.

이 글은 "Claude Code Power User Guide" 시리즈의 마지막 편이다. Part 1에서 MCP, Part 2에서 Hooks를 다뤘고, 이번에는 서브에이전트와 에이전트 팀으로 병렬 작업을 구성하는 방법을 정리한다.

내장 에이전트부터 이해하고 시작한다

Claude Code에는 이미 6개의 내장 에이전트가 있다. Explore 에이전트는 Haiku 모델로 빠르게 코드베이스를 검색하고 분석한다. 읽기 전용이라 실수로 파일을 수정할 위험이 없다. Plan 에이전트는 플랜 모드에서 리서치를 담당하고, General-purpose 에이전트는 모든 도구를 사용해 복잡한 멀티스텝 작업을 처리한다.

처음에는 내장 에이전트만으로 충분했다. 코드 분석이 필요하면 Explore가 자동으로 호출되고, 복잡한 리팩토링은 General-purpose가 맡았다. 하지만 프로젝트가 커지면서 한계가 보이기 시작했다. code-reviewer 에이전트를 만들어서 코드 작성 직후 자동 리뷰를 돌리고 싶었고, 테스트 작성과 문서 업데이트를 병렬로 처리하고 싶었다.

커스텀 에이전트를 만드는 3가지 방법

가장 쉬운 방법은 /agents 커맨드다. Claude가 대화형으로 에이전트를 생성해준다. .claude/agents/ 디렉토리에 마크다운 파일이 만들어진다.

직접 마크다운 파일을 작성할 수도 있다. YAML 프론트매터에 name, description, tools, model, permissionMode 같은 설정을 넣는다. 코드 리뷰어 에이전트를 예로 들면, tools에 Read, Grep, Glob, Bash만 허용하고 model은 sonnet으로 설정한다. 읽기 전용이니까 실수로 코드를 수정할 일이 없다.

---
name: code-reviewer
description: "코드 리뷰 전문 에이전트. 버그, 성능, 보안 이슈를 찾는다"
tools: [Read, Grep, Glob, Bash]
model: sonnet
permissionMode: plan
---

CLI에서 JSON으로 인라인 정의하는 방법도 있다. claude --agents '{"reviewer": {"description": "...", "prompt": "..."}}' 형태로 일회성 에이전트를 바로 실행할 수 있다.

호출 방식은 4가지다. description을 잘 작성하면 Claude가 자동으로 적합한 에이전트를 위임한다. "code-reviewer 에이전트를 써줘"라고 자연어로 요청하거나, @"code-reviewer (agent)" 멘션으로 직접 호출하거나, claude --agent code-reviewer로 세션 전체를 특정 에이전트 모드로 실행할 수도 있다.

포그라운드 vs 백그라운드, 그리고 에이전트 팀

서브에이전트는 기본적으로 포그라운드에서 실행된다. 블로킹 방식이라 권한 요청이 부모 에이전트를 통해 전달된다. 백그라운드로 전환하면(background: true 또는 Ctrl+B) 여러 에이전트가 동시에 실행되고, 권한은 사전 승인된 상태로 동작한다.

내가 실제로 쓰는 패턴은 이렇다. 리팩토링할 때 리서치 에이전트 3개를 백그라운드로 돌린다. 하나는 관련 파일 탐색, 하나는 의존성 분석, 하나는 테스트 커버리지 확인. 3개가 동시에 돌아가니까 코드베이스 분석이 10분에서 3분으로 줄었다.

2026년 2월 Opus 4.6과 함께 도입된 에이전트 팀(Agent Teams)은 한 단계 더 나아간다. 서브에이전트는 부모에게만 보고하지만, 에이전트 팀은 서로 메시지를 주고받는다. TeamCreate로 팀을 구성하고, SendMessage로 에이전트 간 소통하고, 공유 TaskList로 진행 상황을 추적한다. 독립적인 여러 세션이 협업하는 구조다.

memory: project 설정도 중요하다. 이걸 켜면 에이전트가 프로젝트의 코딩 패턴, 아키텍처 결정, 반복되는 이슈를 세션 간에 기억한다. code-reviewer 에이전트에 이 설정을 적용하니 리뷰 품질이 눈에 띄게 좋아졌다. 이전 세션에서 지적한 패턴을 다음 세션에서도 일관되게 잡아낸다.

실전 에이전트 설정 패턴

isolation: worktree 설정은 독립된 git worktree에서 에이전트를 실행한다. 메인 브랜치를 건드리지 않으니 실험적인 변경을 안전하게 시도할 수 있다.

PreToolUse 훅을 결합하면 더 정밀한 제어가 가능하다. DB 쿼리 검증 에이전트를 만들어서 Bash 실행 전에 SQL이 읽기 전용인지 자동으로 체크하는 식이다. effort 파라미터로 low, medium, high, max 중 에이전트의 추론 깊이도 조절할 수 있다. 빠른 검색은 low, 복잡한 디버깅은 max.

1인 개발자에게 이 기능이 특히 강력한 이유가 있다. 코드 작성, 리뷰, 테스트, 문서화를 혼자 다 해야 하는데, 각 역할에 맞는 에이전트를 만들면 4명이 동시에 일하는 효과가 난다. 실제로 나는 writer, reviewer, tester, architect 4개 에이전트를 프로젝트마다 세팅해두고, 작업 시작 전에 병렬로 돌린다.

혼자 개발한다고 혼자 일할 필요는 없다. 에이전트가 팀이 된다.

---

참고 자료

• Claude Code Subagents 공식 문서 - Anthropic
• Agent Teams 공식 문서 - Anthropic
• Claude Code - Anthropic