Claude 가이드

클로드 에이전트 만들기: 서브에이전트 파일 하나로 시작하는 법

클로드 에이전트는 두 가지로 써요. Claude 앱에서는 원하는 결과를 설명해 일을 통째로 맡기고, Claude Code에서는 역할을 적은 파일 하나로 나만의 서브에이전트를 만들어요. 이 글은 서브에이전트를 만들고 저장하고 부르는 순서, 스킬·에이전트 팀과의 차이를 안내해요.

유튜브 「메이커 에반」을 만드는 스킬샵 운영자
9분 읽기
메인 대화가 조사, 검토, 테스트 서브에이전트에게 일을 나눠 맡기고 요약만 돌려받는 그림
이 글에서 다루는 내용
  1. 클로드 에이전트는 무엇을 가리키나요?
  2. 코딩 없이 일을 맡기려면 어떻게 하나요?
  3. 서브에이전트는 무엇이고 왜 쓰나요?
  4. 첫 서브에이전트는 어떻게 만드나요?
  5. 파일은 어디에 두고 무엇을 적나요?
  6. 만든 서브에이전트는 어떻게 부르나요?
  7. 스킬, 서브에이전트, 에이전트 팀은 어떻게 다른가요?
  8. 서브에이전트가 안 불릴 때는 무엇을 확인하나요?
  9. 언제는 쓰지 않는 편이 좋나요?
  10. 자주 묻는 질문
  11. 참고 자료

클로드 에이전트는 무엇을 가리키나요?

‘클로드 에이전트’라는 말은 여러 가지를 가리켜요. 가장 넓게는 클로드가 답만 하지 않고 파일을 읽고 도구를 쓰면서 여러 단계의 일을 스스로 진행하는 것을 뜻해요. Claude 앱에 일을 통째로 맡기는 것도, Claude Code에서 역할별 서브에이전트를 두는 것도 여기에 들어가요.

처음이라면 두 갈래만 기억해 주세요. 코딩 없이 문서와 자료 작업을 맡기려면 Claude 앱, 반복하는 작업에 전담 역할을 만들어 두려면 Claude Code의 서브에이전트예요. 에이전트 팀과 에이전트 뷰는 그다음에 살펴봐도 늦지 않아요.

방법어떤 것인가요상태
Claude 앱에 맡기기대화에서 원하는 결과를 설명하면 클로드가 단계를 나눠 처리해요. 예전의 코워크가 채팅과 합쳐졌어요유료 요금제에 순차 적용 중
서브에이전트Claude Code 한 세션 안에서 따로 일하고 요약만 돌려주는 작업자예요기본 제공
에이전트 뷰백그라운드 세션 여러 개를 한 화면에서 맡기고 지켜봐요연구 미리보기
에이전트 팀여러 세션이 작업 목록을 나누고 서로 메시지를 보내요실험적, 기본 꺼짐
Agent SDK같은 에이전트 기능을 Python과 TypeScript 코드로 내 앱에 넣어요개발자용
Claude Code 공식 문서와 Anthropic 안내 기준이에요(2026년 11월 확인).
Claude Code 한국어 문서의 ‘에이전트를 병렬로 실행하기’ 표다. 서브에이전트, 에이전트 뷰, 에이전트 팀, 프로젝트, 동적 워크플로우를 제공되는 기능과 사용 시기로 비교하고, 에이전트 팀이 실험적이며 기본적으로 비활성화돼 있다고 적혀 있다.
공식 문서의 비교표예요. 최신 상태는 연결된 공식 안내에서 확인해 주세요.출처: 클로드 코드 공식 문서 · 에이전트를 병렬로 실행하기

코딩 없이 일을 맡기려면 어떻게 하나요?

Claude 앱의 대화에 원하는 결과를 적으면 돼요. Anthropic은 2026년 9월 16일에 코워크와 채팅을 하나로 합쳤다고 발표했어요. 새 환경에서는 모드를 고르지 않아도 클로드가 웹을 검색하고, 파일을 읽고, 코드를 실행해 결과를 엮어요. 문서, 수식이 들어간 스프레드시트, 발표 자료 같은 완성된 파일로 돌려받을 수 있어요.

이 환경은 Pro, Max, Ultra 요금제에 순서대로 적용되고 있고, Team과 Enterprise는 조직 설정에 따라 달라요. 오래 걸리는 작업은 노트북을 닫아도 클라우드에서 계속 진행돼요. 내 컴퓨터의 폴더나 앱을 쓰는 작업은 Claude 데스크톱 앱이 열려 있어야 해요. 입력창의 권한 설정에서 클로드가 단계마다 물어볼지(수동), 안전 검사를 거치며 이어서 진행할지(자동) 고를 수 있어요.

