저의 Claude Code 오케스트레이터인 Suhail의 첫 번째 버전에는 에러를 전혀 발생시키지 않는 버그가 있었습니다. 오케스트레이터는 작업 단위당 연구자(researcher), 기획자(planner), 코더(coder), 리뷰어(reviewer), 감사자(auditor)라는 다섯 가지 역할의 서브에이전트(subagents)를 배포해야 했습니다. 하지만 실제로는 오케스트레이터가 모든 일을 하나의 컨텍스트 윈도우(context window) 내에서 직접 수행하며 실행이 "완료"되었습니다. 배포는 전혀 일어나지 않았고, 트랜스크립트(transcript) 상에서도 아무런 징후가 나타나지 않았습니다.

근본 원인은 분명히 옳아 보이는 배치 결정 때문이었습니다. 오케스트레이터는 에이전트(agent)이므로, 저는 이를 agents/ 디렉토리에 정의했습니다.

실제로 일어난 일

Claude Code에서 agents/ 아래의 파일은 Agent 도구(tool)를 통해 호출되는 서브에이전트(subagent)가 됩니다. 당시(2026년 5월 기준) 서브에이전트는 Agent 도구 자체를 받지 못했습니다. 즉, 서브에이전트가 서브에이전트를 생성할 수 없었습니다. 따라서 /su가 저의 오케스트레이터를 호출했을 때, Claude Code는 배포 지침이 가득 담긴 시스템 프롬프트(system prompt)와 아무것도 배포할 수 없는 도구 세트(toolset)를 함께 전달했습니다.

이러한 실패 모드(failure mode)가 위험한 이유는 모델이 도구를 누락했다고 해서 충돌(crash)이 발생하지 않기 때문입니다. 모델은 즉흥적으로 대처합니다. 저의 오케스트레이터는 "연구자 서브에이전트를 배포하라"는 명령을 읽었지만 Agent 도구를 찾지 못했고, 모델이 모순을 해결하는 방식대로, 즉 자신이 할 수 있는 가장 유사한 행동을 함으로써 그 모순을 해결했습니다. 때로는 직접 인라인(inline)으로 연구를 수행하기도 했고, 때로는 세션이 조용히 최상위 레벨에서 파이프라인을 구동하는 방식으로 회귀하기도 했습니다. 어느 쪽이든 실행 결과물은 생성되었고, 이것이 바로 제가 즉시 문제를 발견하지 못한 정확한 이유입니다. 전체 사후 분석(postmortem) 내용은 프로젝트의 결정 로그(decision log)에 공개되어 있습니다.

해결 방법

저는 오케스트레이터 본체를 agents/에서 꺼내 슬래시 커맨드(slash command)로서 commands/로 옮겼습니다. 슬래시 커맨드의 본체는 최상위 세션(top-level session)에 주입되며, 최상위 세션은 Agent 도구를 가지고 있습니다. 프롬프트는 동일하지만 배치가 달라지자 배포가 정상적으로 작동했습니다. 다섯 가지 역할의 에이전트들은 원래 있어야 할 곳인 agents/에 그대로 유지되었습니다. 즉, 단일 배포 및 단일 아티팩트(artifact) 작업자로서 말입니다.

그 덕분에 저는 이후 모든 역할에 적용하는 하나의 경험칙(rule of thumb)을 얻었습니다. 오케스트레이터(orchestrators)와 인터뷰어(interviewers)는 슬래시 명령어(slash commands)이며, agents/는 단 하나의 작업만 수행하고 하나의 아티팩트(artifact)를 반환하는 워커(workers)만을 위한 것이라는 점입니다.

이후 변경된 사항 (2026년 7월 확인됨)

