Sprag

route-scan 동작 상세

티어 기준과 리서치 근거는 TIER_CRITERIA.md에 있습니다. 이 문서는 룰 파일 구조, 스캔 트리거, 사전 준비 같은 운용 내용을 다룹니다.

티어 기준과 리서치 근거는 TIER_CRITERIA.md에 있습니다. 이 문서는 룰 파일 구조, 스캔 트리거, 사전 준비 같은 운용 내용을 다룹니다.

모델 피팅 래칫: 별도 파일에서 로그를 바탕으로 자동 갱신

승격된 위임 룰은 손으로 쓴 래칫 룰과 섞이지 않도록 별도 파일에 둡니다. 프로젝트 범위는 .claude/ratchet-model.md, 글로벌 범위는 ~/.claude/ratchet-model.md입니다. 이 파일은 전적으로 도구가 소유하므로 매 스캔마다 도구가 통째로 다시 쓰고, 그 뒤로도 계속 갱신됩니다.

동작 구조: 실시간 라우팅이 아니라 세션 경계 캘리브레이션

  1. install이 SessionStart 훅을 등록하고, 이 훅이 새 세션을 시작할 때와 /clear를 실행할 때 캐시된 스캔 결과를 세션 컨텍스트로 주입합니다. 재스캔 여부는 시간이 아니라 데이터를 조건으로 가립니다. 마지막 스캔 이후 새 transcript가 5MB 안팎으로 쌓이면 즉시, 소량이면 하루 한 번 돌고, 변화가 없으면 아예 돌지 않습니다. 변화 없는 재스캔은 결과가 같기 때문입니다. 최소 간격 1시간 가드도 있으며, 룰을 등록(promote)한 직후에는 통계 기준선을 확보하려고 즉시 한 번 돕니다.
  2. 반복(3회 이상) 패턴이 있으면 statusline에 🅷⚠ route? R1 칩이 뜨고, Claude가 등록할지와 범위(--project/--global)를 묻습니다.
  3. 등록된 룰은 다음 세션부터 메인 모델이 해당 유형을 haiku/sonnet 서브에이전트에 자동으로 위임하게 만듭니다.

위임이 실제로 실행되면 1번의 조건을 건너뛰고 바로 재스캔합니다. PostToolUse 훅이 Task·Agent 호출을 받아 백그라운드로 스캔을 띄우므로, 🔀 Routing saved 금액이 다음 렌더에 반영됩니다. 이 조건은 결과가 같을 스캔을 건너뛰자는 취지인데, 위임은 결과가 반드시 달라지는 사건입니다. 게다가 위임 한 건의 로그는 5MB에 한참 못 미쳐서, 조건에 맡겨 두면 짧게는 1시간, 길게는 하루를 기다려야 했습니다. 스캔은 실측 0.5초(14일·67MB 기준)이고 위임은 하루 평균 1.6회라서, 추가 비용은 하루 1초 미만입니다. 병렬 위임이 한꺼번에 끝나도 30초 하한 덕분에 스캔은 한 번만 돕니다.

위임 힌트 후속 확인

룰에 맞는 요청에는 그 턴에 위임 힌트가 붙습니다. 14일 실측에서 힌트가 붙은 100턴 중 위임한 턴은 22턴이었고, 나머지는 수정 없이 직접 조회를 2회 이상 했습니다. 그래서 install은 PostToolUse 훅(sprag brief --hook-tool)도 함께 등록해 힌트가 붙은 턴을 이어서 지켜봅니다.

권장 사전 준비

~/.claude/agents/에 model: haiku 서브에이전트(예: t2-explore, t2-runner, t2-translate)와 model: sonnet 범용 서브에이전트를 만들어 두면, 룰을 등록하자마자 바로 실행할 수 있습니다.

룰에는 카테고리와 티어(T2, T1, T1H)만 적고 에이전트 이름은 적지 않습니다. 프리셋의 위임 에이전트마다 맡는 tier와 categories(모든 카테고리면 *)가 있어서, Claude는 조건이 맞는 첫 에이전트에 위임합니다. 명령 실행은 t2-runner, 탐색·읽기·상태 확인·붙여넣은 로그는 t2-explore, T1은 t1-worker, T1H는 t1h-worker가 맡습니다. 그 에이전트 파일이 없으면 룰에는 model: <별칭>이 들어갑니다. Codex는 같은 티어를 읽고 그 티어에 매핑된 모델을 씁니다.

🔀 route-scan: "이 반복 작업은 더 싼 티어로 내려도 됩니다"

세션 로그에서 상위 모델(opus/fable)이 반복 처리해 온 쉬운 작업을 찾아 haiku/sonnet 위임 룰로 승격하자고 제안합니다. 전 과정이 로컬에서 돌아가고 토큰 비용은 0입니다.

설계의 축은 세 가지입니다.

  1. 난이도를 텍스트로 추측하지 않고 결과로 판정합니다. 판정 근거는 도구 에러, 변경을 일으킨 도구 호출, 출력 토큰입니다.
  2. 임계값은 사용자의 최근 14일 로그 분포에 맞춰 자동으로 보정합니다. 고정된 상수는 워크로드가 바뀌면 곧 어긋나기 때문입니다.
  3. 승격된 룰은 도구가 소유한 파일(.claude/ratchet-model.md)에 두며, 이 파일은 스캔할 때마다 스스로 갱신됩니다. 위임한 유형의 에러율이 오르면 ⚠ rule-health 경고가 뜨므로, 룰이 낡았다는 사실을 룰이 직접 알리는 셈입니다.
