Field Log · Entry

[Claude Code] AI 에이전트 Subagent 만들기 — code-reviewer·researcher 역할 분리 패턴 (7/8)

한 명이 코딩하면서 동시에 보안 리뷰까지 하면 둘 다 어중간해집니다. 사람이 그렇듯 AI 에이전트도 마찬가지입니다. 역할이 섞이면 품질이 흐려집니다.

Claude Code는 이 문제를 subagent로 해결합니다. 메인 에이전트는 코딩에만 집중하고, 별도의 격리된 에이전트가 리뷰·조사·테스트 작성을 전담하는 구조입니다. 가장 먼저 만들기 좋은 건 읽기 전용 code-reviewer이고, .claude/agents/에 name·description·tools.allow/deny·시스템 프롬프트만 정의하면 메인 에이전트가 자동으로 위임합니다.

이 글이 답하는 질문

Claude Code subagent는 언제·왜 만들어야 하나?
code-reviewer, researcher, test-writer 각각의 정의 파일은 어떻게 생겼나?
subagent 정의 파일의 어떤 요소가 핵심이고, 실수를 피하려면 뭘 주의해야 하나?

왜 역할을 나누는가

한 에이전트가 모든 걸 하면 두 가지 문제가 생깁니다. 도구 목록이 길어져서 컨텍스트를 많이 차지하고, “코딩하면서 보안도 검토하라”고 하면 둘 다 어중간해집니다. 사람도 코딩하면서 동시에 리뷰하면 품질이 떨어지듯, 에이전트도 마찬가지입니다.

Subagent의 동작 원리

Subagent 위임 플로우: 메인 에이전트가 작업 요청 → subagent가 격리된 환경에서 실행 → 결과만 반환 → 메인이 최종 결정

subagent는 자기만의 격리된 세계에서 일하고, 결과만 부모에게 돌려줍니다.

단계	주체	동작
1	메인	”이 변경 보안 검토해줘” + spawn prompt 전달
2	subagent	격리된 context에서 코드 읽고 분석
3	subagent	결과 보고서를 메인에게 반환
4	메인	보고서를 바탕으로 직접 코드 수정

핵심은 격리된 context + 결과만 반환입니다.

핵심 특징 3가지:

메인의 전체 대화를 물려받지 않고, spawn prompt만 받고 시작
도구 접근을 독립적으로 제한할 수 있음 (예: 읽기만 허용)
중첩 위임(sub가 또 다른 sub를 부르는 것)은 Claude에서 차단됩니다 (Claude Code Sub-agents 공식 문서)

첫 subagent가 필요한 신호

코드를 고쳤는데 보안 취약점을 놓침 — 코딩에 집중하느라 보안 관점을 빠뜨림
조사가 필요한데 코딩도 해야 함 — 조사와 구현이 섞이면서 맥락이 흐려짐
“다 했다”는데 품질이 들쭉날쭉 — 작성과 검토를 동시에 하면 객관성이 떨어짐
특정 전문 작업이 반복 — “타입 에러 봐줘”, “SQL 최적화해줘”
컨텍스트가 길어져 성능 저하 — subagent는 깨끗한 context에서 시작

1순위: 코드 리뷰어

가장 먼저 만들기 좋은 subagent입니다. 읽기만 하니까 부작용이 없고, 효과가 즉각적입니다.

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 코드 변경사항을 리뷰한다. PR 리뷰,
  코드 품질 검토, 보안 취약점 검사가 필요할 때
  이 에이전트에 위임한다.
tools:
  allow:
    - Read
    - Grep
    - Glob
  deny:
    - Write
    - Bash
---

너는 시니어 코드 리뷰어이다.
변경된 코드를 읽고 아래 관점에서 피드백하라:

1. 버그 가능성: 엣지 케이스, null 처리, 타입 오류
2. 보안: SQL injection, XSS, 인증 우회
3. 성능: 불필요한 루프, N+1 쿼리
4. 가독성: 네이밍, 함수 크기, 중복

심각도(Critical/High/Medium/Low)로 분류하라.
코드를 직접 수정하지 말고 문제만 보고하라.

가장 중요한 부분: tools.deny에 Write와 Bash를 넣어서 “보기만 하고 손대지 않는” 리뷰어를 만드는 것입니다 (권한 설계 전반은 (5/8) 권한 설정 참고).

2순위: 조사자(researcher)

---
name: researcher
description: 기술 조사, 라이브러리 사용법 탐색을 수행한다.
  "조사해줘", "찾아봐" 같은 요청에 위임한다.
tools:
  allow: [Read, Grep, Glob, WebSearch]
  deny: [Write, Bash]
---

너는 기술 리서처이다.
요청받은 주제를 조사하고 아래 형식으로 보고하라:
- 핵심 발견사항 (3줄 이내 요약)
- 구체적인 사용법 또는 코드 예시
- 주의사항
- 참고 소스

3순위: 테스트 작성자

---
name: test-writer
description: 테스트 코드를 작성한다.
  "테스트 작성해줘" 같은 요청에 위임한다.
tools:
  allow: [Read, Grep, Glob, Write]
  deny: [Bash]
---

너는 테스트 전문가이다.
정상/경계값/에러 케이스를 모두 커버하라.
테스트 대상 코드는 수정하지 않는다.
tests/ 디렉터리의 파일만 생성/수정한다.

