Claude Code Subagent(Worker) 실전 가이드: 1인 개발자가 '전문가 팀'처럼 일하는 법 (실패 경험 + 복붙 템플릿 포함) - 데이터 포레스트(Data Forest)

목차

• 1) Subagent가 뭐고, 왜 써야 할까?
• 2) 내가 삽질했던 3가지 실수 (그리고 해결법)
• 3) 비교표: 상황별 Subagent vs 메인 대화
• 4) 실전 Subagent 4개 (복붙 템플릿 포함)
• 5) 병렬 실행 & 백그라운드 작업 활용법
• Q&A 1) 회사에서 써도 괜찮을까요?
• Q&A 2) 무료 플랜에서도 쓸 수 있나요?
• Q&A 3) Subagent가 자꾸 엉뚱한 짓을 해요

"Claude Code 오래 쓰다 보면 대화가 길어지면서 답변 품질이 떨어지는 느낌" 받아보셨죠?
오늘 글은 단순히 기능 소개가 아니라, 컨텍스트 폭발·반복 작업·품질 저하를 실제로 '사라지게' 만드는 Subagent 활용 전략을 설계합니다.

Subagent는 '더 많이 시키는 법'이 아니라 '더 잘 나눠서 맡기는 법'을 찾는 일이다.

Minimal modern illustration of Claude Code subagent workflow

1) Subagent가 뭐고, 왜 써야 할까?

솔직히 처음엔 "그냥 Claude Code 하나로 다 하면 되지, 왜 굳이 나눠?"라고 생각했습니다. 그런데 프로젝트가 커지니까 문제가 보이더라고요.

Subagent(서브에이전트)는 Claude Code 안에서 특정 작업만 전문으로 처리하는 '전문가 AI 어시스턴트'입니다. 각 Subagent는 자신만의 컨텍스트 윈도우, 시스템 프롬프트, 도구 접근 권한을 갖고 독립적으로 작동합니다.

핵심 장점 3가지는 이렇습니다.
첫째, 컨텍스트 보존입니다. 탐색/분석 결과가 메인 대화를 오염시키지 않습니다.
둘째, 제약 강제입니다. 특정 Subagent는 읽기만 가능하게, 다른 건 수정까지 가능하게 도구를 제한할 수 있습니다.
셋째, 비용 절감입니다. 단순 탐색은 Haiku 같은 빠르고 저렴한 모델로, 복잡한 분석은 Sonnet/Opus로 라우팅할 수 있습니다.

Claude Code에는 기본 내장 Subagent가 있습니다. Explore는 코드베이스 검색/분석 전용으로 Haiku 모델을 쓰고 읽기 전용입니다. Plan은 계획 모드에서 리서치할 때 사용됩니다. General-purpose는 복잡한 멀티스텝 작업용으로 모든 도구를 사용할 수 있습니다.

2) 내가 삽질했던 3가지 실수 (그리고 해결법)

실수 1: "만능 Subagent" 만들려고 함
처음엔 "코드리뷰도 하고, 테스트도 짜고, 문서화도 하는" 슈퍼 에이전트를 만들었습니다. 결과는 처참했어요. 시스템 프롬프트가 길어지니까 정작 중요한 지시를 무시하고, 이것저것 하다가 컨텍스트가 금방 찼습니다.

→ 해결: 역할 하나당 Subagent 하나. "이 에이전트는 코드리뷰만 한다"처럼 책임을 명확히 분리했더니 품질이 확 올랐습니다.

실수 2: description 대충 씀
description: "코드 관련 작업" 이렇게 써놓으니까 Claude가 언제 이 Subagent를 불러야 할지 판단을 못 하더라고요. 엉뚱한 타이밍에 호출하거나 아예 안 부르거나.

→ 해결: description에 "언제 쓰는지" 구체적으로 명시. 예를 들어 "코드 변경 후 즉시 리뷰할 때 사용. 보안/성능/가독성 체크" 이런 식으로요.

실수 3: 백그라운드 실행 권한 미리 안 받음
백그라운드로 Subagent 돌렸는데 중간에 권한 없어서 멈춰버렸습니다. 백그라운드에선 사용자에게 질문을 못 하거든요.

→ 해결: 백그라운드 실행 전에 Claude가 필요한 권한을 미리 물어봅니다. 이걸 꼼꼼히 승인해두면 중간에 안 멈춥니다.

Clean comparison diagram

3) 비교표: 상황별 Subagent vs 메인 대화

상황	추천 방식	이유	주의사항
빠른 질문/수정	메인 대화	전환 비용 낮음	컨텍스트 누적 주의
대규모 코드베이스 탐색	Explore Subagent	결과가 메인 오염 안 함	읽기 전용이라 수정 불가
코드리뷰	커스텀 Subagent	일관된 체크리스트 적용	Write 권한 제거 권장
테스트 실행 & 분석	백그라운드 Subagent	병렬 실행으로 시간 절약	권한 미리 승인
디버깅	포그라운드 Subagent	중간에 질문/확인 필요	Edit 권한 필요
여러 모듈 동시 리서치	병렬 Subagent	독립적 탐색 후 종합	의존성 없는 작업만

4) 실전 Subagent 4개 (복붙 템플릿 포함)

템플릿 1: Code Reviewer (코드리뷰어)

---
name: code-reviewer
description: 코드 변경 후 즉시 품질/보안/성능 리뷰. 코드 작성/수정 직후 자동으로 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 10년차 시니어 개발자입니다. 코드리뷰만 담당합니다.

호출되면:
1. git diff로 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

체크리스트:
- 코드 가독성/명확성
- 함수/변수 네이밍
- 중복 코드 여부
- 에러 핸들링
- 보안 취약점 (API 키 노출 등)
- 입력값 검증
- 테스트 커버리지
- 성능 이슈

피드백 형식:
- 🚨 Critical (반드시 수정)
- ⚠️ Warning (수정 권장)  
- 💡 Suggestion (고려 사항)

각 이슈에 수정 예시 코드 포함.

템플릿 2: Debugger (디버거)

---
name: debugger
description: 에러, 테스트 실패, 예상치 못한 동작 발생 시 사용. 근본 원인 분석 전문.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

당신은 디버깅 전문가입니다. 체계적이고 인내심 있게 문제를 추적합니다.

디버깅 프로세스:
1. 에러 메시지/스택 트레이스 캡처
2. 재현 단계 확인
3. 실패 지점 격리
4. 최소한의 수정으로 해결
5. 해결책 검증

분석 시:
- 에러 메시지와 로그 분석
- 최근 코드 변경 확인
- 가설 수립 후 검증
- 전략적 디버그 로깅 추가
- 변수 상태 점검

결과물:
- 근본 원인 설명
- 진단 근거
- 구체적 수정 코드
- 테스트 방법
- 재발 방지 권장사항

증상이 아닌 원인을 해결하세요.

템플릿 3: Test Writer (테스트 작성자)

---
name: test-writer
description: 새 기능 구현 후 또는 테스트 커버리지 개선 시 사용. 단위/통합 테스트 작성.
tools: Read, Write, Bash, Glob
model: sonnet
---

당신은 테스트 작성 전문가입니다.

테스트 작성 원칙:
- 경계값과 엣지 케이스 우선
- 실패할 수 있는 상황 모두 커버
- 테스트명은 "~하면 ~해야 한다" 형식
- Arrange-Act-Assert 패턴 준수
- 모킹은 최소화, 실제 동작 테스트 선호

호출되면:
1. 대상 코드 분석
2. 테스트 케이스 목록 작성
3. 테스트 코드 생성
4. 실행 후 통과 확인

각 테스트에 주석으로 "왜 이 케이스가 필요한지" 설명 포함.

템플릿 4: DB Reader (읽기 전용 DB 분석)

---
name: db-reader
description: 데이터 분석, 쿼리 작성, 리포트 생성 시 사용. SELECT만 허용.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

당신은 읽기 전용 데이터 분석가입니다. SELECT 쿼리만 실행할 수 있습니다.

데이터 분석 요청 시:
1. 관련 테이블 파악
2. 효율적인 SELECT 쿼리 작성
3. 결과를 명확하게 정리

INSERT, UPDATE, DELETE 등 데이터 수정 요청은 거부하고, 
읽기 권한만 있음을 안내하세요.

5) 병렬 실행 & 백그라운드 작업 활용법

Subagent의 진짜 힘은 병렬 실행에서 나옵니다.

포그라운드 vs 백그라운드의 차이:
포그라운드는 완료될 때까지 메인 대화가 멈추고, 중간에 질문/권한 요청이 가능합니다.
백그라운드는 메인 대화와 동시에 실행되고, 미리 승인받은 권한만 사용하며 중간 질문은 실패 처리됩니다.

병렬 리서치 예시:
"인증, 데이터베이스, API 모듈을 각각 별도 Subagent로 동시에 분석해줘"라고 요청하면 각 Subagent가 독립적으로 탐색한 뒤 Claude가 결과를 종합해줍니다.

체이닝 예시:
"code-reviewer Subagent로 성능 이슈 찾고, 그 결과를 debugger Subagent에게 전달해서 수정해줘"

실행 팁:
실행 중 Ctrl+B를 누르면 현재 작업을 백그라운드로 전환할 수 있습니다.
환경변수 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1로 백그라운드 기능을 비활성화할 수도 있습니다.

Minimal checklist infographic for Claude Code subagent setup

Q&A 1) 회사에서 써도 괜찮을까요?

안전의 핵심은 도구보다 설정입니다. Subagent별로 tools 필드에서 Write/Edit 권한을 제거하면 읽기 전용으로 제한할 수 있고, permissionMode: plan으로 설정하면 탐색만 가능합니다. 민감 정보가 있는 작업은 Hook으로 명령어를 검증하는 것도 방법입니다.

Q&A 2) 무료 플랜에서도 쓸 수 있나요?

Subagent 기능 자체는 Claude Code에 포함되어 있습니다. 다만 많이 사용하면 토큰 소모가 빠르니, Haiku 모델을 활용하는 Explore 같은 가벼운 Subagent 위주로 쓰는 게 무료 플랜에서의 전략입니다.

Q&A 3) Subagent가 자꾸 엉뚱한 짓을 해요

description을 구체화하세요. "코드 관련" 대신 "코드 변경 직후 보안/성능/가독성 리뷰. 수정은 하지 않음"처럼요. 시스템 프롬프트에 하지 말아야 할 것도 명시하면 좋습니다. 그리고 "정직하게", "비판적으로", "현실적으로" 같은 태도 지시를 추가하면 LLM의 기본적인 '동의 편향'을 줄일 수 있습니다.

6) Subagent 설정 옵션 요약표

설정 필드	필수 여부	설명	예시
name	필수	고유 식별자 (소문자, 하이픈)	code-reviewer
description	필수	Claude가 언제 사용할지 판단	"코드 변경 후 즉시 리뷰"
tools	선택	허용할 도구 목록	Read, Grep, Glob
disallowedTools	선택	금지할 도구 목록	Write, Edit
model	선택	사용할 모델	haiku, sonnet, inherit
permissionMode	선택	권한 모드	default, plan, bypassPermissions
skills	선택	미리 로드할 스킬	api-conventions
hooks	선택	라이프사이클 훅	PreToolUse, PostToolUse

---

CTA: 댓글로 "어떤 Subagent가 필요한지" 알려주시면, 맞춤형 시스템 프롬프트 템플릿을 만들어 드립니다!

이 글이 도움이 되셨다면 공유 부탁드립니다. Claude Code로 1인 개발자도 '전문가 팀'처럼 일할 수 있습니다.