Claude Code의 서브 에이전트에게, 이렇게 지시해 본 적은 없는가? "판단이 어려우면 마음대로 진행하지 말고 한 번 물어봐".

그리고 돌아오는 보고는, 언제나 "물어본 기억이 없다"는 것이었던 적은 없는가.

사실 이것은, AI가 게으름을 피우고 있었던 것이 아니었다. 그 서브 에이전트에게는, 애초에 "묻는다"라는 선택지가 처음부터 존재하지 않는다.

Claude Code의 실측 환경은 2.1.215 (claude --version으로 확인).
서브 에이전트 주변의 사양은 업데이트가 빠르기 때문에, 수중에 있는 버전에서는 동작이 달라져 있을 가능성이 있다.

Claude Code의 공식 문서 「Create custom subagents」에, 이런 구절이 있다.

The first filter removes these tools,

even when listed in the:tools

Agent

, when the subagent is at the depth limit; in a fork the tool stays listed but returns an error instead of spawningAskUserQuestion

EndConversation

, which can end only the main conversationEnterPlanMode

ExitPlanMode

, unless the subagent'spermissionMode
isplan

ScheduleWakeup

TaskOutput

WaitForMcpServers

Workflow

(역: 첫 번째 필터는, tools 필드에 적혀 있어도 이 도구들을 제거한다. Agent (자식을 더 가질 수 있는지 여부)는 중첩 깊이가 상한에 도달했을 때만, ExitPlanMode는 permissionMode가 plan이 아닌 한, 이라는 조건부. 반면 AskUserQuestion (사용자에게 질문)·EnterPlanMode 외에는 무조건 제거된다)

여기서 중요한 것은, 전부가 동일하게 취급되는 것은 아니다라는 점이다. Agent는 중첩 깊이 상한에 도달했을 때만 제외되는 조건부 항목으로, 기본 설정이라면 5층까지 중첩할 수 있다 (= 서브 에이전트가 자식을 가질 수 없게 되는 것은 아니다). ExitPlanMode도 "permissionMode가 plan인 경우를 제외한다"라는 조건부다. 그에 반해 AskUserQuestion에는 조건이 없다. 어떤 설정이라도, 무조건적으로 모든 서브 에이전트에서 사라진다.

tools에 명시적으로 적어도 삭제된다. system prompt에 "모르면 물어봐"라고 덧붙여도, 묻기 위한 도구 자체가 기동하는 순간 빼앗기고 있다.

즉 서브 에이전트가 선택할 수 있는 행동은, 실질적으로 2가지뿐이다. 스스로 결정하거나, 결정하지 않고 보고하며 끝내거나. "모르면 물어봐"는, 물을 수단이 없는 상대에게는 "스스로 결정해"와 같은 의미가 된다.

지시문에 아무리 "물어봐"라고 써도, 이 그림의 왼쪽 상단(AskUserQuestion을 사용하는 분기) 자체가 처음부터 없다. 남아 있는 것은 오른쪽의 2가지뿐이다.

여기까지 왔으므로, "맡기는 법"과 직결되는 다른 사양도 공식 문서에서 다시 확인했다.

출처 (전 행 공통): Claude Code 공식 문서 「Create custom subagents」

풀어서 설명하자면 다음과 같다. 요청한 작업은 기본적으로 백그라운드에서 돌아가기 시작하며, 결과는 즉시 돌아오지 않는다 (포그라운드에서 실행하고 싶을 때는 그 의도를 명시해야 한다). 백그라운드에서 작동하는 동안에는 사용할 수 있는 도구도 제한된다. 규칙을 CLAUDE.md에 적어두면 대부분 전달되지만, Explore와 Plan에는 애초에 전달되지 않는다.

"요청했는데 반응이 없다", "방금 정한 규칙이 적용되지 않는다" —— 서브 에이전트에게 작업을 맡기면서 이런 느낌을 받은 적이 있다면, 원인은 AI의 변덕이 아니라 바로 이 사양 그 자체일지도 모른다.

여기서 "AI 에이전트는 신뢰할 수 없다"는 이야기로 결론을 내리려는 것은 아니다. 사양을 알고 있다면, 맡기는 법을 설계할 수 있다. 물어볼 수 없는 상대에게 판단을 통째로 맡기기 때문에 사고가 발생하는 것이지, 처음부터 "판단은 이쪽에서 한다"는 전제로 두면 이 제약은 오히려 다루기 쉽다.

구체적인 선 긋기는 단순하다.

• 판단이 필요한 일은 맡기지 않는다. "어느 방침이든 성립한다", "이것은 원래 설계와 어긋난다" —— 이런 분기점이 발생하는 작업을 주면, 물어볼 수단이 없는 상대로부터는 독자적인 해석만이 돌아올 뿐이다.
• 읽고 요약을 반환하는 일만 맡긴다. 대량의 로그를 읽게 하여 요점만 반환하게 하거나, 코드를 검색하게 하여 해당 부분을 보고하게 하는 것 —— 판단을 동반하지 않는 일이라면 백그라운드 실행이라도 문제가 되지 않는다.
• 결과가 즉시 필요한 작업은, 포그라운드에서 실행하고 싶다는 의도를 명시한다. 아무 말 없이 맡기면 백그라운드 실행으로 넘어가며, 결과는 "다음 턴"까지 오지 않는다.
• CLAUDE.md에만 의존하여 모든 것을 통제하려 하지 않는다. 모든 계층이 로드된다고는 하지만 Explore / Plan은 예외다. 반드시 지키게 하고 싶은 규칙은 해당 태스크 문구에도 직접 작성한다.

실제로 어떻게 역할 분담으로 연결했는지는 개인 블로그(종합 스트리밍 플랫폼과 은행을 병행하여 만들기 — AI 에이전트의 '편성'에 실기능을 구현하고, 실측을 통해 분업을 튜닝한 기록 · 외부 사이트로 이동합니다)에 정리해 두었다.

지금은 지시문에서 "모르면 물어봐"를 지웠다. 대신 적고 있는 것은 "모르면, 판단하지 말고 실행을 멈추고 보고한 뒤 종료하세요"이다. 묻는 능력이 아니라, 멈추는 능력을 주는 것이다. 그것만으로도 독단적으로 진행한 뒤 나중에 앞뒤를 맞추느라 고생하는 상황은 상당히 줄어들었다.

솔직히 말하자면, 처음에는 지시문 작성 방식이 잘못되었다고 생각했다. '모르면 물어봐'를 '반드시 한 번 확인한 후에 진행해'로 바꿔보거나, 굵게 표시해보거나, system prompt의 눈에 잘 띄는 위치로 옮겨보는 등—글자만 수없이 만지작거렸다. 공식 문서의 '무조건 박탈되는 도구(tool)' 목록을 접하기 전까지는, 이것이 내 프롬프트의 정밀도 문제라고 착각하고 있었다. 아무리 문구를 고쳐도 해결되지 않을 것이라는 것을 알게 된 것은, 그 도구 자체가 제공되지 않았다는 것을 알고 난 뒤였다.

'작동하지 않는 원인은 내가 글을 못 써서다'라고 단정 짓기 전에, 먼저 '애초에 그런 수단이 존재하는가'를 의심해보는 것이 좋다고 생각한다.

• Claude Code 공식 문서 'Create custom subagents'(서브 에이전트로부터 제거되는 도구 목록・백그라운드 실행 사양・CLAUDE.md의 상속 범위): https://code.claude.com/docs/en/sub-agents

개인 블로그(https://mint041223techblog.netlify.app/)에 매일 개발하며 깨달은 것을 자세히 쓰고 있습니다 (외부 사이트로 이동합니다).