클로드 코드 서브에이전트 사용법(claude code subagents): .claude/agents/ 에 파일 하나로 만들고 검토는 쓴 쪽과 다른 서브에이전트에 맡긴다

같은 종류의 일을 매번 같은 지시로 맡기고 있다면 그 지시를 서브에이전트 파일 하나로 만들어 두면 된다. 클로드 코드 서브에이전트 사용법은 세 걸음. 프로젝트의 .claude/agents/(나만 쓰려면 ~/.claude/agents/)에 마크다운 파일을 하나 두고 맨 위 frontmatter 에 name · description 을 적은 뒤 그 아래에 서브에이전트가 따를 지시를 쓴다. 그다음엔 Claude가 description 을 보고 알아서 맡기거나 내가 이름 · @ 로 직접 맡긴다. 작업은 서브에이전트의 컨텍스트 창 안에서 돌고 메인 대화로 돌아오는 건 요약뿐. 쓸 도구는 tools 로 좁힌다. 빼 두면 쓸 수 있는 도구를 전부 물려받으니까. 여기에 우리 기준 하나를 더하면, 검토는 쓴 쪽과 다른 서브에이전트에 맡기고 그 서브에이전트는 결과물을 고치지 않고 찾은 것만 돌려준다. 출처는 Claude Code 서브에이전트 문서, 2026-10-21 조회.

서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려준다 (2026-10-21 공식 문서 기준)

공식 문서는 서브에이전트를 정해진 종류의 일을 맡는 전문 조수라고 부른다. 자기 컨텍스트 창, 자기 시스템 프롬프트, 정해진 도구, 따로 된 권한을 가지고 도는 조수. 검색 결과 · 로그 · 파일 내용처럼 다시 안 볼 출력이 메인 대화를 덮을 것 같을 때 쓰라고 문서는 안내한다. 그 일은 서브에이전트 컨텍스트 안에서 끝나고 메인 대화로는 요약만 돌아온다. 한 가지 더, 서브에이전트가 보내는 요청도 메인 대화와 같은 사용 한도에 잡힌다는 점.

만들지 않아도 들어 있는 내장 서브에이전트 가운데 자주 보이는 셋. Explore(코드베이스 검색 · 분석)와 Plan(플랜 모드에서 계획 전에 맥락 모으기)은 읽기 전용이라 Write · Edit 가 막혀 있다. general-purpose 는 서브에이전트가 쓸 수 있는 도구를 전부 받는다. 스킬과 어떻게 나눠 쓰는지는 15편에.

1단계: 서브에이전트 만들기 — Claude에게 부탁하거나 파일을 직접 쓴다

서브에이전트는 YAML frontmatter 가 붙은 마크다운 파일이다. 만드는 길은 둘. Claude에게 써 달라고 하거나 파일을 직접 쓰거나. /agents 를 쳐도 지금은 이 두 길을 알려 주는 안내만 나온다. v2.1.197 까지는 같은 명령이 만들기 · 고치기 · 지우기를 하는 대화형 화면을 열었다.

Claude에게 맡긴다면 이런 식(공식 예시를 줄여 옮김).

~/.claude/agents/ 에 개인용 code-improver 서브에이전트를 만들어 줘.
파일을 훑어서 읽기 쉬움 · 성능 · 관례 쪽 개선점을 제안하게 하고
읽기 전용으로, 모델은 Sonnet 으로.

Claude가 만든 파일은 한 번 열어 본다. tools 에 무엇이 들어갔는지, description 이 언제 맡길지를 말하고 있는지. ~/.claude/agents/ 에 둔 파일은 내 모든 프로젝트에서 쓰인다. 한 프로젝트에서만 쓰려면 그 프로젝트의 .claude/agents/ 로 옮길 것.

2단계: 파일 위치 — 팀과 나눌 건 .claude/agents/, 나만 쓸 건 ~/.claude/agents/

위치	쓰이는 곳	같은 이름일 때 순위
회사 관리 설정	조직 전체	1(가장 높음)
실행 옵션 --agents(JSON)	지금 세션	2
.claude/agents/	지금 프로젝트	3
~/.claude/agents/	내 모든 프로젝트	4
플러그인의 agents/ 폴더	플러그인을 켠 곳	5(가장 낮음)

프로젝트 서브에이전트는 버전 관리에 넣어 팀이 같이 쓰고 고치라는 게 문서의 권고. 폴더는 하위 폴더까지 훑는다. 같은 서브에이전트인지 가르는 기준은 파일 이름 말고 name 필드. --agents 는 실행할 때 JSON 으로 넘기는 정의라 디스크에 남지 않는다.

