가이드 · 2026년 10월 29일

Claude Code 서브에이전트 만들기 — .claude/agents 파일 하나로 '전담 직원' 두는 법

Q: 서브에이전트를 만들려면 꼭 /agents 명령을 써야 하나요?

아니다. .claude/agents/ 나 ~/.claude/agents/ 에 마크다운 파일을 직접 만들면 된다. 공식 문서에 따르면 최근 버전의 /agents 는 "Claude에게 부탁하거나 폴더를 직접 고치라"는 안내를 보여 주고, 예전 버전은 만들기·고치기 화면을 열었다.

Q: Claude Code에 처음부터 들어 있는 서브에이전트도 있나요?

있다. 읽기 전용으로 빠르게 코드를 찾는 Explore , plan 모드에서 조사하는 Plan , 여러 단계 일을 하는 general-purpose 등이다. Explore 는 Write·Edit가 막혀 있다.

Q: 같은 이름의 에이전트가 프로젝트와 내 폴더에 둘 다 있으면요?

우선순위가 높은 쪽, 즉 프로젝트의 .claude/agents/ 것이 쓰인다(위 표 3번이 4번보다 먼저).

Claude Code 서브에이전트는 마크다운 파일 하나다. 어디에 두는지, name·description·tools·model 같은 머리 항목이 무엇을 정하는지, Claude가 언제 알아서 맡기는지, 하이아이오가 실제로 쓰는 14명 중 '전령' 파일을 예로 정리했다.

한눈에 보기

Claude Code 서브에이전트는 YAML 머리말이 달린 마크다운 파일이고, 본문이 그 에이전트의 시스템 프롬프트가 된다. 프로젝트용은 .claude/agents/, 모든 프로젝트용은 ~/.claude/agents/ 에 둔다. 꼭 필요한 항목은 name과 description 두 개이고, tools를 빼면 쓸 수 있는 도구를 모두 물려받는다. Claude는 description을 보고 언제 맡길지 정하므로 'use proactively' 같은 말을 넣으면 더 자주 맡긴다. 서브에이전트는 자기 컨텍스트 창에서 일하고 요약만 돌려주기 때문에 긴 검색·게시 같은 일을 맡기면 본 대화가 덜 어지럽다.

Claude Code 한국어 실전 가이드 · 4/10편

결론부터. 서브에이전트는 "이 일은 이 사람한테"를 파일 하나로 적어 두는 것이다. 마크다운 파일 하나에 이름·언제 맡길지·쓸 수 있는 도구를 적으면, Claude Code가 그 일이 나올 때 알아서 넘긴다. 이 글은 AI(Claude)가 썼고, 내용은 Claude Code 공식 문서 — Subagents와 대조했다. 하이아이오는 1인 앱 스튜디오 일을 디자인·카피·SNS 게시 등 서브에이전트 14개로 나눠 돌리고 있다.

서브에이전트가 뭐가 좋은가

공식 문서의 설명은 이렇다. 서브에이전트는 자기 컨텍스트 창에서, 자기 시스템 프롬프트·도구·권한으로 일한다. 본 대화 기록은 보지 않고 Claude가 써 준 지시문만 받아 일하며, 끝나면 요약만 돌려준다.

그래서 이런 일에 맞는다.

파일을 수십 개 뒤지는 검색 — 긴 결과가 본 대화에 쌓이지 않는다
늘 같은 규칙으로 하는 일 — 규칙을 매번 다시 말하지 않아도 된다
도구를 좁혀야 하는 일 — 예: 읽기만 하는 검토 담당

파일은 어디에 두나

위치	범위	우선순위
관리자 설정(managed settings)	조직 전체	1 (가장 높음)
`--agents` 실행 옵션	이번 세션	2
`.claude/agents/`	이 프로젝트	3
`~/.claude/agents/`	내 모든 프로젝트	4
플러그인의 `agents/` 폴더	그 플러그인을 켠 곳	5

같은 이름이 여러 곳에 있으면 우선순위가 높은 쪽이 쓰인다. 폴더 안에 하위 폴더를 만들어도 찾아 주고, 에이전트를 구분하는 건 파일 경로가 아니라 name 값이다.

파일 모양

---
name: code-reviewer
description: 코드 품질을 검토한다. Use proactively when 코드를 고친 뒤.
tools: Read, Glob, Grep
model: sonnet
---

너는 코드 검토 담당이다. 바뀐 코드를 읽고 고칠 점을 구체적으로 적는다.

--- 사이가 머리말이고, 그 아래 본문이 이 에이전트의 시스템 프롬프트가 된다.

꼭 알아야 할 항목

항목	정하는 것	빼면
`name`	이름(필수). `:`는 못 쓴다	—
`description`	언제 맡길지(필수)	—
`tools`	쓸 수 있는 도구 목록	쓸 수 있는 도구를 모두 물려받음
`disallowedTools`	빼고 싶은 도구	—
`model`	`sonnet`·`opus`·`haiku`·`fable`·모델 ID·`inherit`	정해진 순서로 고름(아래)
`permissionMode`	권한 모드	—
`memory`	기억을 둘 범위(`user`·`project`·`local`)	—

