이 가이드로 하는 것 클로드 코드에 서브에이전트(subagent)를 만들어 연동하고, 긴 조사나 대량의 출력이 발생하는 작업을 전담 AI 직원에게 맡겨 메인 대화창의 맥락을 깔끔하게 유지하는 방법을 정리합니다.
터미널 창을 열고 작업을 진행하다 보면, 작은 조사 하나 때문에 대화창 전체가 길고 복잡한 로그와 수많은 검색 결과로 뒤덮이는 상황을 자주 마주하게 됩니다.
방대한 테스트 결과나 라이브러리 문서의 긴 내용이 작업 창을 가득 채우고 나면, 정작 본래 하려던 작업의 흐름을 놓치기 쉽습니다. 인공지능과의 대화 역시 맥락이 너무 길어지면 이전에 나눈 중요한 지시사항이나 작업의 맥락이 희미해지는 어려움을 겪습니다.
이런 상황에서 긴 탐색이나 대량의 출력이 발생하는 작업을 독립된 작업 공간에서 대신 처리하고, 핵심 결과만 요약해서 메인 대화창으로 가져다주는 방법이 있습니다.
클로드 코드(Claude Code)의 공식 기능인 서브에이전트(Subagent)입니다. 특정 작업만을 전담하는 전문 비서이자 인공지능 직원을 두고 업무를 나눠 맡기는 방식입니다.
1. 서브에이전트(Subagent)란 무엇인가 (공식 문서 기준)
공식 문서에 따르면, 서브에이전트(Subagent)는 특정한 유형의 작업을 전담하여 처리하도록 설계된 전문 AI 도우미입니다.
보조적인 작업이 수많은 검색 결과나 로그, 파일 내용 등으로 메인 대화창을 채워버리지 않도록 격리하는 것이 서브에이전트의 핵심 역할입니다. 서브에이전트는 메인 대화창과 분리된 자체적인 독립 컨텍스트 윈도우(context window) 안에서 작업을 수행하며, 작업이 모두 끝나면 그 결과 요약만을 메인 대화창에 반환합니다.
공식 문서에서 설명하는 서브에이전트의 주요 특징은 다음과 같습니다.
- 독립된 작업 공간 유지: 탐색과 중간 작업 내용이 메인 대화창으로 흘러넘치지 않도록 하여 본래 작업의 맥락을 보존합니다.
- 도구 접근 제한: 서브에이전트마다 사용할 수 있는 도구의 종류를 제한하여 안전하게 읽기 전용 작업만 수행하게 하거나 특정 명령어만 쓰도록 제한할 수 있습니다.
- 독립된 시스템 프롬프트: 특정 분야나 역할에 집중할 수 있도록 맞춤형 지침(system prompt)을 별도로 부여받아 동작합니다.
- 프로젝트 간 재사용: 컴퓨터 전역 설정에 등록해 두면 서로 다른 여러 프로젝트에서도 동일한 전담 직원을 그대로 불러와 활용할 수 있습니다.
단일 세션 안에서 동작하며, 사용자의 요청 내용과 서브에이전트의 설명문을 대조하여 적합한 작업이 들어왔을 때 클로드가 해당 서브에이전트에게 업무를 자동으로 위임합니다.
2. 서브에이전트 만들기: 클로드에게 말하기 (공식 문서 기준)
서브에이전트는 상단에 YAML 형식의 프론트매터(frontmatter)를 두고, 그 아래에 마크다운 형식의 시스템 프롬프트를 작성한 단일 마크다운(.md) 파일로 구성됩니다.
직접 파일을 작성할 수도 있지만, 가장 직관적인 방법은 클로드 코드에게 원하는 직원의 역할과 저장 위치를 대화로 설명하는 방식입니다.
1) 클로드에게 생성 요청하기
공식 문서의 빠른 시작(Quickstart) 안내에 수록된 코드 개선 전담 직원(code-improver) 생성 요청 예시는 다음과 같습니다.
Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.
이 요청은 파일들을 검사하여 가독성, 성능, 모범 사례 측면의 개선점을 제안하는 읽기 전용 서브에이전트를 사용자 폴더(~/.claude/agents/)에 만들고, 모델로 Sonnet을 지정하도록 지시하는 내용입니다.
2) 생성된 서브에이전트 파일 구조
요청을 전달하면 클로드는 name, description, tools, model, 그리고 시스템 프롬프트를 포함한 마크다운 파일을 생성합니다. 생성된 ~/.claude/agents/code-improver.md 파일의 내용은 공식 문서에 다음과 같이 정리되어 있습니다.
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.
상단의 --- 기호 사이에 위치한 프론트매터는 서브에이전트의 설정 정보를 담고 있으며, 닫는 --- 아래의 본문은 해당 직원이 따를 고유한 시스템 프롬프트가 됩니다.
서브에이전트 설정에서 반드시 포함되어야 하는 필수 항목은 고유 식별자인 name과 위임 시점을 판단하는 description 두 가지뿐입니다. 나머지 도구 목록(tools)이나 모델(model) 등은 필요에 따라 선택적으로 지정할 수 있습니다.
클로드는 각 서브에이전트의 description 필드를 읽고 언제 그 직원을 불러낼지 판단하므로, 어떤 상황에서 이 서브에이전트를 사용해야 하는지 명확하게 적어 주는 것이 중요합니다.
다만 공식 문서에 따르면 내장 서브에이전트를 제외한 등록된 서브에이전트들의 설명문 총합이 15000 토큰을 초과할 경우 클로드 코드가 시작할 때 경고 메시지를 표시합니다. 따라서 설명문은 핵심 위임 조건 위주로 간결하게 작성하고, 구체적인 지침이나 업무 절차는 시스템 프롬프트 본문에 적어 두는 방식이 권장됩니다.
3. 저장 위치와 적용 범위 (공식 문서 기준)
서브에이전트 마크다운 파일을 컴퓨터의 어느 디렉터리에 보관하느냐에 따라 해당 직원을 불러낼 수 있는 범위(Scope)가 달라집니다. 공식 문서에 명시된 주요 저장 위치와 우선순위는 다음과 같습니다.
| 위치 (Location) | 적용 범위 (Scope) | 우선순위 (Priority) | 생성 방법 (How to create) |
|---|---|---|---|
| 관리자 설정 (Managed settings) | 조직 전체 (Organization-wide) | 1 (가장 높음) | 조직 관리자 배포 |
--agents CLI 플래그 |
현재 세션 (Current session) | 2 | 세션 실행 시 JSON 전달 |
.claude/agents/ |
현재 프로젝트 (Current project) | 3 | 클로드에게 요청하거나 수동 작성 |
~/.claude/agents/ |
내 모든 프로젝트 (All your projects) | 4 | 클로드에게 요청하거나 수동 작성 |
플러그인 agents/ 디렉터리 |
플러그인이 활성화된 곳 | 5 (가장 낮음) | 플러그인 설치 |
일상적인 작업에서 주로 쓰이는 두 가지 위치는 다음과 같습니다.
- 사용자 서브에이전트 (
~/.claude/agents/): 사용자 홈 디렉터리에 위치하여 내 컴퓨터 안의 모든 프로젝트에서 공통으로 불러올 수 있는 개인 전담 직원입니다. - 프로젝트 서브에이전트 (
.claude/agents/): 특정 프로젝트 디렉터리 안에 위치하여 해당 작업 공간 안에서만 동작하는 직원입니다. 깃(Git)과 같은 버전 관리 시스템에 커밋하여 팀원들과 함께 공유하고 개선해 나갈 수 있습니다.
클로드 코드는 ~/.claude/agents/와 .claude/agents/ 폴더 내부를 재귀적으로 검색하므로, agents/review/나 agents/research/처럼 하위 폴더를 만들어 체계적으로 분류해 두어도 정상적으로 인식됩니다.
4. 서브에이전트를 호출하는 세 가지 방법 (공식 문서 기준)
등록된 서브에이전트를 호출하여 작업을 맡기는 방식은 크게 세 가지로 나뉩니다.
1) 자연어로 요청하기
프롬프트 안에 서브에이전트의 이름을 언급하면, 클로드가 문맥을 파악하여 적절한 시점에 해당 서브에이전트에게 작업을 위임합니다.
Use the code-improver agent to suggest improvements in this project
Have the code-reviewer subagent look at my recent changes
2) @ 기호로 직접 지정하여 호출하기 (골뱅이 멘션)
파일을 지정할 때처럼 대화창에 @를 입력하면 자동완성 목록에 등록된 서브에이전트들이 나타납니다. 여기서 원하는 서브에이전트를 선택하면 클로드의 자의적인 판단에 맡기지 않고 특정 직원이 확실하게 실행되도록 보장할 수 있습니다.
@"code-reviewer (agent)" look at the auth changes
키보드로 직접 타이핑할 때는 @agent-<이름> 형식을 입력하여 지정할 수도 있습니다. 이 방식은 메인 대화창에서 보낸 질문과 지시사항을 바탕으로 클로드가 해당 서브에이전트 전용 작업 프롬프트를 작성하여 전달하는 구조로 동작합니다.
3) 세션 전체를 서브에이전트로 실행하기
특정 작업에만 잠시 부르는 것이 아니라, 세션 전체를 해당 서브에이전트의 역할과 도구 제약으로 운영하고 싶다면 터미널에서 세션을 시작할 때 --agent 플래그를 넘깁니다.
claude --agent code-reviewer
프로젝트 전체에서 항상 특정 서브에이전트를 기본값으로 쓰고 싶다면 프로젝트 내 .claude/settings.json 파일에 "agent": "code-reviewer" 항목을 지정해 둘 수도 있습니다.
5. 어떤 작업에 맡기면 좋은가: 세 가지 활용 패턴 (공식 문서 기준)
서브에이전트가 가장 뛰어난 역량을 발휘하는 작업들은 공식 문서의 공통 패턴(Common patterns)에 명확히 정리되어 있습니다.
1) 방대한 출력이 발생하는 작업의 격리 (Isolate high-volume operations)
서브에이전트의 가장 효과적인 활용 사례 중 하나는 대량의 출력을 만들어내는 작업을 독립된 공간에 격리하는 것입니다.
전체 테스트를 실행하거나, 거대한 라이브러리 문서를 조회하거나, 수천 줄의 로그 파일을 분석하는 작업은 메인 대화창의 컨텍스트를 급격히 소모합니다. 이러한 작업을 서브에이전트에게 맡기면 장황한 세부 출력은 서브에이전트의 자체 공간에서만 처리되고, 메인 대화창에는 정리된 요약 보고서만 전달됩니다.
공식 문서에 소개된 대표적인 지시문 예시는 다음과 같습니다.
Use a subagent to run the test suite and report only the failing tests with their error messages
방대한 테스트 전체 결과 대신 실패한 테스트의 이름과 핵심 에러 메시지만 골라 메인 대화창으로 가져오도록 지시함으로써 대화창을 깔끔하게 유지할 수 있습니다.
2) 독립된 주제의 병렬 조사 (Run parallel research)
서로 의존성이 없는 독립적인 연구나 코드 탐색 과제라면 여러 서브에이전트를 동시에 띄워 병렬로 조사를 진행할 수 있습니다.
Research the authentication, database, and API modules in parallel using separate subagents
인증 모듈, 데이터베이스 모듈, API 모듈을 각기 다른 서브에이전트가 동시에 독립적으로 분석하고, 조사가 완료되면 클로드가 각 직원의 보고를 모아 최종 종합 분석을 사용자에게 전달합니다.
3) 순차적 연결 (Chain subagents)
다단계 작업 흐름이 필요한 경우 서브에이전트들을 순차적으로 이어붙여 작업을 완수하게 할 수도 있습니다.
Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them
먼저 코드 검토 직원이 문제점을 진단하고 그 결과를 메인 대화창에 보고하면, 클로드가 그 맥락을 최적화 담당 직원에게 전달하여 수정 작업을 진행하도록 단계를 이어갑니다.
6. 사용하기 전에 알아 둘 점 (공식 문서 기준)
서브에이전트를 실제 환경에 적용하기 전에 공식 문서에 명시된 세부 동작 규칙들을 숙지해 두는 것이 좋습니다.
1) 새 서브에이전트 생성 후 재시작이 필요한 상황
클로드 코드는 기본적으로 ~/.claude/agents/와 .claude/agents/ 폴더를 감시하고 있으므로, 세션 도중에 마크다운 파일을 추가하거나 수정하더라도 몇 초 안에 자동으로 변경 사항을 감지합니다.
하지만 세션이 처음 시작되던 시점에 ~/.claude/agents/ 폴더 자체가 디스크에 존재하지 않았던 경우라면, 실행 중인 세션이 새롭게 생성된 폴더를 자동으로 감지하지 못합니다. 이 경우에는 클로드 코드를 한 번 종료한 뒤 다시 실행해 주어야 새 서브에이전트가 정상적으로 인식됩니다.
2) 동시 실행 한도와 중첩 깊이 제한
한 세션 안에서 동시에 실행될 수 있는 서브에이전트의 기본 숫자는 최대 20개로 정해져 있습니다. 20개의 서브에이전트가 동시에 실행 중일 때 추가로 호출을 시도하면 Concurrent subagent limit reached 오류가 발생합니다.
또한 서브에이전트가 자체적으로 다른 보조 서브에이전트를 생성하여 작업을 위임하는 중첩 깊이는 기본 최대 3단계까지 허용됩니다. 이 설정값들은 환경 변수(CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH)를 통해 조정할 수 있습니다.
3) 독립된 컨텍스트 시작과 환경 정보
서브에이전트는 메인 대화창의 이전 대화 내역이나 기존에 읽었던 파일 기록을 보지 못한 채 깨끗한 상태의 새 컨텍스트 창에서 시작합니다. 클로드가 위임 시점에 작성해 주는 작업 프롬프트와 자체 시스템 프롬프트를 바탕으로 독립적으로 판단하고 움직입니다.
다만 프로젝트의 공통 규칙이 담긴 CLAUDE.md 파일 계층과 깃 저장소 상태(Git status snapshot)는 서브에이전트 시작 시 함께 전달됩니다. 만약 서브에이전트에게 프로젝트 지침 파일 전달조차 생략하고 순수하게 작업 지시문만 주고 싶다면 프론트매터에 omitClaudeMd: true 설정을 추가할 수 있습니다.
4) 이어서 작업하기(Resume)
서브에이전트는 호출될 때마다 기본적으로 새로운 인스턴스를 생성하지만, 이전에 마친 작업의 맥락을 그대로 유지한 채 추가 작업을 지시하고 싶다면 해당 서브에이전트를 다시 재개(Resume)하여 작업을 이어갈 수 있습니다.
Use the code-reviewer subagent to review the authentication module
[Agent completes]
Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]
서브에이전트가 작업을 마치면 클로드는 고유한 에이전트 식별자(agent ID)를 전달받으며, 이후 후속 지시가 내려지면 SendMessage 도구를 통해 이전 대화와 도구 호출 내역을 온전히 유지한 상태에서 작업을 이어갑니다.
복잡한 조사는 전문 AI 직원에게 맡기고 내 저녁을 지키기
우리가 터미널 앞에서 새로운 도구를 익히고 기능을 설정하는 이유는, 복잡한 인공지능 기술 그 자체를 탐닉하기 위해서가 아닙니다.
화면 가득 쏟아지는 수천 줄의 로그와 끝없는 검색 결과 사이에서 길을 잃고 헤매느라 정작 중요한 업무의 본질을 놓치고, 야근으로 이어지던 일상의 피로를 덜어내기 위해서입니다.
클로드 코드의 서브에이전트를 활용하면 내 작업 공간의 중심을 단단하게 지킬 수 있습니다. 긴 테스트나 방대한 문서 분석은 전담 AI 직원에게 조용히 넘겨두고, 우리는 핵심 요약 보고서만을 받아보며 가장 중요한 판단과 의사결정에 집중할 수 있습니다.
오늘 작업 중인 프로젝트 디렉터리나 홈 폴더에 작은 서브에이전트 하나를 정의해 보세요. 반복되는 조사업무를 AI 직원에게 믿고 맡기면서, 내 집중력과 소중한 저녁 시간을 차분하게 지켜내시길 바랍니다.
내 업무에 적용하고 싶다면
가이드를 읽고도 내 업무에 어떻게 적용할지 막막하시다면, 홈페이지 문의 폼으로 상담을 신청해 주세요. 문의 분야에서 '생성형 AI 실무 교육·특강' 또는 '기타 제휴 및 솔루션 도입'을 고르시면 됩니다.
출처 및 참고 자료
- 클로드 코드 공식 문서: Create custom subagents (https://code.claude.com/docs/en/sub-agents)
- 클로드 코드 공식 문서: Scheduled tasks and background work (https://code.claude.com/docs/en/scheduled-tasks)
