서브 에이전트를 5단계까지 중첩하는 방법: 활용 사례와 한계점 (Claude Code)

당사(合同会社ジョインクラス)는 직원으로 저 혼자입니다. 대신 Claude Code의 에이전트 17개(CTO, CMO, 출판부장, 세무사 등)를 배치하고, launchd로 17개 이상의 작업을 실행하고 있습니다.

조직도를 그리다 보면 깊이를 더하고 싶은 충동을 느낍니다. 'CEO → 부장 → 담당 → 작업자 → 검증자'의 5단계 구조입니다. 실제로 만들어 작동시켜 보았습니다. 결론부터 말씀드립니다.

• Claude Code의 내장 서브 에이전트(Agent/Task 도구)는 중첩할 수 없습니다. 서브 에이전트 안에서 또 다른 서브 에이전트를 호출할 수 없다는 것입니다. - 5단계를 만들려면, claude -p를 프로세스로 호출해야 합니다. - 계층이 깊어질 때마다 고정 비용이 약 $0.3이 발생합니다. 5단계의 일직선 구조만으로도 $1.5 정도가 됩니다. - 실용적인 것은 3단계까지입니다. 4단계부터는 비용과 실패 전파 방식을 고려했을 때 이득이 없어집니다.

본문에서는 당사에서 실제로 작동하는 스크립트를 사용하여, 구성 방법, 깊이를 제한하는 가드(guard), 비용 측정 방법, 그리고 시스템이 무너지는 지점을 순서대로 설명하겠습니다.

즉, 5단계는 이 두 가지 종류를 번갈아 쌓아서 만듭니다.

L1 launchd(cron 상당)
└ L2 claude -p … 부문 오케스트레이터 (예: 출판부장)
└ L3 내장 서브 에이전트 (Agent 도구) … 담당자
...

L3 → L4 단계만은, 서브 에이전트에게 Bash를 허용하여 claude -p를 실행시키는 '우회로'입니다. 본문에서 다룰 대부분의 시스템 붕괴 지점이 이 단계에서 발생합니다.

당사에서는 무인 실행되는 claude는 모두 이 래퍼(wrapper)를 거치게 합니다. .company/scripts/lib/claude-run.sh 그대로입니다.

#!/bin/bash
# claude를 무인 실행할 때의 공통 래퍼. 실질 비용을 기록함.
#
...

핵심 포인트는 세 가지가 있습니다.

• --output-format json으로 total_cost_usd를 추출하고, record-cost.py가 cost-tracker.json에 라벨별로 기록합니다. 단계마다 라벨을 구분해 두면, 어느 단계에서 얼마가 사용되었는지 나중에 알 수 있습니다.
• --max-budget-usd 3으로 1프로세스당 상한선을 정합니다. 중첩할 경우 이 상한선은 단계별로 독립적으로 적용되므로, 5단계라면 최악의 경우 $15가 될 수 있습니다.
• 표준 출력에는 응답 텍스트만 흘립니다. 부모는 RESULT=$(...)로 받을 수 있습니다.

launchd에서 매주 수요일 7:00에 실행되는 출판 부문의 작업입니다 (발췌).

