View Categories

Claude Subagents

윤후 이
Updated on 6월 5, 2026

2 min read

Claude Subagents: 별도 컨텍스트를 가진 전문 작업자 #

Claude Subagents 는 별도 컨텍스트에서 동작하는 전문 에이전트입니다.

많은 파일을 읽고 분석해도 중간 과정이 메인 대화에 쌓이지 않고, 최종 요약만 돌아옵니다.

저는 개인적으로 Claude Subagents 를 작성하여 활용한 적은 아직 없습니다.

이미 너무 잘 개발된 skill framework 들이 존재하기 때문이죠;;

하지만 개념적으로 병렬 작업 및 컨텍스트 유지에 좋다는 점만 이해하고 있으면 향후 필요 시 커스텀해서 활용 할 수 있을 것 같습니다.

subagent 파일 위치

모든 프로젝트에서 재사용할 개인 Subagent는 ~/.claude/agents/에 둘 수 있습니다.

같은 이름의 Subagent가 여러 위치에 있으면 더 높은 우선순위의 위치가 적용됩니다.

~/.claude/agents/             # 전역: 개인이 모든 프로젝트에서 재사용
./.claude/agents/             # 프로젝트: 해당 저장소에서 팀과 공유
./.claude/agents/review/      # 하위 폴더로 분야별 정리 가능
./.claude/agents/security-reviewer.md

Subagent 파일은 크게 두 부분으로 구성됩니다.

위쪽의 YAML frontmatter에는 name, description, tools, model, permissionMode, skills 같은 실행 설정을 적고, 아래 Markdown 본문에는 해당 에이전트의 역할과 판단 기준을 적습니다.

Claude Code는 Subagent 파일을 세션 시작 시 로드하므로, 파일을 직접 추가하거나 수정했다면 새 세션에서 다시 읽히도록 재시작하는 것이 안전합니다.

특히 name은 호출할 때 사용하는 식별자이고, description은 Claude가 “이 작업을 어떤 Subagent에게 맡길지” 자동 판단할 때 참고하는 설명입니다.

따라서 파일명보다 중요한 것은 frontmatter의 name과 description입니다.

---
name: security-reviewer
description: 인증, 권한, API 엔드포인트 보안 검토가 필요할 때 사용.
tools: Read Grep Glob Bash
model: opus
permissionMode: plan
skills:
  - security-patterns
---

## 역할
시니어 보안 엔지니어처럼 변경 사항을 검토합니다.

## 검토 기준
- 인증/인가 누락
- 입력 검증 부족
- 민감 정보 노출
- SQL injection, XSS 가능성

Subagent는 다음 경우에 적합합니다.

  • 코드베이스 전체 탐색이 필요한 작업
  • 보안, 성능, 아키텍처처럼 전문 관점이 필요한 검토
  • 여러 분석을 병렬로 실행하고 싶은 경우
  • 메인 대화의 컨텍스트를 깨끗하게 유지해야 하는 경우

Claude Subagents 호출 방법 #

설정 파일(.claude/agents/security-reviewer.md)을 올바른 경로에 저장해 두었다면, 메인 Claude에게 별도의 복잡한 명령어를 입력할 필요 없이 자연스럽게 호출할 수 있습니다.

  1. 자연어로 명시적 요청 (가장 확실한 방법) 프롬프트에 에이전트의 이름을 직접 언급하며 일을 시키면 됩니다. Claude는 .claude/agents/ 디렉토리를 탐색해 이름이 일치하는 에이전트를 찾아 깨웁니다.
    • 예시: "이번에 수정한 로그인 엔드포인트를 security-reviewer 에이전트한테 검토하라고 해줘."
    • 예시: "인증 로직을 조금 고쳤는데, security-reviewer로 취약점 좀 봐줄래?"
  2. Claude의 자동 판단 (라우팅) 에이전트 이름을 직접 말하지 않고 "이번에 새로 작성한 API 엔드포인트들에 보안상 허점이 없는지 코드베이스 전체적으로 검토해줘"라고만 말해도 됩니다. 메인 Claude가 파일 상단의 description 필드(인증, 권한, API 엔드포인트 보안 검토가 필요할 때 사용)를 읽고 “아, 이 일은 security-reviewer가 제격이겠네!” 하고 알아서 판단해 업무를 위임(Delegation)합니다.

Claude Subagents 내부 동작 방식 #

작동 메커니즘은 ‘오케스트레이터-워커(Orchestrator-Worker)’ 패턴으로 이해하시면 쉽습니다.

메인 대화창 뒷단에서 다음과 같은 순서로 깔끔하게 움직입니다.

  • 독립된 방(Context) 개설: 메인 Claude가 이 에이전트를 호출하는 순간, 설정된 모델(opus)을 사용하는 완전히 새로운 Claude 인스턴스가 독립된 컨텍스트 창을 가지고 하나 더 생성됩니다.
  • 엄격한 도구 및 권한 제한: 이 서브에이전트는 메인 에이전트의 권한을 그대로 상속받는 것이 아니라, 프론트매터(Frontmatter)에 적힌 tools(Read, Grep, Glob, Bash)만 사용할 수 있도록 물리적인 제약을 받습니다.
  • 중간 소음 차단: 서브에이전트가 소스코드를 뒤적거리고(Read), 정규식으로 취약점 패턴을 검색(Grep)하는 수많은 중간 과정과 파일 내용, 오류 로그들은 오직 서브에이전트의 독립된 방에만 쌓입니다. 메인 대화창에는 이 지저분한 흔적이 전혀 노출되지 않습니다.
  • 최종 요약본만 배달: 모든 분석이 끝나면 서브에이전트는 지정된 ‘검토 기준’에 맞춰 작성한 최종 결과 리포트만 메인 Claude에게 전달하고 메모리에서 조용히 사라집니다. 사용자는 메인 대화창에서 이 깔끔한 요약본만 받아보게 됩니다.
글이 도움이 되셨나요?

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다