Claude Code 서브에이전트 만들기: 조사·검토 역할 나누기

Claude에게 코드베이스 조사를 시키면, Claude가 읽은 파일 내용이 메인 대화에 그대로 쌓입니다. 조사가 끝나고 정작 고칠 차례가 오면 컨텍스트가 이미 빠듯하죠. 서브에이전트는 그 읽기를 별도 컨텍스트 창에서 하고 요약만 돌려주는 보조 에이전트입니다.

만드는 건 어렵지 않아요. .claude/agents/<이름>.md 파일 하나면 됩니다.

저는 조사용은 tools: Read, Grep, Glob으로 읽기만 하게, 검토용은 disallowedTools: Write, Edit로 고치지 못하게 묶고, 부를 때는 “researcher 서브에이전트에게 맡겨 줘”처럼 이름을 직접 말하는 쪽을 권합니다. description만 잘 써 두고 자동으로 맡겨지길 기다렸더니 걸리지 않았다는 보고가 있거든요.

2026년 9월 11일 공식 문서 기준이고, --agents 플래그는 Claude Code 2.1.267에서 직접 확인한 것입니다.

10월 12일에는 Windows 11 · PowerShell 5.1 · Claude Code 2.1.296에서 아래 조사 에이전트를 실제로 만들어 모델 지정, 읽기 전용 제한, 모델 결정 순서를 확인했습니다. 자동 위임과 도구·모델 제한이 어긋난 사례는 공개 이슈를 인용했습니다. /compact·/clear와 견줘 언제 쓰는지는 컨텍스트가 찰 때 고르는 법에 있습니다.

파일 하나면 됩니다

YAML frontmatter와 지시문으로 된 마크다운 파일을 아래 자리 중 하나에 두면 됩니다. 어디에 두느냐가 적용 범위를 정해요. 이 프로젝트에서만 쓸 것은 .claude/agents/, 모든 프로젝트에서 쓸 것은 ~/.claude/agents/입니다.

위치	범위	팀과 공유
.claude/agents/	이 프로젝트	됨(커밋)
~/.claude/agents/	모든 프로젝트	안 됨
--agents 플래그(JSON)	이번 세션만	안 됨
관리 정책 설정	조직 전체	됨(관리자)

파일 모양은 이렇습니다.

---
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뿐입니다. 역할을 나눌 때는 아래 선택 필드를 씁니다.

• tools: 쓸 수 있는 도구를 허용 목록으로 좁힙니다. 생략하면 쓸 수 있는 도구를 모두 물려받습니다.
• disallowedTools: 물려받은 도구 중 일부만 뺍니다.
• model: sonnet·opus·haiku·fable 같은 별칭, claude-opus-5 같은 전체 모델 ID, 또는 메인 대화를 따르는 inherit.
• mcpServers: 특정 MCP 서버를 이 서브에이전트에만 붙입니다. 연결 절차는 Claude Code에 MCP 서버 연결하기에 있습니다.

파일을 손으로 쓰는 대신 Claude에게 “읽기 전용 researcher 서브에이전트를 .claude/agents/에 만들어 줘”라고 시켜도 됩니다. 하나 걸리는 게 있는데, 세션을 시작할 때 agents 폴더가 없었다면 실행 중인 세션이 새 폴더를 알아채지 못해요. 만든 서브에이전트를 못 찾으면 Claude Code를 다시 시작하세요(2026-10-06 확인).

이름 때문에 헷갈리는 것도 하나 있습니다. Explore·Plan은 Claude Code에 이미 들어 있는 서브에이전트라 파일이 필요 없어요. 커스텀 서브에이전트는 도구 제한과 지시문을 내 프로젝트에 맞게 고정해 두고 반복해서 쓰려고 만드는 것입니다.

model을 비우면 무엇으로 도나

메인 대화 모델을 따라갈 것 같지만, 메인 대화 모델은 마지막 순위입니다. 어느 모델로 돌지는 아래 순서로 정해지고, 위에서 먼저 정해진 것이 이깁니다.

1. 호출할 때 넘긴 model 값
2. 서브에이전트 파일의 model (inherit이면 메인 대화 모델)
3. CLAUDE_CODE_SUBAGENT_MODEL 환경 변수
4. 메인 대화의 모델

그래서 셸에 CLAUDE_CODE_SUBAGENT_MODEL을 걸어 두었다면, model을 비운 서브에이전트는 메인 대화가 아니라 그 환경 변수의 모델로 돕니다.

Windows에서 model을 비운 요약 에이전트를 메인 sonnet 세션에서 불러 확인해 봤습니다. 어느 모델이 쓰였는지는 --output-format json의 modelUsage로 봤어요.

