Claude Code Subagent 사용법: 개발 작업 병렬로 처리하기

Claude Code Subagent는 하나의 세션 안에서 코드 탐색, 테스트 로그 분석과 보안 리뷰 같은 하위 작업을 별도 문맥에 맡기고 요약된 결과만 주 대화로 돌려받는 기능입니다. 서로 의존하지 않는 조사 작업은 동시에 처리할 수 있지만 같은 파일을 여러 Subagent가 수정하면 충돌과 검증 비용이 커집니다. 병렬화할 작업보다 먼저 파일 소유 범위와 최종 통합 책임을 정해야 합니다.

Claude Code Subagent란 무엇인가

Subagent는 주 대화가 특정 하위 작업을 위임할 수 있는 전문 에이전트입니다. 각 Subagent는 독립된 문맥 창, 자체 시스템 프롬프트, 지정한 도구와 권한을 사용하고 완료되면 결과를 주 대화에 반환합니다. 많은 파일이나 로그를 읽는 과정은 별도 문맥에 남고 핵심 결과만 돌아오므로 주 대화의 문맥을 절약할 수 있습니다.

Claude Code에는 Explore, Plan과 범용 역할 같은 내장 Subagent가 있으며 반복적으로 사용하는 코드 리뷰어, 테스트 분석가와 문서 조사자는 커스텀 Subagent로 정의할 수 있습니다. 어떤 역할을 언제 호출할지는 설정의 description이 중요한 판단 근거가 됩니다.

Subagent가 효과적인 개발 작업

• 코드베이스 탐색: 프론트엔드, 백엔드와 데이터 계층을 나눠 실행 흐름을 조사합니다.
• 로그 분석: 긴 테스트·빌드 로그에서 최초 실패와 공통 원인을 찾습니다.
• 독립 리뷰: 보안, 성능, 접근성, 테스트 누락을 서로 다른 관점으로 검토합니다.
• 문서 조사: 공식 API 문서와 현재 구현의 차이를 정리합니다.
• 테스트 분류: 단위·통합·E2E 실패를 영역별로 분리합니다.
• 독립 모듈 작업: 공개 인터페이스와 담당 파일이 겹치지 않는 기능을 나눕니다.

한 파일의 작은 수정, 앞 단계 결과를 계속 참고해야 하는 작업, 사용자와 자주 방향을 조정해야 하는 일은 주 대화에서 순차적으로 처리하는 편이 빠를 수 있습니다. Subagent는 시작할 때 다시 문맥을 모으므로 무조건 병렬화한다고 시간이 줄어들지는 않습니다.

Subagent·Agent View·Agent Teams·worktree 차이

Agent Teams는 공식 문서상 실험적이며 기본적으로 비활성화되어 있습니다. Subagent는 결과를 주 에이전트에 보고하지만 팀원끼리 직접 조정해야 한다면 Agent Teams가 더 맞을 수 있습니다. 단순히 파일 충돌만 막고 싶다면 협업 기능보다 worktree 격리가 핵심입니다.

가장 간단하게 병렬 Subagent 요청하기

“여러 에이전트로 봐줘”보다 담당 범위, 읽기·쓰기 여부, 반환 형식과 최종 대기 조건을 구체적으로 적어야 중복 탐색과 성급한 결론을 줄일 수 있습니다.

좋은 병렬 요청의 7가지 요소

1. 공통 목표: 최종적으로 판단하거나 완성할 결과를 씁니다.
2. 독립 범위: 디렉터리, 위험 축이나 테스트 종류를 겹치지 않게 나눕니다.
3. 권한: 읽기 전용인지 어떤 파일까지 수정 가능한지 지정합니다.
4. 근거 형식: 파일 경로, 코드 위치, 명령과 로그를 요구합니다.
5. 완료 기준: 테스트 통과, 문제 목록과 남은 위험을 정의합니다.
6. 대기 조건: 모든 Subagent 결과를 기다린 뒤 답하도록 요청합니다.
7. 통합 규칙: 중복 제거, 상충하는 결론과 미확인 항목 처리법을 정합니다.

커스텀 Subagent 만드는 방법

개인 계정의 모든 프로젝트에서 사용할 역할은 ~/.claude/agents/, 저장소와 함께 공유할 역할은 .claude/agents/에 Markdown 파일로 만듭니다. 파일의 YAML frontmatter는 이름, 호출 설명과 도구 범위를 정의하고 본문은 해당 역할의 시스템 프롬프트가 됩니다.

