들어가며
솔직히 처음엔 “subagent가 뭐가 다르다는 거지?” 싶었다. Claude Code 쓰다 보면 가끔 대화가 너무 길어지고, 컨텍스트가 터질 것 같은 순간이 생기는데, 그 문제를 해결하는 게 바로 사용자 정의 subagent다.
공식 문서(code.claude.com/docs/ko/sub-agents)를 처음부터 끝까지 읽으면서 직접 만들어봤다. 개념은 단순한데, 막상 쓰기 시작하면 생각보다 활용 폭이 넓어서 정리해두면 좋겠다 싶었다.
Subagent가 뭔지부터 짚고 가자
한 줄로 정리하면, 특정 작업만 담당하는 독립적인 AI 어시스턴트다.
예를 들어 코드 리뷰를 요청하면, 보통은 메인 대화 컨텍스트에 리뷰 결과가 쭉 쌓인다. 근데 코드 리뷰용 subagent를 만들어두면, 그 에이전트가 자기 컨텍스트에서 혼자 분석하고 결과 요약만 메인 대화로 돌려준다. 컨텍스트 오염이 없다.
Claude Code에는 기본 내장 subagent가 있다.
- Explore: Haiku 모델 기반, 읽기 전용. 코드베이스 탐색용
- Plan: 계획 수립 전 코드베이스 조사용
- General-purpose: 탐색 + 수정 모두 필요한 복잡한 작업용
근데 이것들 외에, 내가 원하는 역할로 직접 만들 수 있다는 게 포인트다.
직접 만들어본 방법 (빠른 시작)
1단계: /agents 명령으로 인터페이스 열기
Claude Code 안에서 그냥 /agents 치면 된다. Library 탭에서 “Create new agent” 누르고, 개인용이면 Personal 선택. 이렇게 하면 ~/.claude/agents/ 경로에 저장되고 모든 프로젝트에서 쓸 수 있다.
2단계: Claude가 대신 생성해줌
“Generate with Claude” 버튼 누르고, 원하는 에이전트를 설명하면 된다. 예를 들어:
“코드 가독성, 성능, 베스트 프랙티스 개선점을 스캔하고 제안해주는 에이전트. 현재 코드와 개선 버전을 함께 보여줘.”
그러면 이름(identifier), 설명(description), 시스템 프롬프트까지 자동 생성된다.
3단계: 도구 범위 좁히기
읽기 전용 코드 리뷰어라면 Write, Edit 권한은 없애는 게 맞다. Read, Grep, Glob, Bash 정도만 남기면 충분하다. 이게 보안 측면에서도 훨씬 안전하다.
4단계: 모델 선택
Haiku(빠름), Sonnet(균형), Opus(강력) 중에 고른다. 코드 리뷰 정도면 Sonnet이 적당하다.
직접 파일로 만드는 방법
/agents UI 대신 파일을 직접 만들 수도 있다. .claude/agents/ 또는 ~/.claude/agents/에 마크다운 파일을 놓으면 된다.
---
name: code-reviewer
description: 코드 품질, 보안, 유지보수성을 검토하는 읽기 전용 리뷰어. 코드 수정 직후 자동으로 실행됩니다.
tools: Read, Grep, Glob, Bash
model: sonnet
---
당신은 시니어 코드 리뷰어입니다.
호출 시:
1. git diff로 최근 변경사항 확인
2. 수정된 파일 집중 분석
3. 즉시 리뷰 시작
피드백은 다음 순서로 정리합니다:
- Critical (반드시 수정)
- Warning (가급적 수정)
- Suggestion (고려할 개선점)
핵심은 name과 description만 필수라는 것. description을 잘 써야 Claude가 언제 이 에이전트를 쓸지 판단할 수 있다.
실제로 쓸 때 알아두면 좋은 것들
에이전트 범위(scope) 선택이 중요하다. 프로젝트 전용이면 .claude/agents/, 모든 프로젝트에서 쓰고 싶으면 ~/.claude/agents/에 넣는다. 팀 전체에 배포하려면 관리되는 설정을 쓰면 된다.
모델은 비용과 성능의 트레이드오프다. 단순 파일 탐색은 Haiku, 복잡한 분석은 Sonnet, 최고 품질이 필요하면 Opus. 코드 리뷰나 디버깅은 Sonnet이 가성비가 제일 낫더라.
지속적 메모리 기능도 있다. memory: user로 설정하면 대화가 끝나도 에이전트가 배운 것들을 ~/.claude/agent-memory/ 에 저장해둔다. 코드베이스 패턴이나 반복 이슈 같은 걸 쌓아가면서 갈수록 똑똑해진다.
@-mention으로 명시적 호출도 가능하다. @"code-reviewer (agent)" 이런 식으로 붙이면 Claude가 알아서 쓸 것 같은 상황이 아니어도 강제로 그 에이전트를 쓸 수 있다.
언제 subagent를 쓰고, 언제 메인 대화를 써야 할까
이게 사실 처음에 제일 헷갈렸다.
메인 대화가 나은 경우:
- 여러 단계가 컨텍스트를 공유해야 할 때 (계획 → 구현 → 테스트)
- 빠른 단발성 수정이 필요할 때
- 반복적으로 앞뒤 주고받으며 개선할 때
Subagent가 나은 경우:
- 테스트 실행, 로그 분석처럼 엄청난 양의 출력이 나올 때
- 특정 권한만 부여하고 싶을 때 (읽기 전용 DB 접근 등)
- 독립적인 작업이고 요약만 받아도 될 때
개인적으로 가장 유용하게 쓴 패턴은 병렬 연구다. “인증 모듈, DB 모듈, API 모듈을 각각 별도 subagent로 동시에 분석해줘” 이렇게 던지면, 세 개가 동시에 돌고 요약이 돌아온다. 시간이 확 줄더라.
마무리
Claude Code subagent는 결국 컨텍스트를 아끼면서, 역할을 분리하는 도구다. AI가 만능처럼 보여도 컨텍스트 관리가 실력인 시대다. 잘 설계된 subagent 하나가 프로젝트 전체 작업 흐름을 바꿔놓을 수 있다.
직접 만들어보면 진입장벽이 생각보다 낮다. /agents 명령 하나로 시작할 수 있으니까. 지금 Claude Code 쓰고 있다면, 가장 자주 반복하는 작업 하나만 골라서 subagent로 만들어보길 추천한다.
👉 관련해서 Claude MCP 서버 연결하는 법도 함께 읽어보면 도움이 된다.
포커스 키프레이즈: Claude Code subagent
슬러그: 클로드-코드-subagent-만들기
메타 디스크립션 (140자): Claude Code에서 사용자 정의 subagent를 직접 만드는 방법을 정리했습니다. /agents 명령으로 5분 만에 코드 리뷰어, 디버거 등 특화 AI 에이전트를 만들 수 있습니다.
태그: Claude Code, subagent, AI 활용, 개발자 도구, Anthropic, AI 자동화, AX, 코드 리뷰, 컨텍스트 관리, 개발 생산성