source "/Users/kyoagun/workspace/one-ceo/.company/scripts/lib/claude-run.sh"
cd "$PROJECT_ROOT"
RESULT=$(claude_run dept-publishing --effort low -p "
...

여기서 중요한 것은 `--allowedTools

CLAUDE_MAX_DEPTH="${CLAUDE_MAX_DEPTH:-3}"
claude_run() {
local label="$1"; shift
...
변경점은 다음 3가지입니다.

CLAUDE_NEST_DEPTH
을 1씩 늘려 자식 프로세스에 전달하고, 상한에 도달하면 claude를 실행하지 않고 종료 코드 75를 반환합니다. 비용 레이블에는 @L2처럼 단계를 붙입니다. 어떤 단계가 높은지는 cost-tracker.json만 보면 알 수 있습니다.
일부러 재귀시켜서, 멈추는 것을 확인해봅니다.

source .company/scripts/lib/claude-run.sh
CLAUDE_MAX_DEPTH=2 claude_run nest-test -p '다음 명령어를 그대로 한 번만 실행하고, 출력을 그대로 반환하시오: ...'

CLAUDE_MAX_DEPTH=2라면 L2와 L3까지는 실행되고, 그 아래는 refused가 stderr에 출력되면 성공입니다.

내장(組み込み) 서브 에이전트는 .claude/agents/*.md의 프론트매터에서 툴을 제한합니다. 저희 회사의 CTO 에이전트는 다음과 같습니다.

---
name: ai-ceo-cto
description: CTO/개발부장 에이전트. 제품 개발 전반을 총괄하며, dev-architect, dev-coder, dev-reviewer의 태스크를 관리한다.
...

description에 'dev-coder를 관리한다'고 쓰여 있지만, 내장 서브 에이전트에서는 dev-coder를 Agent 툴로 호출할 수 없습니다. Bash가 허용되어 있기 때문에 claude -p 경유로 L4를 만들 수는 있지만, 그것을 시키는지는 본문에서 명시해 두어야 합니다. 저는 다음 한 줄을 본문에 넣었습니다.

## 위임 규칙
- 하위 에이전트의 기동은 `claude_run` 경유로만 제한한다. `claude`를 직접 호출하지 않는다(깊이 가드 통과 목적)
- 위임할 수 있는 것은 '독립적으로 검증 가능한 결과물'이 있는 태스크뿐이다. 조사 과제 전가(丸投げ)는 금지

5계층의 구성을 짜서 검증했을 때, 문제가 된 것이 다음 4가지입니다.

래퍼의 주석에 나와 있듯이, claude -p는 내용이 '2+2'여도 한 번 $0.27~$0.47가 걸립니다. 캐시 생성 시 약 41,000 토큰 중, 자체 CLAUDE.md나 에이전트 정의는 5,800 토큰밖에 없습니다. 나머지는 Claude Code 측의 고정 오버헤드라 프롬프트를 줄여도 내려가지 않습니다.

L5의 검증자가 '테스트가 3건 실패했다'고 돌려줘도, L4가 그것을 요약하고, L3가 더 요약하면, L2의 Slack 알림에서는 '대체로 문제없음'이 되어버립니다. 각 단계가 tail -20이나 '결과를 간결하게 보고'로 출력을 줄여서, 나쁜 소식일수록 먼저 사라집니다.

대책으로, 실패는 텍스트가 아니라 종료 코드와 파일로 반환하도록 했습니다.

# L4 측: 실패는 exit code와 전용 파일로 반환
if ! npm test > "$WORK/test.log" 2>&1; then
echo "FAILED" > "$WORK/STATUS"
...

L2는 요약문이 아니라 STATUS 파일을 읽고 판단합니다.

L2에 `--allowedTools

5단계에서 무슨 일이 일어났는지 추적하려면 5개의 세션 로그를 시간 순서로 재구성해야 합니다. 현재의 Wrapper는 라벨이 부서명만이라, 중첩되면 어떤 프로세스가 어느 단계인지 알 수 없습니다. Step 3에서 라벨에 @L4와 같은 단계 번호를 붙인 이유가 바로 이것입니다.

이를 바탕으로 저희 회사의 규칙은 다음과 같습니다.

판단 기준은 단 하나입니다. **'해당 단계의 출력을 LLM이 아닌 스크립트로 합격/불합격 판정할 수 있는가'**입니다. 할 수 없다면, 해당 단계는 부모가 직접 처리하는 것이 비용도 적고 고장 나기 쉽지 않습니다.

• 내장 서브 에이전트는 중첩될 수 없습니다. 5단계는 claude -p 프로세스와 번갈아 가며 만들어야 합니다 -
  claude -p
  1회 고정 비용은 약 $0.3입니다. 줄일 수 있는 것은 호출 횟수뿐입니다 -
  CLAUDE_NEST_DEPTH 환경 변수로 깊이 제한을 걸고, 비용 라벨에 단계 번호를 붙이며, 실패는 텍스트가 아닌 종료 코드와 파일로 반환합니다.
• 실용상의 상한은 3단계입니다. 4단계부터는 '스크립트로 검증할 수 있는 결과물'이 있을 때만 가능합니다.

경영 관점에서 말하자면, 조직도를 그대로 에이전트 계층에 옮기는 것은 인간 회사에서 중간 관리직을 늘리는 것과 같아서, 전언 게임과 비용 증가만 가져올 뿐입니다. 저희가 CLAUDE.md를 1,000줄 이상으로 부풀리다 실패하고 200줄로 줄여 .claude/agents/에 분리했을 때와 같은 교훈입니다. 계층은 얕게, 책임은 명확하게.

오케스트레이터와 서브 에이전트의 역할 분담, 컨텍스트 전달, 실패 시 재시도 설계는 저서 『Claude Code 멀티에이전트 개발』에서 저희 회사의 17개 에이전트 구성을 바탕으로 체계적으로 정리했습니다.

도서 목록은 여기를 참고하세요 → https://zenn.dev/joinclass?tab=books