결과를 설명해요인터뷰 메모 다섯 개에서 주제를 뽑아 줘
클로드가 단계를 나눠요검색, 파일 읽기, 코드 실행
파일로 돌려받아요문서, 스프레드시트, 발표 자료
검토하고 고쳐요같은 대화에서 수정을 요청해요
Claude 앱에서는 모드를 고르지 않고 원하는 결과부터 적어요.

서브에이전트는 무엇이고 왜 쓰나요?

서브에이전트는 특정 종류의 작업을 맡는 전담 작업자예요. Claude Code 공식 문서에 따르면 서브에이전트는 자기만의 컨텍스트 윈도우에서 일하고 요약만 돌려줘요. 검색 결과나 로그처럼 다시 볼 일이 없는 내용이 메인 대화를 가득 채우는 일을 막아 줘요.

Claude Code에는 이미 내장 서브에이전트가 있어요. 읽기 전용으로 파일과 코드를 찾는 Explore, 계획을 세우기 전에 자료를 모으는 Plan, 여러 단계 작업을 맡는 General-purpose예요. 여기에 내 작업에 맞는 서브에이전트를 더할 수 있어요. 도구를 제한해 읽기만 하게 하거나, 가벼운 작업은 더 빠른 모델로 보낼 수 있어요.

메인 대화에서 직접 할 때
  • 읽은 파일과 검색 결과가 대화에 쌓여요
  • 주고받으며 다듬는 작업에 좋아요
  • 여러 단계가 같은 맥락을 써요
서브에이전트에 맡길 때
  • 따로 일하고 요약만 돌아와요
  • 쓸 수 있는 도구를 제한할 수 있어요
  • 독립된 작업을 나눠 맡기기 좋아요
출력이 길고 독립적인 작업일수록 서브에이전트가 맞아요.

첫 서브에이전트는 어떻게 만드나요?

서브에이전트는 맨 위에 설정을 적은 Markdown 파일 하나예요. 직접 쓸 수도 있지만, 공식 문서의 빠른 시작은 Claude에게 만들어 달라고 요청하는 방법을 안내해요. Claude Code에서 어떤 서브에이전트를 원하는지와 저장할 위치를 말로 설명하면 클로드가 이름, 설명, 도구 목록, 모델, 지침이 들어간 파일을 써 줘요.

파일이 만들어지면 열어서 요청한 내용과 맞는지 확인하고, 이름을 불러 한 번 시켜 보세요. 클로드가 새 서브에이전트를 찾지 못하면 Claude Code를 다시 시작해요. 참고로 지금 ‘/agents’ 명령은 만들기 화면을 열지 않아요. 클로드에게 요청하거나 파일을 직접 고치라는 안내만 보여 줘요.

Claude Code에 입력하는 요청 예시
~/.claude/agents/ 에 draft-reviewer 라는 개인용 서브에이전트를 만들어 줘.
글 초안 파일을 읽고 어색한 문장, 사실 확인이 필요한 부분, 빠진 내용을 찾아 목록으로 알려 주는 역할이야.
파일은 고치지 말고 읽기만 하게 하고, 모델은 Sonnet을 써 줘.
만들어지는 파일 예시: ~/.claude/agents/draft-reviewer.md
---
name: draft-reviewer
description: 글 초안을 읽고 어색한 문장, 사실 확인이 필요한 부분, 빠진 내용을 찾아 알려 줘요. 초안 검토를 요청받으면 사용해요.
tools: Read, Grep, Glob
model: sonnet
---

너는 글 초안을 검토하는 편집자야. 파일을 고치지 말고 읽기만 해.
문제를 찾으면 해당 문장을 인용하고, 왜 문제인지와 고친 문장을 함께 적어 줘.
마지막에 가장 먼저 고칠 세 가지를 요약해 줘.
STEP 1말로 요청해요역할, 저장 위치, 읽기 전용 여부, 모델을 적어요.
STEP 2파일을 확인해요이름, 설명, 도구, 모델이 요청과 맞는지 봐요.
STEP 3이름을 불러 시켜요draft-reviewer 서브에이전트로 이 초안을 검토해 줘.
공식 문서 빠른 시작의 세 단계예요.

파일은 어디에 두고 무엇을 적나요?

저장 위치가 쓰임새를 정해요. 프로젝트 폴더의 .claude/agents/ 에 두면 그 프로젝트에서만 쓰고, 저장소에 함께 올리면 팀이 같이 써요. 내 컴퓨터의 ~/.claude/agents/ 에 두면 모든 프로젝트에서 쓸 수 있어요. 같은 이름이 여러 곳에 있으면 우선순위가 높은 쪽이 쓰이는데, 프로젝트가 개인 폴더보다 앞서요.

