Claude Code Subagent 사용법, 역할만 정해주면 AI가 알아서 처리한다

AI를 어떻게 활용하느냐에 따라 업무 생산성은 완전히 달라집니다. 이제 AI는 단순히 사용자의 프롬프트에 답변하는 도구를 넘어, 주어진 업무를 역할에 맞게 처리하는 에이전트 방식으로 확장되고 있습니다.

이 흐름에서 주목할 만한 기능이 바로 ‘Claude Code Subagent(서브 에이전트)’입니다. 업무를 역할별로 나누고, 각 역할에 맞는 AI가 작업을 스스로 처리하도록 돕는 보조 에이전트 기능으로 사용자가 각 과정을 일일이 확인하고 지시하지 않아도, 필요한 Subagent를 호출하고 결과를 취합해 하나의 작업 흐름으로 이어갑니다. 

덕분에 긴 작업에서도 메인 흐름이 복잡해지는 것을 줄이고, 사용자는 세부 과정이 아니라 전체 방향과 최종 결과물의 품질에 더 집중할 수 있습니다.

이 글에서는 Claude Code Subagent가 어떤 방식으로 동작하는지, 어떤 작업에 적합한지, 그리고 실제 개발 환경에서 어떻게 활용할 수 있는지를 중심으로 정리해보겠습니다.

.

Claude Code Subagent(서브 에이전트) 핵심 요약

• Claude Code Subagent는 역할을 지정해 작업을 처리하는 보조 에이전트 기능입니다. 코드 탐색, 테스트 분석, 보안 검토, 문서 확인처럼 메인 작업과 분리하면 좋은 일을 별도 에이전트에게 위임하는 기능입니다.
• 긴 작업에서 컨텍스트 관리를 도와줍니다 작업이 길어질수록 코드 탐색 결과, 에러 로그, 테스트 결과가 한 대화 안에 쌓여 흐름이 복잡해질 수 있습니다. Subagent는 부가 작업을 별도 컨텍스트에서 처리하고 요약 결과만 반환해 메인 Claude Code가 핵심 판단에 집중하도록 돕습니다.
• 역할 분담이 필요한 작업에 유용합니다. 파일에서는 keyword-researcher, outline-planner, blog-writer, fact-checker, seo-editor로 역할을 나눈 예시를 제시합니다. 메인 Claude Code가 각 Subagent를 순서대로 호출하고 결과를 취합하면 콘텐츠 제작 흐름을 체계적으로 운영할 수 있습니다.
• 결과 품질은 역할과 규칙 설계에 따라 달라집니다 Subagent는 에이전트 팀이 아니라 메인 Claude Code가 특정 작업을 위임하고 결과를 받아오는 보조 에이전트 구조입니다.
   따라서 작업 범위, 도구 권한, 메모리 범위, 검증 기준, 하네스 엔지니어링 규칙을 명확히 설계해야 합니다.

Claude Code Subagent(서브 에이전트)란?

Claude Code Subagent는 Claude Code 안에서 특정 작업을 별도로 맡아 처리하는 전문 AI 작업자입니다. 

코드 탐색, 테스트 분석, 보안 검토, 문서 확인처럼 분리해서 처리하면 좋은 작업을 별도 에이전트에게 위임하는 구조로, 각 Subagent는 자체 컨텍스트 윈도우, 별도의 시스템 프롬프트, 개별 도구 권한을 가지고 독립적으로 실행됩니다.

Explore, Plan, general-purpose처럼 별도 설정 없이 바로 쓸 수 있는 빌트인 Subagent와, 사용자가 직접 만드는 커스텀 Subagent 두 종류가 제공되어 필요할 때 원하는 작업을 위임할 수 있습니다. 

덕분에 사용자는 긴 개발 작업 중에도 중요한 판단과 실행 흐름에 집중할 수 있습니다. 

Claude Code Subagents(서브에이전트)가 

주목받는 이유

Claude Code 작업이 길어질수록 

컨텍스트 관리가 중요해집니다

Claude Code로 기능 개발이나 리팩토링을 오래 진행하면 코드 탐색 결과, 에러 로그, 테스트 결과, 수정 방향이 하나의 대화 안에 계속 쌓입니다. 이렇게 정보가 많아지면 핵심 작업보다 주변 정보에 영향을 받을 수 있습니다.

