들어가며
Claude Code로 서브에이전트를 활용한 개발 워크플로우를 운영하고 있다. 설계자(Architect)가 분석하고, 구현자(Implementer)가 코드를 쓰고, 검증자(Reviewer)가 리뷰하는 구조다. CAOF(Claude Agent Orchestration Framework)라는 이름을 붙였다.
잘 돌아갈 때는 마법 같다. 문제는 잘 안 돌아갈 때다.
사건: 50분간 응답 없음
React + Next.js 프로젝트(KARS)에서 /review 명령을 실행했다. 22개 파일이 변경된 상태에서 전체 코드 리뷰를 요청한 것이다.
50분이 지나도 응답이 없었다. 토큰은 계속 소비되고 있었다. 강제 중단하고 확인해보니, 리뷰 작업 자체는 이미 끝나 있었다. 결과 보고서를 생성하는 과정에서 멈춘 것이다.
원인: 3가지가 겹쳤다
1. 22개 파일을 한 번에 읽었다
에이전트가 git diff로 변경 파일 목록을 받고, 22개를 전부 Read했다. 컨텍스트 윈도우가 가득 차면 토큰 생성 속도가 극적으로 느려진다.
2. 빌드 실패 → 수정 → 재빌드 무한 루프
"빌드 실패 시 즉시 수정, 다음 단계 진행 금지"라는 규칙이 있었는데, 중단 조건이 없었다. npm run build가 2~5분이니까, 5회 반복하면 그것만 20~30분.
3. 장문 보고서 생성 병목
모든 에이전트에 테이블, 시나리오, 체크리스트가 포함된 상세 보고서를 요구했다. 작업은 끝났는데 보고서 쓰는 데 수십 분이 걸렸다.
첫 번째 시도: 제한을 걸었다 — 그리고 의문이 생겼다
처음에는 직관적인 해결책을 적용했다:
- 파일 읽기 최대 10개
- 디렉토리 전체 탐색 금지
- docs/ 읽기 금지효과는 있었다. 폭주는 멈췄다. 하지만 역효과가 보이기 시작했다.
BLE 센서 분석처럼 깊은 탐색이 필요한 작업에서 "파일 10개 읽었으니 여기서 멈춥니다"가 발생했다. 에이전트의 능력을 깎고 있었던 거다.
깨달음: 제한이 아니라 전략
사용자가 직접 에이전트에게 이렇게 말했더니 정상 동작했다:
"overview 먼저 하고, 기능별로 나눠서 순차적으로 리뷰해"
파일 22개를 읽는 건 똑같은데, 한 번에 읽느냐 나눠서 읽느냐의 차이였다.
| 방식 | 예시 | 효과 |
|---|---|---|
| ❌ 제한 | "파일 10개만 읽어라" | 능력을 깎는다 |
| ✅ 전략 | "한 번에 다 읽지 말고 overview → 순차 처리" | 능력은 그대로, 접근법만 바꾼다 |
이게 핵심이다. 에이전트를 제한하면 안 되고, 에이전트의 접근법을 바꿔야 한다.
해결: 전략 → 간소화 → 안전장치
1. 전략: 대규모 변경 처리법 (가장 효과적)
1. Overview: git diff --stat으로 파일 목록만 확인
2. 그룹핑: 기능별로 묶기 (품목 관리, 발주, 판매...)
3. 순차 처리: 그룹별로 관련 파일만 읽고 작업
4. 종합: 그룹별 결과를 합산이걸 에이전트 프롬프트에 기본 동작으로 넣었다:
변경 파일 10개 이상일 때:
한 번에 전부 읽지 않는다. overview → 그룹핑 → 순차 처리.탐색도 마찬가지:
# 제한 (❌)
"파일 읽기 최대 10개"
# 전략 (✅)
"Grep 먼저, Read 나중. 디렉토리를 통째로 읽지 않는다."2. 간소화: 출력 형식 줄이기
에이전트 간에 주고받는 산출물은 기계가 읽는 것이다. 예쁘게 꾸밀 필요 없다.
# 변경 전 (리뷰 에이전트)
심각/경고/권장 분류 테이블 + 6개 체크리스트 + 빌드 상태 + 설계 일치도
# 변경 후
대상: path, path
빌드: TS ✅ | Lint ✅
이슈:
- 🔴 path:line — 설명
체크: 권한 ✅ | 캐시 ✅ | 날짜 ✅간결한 출력이 빠른 응답이다.
3. 안전장치: 실패 제한 (전략이 아니라 안전장치)
전략으로 해결되지 않는 영역도 있다. 빌드 무한 루프 같은 건 전략이 아니라 중단 조건이 필요하다:
빌드 수정: 최대 3회. 초과 시 에러 목록 정리 후 중단.
에이전트 스폰 재시도: 최대 3회. 초과 시 메인 Claude가 직접 처리.4. 최후 수단 (선택): Claude Code Hook
위 3가지로 대부분 해결된다. 하지만 에이전트 시스템이 복잡하거나(4+ 에이전트, 병렬 비평 등) 반복적으로 폭주가 발생하면 물리적 차단을 추가할 수 있다.
Claude Code의 PreToolUse Hook은 도구 호출 전에 스크립트를 실행하고, deny를 반환해서 차단한다.
#!/bin/bash
# 세션 파일 크기로 컨텍스트 포화 감지
INPUT=$(cat)
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
SIZE_MB=$(( $(stat -f%z "$TRANSCRIPT") / 1048576 ))
if [[ $SIZE_MB -ge 6 ]]; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "세션 크기 초과. 새 세션에서 이어가세요."
}
}'
fi모든 도구 호출마다 스크립트가 돌아가므로 오버헤드가 있다. 필요할 때만 도입하자.
왜 "제한"이 아니라 "전략"인가
처음에는 직감적으로 제한을 걸었다. 그런데 적용하고 보니:
- "파일 10개 제한"은 더 깊이있는 호출에서 역효과 — 깊은 탐색이 필요한데 능력을 깎았다
- "overview → 순차 처리"는 동일한 효과를 내면서 능력은 보존 — 22개 파일을 다 읽되, 나눠서 읽었다
- 숫자 제한은 프로젝트마다 적정값이 다름 — 유지보수 비용이 높다
제한은 증상을 억누르고, 전략은 원인을 해결한다.
정리
| 구분 | 수단 | 필수 여부 |
|---|---|---|
| 전략 | overview → 그룹핑 → 순차 처리, Grep 먼저 Read 나중 | 필수 (가장 효과적) |
| 간소화 | 출력 형식 줄이기, 에이전트 간 I/O 규격 | 필수 |
| 안전장치 | 빌드 루프 3회 제한, 스폰 재시도 3회 | 필수 |
| 최후 수단 | PreToolUse Hook으로 물리적 차단 | 선택 |
에이전트 오케스트레이션은 "잘 돌아갈 때"만 설계하면 안 된다. 실패할 때 어떻게 멈추는가, 그리고 멈추는 방법이 에이전트의 능력을 깎지 않는가가 더 중요하다.
