클로드 코드 서브에이전트 사용법, 긴 검색은 요약만 받기

코드 폴더를 뒤지다 보면 대화창은 금세 길어집니다.

서브에이전트는 검색 결과와 기록을 따로 살핀 뒤 핵심만 주 대화로 돌려줍니다. 긴 자료를 전부 떠안지 않고도 작업을 이어 갈 수 있는 방식이죠.

핵심 내용

서브에이전트는 파일 검색이나 코드 검토처럼 분리해 맡길 수 있는 보조 AI입니다. 작업을 마치면 주 대화에는 전체 자료 대신 요약 결과를 보냅니다.
처음에는 Claude Code에 원하는 역할과 저장 위치를 자연어로 요청해 만들 수 있습니다. 모든 프로젝트에서 쓸지, 현재 프로젝트에서만 쓸지도 정할 수 있습니다.
서브에이전트 파일에는 이름과 설명이 꼭 필요합니다. 특히 설명은 Claude가 어떤 일을 맡길지 판단하는 기준이므로 짧고 분명하게 써야 합니다.
같은 이름을 여러 파일에 두면 엉뚱한 정의가 선택될 수 있습니다. 새 agents 폴더를 처음 만들었다면 Claude Code를 다시 시작해야 할 수도 있습니다.

왜 대화를 따로 나눌까

프로젝트에서 특정 기능이 어디에 쓰이는지 찾거나, 바뀐 코드에 문제가 없는지 훑어야 할 때가 있습니다. 검색 결과와 파일 내용이 길어지면 정작 처음 하려던 질문이 대화 위로 밀려나는 느낌을 받을 수 있죠.

Claude Code의 서브에이전트는 이런 부작업을 별도 공간에서 처리하는 특화된 보조 AI입니다. 파일을 찾아 읽고 코드를 분석한 뒤 필요한 내용을 정리해 주 대화에는 결과 요약만 보냅니다. 주 대화가 검색 기록과 긴 파일 내용으로 가득 차는 일을 줄일 때 쓰기 좋습니다.

기본으로 들어 있는 Explore는 코드를 찾고 읽는 작업에 맞춰져 있습니다. 파일을 바꾸는 도구는 쓰지 못합니다. 그래서 “어디를 고쳐야 하는지 먼저 찾아 달라”는 상황에서 부담이 적습니다. 실제 수정이 필요한 일은 주 대화에서 이어서 판단하거나, 목적에 맞춘 별도 서브에이전트에 맡기는 편이 자연스럽습니다.

서브에이전트는 여러 세션을 한꺼번에 운영하는 기능은 아닙니다. 현재 한 번의 Claude Code 작업 안에서 검색·검토 같은 일을 떼어 내는 도구입니다. 긴 연휴 동안 개인 프로젝트의 구조를 다시 파악해야 한다면, 먼저 탐색 역할에 요약을 맡긴 뒤 다음 작업을 정하는 식으로 써 보세요.

💡 꿀팁 · 처음에는 파일을 고치게 하기보다 “찾고 요약하기” 역할부터 맡기면 결과를 검토하기 편합니다.

클로드 코드 서브에이전트 시작법

처음 만들 때 설정 파일을 처음부터 손으로 작성할 필요는 없습니다. Claude Code 대화에서 맡길 일과 저장 위치를 말하면 Claude가 서브에이전트 파일을 만들 수 있습니다. 공식 안내의 첫 예시는 코드를 검토하고 개선점을 제안하는 역할입니다.

모든 프로젝트에서 반복해 쓸 개인용 역할이라면 `~/.claude/agents/`에 둡니다. 여러 개인 프로젝트에서 같은 검토 기준을 쓰고 싶을 때 맞습니다. 지금 열어 둔 프로젝트에만 맞춘 역할이라면 프로젝트 안의 `.claude/agents/`에 두면 됩니다. 프로젝트용 파일은 팀이 함께 쓰도록 저장소에 포함할 수도 있습니다.

파일을 만든 뒤에는 내용이 요청과 맞는지 열어 확인하세요. 파일 맨 위 설정에는 이름, 설명, 사용할 도구, 사용할 모델 등이 들어가고 그 아래에는 해당 역할이 따라야 할 지침을 적습니다. 최소한 이름과 설명은 있어야 Claude Code가 파일을 서브에이전트로 읽습니다.

준비가 끝나면 Claude Code에 새 역할에게 일을 맡기라고 요청하면 됩니다. 실행 기록에는 역할 이름과 짧은 작업 설명이 표시됩니다. 막 만들었는데 역할을 찾지 못한다면 새 agents 폴더를 세션 시작 뒤에 처음 만든 경우일 수 있습니다. 이때는 Claude Code를 다시 시작한 뒤 같은 요청을 해 보세요.

💡 꿀팁 · 개인용은 `~/.claude/agents/`, 프로젝트 전용은 `.claude/agents/`에 둔다는 점만 먼저 구분해 두세요.

역할 요청은 이렇게 써 보세요

서브에이전트는 설명을 보고 자신이 맡을 때를 판단합니다. 설명이 “도움이 되는 코딩 도우미”처럼 넓으면 어느 상황에 써야 하는지 분명하지 않습니다. 파일 검색인지, 변경점 검토인지, 개선 제안인지 역할을 한 문장으로 좁히면 Claude Code도 일을 나누기 쉬워집니다.

