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

• 서브 에이전트 호출 시 model / effort를 왜 매번 명시해야 하는가 - 「생략」, 「매번 명시」, 「명시 + 검증(Validation)」의 세 가지 접근 방식 비교
• 어떤 상황에서 이 운영 방식이 적합한가

Claude Code에서는 Workflow나 Skill에서 서브 에이전트를 호출할 때 model과 effort를 생략해도 동작한다. 에러가 발생하지 않기 때문에 가벼운 작업일수록 생략하기 쉽다. 하지만 생략했을 때의 동작은 '적절한 중간값'이 아니라, 부모 세션의 설정을 그대로 상속받는 방식이었다. 부모 세션이 opus의 xhigh로 동작하고 있다면, 오타 수정이나 JSON 정렬과 같은 가벼운 처리를 요청한 서브 에이전트도 동일하게 opus의 xhigh로 동작한다.

서브 에이전트의 model/effort를 어떻게 다룰지에 대해, 실무에서는 크게 세 가지 접근 방식이 있다.

결정적인 이유는 「상속이 기본적으로 안전한 쪽이 아닌 무거운 쪽으로 치우친다」는 동작 그 자체에 있다. 원칙을 「경량·기계적인 작업은 haiku+low, 무거운 판단만 opus+상위 effort」로 정하더라도, 이를 지킬 수 있느냐는 호출 측이 매번 얼마나 성실하게 명시하느냐에 달려 있다. 원칙을 외치는 것만으로는 실천되지 않는다.

게다가 effort는 skill이나 agent의 frontmatter에도 작성할 수 있기 때문에, hihg와 같은 오타나 xtrahigh와 같은 잘못된 값을 작성할 리스크도 있다. 육안 리뷰로는 의외로 놓치기 쉽다. 그래서 「명시하는 운영」과 「작성한 값이 망가지지 않았는지 기계적으로 검증하는 계층」을 세트로 준비하기로 했다.

호출 측의 작성 방식은 다음과 같이 바뀐다.

// Bad: 아무것도 지정하지 않음 → 부모 세션의 opus/xhigh를 그대로 상속함
{ "subagent_type": "general-purpose", "prompt": "이 JSON을 키 순서대로 정렬해줘" }
// Good: 경량·기계적인 작업이라고 알고 있다면 명시함
...

frontmatter에 작성한 값의 검증은, 저장 전에 닫힌 enum(열거형)으로 체크하는 것만으로도 단순한 스크립트를 통해 구현할 수 있다.

#!/usr/bin/env bash
# validate-effort.sh: 인자로 받은 effort 값을 닫힌 enum으로 검증함
echo "$1" | grep -qE '^(low|medium|high|xhigh|max)$' && echo "OK: $1" || { echo "NG: '$1' is not a valid effort tier"; exit 1; }

이 체크를 PreToolUse hook의 입구에 배치하면, 오타 혼입을 리뷰 전에 차단할 수 있다.

Workflow나 Skill에서 서브 에이전트를 빈번하게 호출하는 구성이라면, model/effort의 명시와 검증은 세트로 준비해둘 가치가 있다. 반대로 단발성 서브 에이전트 호출만 있는 소규모 운영이라면, 우선 명시를 철저히 하고 frontmatter를 통한 관리가 늘어나는 단계에서 검증 계층을 추가하는 순서로 진행해도 충분하다고 생각한다.

이 기사에서는 서브 에이전트의 model/effort 상속 문제와, 명시+검증이라는 접근 방식을 선택한 이유를 해설했습니다.

Claude Code의 effort 설정, 서브 에이전트에게 맡기면 비용이 많이 드는 이유 에서는 추가로:

• effortLevel의 기본값을 실제로 조절하며 판단한 내용과, 포맷 변경·의미 변경을 섞어서 실패했던 반성 - Codex CLI 등 다른 에이전트형 코딩 도구와의 설정명 대응표
• 「높이면 안전하다」에 대한 반증과, 실무 체크리스트

를 다루고 있습니다.

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