파일을 더하거나 고치면 Claude Code가 몇 초 안에 알아채고 다음 위임부터 새 정의를 쓴다. 다시 시작해야 하는 경우는 셋.

• 세션을 시작할 때 없던 agents 폴더를 새로 만들고 첫 파일을 넣었을 때
• --add-dir 이나 /add-dir 로 더한 폴더 안의 .claude/agents/ 를 고쳤을 때
• --disable-slash-commands 로 시작한 세션일 때(이때는 폴더를 아예 지켜보지 않는다)

3단계: frontmatter — 필수는 name · description 둘

---
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.

공식 문서에 실린 가장 짧은 꼴. frontmatter 아래 본문이 그 서브에이전트의 시스템 프롬프트가 된다.

• name(필수): 고유 이름, 256자까지.
• description(필수): Claude가 언제 이 서브에이전트에 맡길지 고르는 기준. 알아서 맡기게 하려면 「use proactively」 같은 말을 넣으라고 문서는 적는다. 짧게 쓸 것 — 직접 만든 서브에이전트들의 description 을 합쳐 15,000 토큰을 넘으면 시작할 때 경고가 뜬다(그래도 전부 불러온다).
• tools: 쓸 수 있는 도구. Read, Grep, Bash 같은 쉼표 목록이나 YAML 목록. 빼면 서브에이전트가 쓸 수 있는 도구를 전부 물려받는다.
• disallowedTools: 뺄 도구. 물려받은 목록이나 tools 목록에서 지운다.
• model: sonnet · opus · haiku 같은 별칭, 전체 모델 ID, 또는 inherit. 비워 두면 부를 때 지정한 모델 → 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL → 메인 대화 모델 순으로 정해진다.
• 그 밖에 permissionMode · maxTurns · skills · mcpServers · hooks 같은 필드가 있다. permissionMode 를 비우면 메인 대화의 권한 모드를 물려받는다.

필수는 둘뿐이지만 tools 는 적어 두는 쪽이 낫다. 빼면 위 설명대로 전부 물려받으니까.

4단계: 부르기 — description 으로 알아서 · 이름이나 @ 로 직접

Claude는 요청 내용과 서브에이전트의 description, 지금 맥락을 보고 알아서 맡긴다. 직접 고르는 길은 셋.

test-runner 서브에이전트로 실패하는 테스트를 고쳐 줘
@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

첫째는 이름을 말로 부르는 것, 둘째는 @ 를 치고 목록에서 고르는 것(손으로 칠 땐 @agent-<이름>), 셋째는 세션 전체를 그 서브에이전트로 여는 것. 특정 서브에이전트를 아예 못 쓰게 하려면 설정의 permissions.deny 에 Agent(<이름>) 을 넣는다.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Claude가 띄우는 서브에이전트는 기본값에서 백그라운드로 돈다. 그동안 나는 다른 일을 하고 권한 확인 창은 그때그때 메인 세션으로.

5단계: 도구 제한 — tools 는 허용 목록, Bash 는 따로 거른다

tools 는 허용 목록, disallowedTools 는 차단 목록. 아무것도 적지 않으면 메인 대화에 있는 내장 도구와 MCP 도구를 물려받는다. 파일을 고치면 안 되는 검토용이라면 tools: Read, Grep, Glob 처럼 Write · Edit 를 뺀 목록. 공식 예시 가운데는 여기에 Bash 를 더한 것도 있고 문서는 그 꼴을 「파일을 고치거나 쓸 수 없다」고 설명한다. Edit · Write 도구가 없다는 뜻. Bash 는 셸 명령을 그대로 돌리니 권한이 허용하는 명령이면 파일이 바뀔 수 있다. 셸이 꼭 필요하다면 공식 예시 db-reader 처럼 PreToolUse 훅으로 명령을 거르는 쪽. 그 예시에서는 SQL 쓰기 명령이 보이면 훅 스크립트가 종료 코드 2로 막는다.

서브에이전트는 기본값에서 메인 대화 아래 세 단계까지 자기 서브에이전트를 띄울 수 있다. 막는 길은 셋. 그 서브에이전트 하나만 막으려면 tools 허용 목록에서 Agent 를 빼거나 disallowedTools 에 Agent 를 넣고 모든 서브에이전트를 한꺼번에 막으려면 환경 변수 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 를 1 로 둔다.

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

이 값은 메인 대화 아래 몇 단계까지 띄울지를 뜻한다. 1 이면 중첩이 꺼지는 셈.