파일 맨 위 ‘---’ 사이에는 설정을 적고, 그 아래에는 서브에이전트가 따를 지침을 적어요. 꼭 필요한 항목은 name과 description 두 가지예요. description은 클로드가 언제 이 서브에이전트에게 일을 넘길지 판단하는 근거라서, 어떤 요청에 쓰는지 평소 쓰는 말로 적는 것이 중요해요. 파일을 고치면 몇 초 안에 반영돼요.

항목필수무엇을 적나요
name예서브에이전트의 고유한 이름. 콜론(:)은 쓸 수 없어요
description예클로드가 언제 이 서브에이전트에 맡길지 판단하는 설명
tools아니요쓸 수 있는 도구 목록. 비우면 쓸 수 있는 도구를 모두 물려받아요
model아니요sonnet, opus, haiku 같은 모델. 비우면 Claude Code가 정해요
skills아니요시작할 때 미리 읽혀 둘 스킬 이름
공식 문서 Frontmatter 참조에서 처음에 쓸 다섯 가지만 골랐어요.
  • my-project
  • .claude
  • agents이 프로젝트에서만 써요
  • draft-reviewer.md서브에이전트 하나가 파일 하나
  • skills스킬은 여기에 따로 둬요
프로젝트용 서브에이전트는 .claude/agents/ 아래에 둬요. 개인용은 ~/.claude/agents/ 예요.
Claude Code 한국어 문서의 ‘서브에이전트 범위 선택’ 표다. 관리형 설정, --agents CLI 플래그, .claude/agents/, ~/.claude/agents/, 플러그인의 agents/ 디렉터리가 범위와 우선순위 1부터 5까지로 정리돼 있다.
공식 문서의 저장 위치와 우선순위 표예요.출처: 클로드 코드 공식 문서 · 서브에이전트 범위 선택

만든 서브에이전트는 어떻게 부르나요?

가만히 두어도 클로드가 알아서 넘겨요. 클로드는 요청 내용과 서브에이전트의 description, 지금 대화의 맥락을 보고 위임할지 정해요. 그래서 설명이 구체적일수록 잘 불려요.

직접 부르는 방법은 세 가지예요. 요청에 서브에이전트 이름을 적으면 클로드가 보통 넘겨요. ‘@’를 입력해 목록에서 고르면 그 작업을 그 서브에이전트가 맡도록 지시해요. 세션 전체를 한 서브에이전트로 시작하려면 터미널에서 ‘claude --agent 이름’으로 실행해요.

이름을 적어 요청하기
draft-reviewer 서브에이전트로 guide.md 초안을 검토해 줘
@로 지정하기
@agent-draft-reviewer guide.md 초안을 검토해 줘
세션 전체를 서브에이전트로 시작하기 (터미널)
claude --agent draft-reviewer
자동 위임기본요청과 description이 맞으면 클로드가 넘겨요
이름 언급가볍게요청 문장에 서브에이전트 이름을 적어요
@ 멘션확실하게이 작업은 이 서브에이전트가 하도록 지시해요
--agent세션 전체세션을 그 서브에이전트의 도구와 모델로 시작해요
아래로 갈수록 더 강하게 지정하는 방법이에요.

스킬, 서브에이전트, 에이전트 팀은 어떻게 다른가요?

스킬은 작업 방법이고, 서브에이전트는 그 일을 따로 맡는 작업자예요. 스킬은 메인 대화의 맥락 안에서 불려 와 순서와 기준을 알려 줘요. 서브에이전트는 별도의 컨텍스트에서 일하고 요약만 돌려줘요. 공식 문서도 메인 대화에서 실행되는 재사용 가능한 워크플로가 필요하면 스킬을 고려하라고 안내해요.

둘은 함께 쓸 수 있어요. 서브에이전트 파일의 skills 항목에 스킬 이름을 적으면, 그 스킬의 전체 내용이 시작할 때 서브에이전트에 미리 주입돼요. 에이전트 팀은 한 단계 더 나아가 여러 세션이 작업 목록을 나누고 서로 메시지를 주고받는 방식인데, 아직 실험적 기능이고 기본으로 꺼져 있어요. 단일 세션보다 토큰을 훨씬 많이 쓰니 서브에이전트로 부족할 때 검토해 보세요.

서브에이전트에 스킬 미리 읽히기
---
name: report-writer
description: 주간 보고서 초안을 팀 형식에 맞춰 작성해요.
skills:
  - weekly-report-format
---

