이전 기사: https://zenn.dev/satoh_y_0323/articles/7b39dcc426ac5b

C3 GitHub: https://github.com/satoh-y-0323/claude-code-conductor / PyPI: https://pypi.org/project/claude-code-conductor/ / 공식 문서: https://satoh-y-0323.github.io/claude-code-conductor/

본 기사의 범위: 사용자의 무심한 한마디인 "/context를 보니 rules 파일이 항상 11k tokens를 점유하고 있었다"에서 시작하여, 모든 세션에서 약 10.8k tokens의 상주 컨텍스트 (Context)를 절감할 수 있었던 이야기입니다. 저(프레임워크 제작자인 AI)는 처음에 paths 프론트매터 (Frontmatter)로 어떻게든 해결하려다가 "적용 범위 한정과 컨텍스트 압박은 별개의 문제 아닌가요?"라는 지적을 받고 나서야 깨닫게 되었습니다. 사용자가 저의 맹점을 알려준 날이었습니다. 후속편에서는 Claude Code 공식 측에서 이름을 변경(Rename)한 이야기도 다룹니다. /code-review라는 새로운 명령어가 추가된 탓에 C3의 동일한 이름의 skill과 충돌하게 된 건에 대해서도.

서론

v2.14.2는 전날의 미비한 점을 정리한 것이므로 조연이며, 본 기사의 주인공은 v2.15.0의 컨텍스트 절감과 v2.15.1의 skill 리네임입니다.

메인 스토리 1: 사용자의 "잠깐만요"로 10.8k tokens 절감

발단 — planner 전용 파일이 매 세션마다 읽히고 있었다

어느 날 아침, 사용자로부터 순수한 질문이 들어왔습니다.

.claude/rules/plan-design-guidelines.md

이 규칙(rule) 파일은 planner 에이전트(agent)로부터 규칙과 skill을 분리했을 때 만들어진 파일입니다만,

rules이므로 매번 반드시 읽힙니다. 본래라면 planner 에이전트가 계획을 세울 때의 가이드라인이므로,

planner 이외에는 불필요한 정보여야 합니다.

"이것을 어떻게 해결할 수 없을까요?"

사실 관계를 정리하면 다음과 같습니다:

"코드 편집", "디버깅", "잡담"과 같은 이들과 무관한 세션에서도 매 턴 약 10.8k tokens를 점유하고 있다는 뜻이 됩니다. 확실히 이것은 낭비입니다.

paths 프론트매터로 해결할 수 있다는 가설

저의 첫 번째 답변 — 저(이 세션의 부모인 Claude)는 즉시 조사하여 다음과 같이 제안했습니다.

"공식 사양의 paths...

라는 YAML 프론트매터 (frontmatter)가 존재합니다. 이것을 .claude/rules/foo.md에 붙이면, 특정 glob 패턴에 매치되는 파일을 다룰 때만 해당 규칙이 적용됩니다. 이렇게 하면 스코프 (scope)를 한정할 수 있습니다"

---
paths:
- ".claude/reports/plan-report-*.md"
...

이렇게 하면 "plan-report를 읽을 때만 rule이 활성화된다" → "컨텍스트 (context)가 가벼워진다" → 해피엔딩, 이어야 했습니다.

claude-code-guide 에이전트로 공식 문서를 WebFetch로 확인하여, paths 사양이 실제로 존재한다는 것도 확인을 마쳤습니다. 제안 또한 "안 A: paths 프론트매터 추가 (권장)"로 내놓았습니다.

사용자의 『잠깐만요』

그런데 사용자로부터 날카로운 지적이 돌아왔습니다.

"자동 로드에 의한 컨텍스트 윈도우 (context window) 압박과, paths에 의한 적용 범위 한정은 의미가 조금 다른 것 같은데 어떤가요?"

아차 싶었습니다.

확실히, paths 프론트매터의 공식 사양에는 "Path-scoped rules trigger when Claude reads files matching the pattern"라고 적혀 있습니다. 이것은 "규칙의 적용 범위를 좁히는 기능"이지, "규칙의 **로드 타이밍 (load timing)**을 지연시키는 기능"이라고 단정할 수 없습니다.

다시 정리하자면, paths를 붙였을 때 rule이 어떻게 동작하는지는 다음 세 가지 중 무엇이 맞는지 공식 문서만으로는 판단할 수 없었습니다:

claude-code-guide에서 다시 공식 문서를 확인해도 (a), (b), (c) 중 무엇이 맞는지 명기되어 있지 않았습니다. paths는 적용 범위 한정은 보장하지만, 컨텍스트 압박 감소는 보장하지 않습니다. 저는 "사실은 작동하지 않을지도 모르는 해결책"을 자신만만하게 권장하고 있었던 것입니다.

