Claude Code 기본 서브에이전트 이해하기

Claude Code 기본 서브에이전트 이해하기 Claude Code에는 여러 서브에이전트(Subagent)가 기본으로 포함되어 있습니다. 서브에이전트는 메인 Claude가 모든 작업을 직접 처리하는 대신, 특정 작업을 별도의 작업자에게 맡겨 처리하는 기능입니다.쉽게 말하면 메인 Claude가 팀장이고, 서브에이전트는 특정 업무를 맡아 처리하는 담당자라고 생각하면 됩니다.초보자가 먼저 알아두면 좋은 기본 서브에이전트는 General-purpose, Plan, Explore, statusline-setup, claude-code-guide입니다. ● Explore - 코드와 프로젝트를 조사하는 담당자Explore는 프로젝트 안에서 파일을 찾고, 코드를 검색하고, 구조를 파악하는 데 특화된 읽기 전용 서브에이전트입니다.예를 들어 다음과 같은 질문을 했다고 가정해 보겠습니다.“로그인 기능이 어디에 구현되어 있는지 찾아줘.”“사용자 인증과 관련된 파일을 조사해줘.”“이 프로젝트에서 데이터베이스에 접근하는 코드를 찾아줘.”이런 작업은 코드를 수정하는 것이 아니라 많은 파일을 검색하고 구조를 파악하는 작업입니다. Claude는 이런 경우 Explore 에이전트에게 조사를 맡길 수 있습니다.Explore는 기본적으로 파일을 읽고 검색할 수 있지만 파일을 직접 수정하지는 않습니다.따라서 다음과 같은 상황에 사용하기 좋습니다.어떤 파일을 수정해야 할지 모를 때프로젝트 구조를 먼저 파악해야 할 때특정 기능이 어디에 구현되어 있는지 찾을 때여러 파일의 관계를 조사할 때보통 사용자가 Explore를 직접 지정하지 않아도 Claude가 필요하다고 판단하면 자동으로 사용합니다.직접 요청하고 싶다면 다음처럼 말할 수 있습니다.“Explore 에이전트를 사용해서 로그인 기능과 관련된 파일을 찾아줘.”한마디로 정리하면,Explore = 조사 담당자입니다. ● Plan - 계획을 세우기 위한 조사 담당자Plan 서브에이전트는 이름 때문에 조금 헷갈릴 수 있습니다.Plan은 실제 구현을 담당하는 에이전트라기보다 작업 계획을 세우기 전에 필요한 정보를 조사하는 읽기 전용 에이전트입니다.예를 들어 Claude Code에서/plan 로그인 기능을 JWT 방식으로 변경해줘라고 요청했다고 가정해 보겠습니다.메인 Claude는 바로 코드를 수정하지 않고 먼저 프로젝트를 살펴봅니다. 이때 필요한 코드와 구조를 조사하기 위해 Plan 서브에이전트를 사용할 수 있습니다.Plan은 조사 결과를 메인 Claude에게 전달하고, 메인 Claude는 그 결과를 이용해 최종 작업 계획을 작성합니다.따라서 다음과 같은 상황에서 사용됩니다.큰 기능을 수정하기 전에여러 파일을 변경해야 하는 작업기존 구조를 충분히 이해한 후 계획을 만들어야 하는 작업구현하기 전에 작업 범위를 확인해야 하는 경우중요한 것은 Plan 서브에이전트와 Plan Mode는 같은 것이 아니라는 점입니다.Plan Mode → 메인 Claude를 계획 전용 상태로 만드는 작업 모드Plan 서브에이전트 → Plan Mode에서 필요한 코드와 프로젝트 정보를 조사하는 별도의 작업자라고 이해하면 쉽습니다.초보자라면 Plan 서브에이전트를 직접 지정하기보다는 다음처럼 사용하는 것이 좋습니다./plan 회원관리 기능을 추가하기 위한 작업 계획을 만들어줘.그러면 Claude가 필요에 따라 Plan 서브에이전트를 활용합니다.한마디로 정리하면,Plan = 계획을 만들기 위한 조사 담당자입니다. ● General-purpose - 조사부터 실제 작업까지 할 수 있는 범용 담당자General-purpose는 이름 그대로 여러 종류의 작업을 처리할 수 있는 범용 서브에이전트입니다.Explore와 Plan이 주로 읽기와 조사에 집중한다면 General-purpose는 필요에 따라 파일을 조사하고, 판단하고, 여러 단계를 수행하고, 코드를 수정하는 작업까지 처리할 수 있습니다.예를 들어“로그인 오류의 원인을 찾아서 수정하고 테스트까지 해줘.”라는 요청이 있다고 가정해 보겠습니다.이 작업에는 여러 단계가 필요합니다.오류 위치 찾기 → 관련 코드 분석 → 원인 판단 → 코드 수정 → 테스트이처럼 조사와 실제 수정이 함께 필요한 복잡한 작업은 General-purpose가 적합합니다.다음과 같은 상황에 활용하기 좋습니다.여러 단계를 거쳐야 하는 작업조사 후 실제 코드를 수정해야 하는 작업원인을 분석하고 해결책까지 적용해야 하는 작업서로 연관된 여러 작업을 처리해야 하는 경우예를 들어 다음처럼 요청할 수 있습니다.“General-purpose 에이전트를 사용해서 테스트 실패 원인을 조사하고 필요한 코드를 수정해줘.”한마디로 정리하면,General-purpose = 조사와 실행을 모두 할 수 있는 범용 작업자입니다. ● statusline-setup - 상태 표시줄 설정 담당자statusline-setup은 일반적인 개발 업무를 처리하는 에이전트가 아닙니다.Claude Code 화면 아래쪽에 표시되는 Status Line을 설정할 때 사용하는 전용 보조 에이전트입니다.Claude Code에서 다음 명령을 실행할 수 있습니다./statusline예를 들어 Status Line에현재 모델현재 Git 브랜치컨텍스트 사용량같은 정보를 표시하고 싶다고 요청할 수 있습니다.예를 들면/statusline 모델명과 Git 브랜치를 표시해줘라고 요청할 수 있습니다.이때 Claude Code가 내부적으로 statusline-setup 에이전트를 사용할 수 있습니다.따라서 일반적인 프로젝트 개발 과정에서 이 에이전트를 직접 사용할 일은 거의 없습니다.한마디로 정리하면,statusline-setup = Claude Code 화면 설정 도우미입니다. ● claude-code-guide - Claude Code 사용법 안내 담당자claude-code-guide는 Claude Code 자체의 기능과 사용 방법에 대한 질문을 처리하기 위한 보조 에이전트입니다.예를 들어 다음과 같은 질문을 했다고 가정해 보겠습니다.“Claude Code에서 Hook은 어떻게 만들지?”“Skill과 Subagent의 차이가 뭐야?”“MCP는 어떻게 연결하지?”“settings.json은 어디에 있어?”이런 질문은 현재 프로젝트의 코드를 분석하는 문제가 아니라 Claude Code 자체의 기능에 관한 질문입니다.이런 경우 Claude가 claude-code-guide를 이용해 관련 정보를 확인할 수 있습니다.이 에이전트도 보통 사용자가 직접 선택할 필요는 없습니다. Claude Code 사용법을 질문하면 필요에 따라 자동으로 활용됩니다.한마디로 정리하면,claude-code-guide = Claude Code 사용 설명서 담당자라고 생각하면 됩니다. ● 다섯 가지를 가장 쉽게 구분하면Explore → 프로젝트를 조사한다.Plan → 계획을 세우기 위해 프로젝트를 조사한다.General-purpose → 조사하고 실제 작업까지 수행한다.statusline-setup → Claude Code의 상태 표시줄을 설정한다.claude-code-guide → Claude Code 사용 방법을 알려준다. ● 실제 프로젝트에서는 어떻게 사용하면 될까?예를 들어 새로운 기능을 추가한다고 생각해보겠습니다.먼저“현재 프로젝트에서 사용자 관리 기능이 어떻게 구성되어 있는지 조사해줘.”라고 하면 Explore가 적합합니다.그다음/plan 사용자 관리 기능에 권한 관리 기능을 추가해줘라고 하면 Plan Mode와 Plan 서브에이전트를 이용해 기존 구조를 조사하고 작업 계획을 만들 수 있습니다.계획을 확인한 후“이 계획대로 구현하고 테스트해줘.”라고 하면 메인 Claude나 General-purpose 계열의 작업자가 실제 구현을 수행할 수 있습니다.즉,Explore 조사↓Plan 계획↓General-purpose 구현이라는 흐름으로 생각하면 이해하기 쉽습니다. ● 사용자가 매번 서브에이전트를 지정해야 할까?그럴 필요는 없습니다.Claude Code는 작업 내용에 따라 적절한 서브에이전트를 자동으로 선택해서 사용할 수 있습니다.따라서 초보자라면“Explore를 사용해야 하나, General-purpose를 사용해야 하나?”를 매번 고민할 필요는 없습니다.평소에는 그냥“이 기능이 어디에 구현되어 있는지 조사해줘.”“이 기능을 추가하기 위한 계획을 만들어줘.”“계획대로 구현하고 테스트해줘.”처럼 원하는 작업을 명확하게 요청하면 됩니다.특정 에이전트를 반드시 사용하게 하고 싶을 때만“Explore 에이전트를 사용해서 조사해줘.”처럼 명시적으로 지정하면 됩니다. ● 직접 서브에이전트를 선택할 수도 있다최근 Claude Code에서는 @ 멘션을 이용해 특정 서브에이전트를 지정하는 방법도 지원합니다.입력창에서 **@**를 입력하면 사용할 수 있는 파일이나 에이전트가 표시되고, 원하는 에이전트를 선택해서 작업을 요청할 수 있습니다.하지만 초보 단계에서는 굳이 모든 작업에 에이전트를 직접 지정할 필요가 없습니다. Claude에게 해야 할 일을 명확하게 설명하고 자동으로 적절한 에이전트를 선택하도록 하는 방식부터 사용하는 것이 좋습니다. ● 초보자가 실제로 기억해야 할 것은 세 가지처음에는 다섯 가지를 모두 외울 필요가 없습니다.우선 다음 세 가지만 기억하면 충분합니다.Explore → 조사Plan → 계획을 위한 조사General-purpose → 실제 복잡한 작업 수행그리고 나머지 두 개는statusline-setup  → Claude Code 화면 설정claude-code-guide → Claude Code 사용법 안내정도로 이해하면 됩니다. ● 하네스 엔지니어링 관점에서는 어떻게 볼까?하네스를 구성할 때 중요한 것은 기본 서브에이전트를 많이 사용하는 것이 아닙니다.현재 프로젝트에서 반복적으로 필요한 전문 역할이 있는지를 찾는 것이 더 중요합니다.예를 들어 프로젝트에서 계속문서 조사코드 품질 검토테스트보안 검사같은 업무가 반복된다면 기본 General-purpose 하나에 모든 일을 맡기기보다 나중에는researchercode-reviewertest-runnersecurity-reviewer같은 커스텀 서브에이전트를 만들어 역할을 나눌 수 있습니다.따라서 기본 제공되는 Explore, Plan, General-purpose를 먼저 사용해보고, 반복되는 전문 업무가 생기기 시작했을 때 커스텀 서브에이전트를 만드는 방식이 좋습니다. ● 한 문장으로 정리Claude Code의 기본 서브에이전트는 Explore는 조사, Plan은 계획을 위한 조사, General-purpose는 복잡한 실제 작업을 담당하고, statusline-setup과 claude-code-guide는 Claude Code 자체를 설정하고 안내하기 위한 보조 에이전트라고 이해하면 됩니다.처음에는 에이전트를 직접 하나씩 선택하려고 하기보다는 해야 할 업무를 명확하게 요청하고 Claude가 자동으로 적절한 서브에이전트를 사용하도록 하는 방식으로 시작하는 것이 가장 쉽습니다.