Jev 라우팅 정책 (Claude Code)

~/.codex/AGENTS.md의 Jev 우선 정책을 Claude Code 도구 이름에 맞춰 옮긴 것이다. CLI는 ~/.local/bin/에 있고 ~/.local/share/codex-token-tools/를 공유한다 — 에이전트 중립이므로 Codex와 같은 것을 쓴다.

기본 원칙

작은 작업은 요청·대상·검증만 정해 바로 처리한다. 사실·캐시·종료코드는 코드로 얻고, 복잡한 작업만 최대 5단계로 계획한다. 기존 지침·Git 변경을 보존하고 필요한 설정만 확인한다. 같은 조사·캐시·출력을 모델에 반복 입력하지 않는다.

모든 별도 선택형 의미 판단은 Jev에 먼저 맡긴다. 사실 확인·코드 작성·필수 분석·안전 정책은 그대로 모델이 유지한다. Jev가 UNKNOWN을 반환하면 그것을 모델 결론으로 바꾸지 않는다. 실패·차단을 우회하지 않는다.

판단 위임

원문·출처·UNKNOWN·오류·제약은 항상 보존한다. 결과 판정도 Jev에 맡기고, 원본 로그·종료코드를 조작하지 않는다.

판단은 남기고 텍스트로 발행하지 않는다 (jev-mode)

경계 있는 의미 판단이 5개 이상 반복되면 그걸 내 컨텍스트에서 결정하지 않는다. 자세한 절차는 jev-mode 스킬.

• 항목 텍스트를 컨텍스트에 들이지 않는다. 코드로 읽고, 코드로 요청을 만들고, 개수만 출력한다. 절감의 대부분이 여기서 나온다.
• 호출당 레코드 하나. 배열 state는 하나의 읽기로 뭉개진다.
• 여러 atomic 질문을 argmax로 재조합하지 말고, 짧고 결정적인 규칙을 담은 choice 질문 하나를 쓴다.
• 답의 조합(가중치·임계값)은 코드가 소유한다. confidence가 낮으면 조용히 수용하지 말고 더 날카로운 criteria로 2차 패스한다.
• 쓰지 않는 것: 산문, 코드 작성, 설명, 산술, 개수 세기, 크기 비교, 날짜 비교.

서브에이전트에게 Jev를 쓰라고 산문으로 시키면 거의 안 쓴다(측정: Explore에 산문 지시 → Jev 0회·6분 21초). 강제 수단은 둘뿐이다.

• 워크플로 에이전트: 출력 스키마에 Jev 출력 원문을 담는 required 필드 (102/102 호출).
• Agent 도구 에이전트: 스키마가 없으니 커스텀 에이전트 frontmatter의 PreToolUse 훅 (jev-scout). 이 훅은 서브에이전트 안에서 자기 agent_id로 실행된다(2026-09-22 검증).
• 내장 Explore·Plan은 이 CLAUDE.md를 받지 않는다. SubagentStop은 exit 2를 무시해 종료를 막지 못한다.

출력 규율 — 토큰의 77%가 여기서 나간다

측정값(2026-09-20): Messages 206k / System tools 24k / MCP 22k / Skills 10k. MCP·스킬을 전부 지워도 12%다. 비용은 도구 출력이므로 규율도 거기에 건다.

• 의심 구간 좁히기(원인·호출부·상태 변경 위치 찾기)는 위임하지 않고 부모가 직접 python3 ~/.claude/jev/locate.py "<찾을 것>" --root <저장소> --keywords 'a|b' 를 부르고, 출력된 범위만 읽는다(7.3초 대 Explore 위임 6분). 꼭 위임하면 Explore 말고 jev-scout.
• Explore는 결론 서술이 필요한 조사에만 위임한다 — 여러 파일을 훑어 "어떻게 동작하는가"를 정리해야 할 때. 서브에이전트는 결론만 돌려주고 파일 덤프는 내 컨텍스트에 안 남는다. 파일·심볼을 이미 아는 단건 조회는 직접 한다.
• 조회·Git·검색 출력은 명령마다 head -c 4000 / tail -c 4000. 목록은 head -N으로 자른다.
• Read는 필요한 구간만 — 파일 전체를 읽지 말고 offset/limit을 쓴다.
• 편집 후 재확인 금지. 실패했으면 Edit/Write가 에러를 냈다. 하네스가 파일 상태를 추적한다.
• 이미 컨텍스트에 있는 내용을 다시 붙여넣지 않는다. 같은 조사·캐시·로그를 반복 입력하지 않는다.
• 원문 대신 판단을 남긴다 — 경계 있는 판단 5개 이상이면 위 jev-mode 규칙.
• 답변에 확신도 숫자를 지어내지 않는다. 보정된 확신도는 Jev만 낸다(jev-judge, ~/.claude/jev/jevq.py). 실측(2026-09-22): Claude에게 판정 · 확신도 · 근거 형식을 강제하자 소스를 읽지 않고 0.85를 붙인 오답이 나왔다. 서술 억제는 내장 Concise 출력 스타일로 한다 — 출력 토큰 -18%, 6/6 정답.

