레이트리밋 스로틀 거버너 + 울트라 기본 세팅

개요

19개 세션 + 울트라 병렬 fan-out으로 동시 Claude API 호출이 폭증해 레이트리밋이 걸리는 문제를 해결한다. "약간 느리더라도 절대 안 걸림"을 목표로, 티어별 동시한도 게이트 + 4상 AIMD(걸리면 반감·풀리면 점증) 거버너를 구축했다. 동시에 울트라 병렬/딥리서치를 전 세션 기본-on으로, 모델 분업을 사용자 확정대로 고정했다.

무엇을 했는지

1. 스로틀 거버너 (레이트리밋 회피 핵심)

결정 코어 ~/.claude/skills/분별/스로틀.한선 — 순수 4상 의사결정(티=즉시/옴=페이싱/타=큐/음=백오프) + AIMD 조정. 컴파일 OK(20.9KB), 단위테스트 7/7 통과.

거버너 CLI ~/.claude/scripts/crowny-throttle.sh — 티어별(opus/sonnet/haiku/fable = 각각 다른 레이트리밋 버킷) 동시한도 슬롯 게이트. 원자적 슬롯 확보/해제/만료(300s TTL).

gate <tier> 슬롯 날 때까지 블로킹 / acquire 비블로킹 / release / heartbeat

penalize <tier> 429 감지 → 한도 반감 + 전역 백오프 45s(/tmp/crowny-throttle/last429 전 세션 공유)

ok <tier> 성공 누적 → 한도 +1 회복(429 후 120s 지난 뒤만, 오실레이션 방지)

status 전 티어 4상 현황

웨이브 게이트 ~/.claude/scripts/crowny-throttle-wave.sh — 울트라 병렬 fan-out 전 N슬롯 확보까지 블로킹, 태그 일괄 해제. E2E 검증(5확보→해제).

기본 동시한도(상한): opus 3(6) · sonnet 6(12) · haiku 10(20) · fable 2(3).

2. 울트라 기본 세팅 (전 세션 표준)

• 표준 문서 ~/.claude/skills/분별/울트라기본.md — 울트라 병렬은 분해 가능하면 항상, 딥리서치는 필요하면 항상. 스로틀 결합 패턴 4종(웨이브 크기 맞춤, haiku 대량분산, 429 즉시 penalize, 세션시작 gate).
• 글로벌 ~/.claude/CLAUDE.md + 분별 SKILL.md 상시권한 섹션에 연결.

3. 모델 분업 고정 (사용자 2026-06-14 확정)

• ~/.claude/skills/분별/분업규칙.psv에 추가: 아키텍팅/울트라병렬조율/자율주도작업=opus, 딥리서치종합=fable, 단순코딩=sonnet, 글밥빠른작업=haiku. (자율주도 최고난도는 fable)
• 6개 신규 유형 조회 검증 통과. 모델 티어 분산 = 레이트리밋 버킷 분산.

관련 파일 경로

• ~/.claude/skills/분별/스로틀.한선 (결정 코어)
• ~/.claude/scripts/crowny-throttle.sh (거버너 CLI)
• ~/.claude/scripts/crowny-throttle-wave.sh (웨이브 게이트)
• ~/.claude/skills/분별/울트라기본.md (표준 문서)
• ~/.claude/skills/분별/분업규칙.psv (모델 SSOT)
• 기존 ~/.claude/scripts/crowny-ratelimit.sh — 단순 슬롯 스케줄러(opt-in, 미사용). 스로틀이 티어/AIMD/백오프로 상위호환.

4. PreToolUse 소프트 집행 훅 (2026-06-14 추가 — 사용자 yes)

~/.claude/scripts/crowny-throttle-hook.sh — settings.json PreToolUse(Write|Edit|Bash, timeout 6000ms)에 멱등 연결.

① 429 자동감지: 현재 세션 트랜스크립트의 새로 추가된 바이트만 JSON 파싱해 진짜 에러 레코드(type=system & subtype=api_error, isApiErrorMessage, message.model=<synthetic>)만 판별 → penalize 자동 호출. bare 문자열 grep 금지(대화/스크립트에 적힌 literal "rate_limit"이 중첩 text 필드라 오탐) — 최상위 구조 필드만 신뢰. 바이트크기 dedup으로 같은 429 재발동 차단.

② 소프트 페이싱: 전역 백오프(429 후 45s) 활성 중이면 도구 호출당 최대 2초만 sleep → 세션 자연 감속. 무한 블로킹 없음(wedge 방지), 백오프 지나면 자동 소멸.

검증: 텍스트 오염 라인=무반응, 진짜 api_error/synthetic 레코드=penalize+백오프, 첫 실행=기준선만. 4/4 통과.

잔여 이슈

• 세션 단위 하드 강제(슬롯 미확보 시 도구 차단)는 wedge 위험으로 채택 안 함 — 소프트 페이싱으로 대체(의도된 설계).
• synthetic rate_limit 레코드는 실제 모델 불명 → opus(최빡) 폴백 penalize. 전역 백오프가 주 보호라 영향 미미.
• crowny-ratelimit.sh(구 단순 스케줄러)를 스로틀 별칭으로 흡수 통합 검토.