---
name: security-reviewer
description: 인증·인가, 비밀정보와 입력 검증이 바뀐 코드를 읽기 전용으로 검토할 때 사용합니다.
tools: Read, Grep, Glob
---

변경된 코드와 호출 경로를 근거로 보안 위험을 검토한다.
파일을 수정하지 않는다.
각 항목에 위험도, 파일 경로, 재현 조건과 확인 방법을 적는다.
근거가 부족한 내용은 확정된 취약점이 아니라 미확인 위험으로 구분한다.

description은 “보안을 잘 본다”보다 언제 호출해야 하는지를 분명히 적으세요. 읽기 전용 검토자는 Write와 Edit를 주지 않으면 실수로 코드를 바꾸는 범위를 줄일 수 있습니다. Bash와 외부 MCP가 필요 없다면 허용 도구에서 제외하는 편이 안전합니다.

/agents에서 Subagent 확인하기

1. Claude Code에서 /agents를 입력합니다.
2. Library에서 내장·사용자·프로젝트 Subagent를 확인합니다.
3. 만든 역할의 이름, description, 도구와 설정 출처를 점검합니다.
4. Running 탭에서 현재 실행 중인 Subagent 상태를 봅니다.
5. 작은 읽기 전용 요청으로 호출 여부와 반환 형식을 시험합니다.

현재 세션의 백그라운드 작업은 /tasks에서도 확인할 수 있습니다. 터미널의 claude agents는 여러 세션을 관리하는 Agent View이므로 /agents의 Subagent 패널과 구분해야 합니다.

자동 위임과 명시적 호출 차이

Claude는 요청 내용, Subagent의 description과 현재 문맥을 보고 자동 위임할 수 있습니다. 자동 선택이 불안정하면 자연어로 역할 이름을 지정하거나 입력창에서 Subagent를 @멘션해 한 작업의 실행을 보장할 수 있습니다.

전체 세션을 특정 역할로 실행하려면 claude --agent code-reviewer처럼 시작할 수 있습니다. 이때 주 대화 자체가 해당 Subagent의 시스템 프롬프트와 도구 제한을 사용하므로 일회성 위임과 목적이 다릅니다.

포그라운드와 백그라운드 실행

포그라운드 Subagent는 결과가 나올 때까지 주 대화를 기다리게 하고 권한 질문을 사용자에게 전달합니다. 백그라운드 Subagent는 주 대화가 다른 일을 계속하는 동안 실행되며 필요한 권한 요청은 어떤 Subagent가 요청했는지 표시되어 주 세션에 전달됩니다.

백그라운드 실행은 동시에 진행되는 이점이 있지만 완료 전에 주 에이전트가 최종 답을 만들지 않도록 해야 합니다. 프롬프트에 “모든 결과가 완료될 때까지 기다린 뒤 통합”이라고 적고, /tasks에서 실패·중단·승인 대기 상태도 확인하세요.

파일 수정은 worktree로 격리하기

읽기 전용 조사와 달리 여러 Subagent가 같은 체크아웃에서 코드를 수정하면 변경을 덮어쓰거나 테스트 상태를 서로 오염시킬 수 있습니다. 커스텀 Subagent frontmatter에 다음처럼 worktree 격리를 지정할 수 있습니다.

---
name: api-implementer
description: API 모듈의 독립된 기능을 구현하고 테스트할 때 사용합니다.
isolation: worktree
---

할당된 API 파일과 테스트만 수정한다.
공개 인터페이스 변경은 구현 전에 보고한다.
완료 후 변경 파일, 테스트 결과와 통합 위험을 요약한다.

Subagent의 임시 worktree는 변경이 없으면 완료 후 자동 정리될 수 있습니다. 변경이 남았다면 주 브랜치에 합치기 전에 커밋, diff, 테스트와 충돌을 사람이 확인해야 합니다. worktree는 파일을 격리할 뿐 잘못된 설계나 호환성 문제까지 해결하지 않습니다.

프론트엔드·백엔드·테스트 작업 나누기

구현 전에는 세 역할을 읽기 전용으로 병렬 실행하고, 결과가 합의된 뒤 파일 소유권을 나눠 구현하는 2단계 접근이 안전합니다. 데이터 모델이 확정되기 전에 프론트엔드와 백엔드를 동시에 고치면 가정이 달라 재작업이 커질 수 있습니다.

코드 리뷰를 병렬로 처리하는 예시