Subagents는 코드 탐색, 테스트 분석, 문서 확인 같은 부가 작업을 별도 컨텍스트에서 처리합니다. 덕분에 메인 대화는 핵심 판단과 실행 흐름에 집중할 수 있고, 긴 개발 작업에서도 작업의 흐름을 더 깔끔하게 유지할 수 있습니다.

시간이 오래 걸리는 작업을 

따로 맡길 수 있습니다

Subagents를 사용하면 코드 탐색이나 분석 같은 작업을 별도 에이전트에게 위임해, 메인 Claude Code가 구현 판단에만 집중할 수 있습니다.

개발 작업에서는 특정 함수가 어디에서 호출되는지, 테스트가 왜 실패했는지, 기존 코드 규칙이 어떻게 구성되어 있는지 확인해야 할 때가 많습니다. 

이럴 때 Subagents를 사용하면 탐색 작업을 별도 에이전트에게 위임해 탐색 과정이 메인 대화 밖에서 처리되어 컨텍스트가 깔끔하게 유지되고, 요약된 결과만 돌아오기 때문에 다음 구현 단계로 바로 넘어갈 수 있습니다. 

덕분에 사용자는 탐색 결과를 기다리거나 직접 파일을 뒤지는 시간 없이, 구현과 판단에만 집중할 수 있습니다.

Claude Code Subagent(서브 에이전트) 사용법

- 블로그 콘텐츠 제작 Agent 생성하기

Claude Code Subagents의 활용 이해를 돕기 위해 블로그 콘텐츠 제작을 예시로 들어보겠습니다.

1. Subagent의 역할 지정하기

블로그 하나를 작성할 때도 키워드 조사, 목차 구성, 본문 작성, 사실 검증, SEO 최적화까지 여러 단계가 필요합니다. 이 과정을 하나의 Claude가 순서대로 처리하면 컨텍스트가 빠르게 쌓이고 흐름이 느려집니다. 

Subagents를 활용하면 각 단계를 전문 에이전트에게 동시에 위임해 같은 시간 내에도 더 많은 콘텐츠를 작성할 수 있습니다.

블로그 콘텐츠 제작 Subagent의 역할 분담

• keyword-researcher — 타겟 키워드와 연관 검색어를 조사해 메인 에이전트에 전달
• outline-planner — 키워드를 기반으로 SEO 구조에 맞는 목차를 구성
• blog-writer — 목차에 따라 각 섹션 본문을 작성
• fact-checker — 본문의 수치, 날짜, 제품명 등 사실 관계를 검증
• seo-editor — 메타 설명, 소제목 구조, 키워드 밀도를 최종 점검

2. Claude Code에서 Subagent 생성하기

블로그 콘텐츠 제작의 역할을 나눴으면 이제 역할에 맞는 Subagent를 생성합니다. /agents 명령을 실행하면 Subagent를 관리할 수 있는 인터페이스가 열립니다. Library 탭에서 Create new agent를 선택하고 저장 범위를 지정합니다 

Subagent를 생성하고 관리할 수 있는 화면이 나옵니다. Personal을 선택하면 모든 프로젝트에서 사용할 수 있고, Project를 선택하면 현재 프로젝트에서만 사용할 수 있습니다. 

Subagent의 이름, 설명, 시스템 프롬프트를 설정할 수 있는 화면이 나옵니다. Generate with Claude를 선택해 역할 설명을 입력하면 Claude가 이름, 설명, 시스템 프롬프트를 자동으로 생성합니다. 

위의 이미지처럼 Agent의 이름과 역할을 입력한 뒤 Enter를 클릭합니다.

Subagent에 허용할 도구 권한을 선택하는 화면이 나옵니다. keyword-researcher처럼 탐색과 분석만 필요한 경우에는 Read-only tools만 선택하면 됩니다. 

도구를 선택하면 AI 모델을 선택하는 화면이 나옵니다. keyword-researcher처럼 정보만 빠르게 확인하면 되는 경우 Haiku 모델을 선택하면 속도가 빠르고 비용 부담이 작습니다. 저장하면 해당 Subagent가 즉시 사용 가능한 상태가 됩니다. 

Subagent의 컬러를 지정하는 화면이 나옵니다. 색상은 여러 Subagent가 동시에 실행될 때 어떤 에이전트가 작동 중인지 구분하는 용도로 사용됩니다. 원하는 색상을 선택합니다.

