클로드코드 서브에이전트 만들기 — 나만의 AI 팀 꾸리는 법

클로드코드 서브에이전트는 특정 작업만 전담하는 별도의 AI 보조를 만들어, 본 대화와 분리된 자기만의 컨텍스트 창에서 일하게 하는 기능입니다.

2026년 7월 기준으로 보면, 서브에이전트는 코딩을 몰라도 클로드코드에 말로 시켜서 만들 수 있습니다. 결과물은 `.claude/agents/` 폴더에 마크다운 파일 하나가 생기는 게 전부입니다.

이 글을 끝까지 읽으면 서브에이전트가 뭔지, 왜 쓰는지, 그리고 직접 하나 만들어 호출하는 방법까지 손에 잡힙니다.

지침·스킬 편과 이어지는 클로드코드 생태계 연작의 세 번째 글입니다.

서브에이전트는 별도 컨텍스트 창에서 도는 독립 전문가입니다. 장황한 출력을 본 대화에서 격리하거나, 특정 도구만 쓰게 제한하고 싶을 때 씁니다. 만드는 가장 쉬운 방법은 클로드코드에 말로 시키는 것입니다.

서브에이전트가 뭔가요?

서브에이전트는 특정 종류의 작업을 전담하는 전문 AI 보조입니다.

비유하자면, 회사의 한 부서에 그 일만 잘하는 전문가를 한 명 채용하는 것과 비슷합니다.

검색이나 로그 확인, 파일 뒤지기 같은 곁다리 작업이 본 대화를 어지럽힐 때, 그 일을 다른 방으로 보내 처리하고 요약만 받아오는 구조입니다.

핵심은 각 서브에이전트가 자기만의 컨텍스트 창을 가진다는 점입니다.

여기에 커스텀 시스템 프롬프트, 지정된 도구 접근 권한, 독립된 실행 권한이 더해집니다.

클로드는 지금 하려는 작업이 어떤 서브에이전트의 설명과 맞으면 그 일을 위임하고, 서브에이전트는 혼자 일한 뒤 결과를 돌려줍니다.

Anthropic 공식 문서(code.claude.com/docs)가 2026년 7월 기준으로 정리한 정의가 바로 이것입니다.

왜 굳이 서브에이전트를 쓸까

AI 하나에 모든 걸 얹으면 금방 한계가 옵니다.

커뮤니티에는 "위에서 준 지시를 잊고, 질문 하나에 파일 30개를 읽다가 왜 시작했는지도 잊는다"는 후기가 반복해서 올라옵니다.

역할을 나누는 것이 그 해법으로 자주 언급됩니다.

Anthropic 공식 문서가 밝힌 서브에이전트의 이점은 다섯 가지입니다.

이점	무슨 뜻인가
컨텍스트 보존	탐색·구현을 본 대화 밖으로 빼서 메인 대화가 지저분해지지 않게 한다
제약 강제	서브에이전트가 쓸 수 있는 도구를 제한한다 (읽기 전용 리뷰어 등)
설정 재사용	한 번 만든 서브에이전트를 여러 프로젝트에서 다시 쓴다
행동 특화	특정 도메인에 집중된 시스템 프롬프트로 좁고 깊게 일하게 한다
비용 관리	가벼운 작업은 Haiku 같은 빠르고 저렴한 모델로 돌린다

여기에 하나 더, 여러 서브에이전트를 동시에 돌리는 병렬 실행도 가능합니다.

인증·DB·API 모듈을 각각 별도 서브에이전트로 나눠 한꺼번에 조사시키는 식입니다.

개인적으로는 이 "컨텍스트 격리"가 가장 큰 이유라고 봅니다. AI가 한 가지에만 집중할 환경을 만들어주면 결과의 안정성이 확실히 올라갑니다.

직접 만들어 보기 — 3단계

말로만 들으면 막연하니, 직접 하나 만들어 보겠습니다.

서브에이전트는 결국 `.claude/agents/` 폴더 안의 마크다운 파일 하나입니다.

Step 1. 말로 시키기 (가장 쉬운 길)

클로드코드에 원하는 서브에이전트를 문장으로 요청하는 방법입니다.

예를 들어 이렇게 말하면 됩니다.

"~/.claude/agents/에 코드 개선 서브에이전트를 만들어줘. 파일을 읽고 가독성·성능·베스트프랙티스를 제안하고, 읽기 전용에 Sonnet을 쓰게 해줘."

