서브에이전트 스폰 상한으로 자동화 파이프라인 안정화하기

자동화 & 파이프라인

Claude Code로 자동화 파이프라인을 구축할 때, 서브에이전트가 통제 없이 늘어나면 API 비용이 기하급수적으로 폭발할 수 있습니다. 환경변수 하나로 이 위험을 차단하는 방법을 정리합니다.

📌 3줄 요약

• 서브에이전트 폭주는 API 비용을 예상치의 수십 배로 뻥튀기시킬 수 있다
• CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 환경변수로 세션당 서브에이전트 상한을 설정하면 된다
• 작업 유형별로 상한을 분리하고, 초과 시 대응 로직을 미리 설계해두자

📚 목차

• 1. 자동화 파이프라인에서 서브에이전트가 위험한 이유
• 2. CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 설정 방법
• 3. 상한 초과 시 동작 방식과 대응 전략
• 4. 자동화 스크립트에 상한 설정을 녹이는 실전 패턴

자동화 파이프라인에서 서브에이전트가 위험한 이유

Claude Code로 자동화 파이프라인을 구축하면, 에이전트가 작업을 처리하다가 스스로 서브에이전트(subagent)를 생성하는 상황이 발생합니다. 한두 개쯤이야 괜찮지만, 복잡한 작업에서는 서브에이전트가 또 다른 서브에이전트를 호출하면서 수가 기하급수적으로 늘어날 수 있습니다. 예를 들어 코드 리팩토링을 지시하면, 에이전트가 파일별로 서브에이전트를 띄우고, 각 서브에이전트가 다시 테스트 검증용 서브에이전트를 만드는 식이에요. 이렇게 트리 구조로 퍼지면 원래 의도했던 작업 범위를 훨씬 넘어서게 됩니다.

🔍 서브에이전트 폭주란?
이 현상을 "서브에이전트 폭주"라고 부릅니다. 서브에이전트가 또 다른 서브에이전트를 호출하면서 트리 구조로 무한히 퍼지는 현상을 말합니다.

폭주가 발생하면 API 호출 비용이 예상치의 수십 배로 뛰어오르는 것이 가장 큰 문제입니다. 토큰 소비량이 선형이 아니라 지수적으로 증가하기 때문에, 10분만 방치해도 하루 예산을 초과하는 일이 실제로 생깁니다. 특히 Opus 모델처럼 토큰 단가가 높은 모델을 사용할 때는 피해 규모가 더 커요.

⚠️ 자동화 환경에서는 사람이 실시간으로 모니터링하지 않기 때문에, 폭주를 늦게 발견하면 이미 큰 비용이 청구된 뒤입니다. 수동으로 Claude Code를 쓸 때는 이상하다 싶으면 바로 중단하면 되지만, 스크립트로 돌리는 경우에는 그 판단이 불가능합니다. 새벽에 cron으로 돌려놓고 아침에 확인했더니 API 비용이 수십 달러가 찍혀 있었다는 후기도 커뮤니티에서 종종 보입니다.

💬 직접 자동화 파이프라인을 운영해보니, 서브에이전트 상한 없이 돌리는 건 안전벨트 없이 고속도로를 달리는 것과 비슷합니다. 처음에는 괜찮아 보여도, 한 번 사고가 나면 피해가 큽니다. 그래서 파이프라인을 처음 설계할 때부터 상한을 걸어두는 것이 기본 중의 기본이에요.

CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 설정 방법

서브에이전트 스폰(spawn, 생성) 상한을 거는 환경변수가 바로 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION입니다. 이 값을 설정하면, 한 세션 내에서 생성할 수 있는 서브에이전트의 총 개수가 제한됩니다. 세션이란 하나의 claude 명령 실행 단위를 의미하며, 세션이 끝나면 카운트가 초기화됩니다.

설정 방법은 간단합니다. 자동화 스크립트에서 Claude Code를 실행하기 전에 환경변수를 선언하면 됩니다.

bash

export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=10
claude --prompt "작업 내용"

 

Windows 환경에서는 set 명령을 사용합니다. PowerShell을 쓰는 경우에는 $env:CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION = "10" 형태로 설정할 수도 있어요.

cmd

set CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=10
claude --prompt "작업 내용"

 

Python 스크립트 안에서 설정하는 방법도 있습니다. subprocess로 Claude Code를 호출할 때 env 파라미터에 넘기면 됩니다. 이 방식은 스크립트 내에서 작업별로 상한을 동적으로 바꿀 수 있어서 가장 유연합니다.

python

import subprocess
import os

env = os.environ.copy()
env["CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION"] = "10"

subprocess.run(["claude", "--prompt", "작업 내용"], env=env)

권장 상한값은 작업 복잡도에 따라 5~20 사이입니다. 단순 반복 작업이면 5로 충분하고, 멀티스텝 파이프라인이면 15~20 정도가 적당합니다.

💡 상한을 0으로 설정하면 서브에이전트 생성이 완전히 차단되므로, 에이전트가 모든 작업을 혼자 처리하게 됩니다. 서브에이전트가 필요 없는 단일 프롬프트 작업이라면 0으로 설정하는 것도 좋은 선택이에요.

💬 제가 직접 써보니까, 처음에는 넉넉하게 30으로 잡았다가 비용 폭탄을 맞은 뒤 10으로 줄였습니다. 대부분의 자동화 작업은 10이면 충분합니다.

