Claude Code의 서브 에이전트에게 '묻지 않고' 작업을 위임하는 방법: hook 대신 description과 CLAUDE.md로

저는 개인 개발한 육아 기록 앱을 거의 모든 부분을 Claude Code를 이용해 구현하고 있습니다.

.claude/agents/ 폴더에는 구현 담당, 테스트 담당, 문서 감사 담당의 서브 에이전트를 배치했습니다.

이렇게 공들여 만들었으니, 제가 이름을 직접 언급하지 않아도 상황에 맞춰 사용했으면 좋겠다고 생각했습니다.

그래서 '서브 에이전트가 자동으로 호출되도록 고안해 달라'고 Claude에게 요청했습니다.

이번 글에서는 그때 알게 된 다음 두 가지를 소개합니다.

• 서브 에이전트에 자동 위임은 hook이 아니라 description과 CLAUDE.md로 결정된다.
• 리뷰와 같은 무거운 처리는 서브 에이전트 측에서 실행되어야 메인 대화가 오염되지 않는다.

이는 Claude Code에서 커스텀 서브 에이전트를 만들었지만, 그다지 사용되지 않는다고 느끼는 분들을 위한 내용입니다.

• Claude는 '요청 내용', 서브 에이전트의 description, 그리고 '현재 문맥'을 바탕으로 위임할지 여부를 스스로 판단합니다. 확실하게 위임시키고 싶다면, description에 어떤 요청으로 사용할 것인지를 구체적으로 작성해야 합니다. 그래도 부족한 부분은 CLAUDE.md에 '이런 상황에서는 확인 없이 위임한다'는 표를 작성해야 합니다. hook으로는 조건을 확인할 수 있는 판단용 서브 에이전트(실험적 기능)까지만 가능합니다. '이 작업은 feature-dev에게 맡긴다'와 같이 작업 자체를 커스텀 서브 에이전트에 할당하는 것은 불가능합니다. 범용적인 역할(코드 리뷰)은 직접 만들지 않고, 공식의 /code-review에 의존했습니다. 프로젝트 고유의 관점은 CLAUDE.md에 작성하면 서브 에이전트에게도 전달되는 /code-review를 서브 에이전트를 통해 호출하여 메인 컨텍스트를 보호했습니다. 현재는 이 방식이 공식적으로 통합된 형태가 되었습니다.

/code-review는 처음부터 별도의 컨텍스트에서 작동합니다.

| 검토 날짜 | 2026-08-24 |

공식 문서에서는 자동 위임 메커니즘이 다음과 같이 설명되어 있습니다.

Claude automatically delegates tasks based on the task description in your request, the description field in subagent configurations, and current context.

즉, 위임 여부는 당장의 Claude가 요청 내용과 description을 비교하여 결정합니다.

'반드시 이 에이전트를 실행한다'는 스위치가 있는 것은 아닙니다. '자동으로 무언가를 실행하게 한다'고 생각하면 hook이 떠오릅니다. '구현이 끝나면 반드시 리뷰용 서브 에이전트를 실행하게 할 수 있을까?'와 같이요.

