클로드 코드로 큰 작업을 하다 보면 메인 대화가 금방 길어집니다. 파일을 수십 개 훑어보고, 테스트를 돌리고, 로그를 읽는 과정이 전부 대화에 쌓이기 때문이죠. 서브에이전트(Subagents)는 이런 하위 작업을 별도 공간에서 처리하고 결과만 돌려주는 보조 에이전트입니다.
서브에이전트가 필요한 이유
| 문제 | 서브에이전트로 해결 |
|---|---|
| 탐색 과정이 메인 대화를 채움 | 별도 컨텍스트에서 탐색, 요약만 반환 |
| 역할마다 다른 관점이 필요 | 리뷰어·테스터 등 역할별 지침 |
| 위험한 도구 접근 제한 | 에이전트별 허용 도구 지정 |
| 같은 지시를 반복 입력 | 한 번 정의해 두고 재사용 |
비유하자면, 팀장(메인 클로드)이 "이 코드 리뷰해서 문제점만 정리해 와"라고 리뷰 담당자(서브에이전트)에게 맡기는 것과 같습니다. 팀장은 리뷰 과정 전부가 아니라 결과 보고서만 받습니다.
만드는 방법 1: /agents 명령
클로드 코드 세션에서 /agents를 입력하면 서브에이전트를 만들고 관리하는 화면이 열립니다. 새 에이전트를 만들 때 역할을 설명하면 클로드가 설정 초안을 만들어 주고, 허용할 도구를 고를 수 있습니다. 처음에는 이 방법이 가장 쉽습니다.
만드는 방법 2: 파일로 직접 작성
서브에이전트는 마크다운 파일 하나로 정의됩니다.
| 위치 | 적용 범위 |
|---|---|
.claude/agents/ |
이 프로젝트 (팀 공유 가능) |
~/.claude/agents/ |
내 모든 프로젝트 |
파일 구조는 앞부분 설정(front matter) + 본문 지침입니다.
---
name: code-reviewer
description: 코드 변경 후 품질·보안 문제를 검토한다. 기능 구현이 끝나면 사용한다.
tools: Read, Grep, Glob, Bash
---
너는 꼼꼼한 시니어 코드 리뷰어다.
검토 순서:
1. git diff로 변경된 부분을 확인한다.
2. 다음 관점으로 검토한다.
- 버그 가능성 (경계값, 예외 처리)
- 보안 (입력 검증, 비밀값 노출)
- 기존 코드 스타일과의 일관성
3. 결과는 심각도(높음/중간/낮음)별로 정리한다.
규칙:
- 파일을 직접 수정하지 않는다. 문제와 수정 제안만 보고한다.
- 근거가 되는 파일명과 줄 번호를 함께 적는다.
설정 항목
| 항목 | 의미 |
|---|---|
name |
에이전트 이름 (호출할 때 사용) |
description |
언제 이 에이전트를 써야 하는지 — 자동 호출 판단 기준 |
tools |
허용할 도구 (생략하면 메인과 같은 도구 상속) |
model |
사용할 모델 (선택) |
description이 자동 호출의 핵심입니다. "코드 리뷰어"처럼 짧게 쓰기보다 "기능 구현이 끝나면 사용한다"처럼 사용 시점을 적어 주세요.
위 예시처럼 리뷰어에게 파일 수정 도구(Edit, Write)를 빼 두면, 실수로 코드를 고치는 일이 생기지 않습니다.
호출하는 방법
- 자동: 클로드가 description을 보고 적절할 때 스스로 호출합니다.
- 직접 지목: "code-reviewer 에이전트로 방금 변경 사항 리뷰해 줘"
실제로 쓰는 서브에이전트 구성
이 블로그 작업에 쓰는 구성입니다.
| 에이전트 | 역할 | 허용 도구 |
|---|---|---|
| code-reviewer | 템플릿·스크립트 변경 리뷰 | 읽기, 검색, git 명령 |
| content-checker | 글의 링크 깨짐, 날짜 형식, 필수 항목 점검 | 읽기, 검색 |
| build-verifier | 빌드 실행 후 오류·경고 요약 | 읽기, 명령 실행 |
글을 여러 개 쓴 뒤 content-checker에게 맡기면, 메인 대화는 깨끗하게 유지되면서 문제 목록만 받을 수 있습니다.
주의할 점
- 사용량: 서브에이전트도 모델을 호출합니다. 여러 개를 동시에 돌리면 사용량이 빠르게 늘어납니다.
- 맥락 전달: 서브에이전트는 메인 대화의 전체 맥락을 모릅니다. 맡길 때 필요한 정보를 충분히 전달해야 합니다.
- 결과 검토: 서브에이전트가 돌려준 요약도 결국 AI의 판단입니다. 중요한 지적은 직접 확인하세요.
메인 대화가 깔끔해졌습니다
서브에이전트를 쓰고 나서 가장 좋았던 점은 메인 대화가 깔끔해진 것입니다. 예전에는 리뷰를 요청하면 리뷰 과정의 파일 읽기, 검색 결과가 전부 대화에 남아 금방 길어졌는데, 지금은 결과 보고만 남습니다. 처음 만든다면 읽기 전용 리뷰어 하나로 시작해 보세요. 위험 부담 없이 효과를 바로 체감할 수 있습니다.
핵심 요약
- 서브에이전트는 별도 컨텍스트에서 특정 역할을 처리하고 결과만 돌려주는 보조 에이전트입니다.
/agents명령이나.claude/agents/파일로 만들고, description에 사용 시점을 적으세요.- 역할에 필요한 도구만 허용하고, 맡길 때 필요한 맥락을 충분히 전달합니다.