서브에이전트 모델 라우팅

부모 모델을 자식이 그대로 물려받으면 비싸다. Fable 5.1/Opus로 울트라코드·워크플로를 돌릴 때 에이전트 다수가 부모 티어로 떠서 소모가 급증한다. 그래서 티어를 명시한다.

• ~/gameforge/plugins/gameforge/agents/*.md의 model:은 Jev 판단으로 고정돼 있다 (game-designer=opus, 나머지 4개=sonnet). inherit로 되돌리지 않는다.
• 정의가 없는 일회성 Agent 호출은 model을 명시한다. 판단이 서면 Jev에 묻는다:

  jev-mode ask --state-file <작업설명파일> --questions-file ~/.claude/jev/agent-tier.json

  haiku=절차 실행·관찰·대조 / sonnet=구현·리뷰·규칙적용 / opus=충돌하는 제약 속 설계·되돌리기 어려운 방향 결정. confidence가 0.7 미만이면 조용히 수용하지 말고 더 날카로운 기준으로 2차 패스한다.
• subagent_type: "fork"는 model이 무시된다 — 포크는 항상 부모 모델을 쓴다. 비싼 부모일 때 포크를 남발하지 않는다.

검색

좁은 검색(알려진 파일·정확한 심볼·작은 작업)은 Grep/rg. 많은 구절이 나올 넓은 관련성 검색은 mcp__jev_context__search_code — ripgrep 후보를 컨텍스트에 넣기 전에 Jev가 걸러 Yes만 돌려준다. 자세한 규칙은 jev-code-search 스킬.

• 걸러지지 않은 검색을 먼저 돌리고 그 결과를 넘기지 않는다 — 절감이 사라진다.
• repository_root는 매 호출 절대경로로 명시한다. 서버 작업 디렉터리나 이전 작업에서 추론하지 않는다.
• 빈 결과는 "통과한 후보 없음"이지 "증거 없음"이 아니다. 질의·목표를 다듬는다. 무관한 파일·생성물·의존성은 제외한다.

브라우저·UI 조작

브라우저는 활성 aside-browser를 우선한다. 허용된 반복 조작은 jev-action-control 스킬의 Aside·macOS·iOS 실행기에 이양한다. 판단만 요청받았으면 실행하지 않는다. 정확성·기능·테스트·안전성·필수 분석은 유지한다.

서브에이전트 위임

모든 서브에이전트·Aside 위임에 이 규칙과 작업 범위·결과 형식을 직접 전달한다. 전체 이력 대신 필요한 파일·사실만 준다. 판단은 선택값으로, 작업은 변경·검증·주의만 받는다. 기존 자식에게도 갱신 규칙을 전달하고, 위반·누락 시 필요한 부분만 보정한다. 관련 수정·가까운 검증을 묶으며, 설명·최종 보고에 원문·로그·반복 해설을 넣지 않는다.

Claude Code에서 쓸 수 없는 것 (Codex 전용)

• jev-session-read — Codex rollout JSONL(response_item) 스키마 전용. Claude Code transcript(~/.claude/projects/*/*.jsonl)에 대해서는 오류 없이 0 records를 반환하므로 "확인했다"고 착각하기 쉽다. 쓰지 않는다.
• jev-browser-use — cua_repl 런타임을 요구한다. Claude Code 브라우저 연동은 미지원.
• jev-codex / jev-gateway-codex — Codex 모델 라우터·툴 게이트웨이. Claude Code에는 해당 경로가 없다.

기능 토글

~/.local/share/codex-token-tools/features.json; jev-features disable <기능명>으로 끈다.