조건	modelUsage에 찍힌 모델
환경 변수 없음	claude-sonnet-5-5만
CLAUDE_CODE_SUBAGENT_MODEL=haiku	claude-sonnet-5-5, claude-haiku-5-5

환경 변수가 없을 때는 메인 대화 모델로, 있을 때는 그 모델로 돌았습니다. 순서표 그대로예요.

조사용은 읽기만, 검토용은 고치지 못하게

두 역할은 묶는 방향이 반대입니다. 조사는 많이 읽되 아무것도 바꾸면 안 되고, 검토는 테스트까지 돌려 보되 고치면 안 되죠.

1. 조사 에이전트 만들기

몇 파일 훑고 요약만 받으면 되는 조사라면 굳이 파일을 만들 필요가 없습니다. 내장 Explore에 맡기면 돼요. 읽기 전용 도구만 쓰고, CLAUDE.md와 git 상태를 건너뛰어 빠르고 쌉니다.

“항상 테스트 파일부터 찾는다”처럼 반복하는 조사 방식이 있을 때 파일로 굳혀 둡니다. .claude/agents/researcher.md:

---
name: researcher
description: 코드베이스에서 관련 파일과 기존 구현을 찾아 요약만 보고한다. 수정하지 않는다.
tools: Read, Grep, Glob
model: haiku
---

주어진 주제와 관련된 파일을 찾아 각 파일이 무엇을 하는지, 어디를 고치면
되는지 요약해 보고한다. 파일을 고치거나 명령을 실행하지 않는다.

tools에 읽기 도구만 있으니 이 에이전트는 파일을 고칠 수 없습니다. 많이 읽고 결론만 필요한 일이라 haiku처럼 가벼운 모델을 주면 비용과 응답 시간이 줄어들고요.

이 파일을 Windows 프로젝트에 그대로 두고 메인 sonnet 세션에서 “researcher 서브에이전트에게 맡겨서 로그인 처리가 어느 파일에 있는지 알려 줘”라고 시켜 봤습니다. modelUsage에 claude-sonnet-5-5와 함께 claude-haiku-5-5가 찍혀서, 지정한 모델로 돈 걸 확인했어요. 이 버전에서 haiku 별칭은 Haiku 5.5로 풀렸습니다.

읽기 전용 제한도 시험해 봤습니다. 같은 에이전트에게 src/auth.ts 맨 위에 주석 한 줄을 넣으라고 시키니, 읽기 도구만 있어서 수정할 수 없다고 보고하고 파일은 그대로 두더라고요. 메인 세션은 편집을 허용한 상태였는데도요.

2. 검토 에이전트 만들기

검토하다가 스스로 고쳐 버리면 무엇이 잘못됐는지가 기록에 남지 않습니다. 그래서 수정 도구만 뺍니다. .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 변경된 코드를 검토해 문제점만 보고한다. 직접 고치지 않는다.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
---

변경 사항에서 버그, 놓친 예외 처리, 테스트 부재를 찾는다. Bash로 테스트를
실행하되 파일은 고치지 않는다. 문제마다 파일 경로, 줄 번호, 재현 조건을 적는다.

3. 여러 갈래 조사를 동시에 맡기기

조사 대상이 나뉘면 “인증·데이터베이스·API 모듈을 각각 서브에이전트로 나눠 조사해 줘”처럼 한 번에 시키면 됩니다. 각자 따로 컨텍스트 창에서 일하고, 메인 대화에는 끝나는 대로 요약만 쌓여요.

한 세션에서 동시에 돌 수 있는 서브에이전트는 기본 20개입니다. 넘으면 Concurrent subagent limit reached가 나고, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 상한을 바꿀 수 있습니다.

메인 대화에서 그냥 시키면 안 되느냐 하면, 짧은 조사는 그래도 됩니다. 다만 읽은 파일 내용이 메인 컨텍스트에 그대로 쌓여 이후 작업이 무거워지고, 검토를 같은 대화에서 하면 방금 고친 쪽이 자기 변경을 감싸기 쉬워요. 역할을 나눠서 얻는 건 바로 이 두 가지를 피하는 것입니다.

반대로 한두 번 주고받으며 다듬는 일은 메인 대화에서 하는 편이 빠릅니다.

그리고 검토 서브에이전트가 통과시켰다고 품질이 보장되지는 않아요. 결과에 파일 경로·줄 번호 같은 근거가 없으면 다시 시키거나 직접 확인하세요.

서브에이전트가 맡기는 정도의 어느 단계에 해당하는지는 반복 작업을 넘기는 네 단계에 정리해 두었습니다.

부를 때는 이름을 말하세요

Claude는 서브에이전트의 description을 보고 언제 맡길지 스스로 정하게 되어 있습니다. 적극적으로 맡기게 하려면 description에 “use proactively”를 넣으라고도 권장되고요.