그러면 클로드가 이름·설명·도구·모델·시스템 프롬프트를 갖춘 파일을 대신 써줍니다.

✅ 성공 기준: `.claude/agents/` 안에 새 마크다운 파일이 생기고, 열어보면 요청한 내용이 프론트매터에 반영되어 있으면 됩니다.

⚠️ 안 되면: 파일이 안 보인다면 폴더가 세션 시작 전에 없었을 가능성이 큽니다. 아래 "자주 막히는 부분"을 보세요.

Step 2. 파일 직접 쓰기

구조를 이해하고 싶다면 파일을 직접 만드는 것도 어렵지 않습니다.

맨 위 YAML 프론트매터에 설정을 적고, 그 아래 본문이 곧 시스템 프롬프트가 됩니다.

공식 문서의 코드 리뷰어 예시는 이렇게 생겼습니다.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

필수 항목은 name과 description 둘뿐입니다.

name은 소문자와 하이픈으로 된 고유 이름이고, description은 "언제 이 서브에이전트에 일을 맡길지"를 적는 칸입니다.

tools는 허용할 도구 목록인데, 적지 않으면 본 대화의 모든 도구를 그대로 물려받습니다.

model은 생략하면 본 대화와 같은 모델을 씁니다.

✅ 성공 기준: 파일을 저장하고 몇 초 뒤 서브에이전트 목록에 이름이 뜨면 됩니다.

Step 3. 불러 쓰기

만든 서브에이전트를 실제로 호출하는 방법은 세 가지입니다.

첫째, 자연어로 "code-reviewer 서브에이전트로 내 최근 변경을 봐줘"라고 하면 클로드가 위임 여부를 판단합니다.

둘째, `@`를 치고 타입어헤드에서 서브에이전트를 고르면 그 서브에이전트가 반드시 실행됩니다.

셋째, 세션 전체를 그 서브에이전트로 돌리려면 `claude --agent code-reviewer`처럼 시작하면 됩니다.

✅ 성공 기준: 위임이 일어나면 "그 서브에이전트가 일하는 중"이라는 표시가 뜨고, 끝나면 요약 보고가 본 대화로 돌아옵니다.

---

팁과 함정 — 여기서 자주 넘어진다

몇 가지만 알아두면 헛수고를 크게 줄일 수 있습니다.

가장 중요한 것은 description이 위임의 전부라는 점입니다.

클로드는 오직 이 설명 문장만 보고 일을 맡길지 정합니다.

구체적으로 쓰고, 알아서 나서주길 원하면 "use proactively" 같은 문구를 넣으라고 공식 문서는 안내합니다.

다음은 tools 필드의 함정입니다.

tools를 생략하면 전체 도구를 상속하고, 읽기·검색만 시키려면 `tools: Read, Grep, Glob`처럼 화이트리스트로 좁혀야 합니다.

주의할 점이 하나 있습니다. tools에 적은 이름이 오타 등으로 실제 도구와 하나도 안 맞으면, 최신 버전에서는 서브에이전트가 아예 실행에 실패하고 에러를 냅니다.

사실 이 블로그도 예전에 tools 필드를 잘못 써서 도구가 하나도 안 붙는 바람에, 서브에이전트가 조기 종료하는 사고를 겪은 적이 있습니다.

개인적으로는 리뷰어나 리서처처럼 파일을 쓸 일이 없는 역할이라면 `disallowedTools: Write, Edit`로 쓰기를 아예 막아두는 편이 마음이 편하다고 생각합니다.

못 쓰는 서브에이전트는 실수로도 덮어쓸 수 없기 때문입니다.

지침·스킬·서브에이전트, 뭐가 다른가

이 셋은 자주 헷갈리지만 역할이 분명히 다릅니다.

연작 1편에서 다룬 지침(CLAUDE.md)은 항상 지켜야 할 규칙이고, 2편의 스킬은 필요할 때 꺼내는 작업 레시피이며, 이번 서브에이전트는 별도 방에서 일하는 독립 전문가입니다.