이 밖에도 maxTurns·skills·mcpServers·hooks·effort·isolation(worktree)·background·color 등이 있다. 공식 문서가 경고하는 함정 하나: 항목 이름을 틀리게 쓰면 오류 없이 무시된다. 여러 단어 이름은 disallowedTools처럼 camelCase로 쓴다.

모델은 ① Claude가 맡길 때 따로 정한 모델 → ② 머리말의 model(inherit면 본 대화 모델) → ③ 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL → ④ 본 대화 모델 순서로 정해진다.

Claude는 언제 맡기나

공식 문서: Claude는 각 서브에이전트의 description을 보고 언제 맡길지 정한다. 알아서 자주 맡기게 하려면 description에 "use proactively" 같은 말을 넣으라고 한다. 대신 description을 너무 길게 쓰면 안 된다. 모든 에이전트의 description을 합쳐 15,000토큰이 넘으면 시작할 때 경고가 뜬다.

직접 부르는 법도 있다.

말로: "test-runner 서브에이전트로 실패하는 테스트 고쳐 줘"
@로: @"code-reviewer (agent)" 로그인 바뀐 부분 봐 줘
세션 전체를: claude --agent code-reviewer

우리 파일 예: '전령'

하이아이오의 SNS 게시 담당 jeollyeong(전령) 파일 머리말이다(도구 목록은 줄였다).

---
name: jeollyeong
description: 전령(SNS 게시 담당). Use proactively when 완성된 원고를 스레드·X·인스타·링크드인·틱톡·GeekNews에 실제로 올리거나, 큐를 처리하거나, 게시 링크를 기록할 때. 원고 작성·일정은 sns-manager, 헤드라인은 copywriter. 전령은 글을 고치지 않고 정확히 옮긴다.
tools: Read, Grep, Glob, Bash, Edit, mcp__claude-in-chrome__navigate, ...
model: inherit
memory: project
---

써 보며 정한 것 세 가지.

description에 '하지 않는 일'과 '그건 누구 일'을 같이 쓴다. "원고 작성은 sns-manager"처럼 적어 두니 비슷한 에이전트끼리 일이 겹치지 않았다.
tools는 꼭 필요한 것만. 전령은 글을 올리기만 하니 Write를 뺐다. 원고를 고칠 수단이 없으니 "받은 글 그대로"가 지켜진다.
공통 규칙은 파일 하나로 빼고 본문 첫 줄에서 읽게 한다. 14개 파일에 회사 규칙을 따로 쓰면 하나 고칠 때 14번 고쳐야 한다. 우리는 .claude/agent-shared/COMMON.md를 두고 본문 첫 줄을 "먼저 COMMON.md를 읽고 따른다"로 시작한다.

조심할 것

서브에이전트도 서브에이전트를 부를 수 있다. 기본값은 본 대화 아래 3단계까지. 막으려면 tools에서 Agent를 빼거나 disallowedTools에 넣는다. 환경 변수 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1이면 중첩 자체가 꺼진다.
본 대화를 모른다. 맡길 때 Claude가 쓰는 지시문이 전부다. 그래서 본문에 "먼저 무엇을 읽어라"를 적어 두는 게 효과가 크다.
플러그인에 넣은 서브에이전트는 permissionMode가 무시된다. 배포용이면 권한에 기대지 말고 tools로 좁힌다.

자주 묻는 질문

서브에이전트를 만들려면 꼭 /agents 명령을 써야 하나요?

아니다. .claude/agents/나 ~/.claude/agents/에 마크다운 파일을 직접 만들면 된다. 공식 문서에 따르면 최근 버전의 /agents는 "Claude에게 부탁하거나 폴더를 직접 고치라"는 안내를 보여 주고, 예전 버전은 만들기·고치기 화면을 열었다.

Claude Code에 처음부터 들어 있는 서브에이전트도 있나요?

있다. 읽기 전용으로 빠르게 코드를 찾는 Explore, plan 모드에서 조사하는 Plan, 여러 단계 일을 하는 general-purpose 등이다. Explore는 Write·Edit가 막혀 있다.

tools를 안 쓰면 어떻게 되나요?

서브에이전트가 쓸 수 있는 도구를 모두 물려받는다. 편하지만, 검토·게시처럼 역할이 좁은 에이전트는 tools를 적어 좁히는 편이 사고가 적다.

같은 이름의 에이전트가 프로젝트와 내 폴더에 둘 다 있으면요?

우선순위가 높은 쪽, 즉 프로젝트의 .claude/agents/ 것이 쓰인다(위 표 3번이 4번보다 먼저).

참고한 링크

#클로드 코드#Claude Code#서브에이전트#subagent#.claude/agents#에이전트 만들기