Claude Code 라우팅 매트릭스를 글로벌 CLAUDE.md 와 SKILL.md 에 박은 회고

한 줄로 끝낸 처방이 마음에 걸렸습니다

지난 글 Claude Code 사용 패턴, transcript jsonl 로 직접 진단해봤습니다 의 마지막에 측정 후 처방 세 가지를 적어두고 끝냈습니다. 그 중 1번이 "general-purpose 호출 비중이 높다면 전문 에이전트로 명시 위임 한다" 였는데, 막상 적고 보니 한 줄로 끝낼 일이 아니었습니다. 어디에, 어떻게 박아야 다음 호출부터 실제로 반영되는가 — 그게 더 중요한 회고였습니다.

이번 글은 그 처방을 어디에 어떻게 박았는가에 대한 짧은 후속편입니다. 결과적으로 두 곳에 박았고, 일부러 한 곳에는 박지 않은 이유까지 함께 정리해두려고 합니다. 효과는 1주~2주 후 transcript 를 다시 들여다본 다음에야 단정할 수 있을 것 같아, 지금 글에서는 어디까지나 지점 선택의 근거까지만 적어두기로 했습니다.

메모리에 적기만 해서는 스킬 분기 안까지 도달하지 않습니다

처음에는 Claude Code 의 글로벌 메모리, 즉 ~/.claude/CLAUDE.md 에 한 줄 추가하면 끝나는 일이라고 생각했습니다. 메인 에이전트는 이 파일을 매 turn 시스템 프롬프트로 보니까, 거기에 "전문 에이전트 우선" 만 적어두면 다음부터는 알아서 골라 부를 것이라고 막연히 기대한 것입니다.

그런데 비슷한 패턴에서 이미 어긋난 사례가 있었습니다. 2026-05-05 부터 ChatGPT Pro 구독이 만료되어 codex 위임을 임시 비활성화했고, 글로벌 CLAUDE.md 의 "Codex 위임" 박스에도 그 사실을 박아두었습니다. 그럼에도 불구하고 7일치 transcript 를 들여다보니, 메인 세션에서 24건, review-loop sidechain 안에서 45건이 여전히 codex:codex-rescue 호출 후 (Subagent completed but returned no output.) 로 silent fail 하고 있었습니다.

이유를 곰곰이 생각해보니 단순했습니다. 메인 에이전트는 글로벌 CLAUDE.md 를 시스템 프롬프트로 보지만, 스킬 SKILL.md 안의 분기는 그것과 별개의 default 를 갖고 있습니다. 스킬 본문에서 "subagent_type 을 따로 명시하지 않으면 codex 부터" 식으로 적혀 있으면, 메모리 룰이 그 분기까지는 도달하지 않습니다. 같은 룰을 호출 지점마다 박아야 한다는 사실을 데이터로 다시 확인한 셈입니다.

조치 1 — 글로벌 CLAUDE.md 에 ground truth 박스

먼저 ~/.claude/CLAUDE.md 안 "Codex silent fail + 자동 폴백" 박스 바로 아래에 ## Sub-agent 라우팅 정책 박스를 추가했습니다. 이 박스는 메인 에이전트가 sub-agent 를 spawn 할 때 보는 모든 turn 시스템 프롬프트로 들어가니까, 일단 한 곳에는 ground truth 가 있어야겠다는 판단이었습니다.

박스의 구성은 사유 한 단락 + 매트릭스 표 + 적용 룰 + 안티패턴 + 단일 source of truth 룰 순서로 잡았습니다. 사유에는 지난 글에서 jq 한 줄로 잰 수치를 그대로 옮겨두었습니다. 메인 에이전트 Agent 호출 중 general-purpose 비중 40%, review-loop sidechain 안에서는 69% 가 그 수치입니다. 이 두 숫자가 박스의 근거가 되어 주어야, 나중에 룰이 흔들릴 때 다시 돌아볼 자리가 생기겠다고 생각했습니다.

매트릭스는 모두 24행입니다. 그 중 본문에서 자주 부딪히는 행만 추리면 다음과 같습니다. 전체 24행은 위 박스에 그대로 들어 있고, 본문에는 골격만 옮겨둡니다.