sprag route-scan                    # 스캔 (24h 캐시) + 티어별 후보 출력
sprag harness promote R1 --project  # 후보 R1을 모델 피팅 룰로 등록
sprag route-scan dismiss 1          # 관심 없으면 무시 (재스캔에도 안 뜸)
sprag route-scan rules              # 등록된 모델 피팅 룰 목록 (rm <N>으로 제거)
sprag route-scan savings            # 절감 원장: 어느 룰이 어떤 모델에서 어떤 모델로 옮겼는지

route-scan savings는 statusline의 🔀 Routing saved 한 줄 뒤에 있는 근거를 그대로 보여 줍니다. 모델 이동별 합계와 실행별 내역이 함께 나오므로, 금액이 어디서 나왔는지 추적할 수 있습니다.

🔀 라우팅 절감 누적 $2.09  (최근 7일 $1.40 · 30일 $2.09)

모델 이동별:
  claude-fable-5 → claude-sonnet-5  —  1회, $0.72
  claude-opus-5 → claude-haiku-4-5  —  1회, $0.57

티어 기준과 리서치 근거는 TIER_CRITERIA.md에 있고, 룰 파일 구조와 스캔 트리거, 서브에이전트 준비는 이 문서의 앞부분에 있습니다.

게이트웨이(Bedrock·LiteLLM) 경유 환경

사내 게이트웨이를 거치면 로그의 모델명 필드에 추론 프로파일 ARN이 기록됩니다. 그 문자열에는 opus나 haiku 같은 단서가 없어서, 예전 버전은 모든 세션을 Sonnet으로 읽었습니다. 그 결과 T1(→sonnet) 위임 룰이 하나도 제안되지 않았고, 절감 집계는 0이었습니다.

매핑은 이제 세 단계로 풀며, 비용이 적게 드는 단계부터 시도합니다.

  1. LiteLLM 게이트웨이이고 /model/info가 열려 있는 경우. 게이트웨이가 프로파일 ID(또는 ARN)와 모델명의 대응을 이미 알고 있으므로 따로 학습할 필요가 없습니다. sprag profile-map은 캐시된 매핑을 보여 줍니다. 출력에는 게이트웨이 주소와 배포 수, 그리고 항목마다 <키> → <별칭> 한 줄이 담깁니다. sprag profile-map --refresh는 GET /model/info를 다시 호출해 profile-map.json의 gateway 절만 갱신합니다. 이 새로 고침은 LiteLLM 예산 게이지를 갱신하는 자식 프로세스에서, 같은 주기로 실행됩니다. 5분마다 상태를 점검하고 캐시된 매핑에는 24시간 TTL이 붙으므로, 최신 상태를 유지하는 데 별도 호출이 들지 않습니다.
  2. 이 경로가 없거나 /model/info가 막힌 게이트웨이인 경우. v3.10.0에서 도입한 방식이고, 그때와 달라진 것이 없습니다. 프로파일 ID를 역할(main·opus·sonnet·haiku)로 되돌린 다음, ANTHROPIC_DEFAULT_*_MODEL 환경변수가 선언한 별칭으로 바꿉니다. 매핑은 부모 세션의 Task 호출과 그 호출이 띄운 서브에이전트 실행을 toolUseId로 연결해 스스로 학습합니다. 관측이 3건 미만이거나 역할 투표가 80% 이상 일치하지 않으면 추측하지 않고 unknown으로 남기며, 이 항목은 위임 집계에서 빠집니다.
  3. 둘 다 해결하지 못하는 경우. <userDataDir>/profile-map.json에 매핑을 직접 적습니다. 계정 ID와 리전은 *로 가려도 매칭됩니다.
{
  "modelAliases": {
    "arn:aws:bedrock:*:*:application-inference-profile/<PROFILE_ID>": "claude-opus-5",
    "prod-large": "claude-opus-5",   // 사내 별칭도 같은 방식으로 매핑됩니다
    "team-*": "claude-haiku-4-5"
  }
}

모델명에 opus·sonnet·haiku·fable이 들어 있지 않은 사내 별칭(prod-large, team-fast 등)도 modelAliases에 적으십시오. sprag profile-map은 게이트웨이에서 해석하지 못한 키를 함께 알려 주므로, 직접 채워야 할 항목을 그 목록에서 바로 확인할 수 있습니다. Bedrock(anthropic.claude-opus-4-5-v1:0), Vertex(claude-opus-4-5@20251101), 1M 접미사(claude-sonnet-4-5[1m])처럼 계열명이 남아 있는 형태는 그대로 인식합니다. 계열명이 없는 별칭은 가격을 알 수 없습니다. 그래서 라우팅 절감 계산은 틀린 금액을 내놓는 대신 그 실행을 집계에서 제외합니다(비교하는 양쪽 모두 이름을 알아볼 수 있어야 하기 때문입니다). modelAliases에 한 줄을 추가하면 그 실행이 다시 집계에 들어옵니다.

sprag는 인증 토큰을 저장하지 않습니다. 1번 단계의 갱신은 호출 시점에 apiKeyHelper에서 토큰을 받아 /model/info 요청 한 번에만 쓰고, 사본을 남기지 않습니다. 토큰의 수명은 헬퍼가 관리하는데, sprag가 사본을 캐시에 두면 그 수명과 어긋나기 때문입니다. profile-map.json에는 프로파일 ID와 모델 별칭만 들어가고 AWS 계정 ID는 들어가지 않습니다. 그래도 사내 식별자가 평문으로 남으므로 저장소에 커밋하지 마십시오. 직접 API를 쓰는 환경에서는 이 과정이 아예 실행되지 않으며, 동작은 이전과 같습니다.

다른 문서