여러 리뷰 결과가 일치한다고 해서 자동으로 버그가 확정되는 것은 아닙니다. 재현 가능한 테스트와 호출 경로를 확인하고 AI 코드리뷰 결과 검증 절차처럼 오탐·중복·영향도를 사람이 판단해야 합니다.

Subagent 도구와 권한 제한하기

• 탐색 역할에는 우선 Read, Grep, Glob처럼 읽기 도구만 허용합니다.
• 테스트 실행 역할의 Bash 범위는 필요한 명령과 디렉터리로 제한합니다.
• 운영 자격 증명, 배포와 데이터 삭제 권한을 하위 작업에 전달하지 않습니다.
• MCP 도구는 필요한 서버와 작업만 허용하고 외부 전송 범위를 확인합니다.
• write 권한이 필요한 역할도 담당 파일과 worktree를 분리합니다.
• 권한 요청을 승인할 때 해당 Subagent와 명령·대상 경로를 함께 봅니다.

Subagent는 자체 권한을 가질 수 있지만 주 세션과 조직 정책의 기술적 보안 경계를 대신하지 않습니다. 자연어로 “수정하지 마”라고 적는 것보다 쓰기 도구를 제거하는 편이 더 강한 제한입니다.

CLAUDE.md와 문맥 전달 시 주의점

일반 Subagent는 새 문맥에서 시작하고 주 대화 기록이나 이미 호출한 Skill, 이미 읽은 파일 전체를 자동으로 보지 않습니다. Claude는 위임 메시지에 필요한 작업을 요약하므로 중요한 범위, 완료 조건과 출력 형식을 위임 요청에 다시 포함해야 합니다.

공식 문서상 일반 커스텀 Subagent는 주 세션이 로드한 CLAUDE.md 계층과 시작 시점의 Git 상태 같은 일부 정보를 받을 수 있지만 내장 Explore·Plan 역할에는 예외가 있습니다. 특정 디렉터리를 제외해야 하는 것처럼 반드시 지켜야 할 조건은 Subagent 프롬프트에도 명시하세요.

Hooks와 Subagent 함께 사용하기

Subagent의 frontmatter에 전용 Hook을 정의하거나 settings.json에서 SubagentStart와 SubagentStop 이벤트를 사용할 수 있습니다. 모든 Subagent 종료 시 결과 파일을 검사하거나 실행 시간을 기록하는 식으로 활용할 수 있습니다.

Hook은 사용자 권한으로 명령을 실행하므로 병렬 수만큼 실행 횟수가 늘어날 수 있습니다. 무거운 검사, 외부 전송과 공용 파일 기록은 동시성·중복·민감정보 노출을 점검해야 합니다. 자세한 설정은 Claude Code Hooks 사용법에서 확인할 수 있습니다.

병렬화하면 안 되는 신호

• 두 작업이 같은 파일이나 데이터베이스 스키마를 동시에 수정합니다.
• 앞 작업의 설계 결과가 나와야 다음 작업을 정확히 시작할 수 있습니다.
• 완료 기준이 “알아서 잘 구현”처럼 모호합니다.
• 운영 환경, 고객 데이터나 광범위한 자격 증명 접근이 필요합니다.
• 통합 테스트와 최종 검토 책임자가 정해지지 않았습니다.
• 작은 변경인데 Subagent가 각각 전체 저장소를 다시 읽어야 합니다.
• 사용량과 실행 시간 제한에 가까운 상태입니다.

결과를 통합하는 7단계

1. /tasks와 /agents에서 모든 작업의 완료·실패·중단 상태를 확인합니다.
2. 각 결론이 파일 경로, 코드와 실행 결과로 뒷받침되는지 봅니다.
3. 같은 원인의 중복 지적을 하나로 합칩니다.
4. 서로 상충하는 결론은 어느 쪽도 확정하지 말고 추가 검증 항목으로 둡니다.
5. 변경이 있다면 Subagent별 diff와 파일 소유 범위를 비교합니다.
6. 통합 후 lint, typecheck, 단위·통합 테스트를 공통 환경에서 다시 실행합니다.
7. 실행하지 못한 검사, 남은 위험과 사람의 승인 결과를 기록합니다.

속도와 비용을 측정하는 방법

여러 Subagent를 동시에 실행하면 사용량이 증가합니다. 이 글은 특정 절감 시간이나 비용을 직접 측정하지 않았으므로 같은 저장소의 같은 과제를 순차·병렬로 각각 실행하고 통합 시간까지 포함해 비교하세요.

팀 도입 체크리스트