작업 영역	추천 subagent_type
NestJS API/스키마 — 구현	backend-dev
Next.js·React·admin — 구현	frontend-dev
모노레포 라이브러리 (core·adapters·tools)	architecture-reviewer
Dockerfile, CI/CD, CORS·CSP·env, 인증/인가	security-auditor
유닛/E2E/API 테스트	unit-test-dev / e2e-test-dev / api-test-dev
리서치 (시장·웹·학술·커뮤니티)	service-researcher 외 3종
GA4 / GSC 분석	traffic-analyst / search-analyst
블로그 초안 / SEO	blog-writer / seo-reviewer
광범위한 코드베이스 탐색	Explore (빌트인)
다단계 구현 계획 수립	Plan (빌트인)
단순 grep / find (3 쿼리 이하)	Bash 직접 — Agent 호출 X
위 어느 행에도 매칭 안 됨	general-purpose (fallback)

적용 룰에는 다섯 가지를 넣었습니다. 첫째, 호출 직전에 1초만 매트릭스 매칭을 시도해보고 매칭되면 specialized 를 쓴다. 둘째, 다중 영역 작업은 메인 영역 1건으로 통합한다. 셋째, research 류는 병렬 호출이 설계 의도이니 한 메시지에 묶어 보낸다. 넷째, fallback 으로 general-purpose 를 쓸 수밖에 없으면 prompt 첫 줄에 "이 작업 영역: <영역>. 매트릭스 미매칭으로 general-purpose 라우팅됨" 을 명시한다. 다섯째, codex 사용 금지 룰은 그대로 유효하다.

조치 2 — review-loop SKILL.md 본문 박스

두 번째로 손본 곳은 ~/.claude/skills/review-loop/SKILL.md 입니다. 위에서 정리한 것처럼, 메모리 룰만으로는 스킬 분기 안까지 도달하지 않으니 review-loop 본문에도 박스를 직접 박아야 했습니다. 마침 sidechain 의 general-purpose 비중 69% 가 가장 큰 출처이기도 했습니다.

본문 상단에 ## 도구 활용 정책 이라는 박스를 두고, 두 가지 정책을 명시했습니다. 하나는 codex:* 사용 금지 — 본 스킬 안에서는 [codex-fallback] magic token 도 트리거하지 않는다. 또 하나는 PR 변경 영역별 specialized 라우팅 으로, 영역 한정 매트릭스 7행입니다.

라우팅 결정 시점은 단일 모드 Phase 2 Step 2.1 직전 / 병렬 모드 Phase 2 직전으로 묶어두었습니다. PR 번호가 정해진 시점이라, 그 자리에서 한 줄이면 영역을 추출할 수 있습니다.

gh pr view {NUMBER} --json files --jq '.files[].path' \
  | awk -F/ '{print $1"/"$2}' | sort -u