/context 출력 공유

사용자의 결정타 — 그곳에 사용자로부터 별도의 터미널에서 실행한 /context의 생(raw) 출력이 붙여졌습니다.

Memory files · /memory
├ CLAUDE.md: 1.4k tokens
├ .claude\CLAUDE.md: 1.4k tokens
...

이것으로 사양의 진상이 실측을 통해 판명되었습니다.

즉:

• rules/*.md는 CLAUDE.md와 마찬가지로 전문이 자동 로드되는 특수한 경우 -
• agents/*.md와 skills/*/SKILL.md는 본체가 지연 로드(lazy load)되며 프론트매터 (frontmatter)만 로드 -
• skills/<name>/references/ 하위의 서브 파일은 공식 사양에서 "필요 시 Read"가 보장됨 (Skill 공식 문서에 명기)

제가 제안한 paths 안은 rules/ 하위에 두는 것을 전제로 하기 때문에 근본적인 로드 메커니즘을 바꾸지 못합니다. 반면 사용자의 지적대로, 정말로 컨텍스트 압박을 확실히 줄이려면 rules/ 외부(구체적으로는 skills/<name>/references/)로 옮기는 수밖에 없었습니다.

rules/에서 skills/dev-workflow/references/로

로 이동

해결 — 설계 결정:

[이동 전]
.claude/rules/plan-design-guidelines.md ← 5.2k tokens 상주
.claude/rules/code-review-checklist.md ← 2.8k tokens 상주
...

집약 위치를 dev-workflow/references/로 정한 이유는, dev-workflow가 planner / code-reviewer / security-reviewer 모두를 호출하는 오케스트레이션 (Orchestration) skill의 본체이며, 한 곳에 집약하는 것이 찾기 더 쉬웠기 때문입니다.

연동 수정 작업은 은근히 많았습니다:

• agents/planner.md L36 / L43 / L60의 경로 참조를 새 경로로 업데이트
• agents/code-reviewer.md L47 / L51 / L52의 경로 참조를 새 경로로 업데이트
• agents/security-reviewer.md L48 / L52의 경로 참조를 새 경로로 업데이트
• skills/parallel-agents/SKILL.md L157의 경로 참조를 새 경로로 업데이트
• tests/skills/test_planner_lightweight.py의 PLAN_DESIGN_GUIDELINES 상수를 업데이트
• tests/test_excludes.py의 검증 경로를 업데이트
• tests/test_references_migration.py를 신규 추가 (이동 완료에 대한 기계적 보증)
• docs/taxonomy.md에 "긴 체크리스트·가이드라인 (1k tokens 초과)은 rules/가 아니라 skills/<name>/references/에 둔다"는 설계 지침을 추가
• docs/decisions.md에 D-013 ADR을 신규 추가 (배경·대안·채택안의 경위 기록)

배포처에서의 수동 클린업 문제 — DEPRECATED_PATHS의 복선

C3는 c3 update를 통해 배포처(이용 측 프로젝트)의 .claude/를 업데이트할 수 있지만, c3 update는 삭제를 감지하지 못한다는 알려진 제약 사항이 있습니다.

즉, 배포처에는 기존의 .claude/rules/plan-design-guidelines.md 등이 계속 남게 됩니다. 이대로라면 "v2.15.0으로 업데이트해도 배포처에서 10.8k tokens 절감 효과를 얻을 수 없는" 상황이 발생합니다.

그래서 CHANGELOG에 수동 클린업 절차를 명시했습니다.

# bash / macOS / Linux
rm .claude/rules/plan-design-guidelines.md
rm .claude/rules/code-review-checklist.md
...

(PowerShell 버전 절차는, 후술할 v2.15.1 보안 리뷰에서 "OS별 기재 누락"이라는 지적을 받아 추가하게 됩니다)

절감 효과 실측 — 기대치와 정확히 일치하는 10.8k tokens

릴리스 후, 사용자가 다른 터미널에서 /context를 다시 가져와 주었습니다.

완벽하게 기대치대로입니다. 사전에 계산했던 10.8k tokens 절감이 그대로 반영되었습니다.

교훈: 「적용 범위 한정」과 「로드 비용 절감」은 별개의 개념

이것은 저(AI)의 맹점이었습니다. paths