• 병렬 처리할 작업이 서로 독립적인가
• 각 Subagent의 파일·위험·테스트 소유 범위가 명확한가
• 읽기 전용 역할에서 쓰기·실행 도구를 제거했는가
• 반환 형식에 근거, 불확실성, 완료 상태가 포함되는가
• 동시 수정에는 worktree 또는 분리된 브랜치를 사용하는가
• 모든 결과를 기다리고 통합할 주체가 정해졌는가
• 공통 CI와 사람 리뷰를 마지막에 다시 실행하는가
• 사용량, 오탐, 충돌과 실제 절감 시간을 기록하는가

병렬 작업 검증 기록표

같은 과제를 단일 세션과 Subagent 방식으로 각각 실행해 다음 값을 비교하세요. 속도만 줄고 통합 수정이 늘었다면 병렬화 이점이 없는 작업일 수 있습니다.

편집부 결론

Claude Code Subagent의 가장 큰 장점은 에이전트 수가 아니라 문맥과 책임을 분리하는 데 있습니다. 코드 탐색, 로그 분석과 서로 다른 위험 축의 리뷰부터 읽기 전용으로 병렬화하고, 결과가 끝난 뒤 주 에이전트가 근거와 충돌을 통합하도록 하세요. 코드 수정은 담당 파일이 겹치지 않을 때만 나누고 겹칠 가능성이 있으면 worktree로 격리해야 합니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 특정 개발팀의 장기 생산성 실험 결과가 아닙니다. Subagent 실행 방식과 동시성, Agent View·Agent Teams의 제공 범위는 버전에 따라 달라질 수 있으므로 적용 전 현재 Claude Code 버전과 공식 문서를 확인하세요.

공식 문서와 함께 읽을 글

Claude Code Agent Teams로 여러 에이전트 협업시키기

Claude Code 커스텀 Subagent 공식 문서 보기

Subagent·Agent View·Agent Teams 비교하기

worktree로 병렬 변경 격리하기

Claude Code Subagent에 개발 Skill 적용하기

Claude Code Subagent에 MCP 외부 도구 연결하기

Claude Code Hooks로 Subagent 실행 전후 자동화하기

Codex 병렬 에이전트 사용법과 비교하기

Codex와 Claude Code 개발 흐름 비교하기

Claude Skills로 반복 역할과 절차 구성하기

자주 묻는 질문

Claude Code Subagent는 무엇인가요?

주 세션이 집중된 하위 작업을 맡기는 전문 에이전트입니다. 별도 문맥과 설정된 도구·권한으로 작업하고 핵심 결과를 주 대화에 반환합니다.

여러 Claude Code Subagent를 동시에 실행할 수 있나요?

서로 독립된 코드 조사, 테스트 분석과 리뷰를 병렬로 요청할 수 있습니다. 다만 동시에 실행할수록 사용량과 통합 부담이 늘어나므로 작은 수부터 측정해야 합니다.

커스텀 Subagent 파일은 어디에 만드나요?

프로젝트 전용 역할은 .claude/agents/, 사용자 전체에서 사용할 역할은 ~/.claude/agents/에 Markdown 파일로 정의합니다.

Subagent를 직접 지정해서 실행할 수 있나요?

자연어로 이름을 요청하거나 입력창에서 Subagent를 @멘션할 수 있습니다. 전체 세션을 역할로 시작하려면 claude --agent 역할명을 사용할 수 있습니다.

Subagent와 Agent Teams는 무엇이 다른가요?

Subagent는 주 에이전트에 결과를 보고하는 한 세션 안의 작업자입니다. Agent Teams는 별도 세션의 팀원이 공유 작업 목록과 메시지로 서로 조정하며 공식 문서상 실험적 기능입니다.

여러 Subagent가 같은 파일을 수정해도 되나요?

권장하지 않습니다. 파일 소유 범위를 나누거나 isolation: worktree로 별도 체크아웃을 사용하고 최종 diff와 테스트를 통합 단계에서 다시 검증하세요.

Subagent가 작업 중인지 어디에서 확인하나요?

/agents의 Running 탭과 /tasks에서 현재 세션의 실행 상태, 완료·실패와 백그라운드 작업을 확인할 수 있습니다.

Subagent가 많을수록 개발 속도가 빨라지나요?

항상 그렇지는 않습니다. 독립 작업에서는 시간이 줄 수 있지만 문맥 재수집, 토큰 사용, 중복 조사와 코드 통합 비용이 늘어납니다. 통합 검증까지 포함한 총 시간을 측정해야 합니다.