구분	실행 위치	언제 쓰나
지침(CLAUDE.md)	메인 대화에 상시 주입	톤·금지사항 등 늘 적용할 규칙
스킬(Skill)	메인 대화 컨텍스트 안	재사용 프롬프트·워크플로를 본 대화 맥락에서
서브에이전트(Agent)	격리된 자기 컨텍스트	장황한 출력 격리·도구 제한·자기완결 작업

공식 문서의 기준도 같습니다.

재사용 프롬프트를 본 대화 안에서 돌리고 싶으면 스킬을, 격리된 컨텍스트가 필요하면 서브에이전트를 쓰라는 것입니다.

 

이 블로그도 서브에이전트 팀으로 굴러갑니다

서브에이전트 팀이 실제로 어떻게 돌아가는지, 이 블로그가 좋은 예입니다.

지금 읽고 있는 이 글도 세 개의 서브에이전트가 만든 결과물입니다.

리서처가 공식 문서에서 팩트를 모으고, 작성자가 그 자료로 초안을 쓰고, 검증자가 규칙 위반이 없는지 체크리스트로 잡아냅니다.

아무도 혼자 다 하려 하지 않으니, 아무것도 놓치지 않는 구조입니다.

여러 편을 만들 때는 이 팀을 병렬로 여러 세트 돌리기도 합니다.

더 자세한 구축 과정은 이 블로그의 자동화 구축기 글에 정리해 두었습니다.

자주 막히는 부분

만들다 보면 걸리는 지점이 몇 군데 있습니다.

새로 만든 서브에이전트가 안 잡혀요

`~/.claude/agents/` 폴더가 세션 시작 전에 없었다면 새 서브에이전트가 감지되지 않습니다.

이때는 클로드코드를 재시작하면 됩니다. 폴더가 원래 있었다면 몇 초 안에 자동으로 잡히니 재시작이 필요 없습니다.

서브에이전트가 나한테 질문을 못 해요

맞습니다. 서브에이전트는 사용자와 직접 대화하지 못합니다.

질문형 도구(AskUserQuestion 등)는 서브에이전트에서 작동하지 않고, 결과는 요약 보고로 본 대화에 돌아옵니다.

/agents 명령을 쳤는데 마법사가 안 떠요

클로드코드 버전에 따라 동작이 다릅니다.

비교적 최신 버전에서는 `/agents`가 생성 마법사를 열지 않고, 직접 편집하거나 클로드에게 만들어 달라고 하라는 안내만 보여줍니다. 그래서 이 글은 "말로 시키기"와 "파일 직접 쓰기"를 주 경로로 안내했습니다. 정확한 UI 동작은 발행 전 사용 중인 버전 기준으로 다시 확인하는 편이 좋습니다.

자주 묻는 질문

서브에이전트랑 스킬이랑 뭐가 다른가요?

스킬은 본 대화 안에서 도는 작업 레시피이고, 서브에이전트는 별도 컨텍스트 창에서 도는 독립 실행 전문가입니다.

장황한 출력을 격리하거나 도구를 제한하고 싶으면 서브에이전트, 그냥 재사용 프롬프트면 스킬입니다.

서브에이전트를 만들려면 코딩을 알아야 하나요?

아니요. 클로드코드에 "○○하는 서브에이전트 만들어줘"라고 말로 시키면 파일을 자동으로 써줍니다.

`.claude/agents/` 폴더에 마크다운 파일 하나가 생기는 게 전부라, 문법을 외울 필요는 없습니다.

tools를 안 적으면 어떻게 되나요?

생략하면 본 대화의 모든 도구를 그대로 상속합니다.

읽기 전용으로 안전하게 쓰려면 `tools: Read, Grep, Glob`처럼 허용 목록을 직접 지정하세요.

결론

서브에이전트는 "AI 한 명에게 다 시키지 않는다"는 발상의 전환입니다.

역할별로 전문가를 두면 각자 자기 컨텍스트에 집중하고, 그만큼 결과가 안정됩니다.

오늘은 말로 시키기 하나만 따라 해봐도 충분합니다. 코드 리뷰어든 리서처든, 자주 하는 일 하나를 서브에이전트로 떼어내 보세요.

다음 편에서는 여러 서브에이전트와 스킬, 명령을 하나로 묶어 배포하는 플러그인 활용을 다룹니다.

공식 서브에이전트 문서에서 프론트매터 필드 전체와 최신 동작을 확인할 수 있습니다.

📄 클로드코드 서브에이전트 공식 문서 보기 →

 

---