Claude Code subagent 호출 품질이 프롬프트 구조에 의해 결정되는 이유

이 기사는 playpark Blog에서 전재되었습니다.

• Claude Code subagent 호출 시 품질이 들쭉날쭉한 근본 원인
• 호출 프롬프트에 반드시 포함해야 할 5가지 요소와 그 선정 이유
• 어떤 요소를 생략하면 어떤 문제가 발생하는가

Claude Code의 Task

tool로 subagent를 호출하기 시작하면, 다음과 같은 의문이 생깁니다.

"같은 의뢰를 던지고 있는데, 돌아오는 포맷이 매번 다르다"

"탐색 태스크여야 하는데, 멋대로 파일을 수정해 버린다"

"token 소비량을 예측할 수 없다"

처음에는 "모델의 동작이 불안정하다"라고 생각하기 쉽지만, 실제 원인은 따로 있습니다.

Claude Code의 Task

tool에서는 호출한 쪽의 컨텍스트로 돌아오는 것이 subagent의 최종 출력뿐입니다. 중간의 Read / Grep / WebFetch 등의 조작 로그는 메인 세션으로 흘러 들어가지 않습니다.

이는 편리한 분리(context isolation)이지만, 뒤집어 생각하면 **"호출 시점의 프롬프트가 subagent에게 주어지는 유일한 지시"**가 된다는 것을 의미합니다. 메인이 도중에 궤도를 수정할 수 없는 구조이므로, 프롬프트의 품질이 그대로 출력 품질로 직결됩니다.

Anthropic의 Multi-agent research system 해설에서도, delegation 품질이 성패의 대부분을 결정한다고 보고되어 있습니다.

호출 품질을 보장하는 방법은 여러 가지가 있습니다.

접근 방식	장점	단점
매번 리뷰하며 구두로 지적	유연함, 규칙화 불필요	Skill이 늘어나면 인적 비용이 선형적으로 증가
체크리스트 문서화	기록이 남음	읽히지 않음, 적용 누락이 발생함
프롬프트 구조를 사양화 + lint	기계적으로 보장, 신규 Skill에도 자동 적용	초기 설계 비용이 발생함

"매번 리뷰"하는 방식은 Skill이 10개를 넘어가는 시점부터 비용이 맞지 않게 됩니다. "문서화"는 실제로는 지켜지지 않았습니다. 결과적으로, 프롬프트 구조 그 자체를 사양(specification)으로 고정하고, lint로 기계적으로 검사하는 접근 방식을 선택했습니다.

사양화한 요소와 각 요소가 대응하는 트러블의 대응 관계는 다음과 같습니다.

요소	대응하는 트러블	생략했을 때의 증상
Objective	종료 조건 없음 문제	subagent가 끝없이 탐색을 계속함
Output format	포맷 불일치	같은 의뢰라도 매번 다른 형식이 돌아옴
Tools	부작용 누락	탐색 태스크인데 파일을 수정함
Boundary	스코프 팽창	node_modules/ 안으로 파고들어 token을 낭비함
Token cap	출력량 무제한	"간결하게"라고 써도 500행짜리 리포트가 돌아옴

특히 Token cap에서 "간결하게"가 기능하지 않는다는 점은 간과하기 쉽습니다. "간결"은 정성적인 표현이기에, 모델은 "자신의 판단에 따른 간결한 것"을 반환합니다. "1500단어 이내", "상위 10개까지"와 같은 측정 가능한 숫자가 아니면 보장할 수 없습니다.

Task(
subagent_type: "general-purpose",
description: "Short 3-5 word description",
...

Objective 작성 포인트: "조사한다", "확인한다"가 아니라, "〇〇가 A인지 B인지 판정한다", "〇〇의 리스트를 반환한다"라고 작성합니다. 판정 결과인지 성과물인지, 어느 쪽이 반환되어야 하는지를 명시하는 것이 중요합니다.

subagent를 호출하는 dispatch가 늘어나는 타이밍(기준: 동일 리포지토리 내에서 5개 이상)에, 이 5가지 요소를 "모든 dispatch의 최소 기준"으로 도입하는 것이 비용 대비 효과가 높습니다.

dispatch가 적을 때는 매번 확인하며 진행할 수 있지만, Skill이 늘어나면 "이 dispatch는 Token cap이 있었나?"라는 리뷰 비용이 쌓이게 됩니다. 일찍 구조화해 두는 편이 결과적으로 비용이 낮아집니다.

이 기사에서는 subagent 호출 프롬프트의 5가지 요소와 그 선정 이유를 해설했습니다.

에이전트에게 "통째로 맡기는 지시"를 그만두라 —— Claude Code의 subagent 운용 규칙 에서는 더욱:

• 태스크 성격(탐색 heavy / 구현 / 계획 / 리뷰)별 subagent routing 표와 4가지 판단 기준
• 모든 SKILL.md를 스캔하여 5개 요소를 CI에서 강제하는 lint 스크립트 구현 상세
• 「dispatch 편차 → Skill I/O 설계의 재정리」라는 구조적인 부작용의 경위

playpark LLC - 업무 자동화 · AI 활용 · Web 개발