tools 에 적어도 서브에이전트에게서 빠지는 도구가 있다. 사용자에게 되묻는 AskUserQuestion 이 그중 하나. 그러니 맡기는 프롬프트는 그것만 읽고 일을 끝낼 수 있게 쓸 것.

검토는 왜 남이 해야 하나: 쓴 대화를 못 보는 쪽이 읽게 한다

같은 대화에서 「방금 쓴 것 검토해 줘」라고 하면 무엇이 빠질까? 검토하는 쪽도 쓴 이유와 가정을 이미 다 아는 상태. 서브에이전트는 대화 기록 없이, 넘겨받은 프롬프트로 새 컨텍스트에서 출발한다. 예외는 포크. 지금 대화를 통째로 물려받는 서브에이전트라 검토를 맡길 자리는 아니다. 그래서 검토 서브에이전트는 쓴 쪽의 설명 대신 결과물과 그 출처를 놓고 읽게 된다. 여기부터는 우리가 정한 기준.

1. 쓴 에이전트와 다른 에이전트가 검토한다. 원고든 코드든, 만든 에이전트가 아니라 별도 컨텍스트의 검토 에이전트가 본다.
2. 검토 에이전트는 결과물을 고치지 않는다. tools 에 Edit 를 넣지 않고 찾은 것은 보고서나 마지막 메시지로 돌려받는다.
3. 커밋하지 않는다. 커밋은 부른 쪽 세션이 한다.
4. 다시 위임하지 않는다. Agent 를 주지 않아서 검토를 또 다른 서브에이전트에 넘기지 못하고 직접 끝낸다.

공식 문서 꼴로 줄이면 이렇다(이름은 자리표시).

---
name: <AGENT_NAME>
description: Reviews a finished draft or diff against its sources. Use after writing is done, never for writing.
tools: Read, Grep, Glob
model: inherit
---

Review only what the request names. Check each claim against its source.
Return findings in your final message. Do not edit files or delegate.

Bash 가 없으니 이 서브에이전트는 git 명령도 못 돌린다. 테스트나 git diff 가 필요한 검토라면 Bash 를 넣게 되고 그때부터 커밋 금지는 지시문이 지키는 규칙.

실제로 겪은 일

10월 20일, Claude가 쓴 이 블로그 17편 초안을 검토 전용 에이전트가 따로 읽었다. 판정은 「아래를 고치면 통과」, 고칠 것은 여덟 가지. 그중 하나가 우리 설정을 설명한 대목. 초안은 읽기 도구만 승인 없이 열어 둔 그 설정을 권한 허용 규칙으로 했다고 썼는데 기록과 대조해 보니 실제 장치는 훅이었다. 고친 판은 다시 검토를 받아 통과했고 보안 검토도 따로 거쳤다.

내 설정 점검표: 클로드 코드 서브에이전트 사용법

1. 파일이 .claude/agents/(팀 공유) 또는 ~/.claude/agents/(나만)에 있나. 같은 name 이면 프로젝트 것이 이긴다.
2. name 과 description 을 적었나. description 이 언제 맡길지를 짧게 말하나.
3. tools 를 적었나. 빼면 메인 대화의 내장 도구 · MCP 도구를 물려받는다.
4. 검토용이라면 Write · Edit 가 빠졌나. Bash 를 넣었다면 훅으로 명령을 거르나.
5. 다시 위임하지 않게 하려면 Agent 를 tools 에서 뺐거나 disallowedTools 에 넣었나. 한꺼번에 막으려면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 를 1 로.
6. 맡기는 프롬프트만 읽고도 일을 끝낼 수 있나. 서브에이전트는 AskUserQuestion 으로 되묻지 못한다.
7. 검토를 쓴 대화 안에서 하고 있지 않나. 검토는 이름 있는 다른 서브에이전트에.
8. 세션 중에 agents 폴더를 처음 만들었다면 Claude Code를 다시 시작했나.

같이 읽을 글

• 15편 — claude code skills vs agents · 클로드 코드 스킬 vs 서브에이전트: 지금 대화에서 다시 쓸 절차는 스킬, 결과만 받을 일은 서브에이전트: 스킬에 둘지 서브에이전트에 둘지 고르는 기준.
• 9편 — Claude Code · Codex 한 저장소에서 충돌 막는 법(git worktree · git commit 경로 지정): 에이전트 둘이 동시에 커밋한 날: 서브에이전트를 여럿 돌릴 때 커밋이 섞이지 않게, 커밋을 부른 세션에 둔 이유.

다음 글은 클로드 코드 에이전트 만들기. Claude Code에서 에이전트를 만들기 전에 무엇을 따져 볼지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.