공식 문서를 보면, hook에는 `type:

name: qa-tester
description: 품질 보증 에이전트. 버그 탐색・테스트의 공백 보강・엣지 케이스 검증을 수행한다. 코드의 신규 기능 구현은 하지 않고, 수정과 테스트 추가에 전념한다.
...

name: feature-dev
description: 백로그 항목 1건을 설계→구현→테스트→문서 업데이트→커밋까지 엔드투엔드로 완료시키는 개발 에이전트. 병렬로 여러 항목을 진행할 때는 worktree 분리로 기동한다.
...

핵심은 '무엇을 할 수 있는지'뿐만 아니라, '어떤 요청일 때 사용할지'까지 적는 것입니다.

서브 에이전트의 description

은 총 15,000 토큰을 초과하면 기동 시 경고가 발생합니다(공식 문서). 트리거 예시는 자주 사용하는 표현으로 한정하는 것이 좋습니다.

description만으로는 위임할지 여부는 Claude의 판단에 달려 있습니다.

그래서 CLAUDE.md에 **'이 상황에서는 확인을 거치지 않고 위임한다'**는 표를 작성했습니다.

## Subagent 운영(자동 위임)
`.claude/agents/`에 전담 서브 에이전트가 있다. 해당되는 상황에서는 사용자에게 확인을 받지 않고 **자동으로** 위임한다(모두 읽기 주체・push는 하지 않는 전제하에).
| 상황 | 위임처 |
...

작성할 때 주의한 점은 세 가지입니다.

'확인받지 않는다'고 명시하는 것. 구현부터 리뷰까지 중간에 멈추지 않고 흘러가게 하고 싶기 때문입니다 -
'왜 물어볼 필요가 없는지'를 첨부하는 것(읽기 주체・push하지 않음). 이유가 있으면 예외적인 상황에서 AI가 판단하기 쉽습니다 -
사용하지 않을 경우도 적는 것. 몇 줄 수정에까지 서브 에이전트를 기동하면 오히려 빙 돌아가는 것이 되기 때문입니다

검토 전에는 reviewer라는 자작 서브 에이전트로 검토했습니다.

---
name: reviewer
description: 검증 전담의 코드 리뷰 에이전트. feature-dev 구현 완료 후・push 전에 반드시 사용한다....
...

검토할 때 필자로부터 '/code-review 같은 공식 커맨드를 사용하는 편이 낫지 않을까'라는 제안을 받아, 이 자작 에이전트는 삭제했습니다.

자작 reviewer
| 공식 /code-review
|
|---|---|
| 리뷰의 깊이 | 고정 | effort로 변경 가능 (low ~ max, 클라우드에서 작동하는 ultra) |
| 유지보수 | 작성 시점 지식 그대로 | 공식이 계속 업데이트함 |
| 프로젝트 고유 관점 | 프롬프트에 내장 | CLAUDE.md에 적기

프로젝트 고유의 관점(날짜 경계・Supabase의 RLS・1000건 상한 등)은 CLAUDE.md로 옮겼습니다.

공식 문서에 따르면, 커스텀 서브 에이전트는 기동 시 CLAUDE.md를 읽어 들입니다(내장된 Explore와 Plan 제외). CLAUDE.md에 적어두면 검토에도 구현에도 같은 관점이 전달됩니다.

자작 에이전트를 남길 가치가 있는 것은 공식 툴에는 없는 역할만이라고 생각합니다.

필자의 경우, feature-dev (이 프로젝트의 구현 흐름), qa-tester, docs-auditor 세 가지를 남겼습니다.

/code-review를 자동으로 돌리기 시작하자, 또 다른 문제가 생겼습니다.

검토를 위해 읽은 차분(diff)・grep 결과・테스트 출력이 모두 메인 대화의 컨텍스트에 남아버리는 것입니다.

이 프로젝트는 하나의 세션이 길어지기 쉬웠습니다. 그래서 필자로부터 '검토는 서브 에이전트 측에서 실행하는 것이 컨텍스트를 소모하지 않는 것 아니냐'라는 제안을 받았습니다.

새로운 에이전트를 만들 필요는 없었습니다.

내장된 general-purpose 서브 에이전트에게, /code-review의 실행 전체를 맡겼습니다.

– /code-review 및 /security-review는 본체에서 직접 Skill 도구를 호출하는 대신, Agent(subagent_type: "general-purpose")를 통해 호출합니다 (effort: medium).
diff 읽기, grep, lint/test 실행 등의 탐색 비용을 본체의 컨텍스트에 가져오지 않고, 서브 에이전트 쪽에 가두어 지적 사항의 요약만 가지고 돌아옵니다.
프롬프트 예시: "변경 차분(diff)에 대해 /code-review를 effort:medium으로 실행하고, 지적 사항을 200자 정도로 요약하여 보고해".
...

공식 문서에서도 서브 에이전트는 "조사한 결과나 로그로 인해 메인 대화가 넘칠 때" 사용하는 것이라고 설명되어 있습니다. 서브 에이전트는 독립된 컨텍스트에서 작업하며, 요약만 반환합니다.

이 글을 쓰기 위해 공식 문서를 확인해 본 결과, 다음과 같이 적혀 있었습니다.

– /code-review는 독립적인 컨텍스트를 가진 백그라운드 서브 에이전트로 작동한다. 대화에 포함되지 않고, 끝나면 결과가 도착한다 –
/code-review가 forked subagent로 작동하는 것은 v2.1.218부터이다. 그 이전에는 대화 안에서 직접(inline으로) 작동했다.

즉, 필자가 CLAUDE.md에서 고안했던 방식은, 지금은 /code-review가 처음부터 해주고 있다.

새로운 버전에서는,
general-purpose로 감쌀 필요는 없습니다. 생각 자체는 지금도 사용할 수 있습니다.

– **직접 만든 스킬(self-made skill)**이 무거운 탐색을 할 경우, frontmatter에 context: fork를 쓰면 서브 에이전트 안에서 작동할 수 있다 – 반대로,
사용자와 상의하며 진행하는 작업은 서브 에이전트를 거치면 왕복 횟수가 늘어나므로, 메인 대화 상태로 유지합니다.

검토 이후, BACKLOG.md의 완료 기록에서 /code-review에 언급된 작업은 10건 있었습니다.

지적 사항으로 발견된 예시입니다.

RLS용 함수에 security definer가 빠져 있어, 모든 사용자의 쓰기가 멈추었습니다. 차분(diff)을 읽는 것만으로는 알 수 없는 "실제 권한" 문제였고, 발견한 것은 실제 상대의 E2E 테스트였습니다. → Supabase에서 2단계 인증(TOTP)을 넣자 실제 쓰기가 전부 멈췄습니다.

리뷰는 자동화할 수 있지만, 실제 환경에 준하는 검증은 별도로 필요하다는 것을 실감했습니다.

/simplify는 발견한 개선점을 그대로 코드에 반영합니다.

자동 흐름에 넣으면, 요청하지 않은 수정이 섞여 들어옵니다. CLAUDE.md에는 "명시적으로 요청했을 때만 사용한다"고 적었습니다.

qa-tester와 docs-auditor는 frontmatter에서 model: sonnet으로 설정했습니다.
테스트 보강이나 문서 대조는 가벼운 모델로도 충분한 품질이 나온다고 판단했기 때문입니다. 구현 담당의 feature-dev는, 품질에 직결되므로 inherit(메인과 같은 모델) 상태를 유지합니다.

커스텀 서브 에이전트는 메인 대화 기록을 보고 있지 않습니다. 공식 문서에서는 Claude가 작성하는 위임 메시지만을 믿고 작업한다고 설명되어 있습니다.

CLAUDE.md에 없는 전제(예: "이 화면은 오늘 사용자와 결정한 사양이다" 등)는, 위임할 때 전달된다고 보장할 수 없습니다. 중요한 전제는 CLAUDE.md나 태스크 지침에 적어야 합니다.

– 서브 에이전트에게의 위임은 Claude가 description과 요청 내용으로 판단한다. 어떤 요청으로 사용할지를 description에 적는다 - 확실하게 맡기고 싶은 흐름은, CLAUDE.md에 "확인하지 않고 위임하는 것" 표로 작성한다. 사용하지 않을 상황도 적는다 - hook의 agent 타입은 판별용(실험적). 업무 분배에는 사용할 수 없다
– 범용적인 역할은 공식(/code-review

）에 집중하고, 프로젝트 고유의 관점은 CLAUDE.md에 작성합니다. 무거운 처리는 서브 에이전트 측에서 실행하여 메인 컨텍스트를 보호합니다.
/code-review

는 원래부터 그렇게 작동합니다. 직접 만든 스킬이라면 context: fork

관련 기사:

• Claude Code의 완료 알림이 서브 에이전트 때문에 여러 번 울리므로, 모든 것이 끝났을 때만 울리도록 하기
• Claude Code의 메모리를 이해하기 — CLAUDE.md vs auto memory
• Claude Code의 /loop로 '요구사항 정의 → 테스트 → 배포'를 반나절 자율적으로 진행하며 알게 된 운영 노하우 정리