상한 초과 시 동작 방식과 대응 전략

서브에이전트 수가 설정한 상한에 도달하면, Claude Code는 추가 서브에이전트 생성을 거부합니다. 이때 에이전트는 서브에이전트 없이 직접 작업을 처리하려고 시도합니다. 중요한 점은 에이전트가 에러를 내고 멈추는 게 아니라, 가능한 범위 내에서 대안을 찾으려 한다는 것이에요. 다만 서브에이전트에게 위임해야 효율적인 작업을 혼자 처리하다 보면 결과 품질이 다소 떨어질 수 있습니다.

상한에 걸렸다고 해서 전체 작업이 중단되는 것은 아닙니다. 에이전트가 우회 경로를 찾지 못하면 해당 단계만 실패하고, 나머지 작업은 계속 진행됩니다.

🔍 부분 실패(partial failure)란?
전체가 한꺼번에 멈추는 것이 아니라, 실패한 단계만 스킵하고 나머지는 계속 진행되는 구조입니다. 자동화 파이프라인에서는 이런 부분 실패를 허용하는 설계가 오히려 바람직합니다. 실패한 부분만 나중에 재처리하는 편이 운영 효율이 높아요.

자동화 파이프라인에서는 이 실패를 감지하는 로직이 필요합니다. 종료 코드(exit code)를 확인하거나, 출력 로그에서 "max subagents" 관련 메시지를 파싱하는 방식이 일반적입니다. 아래 스크립트처럼 로그를 파일에 저장해두면, 나중에 어떤 시점에서 상한에 도달했는지 추적할 수 있어요.

bash

export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=10

claude --prompt "작업 내용" 2>&1 | tee /tmp/claude_log.txt
EXIT_CODE=$?

if grep -q "subagent" /tmp/claude_log.txt; then
  echo "서브에이전트 상한 관련 이벤트 감지"
fi

 

💡 실전에서는 상한을 너무 낮게 잡으면 정상 작업도 실패하는 경우가 있습니다. 처음 며칠은 상한을 넉넉히 잡고 실제 사용량을 모니터링한 뒤, 점진적으로 줄여나가는 것이 안전합니다. 모니터링 기간 동안 각 작업이 실제로 몇 개의 서브에이전트를 사용하는지 기록해두면, 적정 상한값을 데이터 기반으로 정할 수 있어요. 이 과정을 거치면 불필요한 여유분 없이 딱 맞는 상한을 설정할 수 있습니다.

자동화 스크립트에 상한 설정을 녹이는 실전 패턴

실제 운영 환경에서는 환경변수를 하드코딩하지 않고, 설정 파일이나 .env에서 관리하는 것이 좋습니다. 작업 유형별로 상한값을 다르게 가져가면 유연성이 높아집니다. 하드코딩된 값은 수정할 때마다 코드를 직접 고쳐야 하지만, 설정 파일로 분리하면 배포 없이도 상한을 조정할 수 있어요.

python

import os
import subprocess

TASK_LIMITS = {
    "simple": 5,
    "standard": 10,
    "complex": 20,
}

def run_claude(prompt: str, task_type: str = "standard"):
    env = os.environ.copy()
    limit = TASK_LIMITS.get(task_type, 10)
    env["CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION"] = str(limit)

    result = subprocess.run(
        ["claude", "--prompt", prompt],
        env=env,
        capture_output=True,
        text=True,
    )
    return result

 

작업 유형별 상한 분리는 비용 관리의 핵심입니다. 단순 텍스트 변환에 20개 서브에이전트를 허용할 이유가 없고, 복잡한 코드 리팩토링에 5개로 막아버리면 작업 품질이 떨어집니다. 이 구분을 제대로 해두면 월간 API 비용을 절반 가까이 줄일 수 있는 경우도 있어요.

💬 실제로 저는 이 패턴을 적용한 뒤 월 비용이 눈에 띄게 안정화되었습니다.

cron이나 Windows 작업 스케줄러로 정기 실행하는 경우, 스크립트 상단에 상한 설정을 명시해두면 나중에 디버깅할 때도 편리합니다. 로그에 현재 상한값을 함께 기록하는 습관도 도움이 됩니다.

python

import logging

logging.info(
    f"Claude 실행 - 상한: {limit}, 작업: {task_type}"
)

 

💡 운영하면서 느낀 점은, 상한 설정 자체보다 상한에 걸렸을 때 어떻게 처리할지를 미리 정해두는 것이 더 중요하다는 것입니다. 재시도할 것인지, 알림을 보낼 것인지, 그냥 스킵할 것인지를 파이프라인 설계 단계에서 결정해두면 운영이 훨씬 안정적입니다. Slack 웹훅이나 이메일 알림을 연동해두면 상한 초과 이벤트를 실시간으로 파악할 수 있어서 대응 속도가 빨라져요.

✍️ 마치며

결국 좋은 자동화란 잘 돌아갈 때보다 문제가 생겼을 때 어떻게 반응하느냐로 결정됩니다. CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 환경변수 하나만 설정해도, 예측 불가능한 비용 폭발로부터 파이프라인을 지킬 수 있습니다. 작업 유형별 상한 분리와 초과 시 대응 로직까지 갖추면, 안심하고 자동화를 돌릴 수 있는 기반이 완성됩니다.

#ClaudeCode #서브에이전트 #자동화파이프라인 #API비용절감 #환경변수설정 #AI에이전트