운영 파라미터 가이드

자율 모드 에스컬레이션의 "예산 초과 신호" 임계값을 관리한다. 규칙 본문(`core/04-lifecycle.md`)에 하드코딩하지 않는 이유와, 환경별 튜닝 방법을 정의한다.

guide 2026-04-15 docs/guide/AGENT_BUDGET.md

작성일: 2026-04-15 목적: 자율 모드 에스컬레이션의 "예산 초과 신호" 임계값을 관리한다. 규칙 본문(core/04-lifecycle.md)에 하드코딩하지 않는 이유와, 환경별 튜닝 방법을 정의한다.

1. 왜 규칙 본문에 하드코딩하지 않는가

core/04-lifecycle.md 의 "예산 초과 신호" 섹션은 아래 3가지 신호를 추상화로만 정의한다.

토큰 예산 초과
시간 예산 초과
반복 탐색 감지

구체 임계값은 아래 이유로 규칙 파일에서 분리한다.

모델별 차이 — Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 의 토큰 소비 속도가 다르다
도구별 차이 — MCP 서버, 웹 검색, 서브에이전트 호출 유무에 따라 변동 폭이 크다
환경별 차이 — 대규모 모노레포와 소규모 스크립트 프로젝트의 합리적 상한이 같을 수 없다
운영 중 튜닝 — 규칙 파일은 설계 합의의 결과이지, 숫자 조정의 대상이 아니다

따라서 구체 숫자는 .claude/agent-budget.yaml 운영 파라미터 파일에서 관리한다.

2. 파라미터 파일 위치

프로젝트 루트 기준: .claude/agent-budget.yaml

에이전트는 자율 모드 실행 중 이 파일을 읽고, 아래 3가지 신호 임계값과 비교한다. 파일이 없으면 본 문서의 기본값을 적용한다.

3. 기본값과 설계 근거

# .claude/agent-budget.yaml (기본값)

# 단일 작업에 허용되는 토큰 예산
token_budget_per_task: 100000

# 단일 작업에 허용되는 실시간 시간(초)
time_budget_seconds: 120

# 동일 영역(파일/디렉토리)을 재탐색할 수 있는 최대 횟수
# 이 횟수를 초과하면 무한 루프로 간주
repeated_exploration_limit: 3

근거

항목	기본값	설계 근거
`token_budget_per_task`	100000	CrewAI manager-worker 표준(100K tokens) 채택. Opus 4.6 기준 중규모 리팩토링 한 번에 해당하는 수준
`time_budget_seconds`	120	2분. 사용자 인지적 "한 작업"의 상한에 가까운 값. 이보다 길면 세션 단위 재설계가 필요하다는 신호
`repeated_exploration_limit`	3	L1 self-retry 의 "최대 2회" 와 정합. 재탐색 3회차부터 무한 루프 의심

4. 튜닝 가이드 (환경별)

4.1 소규모 스크립트 프로젝트 (1~5 파일 변경이 일반적)

token_budget_per_task: 50000      # 기본의 절반
time_budget_seconds: 60           # 1분
repeated_exploration_limit: 2     # 탐색 자체가 짧아야 함

4.2 대규모 모노레포 (다수 패키지 크로스 변경)

token_budget_per_task: 200000     # 기본의 2배
time_budget_seconds: 300          # 5분
repeated_exploration_limit: 5     # 패키지 간 연관 탐색 허용

4.3 Haiku 같은 경량 모델 executor

token_budget_per_task: 150000     # 경량 모델은 더 많이 시도해도 비용이 적음
time_budget_seconds: 180          # 응답 시간이 더 빠르므로 상한도 확장
repeated_exploration_limit: 3     # 동일

값을 올리기 전에, 먼저 L1 self-retry 가 2회 제한에 자주 걸리는지부터 확인한다. 토큰/시간이 부족한 게 아니라 문제 정의가 불명확한 경우가 더 많기 때문이다.

5. 예산 초과 시의 동작

core/04-lifecycle.md 의 에스컬레이션 경로 규칙에 따라, 예산 초과 신호 중 하나라도 발생하면 L1/L2 를 건너뛰고 L3 (human handoff) 으로 즉시 전환한다.

HANDOFF blocked: 블록 예시:

blocked:
  - problem: "리팩토링 중 토큰 예산 초과"
    attempts:
      - "L1: 2회 재시도 모두 tsc 에러 해결 실패"
      - "예산 초과 신호 감지 — token_budget_per_task(100000) 초과"
    recommendations:
      - "option_A: 범위를 auth 모듈로만 축소 | risk: R0 | rationale: 토큰 절반 수준"
      - "option_B: 원래 범위 유지, Opus 에서 재시도 | risk: R0 | rationale: 모델 업그레이드로 토큰 효율 개선"
    agent_recommendation: option_A — 범위 축소가 더 빠른 완료를 보장
    why_human_needed: 범위 축소 결정은 제품 우선순위 판단

6. 관련 문서

core/04-lifecycle.md — 자율 모드 에스컬레이션 경로 (L1~L3)
core/03-security.md — R1/R2 가역성 등급 및 확인 문구 정책
docs/guide/AGENT_OPERATING_MODEL.md — 에이전트 팀 운영 모델 전반
docs/guide/AGENT_AUTONOMY_COMPARISON.md — 자율성 수준 비교

7. 향후 확장 (미구현)

다음 파라미터는 현재 규칙에 반영되지 않았으나, 팀 확장 또는 운영 데이터 축적 후 추가 검토한다.

peer_consult_timeout_seconds — L2 peer 호출 시 응답 대기 상한
handoff_recommendations_min / handoff_recommendations_max — 추천안 개수 범위 (현재 "최소 1, 최대 2~3" 은 규칙 본문에만)
cost_budget_per_session — API 비용 기준 상한 (토큰 대신 달러 기준)