Write는 허용하되 Bash는 차단합니다. 테스트 파일을 쓸 수 있지만 실행은 메인이 합니다.

subagent 정의 파일의 핵심 요소

세 정의 파일 모두 같은 4요소 - name / description / tools.allow·deny / 시스템 프롬프트 - 로 구성됩니다. 차이는 권한과 역할 묘사뿐입니다.

요소	역할	중요도
`name`	내부 참조 이름	필수
`description`	언제 위임할지 판단 기준	핵심
`model`	사용할 모델 (생략 시 메인과 동일)	선택
`tools`	도구 허용/차단	핵심
본문 (--- 아래)	시스템 프롬프트	필수

description이 너무 넓거나 좁으면 위임이 안 되거나 너무 자주 됩니다. 이 판단 루프는 (8/8) 검증과 반복의 ‘실패 로그’ 패턴과 맞물립니다. tools가 제한되지 않으면 subagent를 나눈 의미가 없습니다.

테스트하는 법

파일을 .claude/agents/에 만든다
메인에게 리뷰 요청: "src/routes/auth.ts를 보안 관점에서 리뷰해줘"
위임이 되는지 확인 (또는 직접 호출: @code-reviewer 리뷰해줘)
도구 제한이 작동하는지 확인 (코드 수정 시도가 차단되는지)
description이 너무 넓거나 좁으면 조정

확장 경로

1주차: code-reviewer만 (읽기 전용)
3주차: + researcher (읽기 전용)
2개월+: + test-writer (쓰기 가능, Bash 차단)

다음 subagent를 추가할 타이밍 신호:

메인 에이전트가 같은 유형의 작업(예: 코드 조사)을 한 주에 3회 이상 요청받고 있다
특정 도구 조합(예: Read + Grep + WebSearch)만 반복해서 쓴다
메인 컨텍스트의 30% 이상을 한 가지 전문 작업 설명이 차지한다

이 신호 중 2개 이상이 겹치면 새 subagent를 분리할 시점입니다. 5개를 한 번에 만들면 어떤 게 잘 되는지 판단이 어렵습니다.

흔한 실수

메인과 같은 권한 → 리뷰어에 Write를 주면 리뷰어가 아님
description이 모호 → “코드 관련”은 너무 넓음. “보안 취약점 검토”가 적절
시스템 프롬프트가 너무 김 → sub의 context는 작음. 핵심만 간결하게
sub끼리 직접 소통 기대 → 부모-자식 구조. 합치는 건 메인의 역할

내가 실제로 부딪힌 문제와 해결 (1인칭 경험)

역할 분리의 필요성은 실제 작업에서 바로 드러났습니다. 한 에이전트에게 “코드도 고치고, 구조도 찾고, SEO도 검토해줘”를 동시에 맡기면 일은 진행되는데 검토의 밀도가 떨어졌습니다. 특히 블로그처럼 콘텐츠, 레이아웃, 배포가 한 레포에 섞여 있으면 탐색과 수정이 서로 방해하는 순간이 자주 생겼습니다.

반대로 탐색, 수정, 검토를 분리해 보니 누가 어떤 기준으로 판단해야 하는지가 훨씬 선명해졌습니다. 구조를 찾는 역할은 빠르게 넓게 보고, 수정은 좁고 확실하게 하고, 검토는 “이게 정말 검색 친화적인가”를 따로 보게 만드는 식입니다. 제 경험상 subagent의 가치는 일을 병렬화하는 데보다, 판단 기준을 섞지 않게 만드는 데 더 크게 있었습니다.

자주 묻는 질문 (FAQ)

Q1. subagent는 몇 개부터 만들기 시작하면 되나요? 1개(code-reviewer, 읽기 전용)부터 시작하는 걸 권장합니다. 읽기만 하니 부작용이 없고, 효과가 즉각적이기 때문입니다. 1개가 안정적으로 동작하기 시작한 뒤에 researcher, test-writer 순으로 늘리세요. 한 번에 5개를 만들면 어느 게 잘 되는지 판단이 어렵습니다.

Q2. subagent가 메인 에이전트보다 작은 모델을 써도 되나요? 네, 권장되는 패턴입니다. code-reviewer 같은 단순 검토는 Haiku 계열 같은 저렴한 모델로도 충분합니다. subagent 정의의 model 필드를 명시하면 됩니다. 비용·속도·컨텍스트 효율 3가지가 모두 개선됩니다.

Q3. subagent가 또 다른 subagent를 호출할 수 있나요? Claude Code는 중첩 위임을 차단합니다(1단계만 허용). 대신 메인이 여러 subagent를 순차·병렬로 호출해 결과를 조합하는 패턴이 권장됩니다. 오케스트레이터 역할은 메인 에이전트가 맡아야 합니다.

마무리

첫 subagent는 읽기 전용 code-reviewer 하나부터 시작합니다.
name·description·tools·시스템 프롬프트 4요소로 정의 파일이 끝납니다.
역할별로 권한을 다르게 설계해야 분리의 의미가 살아납니다.

다음에 읽으면 좋은 글

(5/8) 권한 설정 — subagent별 권한 설계
(4/8) 도구 설계 — SKILL.md와 subagent 중 뭘 쓸지
(8/8) 검증과 반복 — subagent 실패 로그 루프