Claude Code 서브 에이전트 12개를 6개월 굴려본 결과 — 호출 빈도, 패턴, 5가지 안티패턴
Claude Code의 서브 에이전트를 처음 봤을 때 "이게 정말 단일 모델 호출보다 좋을까"가 의심이었어요. 추가 호출이 늘면 토큰 비용도 늘고, 컨텍스트 분리가 오히려 정보 손실을 만들 수도 있으니까요. 그래서 6개월간 12개의 서브 에이전트를 본인 프로젝트에 만들어 운영해 봤습니다. 결론은 단순합니다 — 잘 쓰면 가치가 크고, 잘못 쓰면 비용만 늘어나는 양면성이에요. 이 글은 그 가운데를 가르는 패턴을 정리한 카탈로그입니다.
도메인별 깊이가 궁금하다면 Playwright + Plan-Gen-Heal 글이 더 적합해요. 이 글은 12개 에이전트 카탈로그 + 패턴·안티패턴에 집중합니다.
먼저, 서브 에이전트가 정확히 무엇인가
Claude Code의 서브 에이전트(sub-agent)는 메인 에이전트가 명시적으로 위임할 수 있는 작업 단위예요. 공식 문서의 정의에 따르면:
- 독립된 컨텍스트: 메인 에이전트와 별도의 메모리. 큰 작업 컨텍스트가 흐려지지 않음.
- 고유한 시스템 프롬프트: 도메인별로 톤·규칙·도구 권한을 다르게 설정 가능.
- 메인이 결과만 받음: 서브의 모든 추론 과정이 아닌 최종 결과물만 메인 컨텍스트로 돌아옴.
파일 위치는 .claude/agents/<name>.md(프로젝트별) 또는 ~/.claude/agents/<name>.md(전역). Markdown frontmatter로 도구 권한·모델·설명을 지정합니다.
---
name: code-reviewer
description: Reviews PRs for security and style issues
tools: Read, Grep, Bash
---
You are a senior code reviewer. Focus on:
- SQL injection, XSS, secret leaks
- Naming consistency with the project
- Cyclomatic complexity hotspots
Output a markdown summary with severity levels.본인의 12개 에이전트 카탈로그
6개월간 정착한 12개입니다. 도메인이 다양해서 어디에 서브 에이전트가 잘 작동하는지 보입니다.
| 에이전트 | 역할 | 월 호출수 |
|---|---|---|
| code-reviewer | PR 코드 리뷰 (보안·스타일) | ~85 |
| test-planner | 새 기능 → 테스트 시나리오 추출 | ~42 |
| test-generator | 시나리오 → Playwright 코드 | ~38 |
| test-healer | 실패한 테스트 진단·수정안 제안 | ~67 |
| db-migrator | 스키마 변경 → 마이그레이션 SQL | ~12 |
| api-doc-writer | OpenAPI spec → 사용자 문서 | ~18 |
| git-commit-helper | staged diff → conventional commit msg | ~120 |
| log-investigator | 에러 로그 → 원인 가설 | ~34 |
| refactor-planner | 리팩토링 단계 분해 | ~22 |
| i18n-extractor | 하드코딩 한국어 → 번역 키 | ~8 |
| a11y-auditor | 접근성 위반 점검 | ~15 |
| blog-summarizer | 긴 글 → 3줄 요약 | ~28 |
월 합계 약 489회 호출. 가장 자주 쓰는 게 git-commit-helper(120회)와 code-reviewer(85회)예요. 의외로 단순해 보이는 git-commit-helper가 1위인 게 흥미롭습니다. 하루 4번 정도 호출되고, 매번 1~2분을 절감해줍니다. 누적 효과가 큽니다.
잘 작동하는 5가지 패턴
12개 에이전트를 굴려보며 "이 형태로 만들면 잘 작동한다"고 정착한 패턴들입니다.
① "한 가지 출력"만 한다
code-reviewer는 코드 리뷰 결과만, test-generator는 테스트 코드만 출력합니다. 한 에이전트가 두 가지 출력을 하면 둘 다 품질이 떨어져요. 단일 책임 원칙이 서브 에이전트에도 그대로 적용됩니다.
② 도구 권한을 최소로 준다
git-commit-helper는 tools: Bash(git diff)만 줍니다. 파일 쓰기 권한 없음. 이러면 에이전트가 의도치 않게 파일을 수정할 수 없어요. 보안 관점에서 결정적입니다.
③ 출력 포맷을 고정
code-reviewer 결과는 항상 같은 markdown 구조(severity / file / line / fix). 메인 에이전트가 후속 처리(예: 슬랙 발송)할 때 파싱 부담이 사라집니다.
④ "절대 하지 마라" 명시
test-healer 시스템 프롬프트에 "NEVER directly modify production code. Only suggest fixes in PR comments."를 명시. 한 줄이지만 큰 차이를 만들어요.
⑤ 호출 빈도 모니터링
월 1~2회만 호출되는 에이전트는 사실상 죽은 에이전트예요. 본인 정리에서 i18n-extractor가 그 케이스였는데, 다행히 8회는 의미 있는 빈도. 하지만 작년에 만들었다가 0회 호출로 폐기한 에이전트가 4개 더 있었습니다.
5가지 안티패턴 — 이렇게 만들면 망함
안티패턴 1: 메가 에이전트
"코드 리뷰 + 테스트 생성 + 문서 작성"을 한 에이전트에 묶음. 결과: 어느 도메인도 깊지 못함. 페르소나가 흐릿해짐. 해결: 잘게 쪼개라.
안티패턴 2: 도구 무제한 부여
편하다고 모든 에이전트에 tools: *를 줌. 결과: 의도치 않은 파일 수정·삭제 발생 가능. 해결: 그 에이전트가 정말 필요한 도구만.
안티패턴 3: 시스템 프롬프트 짜깁기
인터넷에서 본 좋은 프롬프트들을 다 합쳐서 한 시스템 프롬프트로 만듦. 결과: 모순된 지시들이 충돌. 본인 사례 — code-reviewer의 첫 버전에 "엄격하게" + "친절하게" 둘 다 들어있었는데, AI가 어느 톤으로 써야 할지 매번 흔들렸어요. 해결: 한 가지 톤·기준으로 압축.
안티패턴 4: 검증 없는 자동 적용
서브 에이전트 결과를 사람 검토 없이 main 브랜치에 머지. 결과: AI가 잘못 짠 코드가 그대로 들어감. 해결: 결과는 항상 PR/제안 형식으로.
안티패턴 5: 만들고 안 쓰는 에이전트
"이런 거 있으면 좋겠다" 싶어서 만들었지만 실제로 호출 안 함. 결과: 유지보수 부담만 증가. 해결: 월 호출 5회 미만이면 폐기 검토.
서브 에이전트의 가치는 "AI가 더 똑똑해진다"가 아니라 "한 작업을 분리·고정하면 사람이 검수하기 쉬워진다"입니다. 검수 가능성을 높이는 도구로 보면 설계 기준이 명확해져요. "이 에이전트의 결과를 사람이 1분 안에 검수할 수 있나?"가 좋은 1차 필터입니다.
새 에이전트 만들 때 5단계 체크리스트
본인이 새 서브 에이전트를 만들 때마다 적용하는 절차입니다.
- 한 줄 목적: "이 에이전트는 ___을 받아 ___을 만든다"가 한 줄로 안 적히면 보류.
- 주 호출 빈도 추정: 주 1회 미만이면 만들지 마라. 그냥 메인 에이전트 호출이 더 나음.
- 최소 도구 권한: 기본 권한 0에서 시작해서 필요한 것만 추가.
- 출력 포맷 고정: markdown 또는 JSON, 구조 명시.
- "절대 X 하지 마라" 1줄: 가장 위험한 한 가지 행동을 금지로 명시.
본인은 이 5단계 체크리스트를 통과하지 못한 에이전트는 만들지 않아요. 6개월 기준 4번 시도했고 4번 다 막혔는데, 결과적으로 "안 만든 게 잘한" 사례였습니다.
관련 글 — AI 자동화 시리즈
원스의 결론 — 서브 에이전트는 "분리"의 도구
6개월 12개 카탈로그로 정리한 결론은 셋입니다.
① 서브 에이전트의 가치는 똑똑함이 아니라 분리입니다. 한 가지 도메인·한 가지 출력·한 가지 톤으로 고정하면 결과 품질이 안정되고 사람 검수가 쉬워져요. "더 큰 에이전트"보다 "더 잘 분리된 에이전트"가 답입니다.
② 호출 빈도가 가치의 가장 빠른 시그널입니다. 잘 설계된 에이전트는 자연스럽게 자주 쓰여요. 월 5회 미만이면 폐기 검토. 본인 12개 중 4개를 이 기준으로 정리했고 결과적으로 운영이 단순해졌습니다.
③ 안티패턴 5가지는 반복적으로 만나는 함정입니다. 메가 에이전트, 도구 무제한, 짜깁기 프롬프트, 자동 적용, 안 쓰는 에이전트. 새 에이전트 만들기 전에 한 번 점검하면 시간을 크게 아낍니다.
"AI 에이전트 시대"가 본격적으로 열리고 있다는 말이 자주 들립니다. 다만 그 시대를 잘 통과하려면 "에이전트를 잘 만드는 능력"이 새 프로그래밍 언어처럼 핵심 스킬이 됩니다. 이 글이 그 출발점에 도움이 되길 바랍니다.
📚 본 글의 1차 자료
- Anthropic Claude Code 공식 - Sub-agents
- Anthropic Claude Code 공식 발표
- 측정 데이터 — 본인의 6개월(2025-11 ~ 2026-04) 12개 에이전트 호출 로그
- 본인 .claude/agents/ 디렉터리 운영 노트
댓글
댓글 쓰기