그래도 저는 이 자동 위임에 기대지 말고 이름을 넣어 부르기를 권합니다. description만 적어 두고 기다렸을 때 거의 위임되지 않았다는 보고가 있기 때문이에요(아래 첫 번째 사례). 이렇게 부르면 됩니다.

이 부분은 researcher 서브에이전트에게 조사시키고, 끝나면 code-reviewer 서브에이전트로 검토해 줘.

다른 사람들이 겪은 문제

공개 GitHub 이슈의 사례입니다. 첫 건은 자동 위임 이야기이고, 나머지 셋은 파일에 적은 제한이 그대로 걸리지 않았다는 보고예요.

주의: 제한이 어긋난 세 경우 모두 오류 메시지 없이 조용히 일어났습니다. 결과를 보고 확인하는 수밖에 없습니다.

description만 적었더니 위임되지 않았다

ianhomew(2026-07-30, 이슈 #82456, Claude Code 2.1.220, macOS)의 기록입니다.

부른 방식	위임된 횟수
description에 Use PROACTIVELY만 적고 기다림	14건 중 0건
“전담 서브에이전트에게 맡겨 줘”라고 명시	14건 중 12건

보고자는 실행 파일에서 뽑은 텍스트에 “사용자가 요청하지 않았다면 Agent 도구를 부르지 말라”는 지시가 있었고, 2.1.219부터 보였다고 적었습니다. description을 다듬는 것보다 이름을 넣어 부르는 편이 확실하다고 보는 이유입니다.

tools: []로 비웠는데 목록에 (Tools: All tools)로 나온다

도구를 모두 뺀 서브에이전트가 부모 세션의 에이전트 목록에는 (Tools: All tools)로 표시된다는 보고입니다(scvbuild, 2026-07-30, 이슈 #82562, Claude Code 2.1.219, macOS).

이슈 설명으로는 표시 로직이 “지정 안 함”과 “빈 배열”을 구분하지 못할 뿐, 실제 실행은 빈 배열을 제대로 처리합니다. 한 번 실행해 도구 호출 없이 텍스트로만 답하면 계획대로예요.

tools에 Agent·ToolSearch를 넣어도 쓰지 못한다

Bash·Read·Edit은 정상인데 이 둘만 실제로 쓸 수 있는 도구에 나타나지 않는다는 보고입니다(radekBednarik, 2026-07-22, 이슈 #80104). 서브에이전트가 다른 서브에이전트를 부르려 할 때 드러나고, 원인은 확정되지 않았습니다.

중첩은 메인 대화 기준 3단계까지 되고 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 바꿀 수 있지만, 실제로 중첩 호출이 일어나는지는 결과로 확인하세요. 안 되면 메인 대화에서 서브에이전트를 차례로 부르는 구조가 확실합니다.

model을 적었는데 메인 대화 모델로 돈다

model: claude-opus-4-8을 적었는데 메인 대화 모델(보고에서는 Fable 5.1)로 실행됐다는 보고입니다(Daredevll, 2026-09-03, 이슈 #91890, Claude Code 2.1.259, macOS).

보고자는 전체 모델 ID를 인식하지 못했거나 정의가 세션 시작 때 캐시됐을 가능성을 추정했지만 확정되지 않았습니다. 전체 ID는 문서상 쓸 수 있으므로(2026-09-10 확인) 그것만으로 원인이라 보기는 어렵습니다.

확인하는 법은 간단해요. 서브에이전트가 도는 동안 /tasks를 열면 그 줄에 실제 모델이 나옵니다(v2.1.242 이상). 스크립트로 돌린다면 앞에서 쓴 --output-format json의 modelUsage에 서브에이전트 모델이 함께 찍히는지 보면 됩니다.

다르다면 위의 네 단계 중 어디서 뒤집혔는지 보고, 그래도 frontmatter가 무시되면 세션을 새로 시작해 정의를 다시 읽히세요. 그 이상의 확정된 해결책은 아직 없습니다.

마치며

서브에이전트는 결국 파일 하나와 도구 제한 몇 줄입니다. 정작 신경 쓸 곳은 만든 다음이에요.

자동으로 불리길 기다리기보다 이름으로 부르고, 적어 둔 도구·모델 제한이 실제로 걸렸는지 /tasks와 결과로 한 번은 확인해 보세요. 조용히 어긋난 사례가 여럿이라, 저는 이 확인까지를 만드는 일의 일부로 봅니다.

자주 시키는 조사가 있다면 researcher.md로 만들어 커밋해 두고, 다음 조사부터 이름으로 불러 보세요. 여러 세션이 같은 파일을 고칠 일이 생기면 세션마다 워크트리로 파일을 나누는 법으로 이어집니다.