미리 읽은 스킬의 형식과 순서를 따라 보고서 초안을 작성해.
구분스킬서브에이전트에이전트 팀
무엇인가요작업 방법을 적은 지침과 자료따로 일하는 전담 작업자서로 소통하는 여러 세션
일하는 곳메인 대화의 컨텍스트자기만의 컨텍스트세션마다 독립된 컨텍스트
결과대화 안에서 바로 이어져요요약만 메인 대화로 돌아와요팀원끼리 직접 메시지를 보내요
상태기본 제공기본 제공실험적, 기본 꺼짐
Claude Code 공식 문서 기준으로 정리했어요.

서브에이전트가 안 불릴 때는 무엇을 확인하나요?

먼저 파일이 읽혔는지 확인해요. 공식 문서에 따르면 Claude Code는 형식에 문제가 있는 파일을 건너뛰어요. name이 없으면 문서로 취급하고, description이 없거나 YAML을 해석할 수 없으면 건너뛰어요. 여는 ‘---’가 파일의 첫 줄이 아니어도 설정이 없는 파일로 읽어요.

파일은 읽혔는데 자동으로 불리지 않는다면 description을 고칠 차례예요. 어떤 요청에 쓰는지 실제로 쓰는 말로 적고, ‘@’로 직접 지정했을 때는 되는지 비교해 보세요. 원인을 더 보려면 터미널에서 ‘claude --debug’로 실행해 디버그 로그를 확인해요.

  • 여는 ‘---’가 파일의 첫 줄에 있나요?
  • name과 description이 둘 다 있나요?
  • name에 콜론(:)이 들어가거나 ‘-’로 시작하지 않나요?
  • 같은 이름의 서브에이전트가 다른 폴더에 또 있지 않나요?
  • ‘@’로 직접 지정하면 실행되나요?

언제는 쓰지 않는 편이 좋나요?

모든 일을 나눠 맡길 필요는 없어요. 공식 문서는 자주 주고받으며 다듬는 작업, 계획과 구현과 테스트처럼 단계들이 같은 맥락을 쓰는 작업, 빠르고 목표가 분명한 수정은 메인 대화에서 하라고 안내해요. 서브에이전트는 처음부터 새로 시작하기 때문에 맥락을 모으는 데 시간이 들어요.

비용도 살펴봐 주세요. 서브에이전트의 요청은 메인 대화와 같은 사용량 한도에서 차감되고, 여러 개를 동시에 돌리면 토큰 사용량이 배로 늘어요. Claude Code는 모든 유료 요금제에 포함되고 채팅과 한도를 함께 써요. 서브에이전트 하나를 만들어 실제 작업에 몇 번 써 본 뒤에 늘려 가세요.

자주 묻는 질문

클로드 에이전트를 만들려면 코딩을 할 줄 알아야 하나요?

서브에이전트는 Markdown 파일 하나라서 코드를 쓰지 않아도 돼요. Claude Code에서 원하는 역할과 저장 위치를 말로 설명하면 클로드가 파일을 써 줘요. 터미널이 낯설다면 Claude 앱의 대화에서 원하는 결과를 설명해 일을 맡기는 방법부터 써 보세요.

서브에이전트와 스킬은 무엇이 다른가요?

스킬은 작업 방법을 적은 지침이고 메인 대화의 맥락에서 실행돼요. 서브에이전트는 별도의 컨텍스트에서 일하고 요약만 돌려주는 작업자예요. 서브에이전트의 skills 항목에 스킬을 적어 함께 쓸 수도 있어요.

서브에이전트를 쓰면 사용량이 더 드나요?

서브에이전트의 요청도 메인 대화와 같은 사용량 한도로 계산돼요. 여러 서브에이전트를 동시에 실행하면 토큰 사용량이 배로 늘어요. 대신 긴 검색 결과나 로그가 메인 대화에 쌓이지 않아 대화를 길게 이어 가기 좋아요.

서브에이전트가 다른 서브에이전트를 부를 수 있나요?

공식 문서 기준으로 기본값에서는 메인 대화 아래 세 계층까지 부를 수 있어요. 특정 서브에이전트가 다른 서브에이전트를 부르지 못하게 하려면 그 파일의 tools 목록에서 Agent를 빼요.

클로드 코워크는 어디로 갔나요?

Anthropic은 2026년 9월 16일에 코워크와 채팅을 하나의 Claude로 합쳤다고 발표했어요. 새 환경이 적용된 계정에서는 ‘Chat’과 ‘Cowork’을 고르는 버튼 없이 어느 대화에서나 일을 통째로 맡길 수 있어요. 기존 코워크 작업과 설정은 그대로 이어져요.

참고 자료