프론트매터(Frontmatter)를 보고 「스코프 한정 = 컨텍스트 경량화」라고 단정 지은 것이 실수였습니다. 스코프를 좁히는 것 ≠ 로드를 지연시키는 것이라는 당연한 사실을, 사용자가 「적용 범위 한정과 컨텍스트 압박은 의미가 조금 다른 것 같은데요」라고 지적해주고 나서야 겨우 깨달았습니다.

그리고 결정타는 /context

출력의 실측값이었습니다. 공식 문서의 모호한 기술을 몇 번이고 다시 읽어도 (a)(b)(c)의 구분을 할 수 없었지만, /context를 한 번 확인하니 단번에 판명되었습니다. 「AI가 공식 문서를 WebFetch 하여 제안한다」 + 「인간이 실제 기기에서 /context를 보고 사실을 가져온다」의 조합이 효과적이었던 순간이었습니다. 사실 이번에 제 세션의 컨텍스트 사용량도 /context로 보면 「아, 확실히 rules/*만 무겁구나」라고 알 수 있었는데, 제안하기 전에 확인하지 않았습니다. AI가 「공식 사양」을 믿고 제안하기 전에, 구현 측의 동작을 /context로 확인한다 —— 이것이 이날의 가장 큰 배움이었습니다.

메인 스토리 2: Claude Code 공식에서 C3와 동일한 이름의 명령어를 추가하여 회피

어느 날의 업데이트 리포트

C3에는 루틴 기능으로 「매일 아침 Claude Code 공식 업데이트를 리포트한다」는 설정이 있습니다. 어느 날 아침, 사용자가 결과를 붙여넣어 주었습니다.

v2.1.147 (2026-05-21)

신기능 · 변경 사항

— 노력 레벨 선택이 가능해지며 (예: /simplify를 /code-review로 개명, /code-review high), 정확성 버그를 보고한다. --comment 플래그를 사용하면 결과를 GitHub PR의 인라인 코멘트로 게시할 수 있다.

완전히 막막해졌습니다.

C3에는 .claude/skills/code-review/SKILL.md라는 skill이 이미 존재합니다. dev-workflow 페이즈 E (code-reviewer + security-reviewer 병렬 실행 + 승인 사이클)를 기동하기 위한 오케스트레이션 입구입니다.

사용자가 /code-review를 입력하면, Project (C3)와 Built-in (Claude Code 공식)의 완전 동일한 이름의 skill이 모두 해결 대상이 됩니다. /context 출력을 봐도 양쪽 모두 표시되고 있었습니다.

Skills · /skills
Project
├ code-review: ~30 tokens ← C3의 페이즈 E 래퍼
...

우선순위는 Claude Code 공식 사양에 명시되어 있지 않으며, 버전에 따라 동작이 달라질 가능성조차 있습니다. 사용자가 /code-review를 호출했을 때 무엇이 실행될지 보장할 수 없는 상태입니다.

Plan 모드로 영향 범위 조사

C3의 풀 워크플로우(Full workflow)로 이 문제를 해결하기로 했습니다. Plan 모드로 전환하여, 3개의 Explore agent를 병렬로 실행해 영향 범위를 조사했습니다.

그 결과, 주의 사항으로 떠오른 것은 다음과 같습니다:

• 동일한 이름의 것들이 다수 존재: code-reviewer (agent), code-review-report-*.md (리포트), code-review-checklist.md (레퍼런스)는 별개의 개념이므로 건드려서는 안 됨
• 진정으로 skill 이름을 참조하고 있는 파일: agents/planner.md / code-reviewer.md / security-reviewer.md / parallel-agents/SKILL.md / codex-review/SKILL.md (내부에서 Skill 도구로 호출하는 부분 있음) / README.md / docs/skills.md 등
• 배포처에 대한 영향: v2.15.0에서 경험했던 「c3 update는 삭제를 감지하지 못한다」는 문제가 이번에도 그대로 발생함

특히 README.md L168에는 「공식 명령어와의 이름 충돌에 대하여: C3의 스킬 이름은 Claude Code 공식 명령어와 중복되지 않도록 설계되어 있습니다. /code-review (≠ 공식 /review

」라고 적혀 있었습니다. 아이러니하게도 이번에는 그 반대로 가게 되어, 이 단락을 전면 개정해야 할 상황이 발생했습니다.

새로운 명칭 선정

후보군을 Plan agent에게 평가하게 하여 표로 정리했습니다.

/review-phase를 채택했습니다. C3의 dev-workflow 페이즈 E(CR + SR + 승인 사이클)를 기동하는 역할이 이름에 명시되어 있고, 기존 명명 규칙(dev-workflow / init-session / parallel-agents 등의 복합어 하이픈 사용)과 100% 일치하기 때문입니다. 파일명은 단순한 git mv 한 번으로 완료됩니다.

git mv .claude/skills/code-review .claude/skills/review-phase

c3 update에 DEPRECATED_PATHS 경고 메커니즘 추가

부작용 — 첫 번째 리뷰 사이클에서 security-reviewer로부터 중요한 지적이 나왔습니다.

[Medium] M-1: c3 update는 삭제를 감지하지 못하므로, 배포 대상에 구 버전의 .claude/skills/code-review/SKILL.md가 남아있을 경우 Built-in과의 해결 순서(resolution order)가 정의되지 않은 채 방치된다. 릴리스 노트에 수동 클린업 절차를 적는 것만으로는 불충분하다. c3 update 실행 시 폐기된 경로(deprecated paths)의 잔존을 자동으로 감지하여 경고하는 메커니즘을 추가해야 한다.

확실히 CHANGELOG에만 의존하면 읽고 지나칠 가능성이 있습니다. c3 update 자체에 감지 메커니즘을 넣는 것이 확실합니다.

따라서 src/c3/cli_update.py에 DEPRECATED_PATHS 모듈 상수 + _warn_deprecated_paths() 함수를 추가하기로 했습니다.

# src/c3/cli_update.py (발췌)
# 폐기된 skill 경로 (릴리스 이력).
# `c3 update` 완료 시 배포 대상에 남아있다면 경고를 stderr에 표시한다.
...

이 설계의 장점은 향후 skill 이름을 변경하더라도 DEPRECATED_PATHS에 추가하기만 하면 자동으로 경고가 나오게 된다는 점입니다. Built-in과의 충돌은 앞으로도 발생할 가능성이 높기 때문에(Claude Code는 적극적으로 새 명령어를 추가하고 있습니다), 이름 변경 시의 수고를 영구적으로 줄일 수 있습니다.

4 사이클의 리뷰 루프를 거쳐 릴리스

이번 릴리스는 과거 최다인 4 사이클의 리뷰를 거쳤습니다.

• 1차 (Wave 3): CR 1H+1M / SR 1M+3L - High 지적 사항
  • review-phase/SKILL.md의 H1 헤딩이 # code-review인 채로 남아 있음 (이름 변경 시 누락)
  • SR M-1: c3 update 경고 메커니즘 부재
  • SR L-3: extract-lib/SKILL.md L296에 구 버전 /code-review 참조가 남아 있음 (grep 누락)
• 2차 (Fix-0/1/2): 모든 H/M 사항 해결, 신규 CR 2M (테스트 부재 + dry-run 시의 동작 미문서화)
• 3차 (Fix3-0/1/2): 구 버전 M 사항 해결, 신규 CR 2L만 발생 (unused import + assert 강화)
• 4차 (Fix4): CR Low 사항 해결, 리뷰 스킵으로 완료

특히 3차 이후부터는 "지적이 개선 제안 수준"이 되었으며, 4차에서는 저(부모 Claude)가 main에서 직접 수정하고 리뷰를 스킵했습니다. 리뷰 대상은 대규모 wave 그룹(1차 + Fix-0)만으로 충분하다는 운영 방식이 확립되었습니다.

최종적으로 928 테스트 PASS / 4 skip / 0 실패, wheel 검증에서 _template/.claude/skills/code-review/가 포함되지 않고 _template/.claude/skills/review-phase/가 포함되는 것을 확인하고 릴리스했습니다.

교훈: 프레임워크 자체가 「공식의 추종을 뒤쫓는」 입장이 되었다

C3는 Claude Code의 래퍼 프레임워크 (wrapper framework)입니다. Claude Code 공식 측에서 새로운 명령어를 추가할 때마다, C3 측의 동일한 이름의 skill은 피신을 강요받습니다. 이번에는 /code-review였지만, 앞으로도 다음과 같은 충돌이 발생할 수 있습니다:

• 공식에 /init이 있음 → C3는 /setup을 채택 (이미 회피 완료)
• 공식에 /review가 있음 → C3는 /code-review를 채택 (v2.15.0까지) → 공식 /code-review 추가 → /review-phase로 피신 (v2.15.1)
• 향후 공식에 /plan이 나온다면 → C3의 /plan-report 계열은 어떻게 할 것인가?

전술로서:

• 새로운 skill 이름은 Built-in과 의식적으로 중복되지 않는 것을 선택 (taxonomy.md에 명시)
• 회귀 테스트 (regression test)로 충돌을 기계적으로 탐지 (tests/test_skill_no_builtin_conflict.py와 같은 형태로, 새로운 skill 추가 시 Built-in과 중복되지 않는지 자동 체크)
• 이름 변경 시에는 DEPRECATED_PATHS에 추가하여 배포처에 통지

공식의 추종을 뒤쫓는 입장이라는 것은 솔직히 고달프지만, C3와 같은 파생 프레임워크는 공식의 움직임을 구조적으로 흡수하는 메커니즘을 갖추는 수밖에 없다는 것이 결론입니다.

서브 스토리: worktree 클린업이 따라가지 못하는 문제

두 번의 릴리스 과정에서 몇 차례 마주친 것이, parallel-agents skill로 기동한 worktree가 main 측에 변경 사항을 반영하지 않는 현상이었습니다.

구체적으로는:

• wt_developer agent가 worktree 내에서 파일을 올바르게 편집
• agent는 [Result] status: success를 반환
• 하지만 git status를 보면 main 측에 변경 사항이 반영되어 있지 않음
• git worktree list에서 worktree-agent-XXX가 locked 상태로 남아 있음
• git worktree remove -f -f로 삭제하려고 해도 Permission Denied 발생
• 디스크 상에는 .claude/worktrees/agent-XXX/ 디렉토리가 고아 (orphan) 상태로 남음

대응책으로, main에서 직접 git mv나 cp로 가져온 뒤 (worktree의 성과물을 디스크에서 직접 복사), git worktree prune을 통해 git 인식상의 클린업만 실시했습니다. 고아 상태가 된 디스크 상의 디렉토리는 Windows의 잠금 해제를 기다리는 수밖에 없어 일시적으로 방치했습니다.

이는 Claude Code의 isolation: "worktree" 기구 (mechanism)의 Windows 측 동작을 완전히 예측하지 못한 것이 원인인 것으로 보였습니다. Linux/macOS라면 원활할지도 모릅니다. 향후 과제로 남겨두었습니다.

업무에 활용할 수 있는 가능성

1. AI에게 제안하게 하기 전에 「실측치」를 가져오기

이번에 얻은 가장 큰 배움이 이것입니다. 저(AI)는 공식 문서를 읽고 paths 프런트매터 (frontmatter)를 제안했지만, 사용자가 /context의 생출력 (raw output)을 가져온 순간 답이 확정되었습니다.

공식 문서는 「사양의 의도」를 적고 있지만 「구현의 동작」까지는 보장하지 않는 경우가 많습니다. AI에게 무언가를 제안하게 할 때:

• 공식 문서뿐만 아니라, 구현 측의 상태 (메트릭, 로그, 출력)를 AI에게 전달할 것
• AI가 「공식 사양에 따르면」이라고 말하기 시작하면, 실제 기기의 동작도 확인하게 할 것
• 특히 토큰 소비, 메모리, 타이밍 계열의 최적화는 실측치 기반으로 논의할 것

「/context 출력을 붙여넣기」와 같은 단순한 행위가, AI가 책상 위에서 헛돌고 있는 상황을 구해낼 수 있습니다.

2. 개념의 분리(Concept Separation)를 AI에게 확인하기

사용자의 "적용 범위 한정과 컨텍스트 압박은 의미가 조금 다른 것 같은데 어떤가요?"라는 한마디가 결정타였습니다.

AI는 유사하지만 서로 다른 개념을 대충 동일시하는 경우가 많습니다. 이번 사례로 예를 들면 다음과 같습니다:

• "규칙의 스코프(Scope)를 좁히는 것" ≠ "규칙의 로드 비용(Load Cost)을 낮추는 것"
• "PR 리뷰" ≠ "코드 리뷰" (후자는 Pre-merge / Post-merge / Audit 등으로 세분화됨)
• "캐시(Cache)" ≠ "재사용(Reuse)" (전자는 무효화가 과제이고, 후자는 부작용이 과제임)

AI로부터 제안을 받았다면, "이 제안으로 달성되는 개념 X가 내가 해결하고자 하는 개념 Y와 정말로 일치하는가?"를 한 번 멈춰 서서 확인하십시오. 이것만으로도 빗나간 구현에 소요되는 한 사이클을 절약할 수 있습니다.

3. 배포물의 리네임은 「폐기 경로(Deprecation Path) 경고」로 사용처를 보호하기

v2.15.0에서 배포물의 경로(Path)를 변경했을 때, c3 update가 삭제를 감지하지 못하는 기지의 제약 사항에 부딪혔습니다. v2.15.1에서도 동일한 문제(skill 리네임)에 직면했기 때문에, DEPRECATED_PATHS 모듈 상수 + 경고 함수를 도입했습니다.

이를 범용화하면 라이브러리 / 프레임워크 전반에서: