이 글에서 다루는 내용: 서브에이전트의 동작 원리, 레시피 4개 전문, 언제 쓰고 언제 안 쓰는지.
원리: 왜 나누면 좋아지나
사용량과 품질 모두 컨텍스트 길이의 함수입니다(원리). 파일 50개를 뒤지는 탐색을 본 대화에서 하면 그 내용 전부가 컨텍스트에 쌓여 이후 턴이 비싸지고 흐려지지만, 서브에이전트는 자기 컨텍스트에서 뒤지고 결론만 반환합니다. 개념 전반은 서브에이전트·훅·스킬 글에서 다뤘고, 여기선 정의 파일 실전만 다룹니다.
정의 파일의 뼈대
---
name: code-explorer
description: 코드베이스에서 특정 기능·패턴의 위치와 구조를 조사할 때 사용.
구현 위치 찾기, 사용처 추적, 구조 파악 요청 시.
tools: Read, Grep, Glob
---
너는 코드베이스 조사 전문가다. 코드를 수정하지 않는다.
- 질문받은 대상의 위치, 관련 파일, 호출 관계를 조사한다
- 결과는 "핵심 답 → 관련 파일 목록(경로:줄) → 주의점" 순서로 요약한다
- 추측은 추측이라고 명시한다
포인트 셋: tools를 좁혀서(탐색가에게 편집 권한 불필요) 안전과 집중을 확보하고, description에 트리거 상황을 적어 자동 위임이 잘 되게 하고, 보고 형식을 지정해 돌아오는 요약의 품질을 고정합니다.
레시피 ② 리뷰어
tools는 읽기 계열만. 본문 지시: "diff를 보안(시크릿·입력 검증), 성능(N+1·불필요 연산), 관례 위반, 테스트 공백 순으로 검토하고 심각도별로 보고. 스타일 잔소리는 린터 몫이므로 생략." 커밋 전에 "리뷰어 서브에이전트로 이 변경 검토해줘" 한 줄로 부르는 용도입니다. 본 대화(작성자 맥락)와 분리된 시선이라는 점이 핵심 — 자기가 짠 코드를 자기가 리뷰하는 문제를 구조적으로 피합니다.
레시피 ③ 테스트 러너
tools에 Bash 포함. "전체 테스트 실행 → 실패 목록을 원인 유형별로 분류(코드 문제/테스트 문제/환경 문제) → 수정하지 말고 보고만." 긴 테스트 출력이 본 컨텍스트를 오염시키는 것을 막는 용도로, 실패 로그 수천 줄 대신 분류된 요약이 돌아옵니다. 수정은 본 대화에서 판단 후 진행 — 진단과 처방을 분리하는 구성입니다.
레시피 ④ 문서 정리가
"변경된 코드와 기존 문서의 불일치를 찾아 갱신 초안 작성." README·API 문서가 코드를 따라가지 못하는 만성 문제를, 큰 작업 마무리 단계에 이 서브에이전트 호출 한 번으로 처리합니다. 스킬(작성법)과 조합하면 — "릴리스 스킬의 마지막 단계에서 문서 서브에이전트 호출" — 절차 자동화가 완성됩니다.
언제 쓰지 말아야 하나
왕복이 필요한 작업엔 부적합합니다 — 서브에이전트는 대화 상대가 아니라 일회성 파견이라, 중간 판단이 필요한 작업은 본 대화가 맞습니다. 작은 작업도 마찬가지 — 파일 두 개 읽는 일에 파견 비용(서브에이전트 기동·보고)이 더 큽니다. 기준은 이렇게 잡으면 됩니다: "과정은 안 궁금하고 결론만 필요한 30초 이상짜리 일"이 서브에이전트 감입니다.
자주 묻는 질문 (FAQ)
Q. 서브에이전트도 사용량을 소모하나요?
A. 네, 그 작업 자체의 소모는 발생합니다. 절약되는 것은 "이후 턴들"입니다 — 탐색 잡음이 본 컨텍스트에 안 쌓이므로 세션이 길어질수록 이득이 커집니다.
Q. 자동으로 위임되게 할 수 있나요?
A. description이 명확하면 Claude가 관련 작업에서 알아서 위임합니다. 원하는 시점에 확실히 쓰려면 이름을 지목해 지시하세요.
Q. 프로젝트와 개인 중 어디에 두나요?
A. 팀이 함께 쓸 것은 프로젝트(.claude/agents/, git 커밋), 개인 취향의 것은 홈 디렉터리 쪽에 둡니다. 리뷰어처럼 팀 기준이 담기는 것은 프로젝트에 두고 커밋하는 것을 권합니다.
한눈에 보는 요약
탐색가·리뷰어·테스트 러너·문서 정리가 — 넷 다 "결론만 필요한 일"을 본 컨텍스트 밖으로 빼는 장치입니다. tools 최소화, description에 트리거, 보고 형식 지정. 이 세 원칙만 지키면 됩니다.
함께 보면 좋은 글
Claude Code 서브에이전트·훅·스킬 활용법
Claude Code Skills 작성법
Claude Code 사용량 한도 관리법
참고 자료
'Claude Code' 카테고리의 다른 글
| CI에서 Claude Code 돌리기: PR 자동 리뷰 파이프라인 만들기 (0) | 2026.07.22 |
|---|---|
| Claude Fable 5, 내 요금제로 계속 쓸 수 있을까? 7월 20일 프로모션 종료 완전 정리 (2) | 2026.07.21 |
| Claude Code Skills 작성법: 반복 작업을 명령 하나로 만드는 실전 가이드 (0) | 2026.07.20 |
| Claude Opus 4.8 vs Sonnet 5: 언제 뭘 써야 할까? (1) | 2026.07.18 |
| Claude Sonnet 5와 1M 컨텍스트: Claude Code 사용자에게 뭐가 달라지나 (0) | 2026.07.18 |