Subagent의 메모리 범위를 설정하는 화면입니다. 메모리를 활성화하면 Subagent가 대화가 끝난 뒤에도 학습한 내용을 저장하고 다음 세션에서 활용합니다.

옵션은 아래 네 가지로 분류됩니다.

• User scope — 모든 프로젝트에서 메모리를 공유합니다. 여러 프로젝트에 걸쳐 동일한 Subagent를 반복 사용한다면 이 옵션을 선택합니다.
• None — 메모리를 저장하지 않습니다. 매 세션마다 처음부터 시작합니다.
• Project scope — 현재 프로젝트 안에서만 메모리를 유지합니다. 팀원과 공유할 수 있어 협업 프로젝트에 적합합니다.
• Local scope — 현재 프로젝트에서만 메모리를 유지하되 버전 관리에는 포함되지 않습니다.

블로그 콘텐츠 제작 예시라면 keyword-researcher나 seo-editor처럼 반복적으로 사용하는 Subagent는 User scope를 선택해 학습 내용을 누적시키는 것이 좋습니다.

생성할 Subagent의 이름, 저장 위치, 도구, 모델, 메모리, 설명, 시스템 프롬프트를 최종 확인하는 화면이 나옵니다. 

내용이 맞으면 Enter를 눌러 저장하고, 수정이 필요하면 e를 눌러 편집할 수 있습니다. 저장하면 Subagent 생성이 완료됩니다. 

3. Subagent를 통해 콘텐츠 제작하기

Subagent 생성이 완료되면 프롬프트를 입력해 메인 Claude Code에 작업을 지시합니다. 

블로그 제작 요청 프롬프트

메인 Claude Code는 오케스트레이터 역할을 맡아 각 Subagent를 작업 순서에 맞게 호출하고, 반환된 결과를 하나로 정리합니다. 

사용자가 각 단계의 진행 상황을 일일이 확인하지 않아도, 미리 정해둔 역할과 흐름에 따라 작업이 진행됩니다. 

Claude Code Subagent(서브 에이전트) 

사용 시 주의사항

1. Subagent는 에이전트 팀과 같은 개념이 아닙니다

Subagent는 메인 Claude Code가 전체 작업 흐름을 유지하면서 특정 작업이 필요할 때 별도의 에이전트에게 위임하는 구조로 작업이 끝나면 요약된 결과만 메인 대화로 돌아오고 종료됩니다. 

코드 탐색, 테스트 분석, 보안 검토처럼 단일 세션 안에서 처리 가능하고 결과 요약만 필요한 작업은 Agent Teams가 아닌 Subagent를 사용하는게 효율적입니다. 

▶ 동시 다발적인 병렬 작업으로 생산성을 높이는 Agent Teams 활용법 보러가기

2. 작업 범위와 역할을 명확히 정해야 합니다

Subagent를 사용할 때는 작업 범위와 역할을 명확히 정하는 것이 중요합니다.코드 탐색을 맡기는 것인지, 수정 방향까지 제안받는 것인지, 실제 코드 변경까지 허용할 것인지에 따라 결과가 달라집니다. 

단순 분석만 필요한 경우에는 읽기와 요약 중심으로 요청하고, 코드 수정이 필요한 경우에는 어떤 파일을 수정할 수 있는지, 어떤 기준을 지켜야 하는지까지 함께 지정하는 것이 좋습니다. 기준이 명확할수록 사용자의 의도와 가까운 결과가 나옵니다.

3. 하네스 엔지니어링 설계에 따라 결과가 달라집니다

Subagent는 역할, 권한, 규칙, 검증 기준, 피드백 흐름을 사전에 설계하는 하네스 엔지니어링이 어떻게 구성되느냐에 따라 전혀 다른 결과를 만들어냅니다.

그래서 Subagent를 사용할 때는 반드시 원하는 목적에 맞게 하네스 엔지니어링 규칙을 설계하도록 주의해야 합니다.

생산성을 높이는 배로 AI 에이전트 활용법

Codex Goal 사용법, 목표만 설정하면 끝까지 간다

tmux 사용법, Claude Code와 연동한 멀티플렉서로 생산성을 극대화하는 방법

Paperclip 사용법, AI 에이전트 조직 설계와 자동화 아이디어 얻기