이 결과를 매트릭스 7행에 매칭하는 방식입니다. packages/backend/** 면 리뷰는 code-quality-reviewer, 수정은 backend-dev. 웹·admin·creator-flow 면 리뷰는 동일하고 수정만 frontend-dev. core·adapters·tools 면 architecture-reviewer. Dockerfile·workflows·env 면 security-auditor. 테스트만 바뀐 PR 이면 해당 *-test-dev. 다중 영역이면 code-quality-reviewer 한 건으로 통합. 어느 행에도 안 맞으면 그제서야 general-purpose 로 fallback 하되, prompt 첫 줄에 영역을 명시합니다.

두 곳에 같은 매트릭스를 인라인 복제하지는 않았습니다

여기서 한 가지 결정이 필요했습니다. 같은 매트릭스를 두 곳에 다 적어두면, 한쪽이 바뀔 때 다른 쪽이 조용히 stale 됩니다. 그래서 단일 source of truth 룰을 같이 박아두기로 했습니다.

글로벌 CLAUDE.md 박스는 24행 전체를 담는 ground truth 로 두고, review-loop SKILL.md 박스는 PR 변경 파일 영역에 매칭하기 좋은 7행만 두었습니다. SKILL.md 본문에는 "본 박스를 참조하거나, 영역 한정 매트릭스만 본문에 두고 본 박스를 ground truth 로 가리킨다" 라고 적어두어, 추후 동기화 필요 시 어느 쪽이 우선인지 헷갈리지 않게 했습니다. 두 곳을 다 적어두는 편이 안전해 보였지만, 운영해보니 stale 한 매트릭스가 안 적힌 매트릭스보다 더 위험하다는 생각이 들어서였습니다.

왜 hook 으로 강제하지 않았는가

박스로 박는 대신 PreToolUse:Agent hook 으로 강제할 수도 있었습니다. 실제로 codex silent fail 자동 폴백 hook (~/.claude/hooks/codex-state-allow.sh) 이 비슷한 패턴으로 이미 돌고 있습니다. 그럼에도 이번에는 hook 까지 가지 않았습니다.

이유는 두 가지였습니다. 첫째, hook 은 잘못 짜면 정상 호출까지 차단합니다. specialized 가 명시되지 않은 모든 Agent 호출을 일률 차단해버리면, 빌트인 Explore·Plan 같은 호출까지 영향받을 위험이 있었습니다. 둘째, 박스 룰을 시스템 프롬프트와 스킬 본문으로 박아두면 그 자체가 1주일 후 재진단의 비교군이 되어줍니다. 박스만으로 어디까지 잡히는지 먼저 측정해보고, 잔존 케이스가 명확해진 다음에 그 패턴만 hook 으로 잡는 편이 운영 부담이 작겠다고 판단했습니다.

정리하면 단계적 강제입니다. prompt 가드 → SKILL.md 본문 박스 → 글로벌 CLAUDE.md 박스 → (1주 후 재진단) → 필요하면 hook. 처음부터 hook 으로 가지 않은 것은 효과 측정의 여지를 남겨두기 위해서였습니다.

다음에 측정해볼 것 — fallback 도 자산입니다

1주~2주 후 transcript-diagnose 를 다시 돌려서 봐야 할 수치는 네 가지로 추렸습니다. 첫째, 메인 Agent 호출 중 general-purpose 비중이 40% 에서 20% 이하로 내려오는가. 둘째, review-loop 내부 sub-agent 분포에서 69% 가 30% 이하로 내려오는가. 셋째, specialized 호출이 매트릭스 행에 골고루 분산되는가 — 현재는 backend-dev 와 code-quality-reviewer 두 행에 집중되어 있어, 다른 행이 dormant 인지 매트릭스 자체가 편향인지 구분이 필요합니다.

네 번째가 의외로 중요했습니다. fallback 으로 흘러간 general-purpose 호출 prompt 에 "이 작업 영역: <영역>. 매트릭스 미매칭으로 general-purpose 라우팅됨" 이 들어가 있는지 — 이 한 줄이 들어가면, 다음 진단에서 어떤 영역이 매트릭스에 빠져 있는지가 데이터로 자동으로 드러납니다. 지난 글에서도 비슷하게, 짧은 응답을 silent fail 로 단정하지 않고 raw 로 사람이 보게 했던 것과 같은 결입니다. 측정은 자동, 판단은 사람 — 이 경계를 fallback 쪽에서도 지켜두려는 의도였습니다.

일반화하면 네 줄 정도가 남습니다

며칠 들여다본 끝에 자기 자신을 위해 메모해둔 것은 네 줄이었습니다. 먼저, AI 코딩 하네스의 운영 룰은 호출 지점마다 박아야 합니다. 메모리·글로벌 한 곳만으로는 스킬 분기 안까지 도달하지 않는다는 점을 codex 룰에서 이미 한 번 확인했습니다.

둘째, 같은 매트릭스를 인라인 복제하지 않습니다. ground truth 한 곳 + 다른 곳에선 영역 한정만 두고 ground truth 를 가리킵니다. 셋째, 처음부터 hook 으로 강제하지 않습니다. prompt 가드 → SKILL 박스 → 글로벌 박스 → 측정 → 필요 시 hook 의 단계적 강제가 운영 부담이 작습니다. 넷째, fallback 도 측정 자산입니다. general-purpose 로 흘러가더라도 영역만 명시해두면 다음 진단의 매트릭스 갭 보강 자료가 되어 줍니다.

효과는 아직 단정할 수 없습니다. 박스 두 개를 박은 직후라, 적어도 1주~2주는 평소처럼 일하면서 transcript 가 쌓이도록 두려고 합니다. 결과는 다시 jq 한 줄로 같은 자리에서 잰 다음, 같은 형식으로 회고를 남길 생각입니다. 만들고 끝내지 말고 가끔은 멈춰서 측정해본다는 다짐을, 이번에는 measurement 가 아니라 enforcement 쪽에 적용해본 셈이라는 생각이 들었습니다.