route-scan 동작 상세
티어 기준과 리서치 근거는 TIER_CRITERIA.md에 있습니다. 이 문서는 룰 파일 구조, 스캔 트리거, 사전 준비 같은 운용 내용을 다룹니다.
티어 기준과 리서치 근거는 TIER_CRITERIA.md에 있습니다. 이 문서는 룰 파일 구조, 스캔 트리거, 사전 준비 같은 운용 내용을 다룹니다.
모델 피팅 래칫: 별도 파일에서 로그를 바탕으로 자동 갱신
승격된 위임 룰은 손으로 쓴 래칫 룰과 섞이지 않도록 별도 파일에 둡니다. 프로젝트 범위는 .claude/ratchet-model.md, 글로벌 범위는 ~/.claude/ratchet-model.md입니다. 이 파일은 전적으로 도구가 소유하므로 매 스캔마다 도구가 통째로 다시 쓰고, 그 뒤로도 계속 갱신됩니다.
- 자동 갱신: 스캔할 때마다 최신 로그로 반복 횟수와 해당 유형의 에러율을 다시 계산해 파일을 다시 씁니다. 통계가 바뀌어도 사용자의
ratchet.md는 건드리지 않으므로,.claude/를 커밋하는 프로젝트에서도 diff에 잡음이 생기지 않습니다.ratchet-model.md는 gitignore해도 무방합니다. 레지스트리에서 언제든 다시 만들 수 있기 때문입니다. - rule-health: 위임 대상 유형의 에러율이 20%를 넘으면 룰에
⚠ rule-health경고가 붙어, 조건을 좁히거나 룰을 제거하라고 알립니다. "난이도는 결과로 정의한다"는 원칙을 룰의 수명 관리에도 적용한 것입니다. 실제 위임 실행이 5건 이상 쌓인 룰은 형태로 짐작한 에러율 대신 그 실행들의 실측 에러율로 판정하며, 경고 문구에 어느 쪽 값인지 표시합니다. - 실측과 절감액: 서브에이전트 실행 기록(
<세션>/subagents/)을 읽어, 룰별 실제 위임 횟수와 에러율을 14일 윈도로 보여 줍니다. 세션 모델이 같은 일을 했을 때와 견준 절감액(~$)도 함께 표시하는데, 토큰량이 같다고 가정한 근사치입니다. 위임 기록이 없으면$0이 아니라—로 표시합니다. - 예산 문구: 룰마다 보정된 상한이 붙습니다. T2는 도구 호출 8회와 출력 p25, T1은 출력 p75입니다. 상한을 넘길 것으로 예상되거나 에러가 나면 서브에이전트가 멈추고 메인 모델이 이어받습니다. 룰이 요청 텍스트만 보고 발동해서 생기는 오판 비용에 상한을 두는 장치입니다.
- 상대 티어: 세션 모델이 이미 위임 목표와 같은 급이거나 그보다 낮으면 후보를 만들지 않습니다. Sonnet 세션에서 "sonnet 위임" 룰이 생기던 문제를 막기 위해서입니다.
- 사용자 룰은
harness list/rm으로, 모델 피팅 룰은route-scan rules [rm <N>]으로 각각 관리합니다. 두 명령은 서로의 파일도 인덱스도 건드리지 않습니다. harness init이 심는 CLAUDE.md 래칫 절이 두 파일을 모두 참조하므로, Claude가 세션에서 둘을 함께 적용합니다. 기존 사용자는harness init을 다시 실행하면 블록이 갱신됩니다.
동작 구조: 실시간 라우팅이 아니라 세션 경계 캘리브레이션
install이 SessionStart 훅을 등록하고, 이 훅이 새 세션을 시작할 때와/clear를 실행할 때 캐시된 스캔 결과를 세션 컨텍스트로 주입합니다. 재스캔 여부는 시간이 아니라 데이터를 조건으로 가립니다. 마지막 스캔 이후 새 transcript가 5MB 안팎으로 쌓이면 즉시, 소량이면 하루 한 번 돌고, 변화가 없으면 아예 돌지 않습니다. 변화 없는 재스캔은 결과가 같기 때문입니다. 최소 간격 1시간 가드도 있으며, 룰을 등록(promote)한 직후에는 통계 기준선을 확보하려고 즉시 한 번 돕니다.- 반복(3회 이상) 패턴이 있으면 statusline에
🅷⚠ route? R1칩이 뜨고, Claude가 등록할지와 범위(--project/--global)를 묻습니다. - 등록된 룰은 다음 세션부터 메인 모델이 해당 유형을 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)도 함께 등록해 힌트가 붙은 턴을 이어서 지켜봅니다.
- 재촉하는 때: 그 턴의 직접 조회(Read, Grep, Glob, LS, 읽기 전용 셸 명령)가 2회째에 이르면 안내를 한 번만 보냅니다. 안내에는 룰 이름과 힌트가 말한 위임 대상이 들어 있고, 남은 조회를 넘기거나 직접 계속하는 이유를 한 줄로 밝히라고 요청합니다.
- 계수를 멈추는 때: 그 턴에서 위임(
Task·Agent)하거나, 파일을 수정하거나, 상태를 바꾸는 셸 명령(git push,rm, 파일로의 리다이렉트,npm install등)을 실행했을 때입니다. 위임 호출의 PostToolUse 는 서브에이전트가 끝난 뒤에야 도착하므로, 같은 명령을Task·Agent의 PreToolUse 에도 등록해 위임이 시작되는 순간 계수를 멈춥니다. 그래야 서브에이전트가 하는 조회가 부모 턴의 조회로 잡히지 않습니다. - MCP·웹 조회(
mcp__*,WebFetch,WebSearch)도 셉니다. 룰의 에이전트에 그 도구가 없을 수 있어서, 안내는general-purpose(model: haiku)로 넘기라고 말합니다. - 측정:
route-scan rules가 룰마다 한 줄을 더 보여 줍니다. 최근 14일의 힌트 횟수, 즉시 위임, 재촉, 재촉 뒤 위임입니다. 이벤트는config.json옆의route-follow-events.jsonl에 쌓입니다. - 끄기:
config.json에"routeFollowUp": false를 넣습니다. 이 설정을 바꾸는 CLI 명령은 없습니다. Codex도 자체 훅으로 같은 후속 확인을 영어 안내로 받는데, Codex 위임 힌트를 켠 경우(sprag delegate on --agent codex)에만 동작합니다.
권장 사전 준비
~/.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입니다.
- T2 → haiku: 탐색과 조회, 붙여넣은 화면을 놓고 하는 질문, 단순 실행에 해당합니다. 에러가 없고 변경도 거의 없는 작업입니다.
- T1 → sonnet: 빌드 파이프라인과 상태 점검에 해당합니다. 변경이 적고 에러가 1건 이하인 작업입니다.
- T0 유지: 에러가 반복되거나 변경이 많거나 설계와 분석이 필요한 작업입니다. 세션 모델이 계속 담당합니다.
설계의 축은 세 가지입니다.
- 난이도를 텍스트로 추측하지 않고 결과로 판정합니다. 판정 근거는 도구 에러, 변경을 일으킨 도구 호출, 출력 토큰입니다.
- 임계값은 사용자의 최근 14일 로그 분포에 맞춰 자동으로 보정합니다. 고정된 상수는 워크로드가 바뀌면 곧 어긋나기 때문입니다.
- 승격된 룰은 도구가 소유한 파일(
.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이었습니다.
매핑은 이제 세 단계로 풀며, 비용이 적게 드는 단계부터 시도합니다.
- LiteLLM 게이트웨이이고
/model/info가 열려 있는 경우. 게이트웨이가 프로파일 ID(또는 ARN)와 모델명의 대응을 이미 알고 있으므로 따로 학습할 필요가 없습니다.sprag profile-map은 캐시된 매핑을 보여 줍니다. 출력에는 게이트웨이 주소와 배포 수, 그리고 항목마다<키> → <별칭>한 줄이 담깁니다.sprag profile-map --refresh는GET /model/info를 다시 호출해profile-map.json의gateway절만 갱신합니다. 이 새로 고침은 LiteLLM 예산 게이지를 갱신하는 자식 프로세스에서, 같은 주기로 실행됩니다. 5분마다 상태를 점검하고 캐시된 매핑에는 24시간 TTL이 붙으므로, 최신 상태를 유지하는 데 별도 호출이 들지 않습니다. - 이 경로가 없거나
/model/info가 막힌 게이트웨이인 경우. v3.10.0에서 도입한 방식이고, 그때와 달라진 것이 없습니다. 프로파일 ID를 역할(main·opus·sonnet·haiku)로 되돌린 다음,ANTHROPIC_DEFAULT_*_MODEL환경변수가 선언한 별칭으로 바꿉니다. 매핑은 부모 세션의Task호출과 그 호출이 띄운 서브에이전트 실행을toolUseId로 연결해 스스로 학습합니다. 관측이 3건 미만이거나 역할 투표가 80% 이상 일치하지 않으면 추측하지 않고unknown으로 남기며, 이 항목은 위임 집계에서 빠집니다. - 둘 다 해결하지 못하는 경우.
<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를 쓰는 환경에서는 이 과정이 아예 실행되지 않으며, 동작은 이전과 같습니다.