그 규칙의 절반은 만료되었습니다. Claude Code v2.1.172 기준으로, 서브에이전트(subagents)는 최대 5단계 깊이까지 자체적인 서브에이전트를 생성할 수 있습니다. 만약 제가 오늘 이 버그를 마주한다면, agents/에 오케스트레이터를 두는 설계는 대부분 작동할 것입니다. Anthropic은 또한 커스텀 명령어(custom commands)를 스킬(skills)로 병합했지만, commands/*.md 파일은 이전처럼 계속 작동합니다.

하지만 그 문장에서 "대부분"이라는 단어는 실질적인 의미를 갖습니다. 왜냐하면 근본적인 실패 모드(failure mode), 즉 도구(tool)가 누락되어 에러 대신 즉흥적인 동작(improvisation)을 생성하는 문제가 여전히 존재하기 때문입니다. 오늘날 여러분의 디스패처(dispatcher)가 Agent 도구를 조용히 놓칠 수 있는 세 가지 방법은 다음과 같습니다:

1. Agent를 누락한 tools 프론트매터(frontmatter) 목록. tools 필드를 완전히 생략하면 Agent를 포함한 모든 도구를 상속받습니다. 하지만 서브에이전트를 제한하기 위해 tools 목록을 작성하는 순간, 이는 허용 목록(allowlist)이 되며, 오케스트레이터 역할에서 Agent를 잊어버리면 경고 없이 디스패치(dispatch) 기능이 제거됩니다.

2. 깊이 제한(The depth limit). 깊이 5단계에 있는 서브에이전트는 Agent 도구를 전혀 받지 못합니다. 이 제한은 고정되어 있으며 설정할 수 없습니다. 깊은 위임 체인(delegation chains)은 제 v0.1.0 오케스트레이터가 겪었던 것과 동일한 침묵의 벽에 부딪히며, 단지 5단계 뒤에서 발생할 뿐입니다.

3. 세션 상태 도구(Session-state tools)는 서브에이전트에 도달하지 않습니다. AskUserQuestion, EnterPlanMode 및 기타 몇몇 도구들은 최상위 세션에 의존하며, tools에 나열하더라도 서브에이전트에서는 사용할 수 없습니다. 따라서 제 규칙의 인터뷰어(interviewer) 부분은 여전히 유효합니다. 멀티턴(multi-turn) 인터뷰 역할은 반드시 슬래시 명령어에 존재해야 합니다. 서브에이전트 디스패치는 단발성(one-shot)이며 사용자와 대화를 유지할 수 없기 때문입니다.

이를 포착하는 방법

관찰해야 할 증상: 트랜스크립트에 "연구원(researcher)을 디스패치하는 중"이라고 나오지만, 실제 작업은 동일한 컨텍스트 내에서 인라인으로 나타나고 서브에이전트 패널에는 오케스트레이터 아래에 어떤 트리도 표시되지 않습니다. Claude Code의 패널은 에이전트별 후손(descendant) 수를 보여주기 때문에, 실제로 디스패치하는 디스패처는 한눈에 보입니다.

지속 가능한 해결책은 특정 제약 조건 대신 실패 모드에 맞춰 설계하는 것입니다. 즉, 모든 디스패치가 조용히 발생하지 않을 수 있다고 가정하고, 서술(narration)을 신뢰하기보다 출력을 검증해야 합니다. Suhail은 모든 디스패치 후 예상되는 아티팩트 파일이 존재하며 필요한 섹션을 포함하는지 확인하고, 그렇지 않으면 진행하는 대신 블로커를 작성합니다. 이 게이트는 제가 예측하지 못한 문제들을 포함하여 이 문제의 모든 변종을 포착해 왔습니다.

핵심 요약(The takeaway)

에이전트가 도구를 누락했을 때, 오류 메시지를 받지 않습니다. 대신 모델은 그 도구의 최선의 흉내를 내고, 작동하는 것처럼 보이는 파이프라인을 얻게 됩니다. 오늘날 여러분이 의존하고 있는 어떤 오케스트레이션 제약 조건(중첩 규칙, 도구 상속, 깊이 제한)도 밑에서 바뀔 것이므로, 그 제약 조건을 인코딩하지 말고 검사를 인코딩하세요. 즉, 모든 디스패치가 실제로 아티팩트를 생성했는지 검증해야 합니다.

여기서의 사후 분석(postmortem)은 제가 일상적으로 프로덕션 Expo/Supabase 레포지토리에서 사용하는 Suhail의 v0.1.0 버전입니다. Claude Code 동작은 2026년 7월 기준 라이브 문서 및 변경 로그와 비교하여 검증되었습니다 (v2.1.172에서 중첩 규칙이 변경됨).