처음 생성 요청에는 역할과 보관 위치를 함께 적으면 됩니다. 여러 프로젝트에서 재사용할 개인 검토 도우미를 만들고 싶다면 아래 문장을 그대로 써도 좋습니다. Claude가 만든 파일은 바로 믿기보다 이름과 설명, 도구 목록이 의도와 맞는지 한 번 확인하는 편이 낫습니다.

"모든 프로젝트에서 사용할 수 있게 ~/.claude/agents/에 코드를 검토하고 개선점을 제안하는 서브에이전트를 만들어 주세요."

이미 만든 탐색 역할에는 결과물의 범위를 정해 요청해 보세요. 파일 전체를 복사해 달라고 하기보다 관련 파일과 이유를 요약해 달라고 하면 주 대화가 더 깔끔하게 남습니다. 수정 전 구조를 파악하는 단계에 잘 맞는 방식입니다.

"이 프로젝트에서 로그인 처리가 있는 파일을 찾아서, 관련 파일 이름과 각각의 역할만 요약해 주세요."

검토 역할에는 확인 기준을 좁혀 주는 편이 좋습니다. 단순히 개선점을 묻기보다 오류 가능성이나 읽기 어려운 부분처럼 관심사를 정하면, 돌아오는 제안도 판단하기 쉬워집니다.

"현재 변경된 코드를 검토하고, 오류가 날 수 있는 부분과 읽기 어려운 부분을 나누어 제안해 주세요."

💡 꿀팁 · 요청 끝에 “파일 이름과 이유만 요약해 주세요”를 붙이면 긴 탐색 결과를 줄일 수 있습니다.

만들기 전 확인할 주의점

서브에이전트 파일은 맨 첫 줄부터 정해진 설정 형식으로 시작해야 합니다. 이름만 있고 설명이 없거나 설정 형식을 해석하지 못하면 Claude Code는 해당 파일을 서브에이전트로 불러오지 않습니다. 파일이 안 보인다면 역할 지침부터 길게 덧붙이기보다 이름과 설명부터 확인하는 편이 빠릅니다.

이름 관리도 필요합니다. 같은 `.claude/agents/` 폴더 안에 같은 이름의 파일이 있으면 어느 하나만 불러와질 수 있고, 파일을 읽는 순서에 따라 선택될 수 있습니다. 하위 폴더로 정리하더라도 역할 이름 자체는 겹치지 않게 정하세요. `/doctor` 설정 점검은 같은 폴더의 중복 이름을 찾아 주고 이름을 바꾸거나 하나를 제거하라고 안내합니다.

설명은 짧게 쓰는 편이 좋습니다. 여러 서브에이전트의 설명이 길어지면 시작할 때 읽어야 할 내용도 늘어납니다. 세부 작업 방식과 출력 형식, 판단 기준은 설명이 아니라 해당 역할의 본문 지침에 넣는 구성이 맞습니다. 설명에는 ‘무슨 일을 언제 맡길지’만 남기면 됩니다.

권한도 확인해야 합니다. 내장 Explore처럼 읽기 전용으로 동작하는 역할도 있고, 서브에이전트마다 쓸 수 있는 도구와 권한을 다르게 정할 수 있습니다. 처음에는 필요한 도구만 허용하는 쪽이 낫습니다. 파일을 바꿀 필요가 없는 조사 역할이라면 조사와 요약에만 집중하도록 두세요.

💡 꿀팁 · 역할 이름은 `code-reviewer`처럼 한 가지 목적이 드러나게 정하고, 같은 이름은 폴더 전체에서 피하세요.

그래서 나에게 무엇이 달라질까

코드 작업에서 가장 시간을 잡아먹는 순간은 수정 자체보다 어디를 봐야 할지 모를 때입니다. 서브에이전트로 탐색과 검토를 나누면 주 대화에는 판단에 필요한 요약이 남습니다. 반복하는 점검 기준을 역할로 저장해 두면 프로젝트를 바꿔도 같은 방식으로 작업을 시작할 수 있습니다.

내일 바로 써먹기

Claude Code에서 "현재 프로젝트 구조를 읽고, 주요 폴더의 역할만 요약해 주세요"라고 요청해 Explore 방식의 탐색 결과를 먼저 받아 보세요.
반복하는 검토 일이 있다면 "~/.claude/agents/에 코드를 검토하고 개선점을 제안하는 서브에이전트를 만들어 주세요"라고 요청해 개인용 역할을 만드세요.
만든 역할이 보이지 않으면 파일의 이름과 설명을 확인하고, 새 agents 폴더를 만들었다면 Claude Code를 다시 시작하세요.

용어사전

subagent · 주 대화에서 분리한 특정 작업을 맡는 보조 AI입니다. 검색이나 검토를 처리한 뒤 핵심 결과를 돌려줍니다.
YAML frontmatter · 마크다운 파일 맨 위에 이름, 설명, 도구 같은 설정을 적는 구역입니다. 정해진 형식이 맞아야 Claude Code가 설정으로 읽습니다.
Explore · Claude Code에 기본으로 들어 있는 읽기 전용 탐색 역할입니다. 파일과 코드를 찾아보지만 파일을 수정하지는 않습니다.
CLAUDE.md · Claude Code가 프로젝트의 작업 지침으로 읽을 수 있는 파일입니다. 일부 내장 탐색 역할은 빠른 조사를 위해 이 파일을 건너뜁니다.

출처

원문: Claude Code 공식 도움말 · https://code.claude.com/docs/ko/sub-agents

함께 읽으면 좋은 글

오늘 글이 재미있으셨다면, 제 공간에도 한 번 놀러 와 주세요 🙂

제 인포크 링크 둘러보기