Expand token management post with skills strategy

Author: serithemage

content/posts/vibe-coding-token-management-strategy.md

@@ -80,7 +80,49 @@ project/
 
 즉, 좋은 `CLAUDE.md`는 모든 것을 다 담는 문서가 아니라, **무엇을 바로 읽고 무엇은 나중에 읽을지 결정해주는 인덱스**에 가깝다.
 
-## 전략 4: `.claudeignore`로 애초에 읽지 말아야 할 것을 차단하라
+## 전략 4: Skills를 적극적으로 써서 문서를 "항상 로드"가 아니라 "필요시 로드"로 바꿔라
+
+여기서 한 단계 더 나아가면 `CLAUDE.md`만으로는 부족하다. 반복적으로 호출되는 워크플로, 특정 도메인 절차, 리뷰 기준, 배포 체크리스트, 보안 검토 루틴 같은 것은 **skill로 외부화**하는 편이 훨씬 낫다.
+
+Anthropic의 공식 Skills 가이드는 이 점을 꽤 명확하게 설명한다.[^15] skills는 기본적으로 **3단계 progressive disclosure** 구조를 가진다.
+
+- YAML frontmatter는 항상 로드된다.
+- `SKILL.md` 본문은 해당 skill이 관련 있다고 판단될 때만 로드된다.
+- `references/` 같은 연결 문서는 필요할 때만 추가로 탐색된다.
+
+즉, skill의 핵심 가치는 "지식을 많이 넣는 것"이 아니라 **지식을 한 번에 다 넣지 않는 것**이다. 여기에 서브에이전트까지 결합하면 효과가 더 커진다. Anthropic의 subagent 문서도 서브에이전트가 메인 대화와 **분리된 컨텍스트 윈도우**를 사용해 메인 세션 오염을 줄인다고 설명한다.[^16]
+
+다만 여기서 하나는 정확히 짚어야 한다. Anthropic 공식 문서가 "모든 문서를 200줄 이하로 유지하라"고 직접 규정하는 것은 아니다. 공식 가이드가 말하는 것은 더 일반적인 원칙이다. `SKILL.md`는 핵심 지침만 담고, 자세한 문서는 `references/`로 빼고, 큰 컨텍스트 이슈가 생기면 `SKILL.md`를 **5,000단어 이하**로 유지하라는 것이다.[^15] 내가 여기에 덧붙이고 싶은 실무 규칙은 더 공격적이다. **실제로 참조될 문서 조각은 200줄 안쪽으로 쪼개 두는 편이 좋다.** 그래야 skill이 필요한 문서만 골라 읽을 때 단위가 지나치게 커지지 않는다.
+
+예를 들어 아래처럼 구성하는 편이 낫다.
+
+```text
+.claude/
+├── CLAUDE.md
+├── agents/
+│   └── code-reviewer.md
+└── skills/
+    └── security-review/
+        ├── SKILL.md
+        └── references/
+            ├── auth-checklist.md
+            ├── input-validation.md
+            └── secrets-policy.md
+```
+
+이 구조의 장점은 두 가지다. 첫째, 메인 세션에는 skill을 "언제 써야 하는지"만 남는다. 둘째, 세부 문서는 실제로 필요할 때만 들어온다. 토큰 절약은 이 두 번째 단계에서 발생한다.
+
+실측 데이터도 방향은 비슷하다. SkillsBench는 7개 모델/하네스 조합에서 **curated skills가 평균 +16.2%p의 성공률 향상**을 만들었다고 보고한다.[^17] Claude Code Opus 4.6은 30.6%에서 44.5%로, Codex GPT-5.2는 30.6%에서 44.7%로, Claude Code Sonnet 4.5는 17.3%에서 31.8%로 올라갔다.[^17] 더 흥미로운 부분은 토큰이다. 이 연구에서 skills는 모든 환경에서 무조건 토큰을 줄이지는 않았다. GPT-5.2와 Gemini 3 Flash에서는 skill 문맥이 추가되면서 총 토큰이 6~13% 늘었다. 반면 Gemini 3 Pro는 총 토큰이 약 6% 줄었고, Claude Code Opus 4.6은 관측 가능한 입력 토큰이 **1,947K에서 1,448K로 약 26% 감소**했다.[^17]
+
+이 수치가 말해주는 것은 분명하다. skill은 "문서를 더 많이 넣는 기술"이 아니라, **탐색을 줄이고 절차를 재사용하는 기술**이다. 잘 설계된 skill은 시행착오를 줄여 전체 토큰을 낮출 수 있지만, 반대로 너무 큰 skill, 너무 많은 skill, 통째로 로드되는 skill은 오히려 컨텍스트 부채가 된다.
+
+결론적으로 skill 전략의 핵심은 다음 세 줄이다.
+
+- 자주 반복되는 절차는 skill로 승격한다.
+- `SKILL.md`는 짧게 유지하고, 상세 문서는 `references/`로 분리한다.
+- 실제로 참조될 문서는 작게 쪼개 두어 on-demand 로딩이 의미 있게 작동하도록 만든다.
+
+## 전략 5: `.claudeignore`로 애초에 읽지 말아야 할 것을 차단하라
 
 실측 기준으로 가장 ROI가 높은 단일 조치는 `.claudeignore` 설정이다. ideation 문서에 인용된 사례들에서는 `node_modules`, 빌드 산출물, 로그, 바이너리, 대용량 이미지, lock 파일을 제외하는 것만으로도 **30~40% 수준의 절감 효과**가 보고된다.[^6][^7]
 
@@ -105,7 +147,7 @@ coverage/
 
 이 전략의 본질은 절약이 아니다. 모델이 애초에 봐도 도움이 안 되는 정보를 보지 않게 막는 것이다. 특히 lock 파일이나 빌드 산출물은 토큰을 많이 먹지만 추론 가치가 거의 없다.
 
-## 전략 5: `tasks.md`를 하나로 몰아넣지 말고, 인덱스 구조로 쪼개라
+## 전략 6: `tasks.md`를 하나로 몰아넣지 말고, 인덱스 구조로 쪼개라
 
 ideation 문서에서 가장 인상적인 사례 중 하나는 단일 대형 `tasks.md`를 도메인별 문서와 `INDEX.md` 구조로 나누어 **76.1% 절감**을 달성한 케이스다.[^8]
 
@@ -123,7 +165,7 @@ tasks/
 
 토큰 관리란 결국 문서 정보 아키텍처의 문제이기도 하다.
 
-## 전략 6: Plan mode를 먼저 거치고 구현은 나중에 하라
+## 전략 7: Plan mode를 먼저 거치고 구현은 나중에 하라
 
 큰 작업을 곧바로 실행 모드로 던지면, 모델은 탐색과 설계와 구현을 같은 비용 센터 안에서 한꺼번에 처리한다. 이 방식은 시행착오가 많고 토큰도 많이 든다. ideation에서는 Plan mode를 먼저 거쳐 범위를 줄인 뒤 구현으로 들어가는 습관이 **20~30% 절감**에 기여한다고 정리하고 있다.[^7]
 
@@ -136,13 +178,13 @@ tasks/
 
 즉, 토큰 절약은 프롬프트를 짧게 쓰는 기술보다 **불필요한 시행착오를 사전에 제거하는 설계 습관**에 더 가깝다.
 
-## 전략 7: 큰 로그와 검색 작업은 서브에이전트나 별도 세션으로 격리하라
+## 전략 8: 큰 로그와 검색 작업은 서브에이전트나 별도 세션으로 격리하라
 
 웹 검색, 긴 로그 분석, 빌드 출력 검토, 광범위한 코드 탐색은 결과물이 길다. 이런 작업을 메인 세션에서 직접 처리하면 컨텍스트가 빠르게 오염된다. ideation에서도 이런 고노이즈 작업은 서브에이전트에 위임하고, **결과 요약만 메인 컨텍스트로 돌려받는 방식**을 권장한다.[^9]
 
 이 패턴은 Claude Code뿐 아니라 Codex나 Gemini CLI에도 그대로 적용된다. 중요한 것은 어떤 도구를 쓰느냐보다, **노이즈가 많은 작업과 결정이 필요한 작업을 같은 세션에 섞지 않는 것**이다.
 
-## 전략 8: 검색 기반 컨텍스트 주입을 기본값으로 삼아라
+## 전략 9: 검색 기반 컨텍스트 주입을 기본값으로 삼아라
 
 대형 코드베이스에서 전체 파일을 그대로 읽히는 방식은 오래 가지 못한다. ideation 문서에는 함수나 심볼 단위 의존성 그래프를 만들어 필요한 조각만 제공하는 고급 패턴도 소개되어 있는데, 이런 방식은 실측 기준 **80% 이상 절감**이 가능하다는 사례까지 나온다.[^10]
 
@@ -154,13 +196,13 @@ tasks/
 
 즉, 전체 저장소를 덤프하는 대신 **검색 후 주입**을 기본값으로 삼아야 한다.
 
-## 전략 9: MCP 서버도 켜놓기만 하면 비용이다
+## 전략 10: MCP 서버도 켜놓기만 하면 비용이다
 
 MCP는 강력하지만, 활성화된 서버와 도구가 많을수록 컨텍스트와 시스템 지시문이 불어난다. ideation 문서가 지적하듯, 현재 작업과 무관한 MCP를 상시 켜 두는 것은 첫 프롬프트 전부터 예산을 잡아먹는 방식이다.[^11]
 
 따라서 MCP 전략도 "많이 연결"이 아니라 "필요할 때만 연결"이 맞다. 장기적으로는 이 역시 Progressive Disclosure의 일부다.
 
-## 전략 10: 도구별로 역할을 분리하라
+## 전략 11: 도구별로 역할을 분리하라
 
 ideation은 Claude Code, Codex, Gemini를 각각 다른 특성으로 정리한다.[^12][^13][^14]
 
@@ -176,7 +218,8 @@ ideation은 Claude Code, Codex, Gemini를 각각 다른 특성으로 정리한
 
 - "전체 프로젝트를 보고 알아서 해줘" 같은 넓은 요청
 - 한 세션에 탐색, 구현, 디버깅, 회고를 모두 누적하는 방식
-- 대형 `tasks.md`나 거대한 규칙 파일을 항상 통째로 로드하는 구조
+- 대형 `tasks.md`, 거대한 규칙 파일, 비대한 skill을 항상 통째로 로드하는 구조
+- skill 안에 모든 배경지식을 한 파일로 몰아넣고 `references/`를 사실상 쓰지 않는 구조
 - build 로그, diff, 검색 결과를 압축 없이 그대로 붙여넣는 습관
 - 현재 작업과 무관한 MCP 서버와 도구를 상시 활성화하는 설정
 - 큰 컨텍스트 창이 있으니 정리하지 않아도 된다고 믿는 태도
@@ -190,14 +233,15 @@ ideation 메모의 제안은 합리적이다. 투자 대비 효과 기준으로
 1. `.claudeignore` 또는 동등한 ignore 파일부터 잡는다.
 2. `tasks.md`와 작업 문서를 인덱스 구조로 쪼갠다.
 3. Plan mode와 handoff 문서를 습관화한다.
-4. `CLAUDE.md`를 슬림하게 재구성하고 온디맨드 링크 구조로 바꾼다.
-5. 그 다음에야 검색 기반 컨텍스트 서빙이나 MCP 최적화를 고려한다.
+4. `CLAUDE.md`를 슬림하게 재구성하고, 반복 절차는 skill로 승격한다.
+5. skill의 `SKILL.md`는 짧게 유지하고 상세 문서는 잘게 쪼갠 `references/`로 분리한다.
+6. 그 다음에야 검색 기반 컨텍스트 서빙이나 MCP 최적화를 고려한다.
 
 즉, 대부분의 팀은 고급 인프라보다 먼저 **문서 구조와 세션 습관**만 바꿔도 큰 차이를 체감할 수 있다.
 
 ## 결론
 
-바이브 코딩의 토큰 관리 전략은 결국 한 문장으로 요약된다. **모델에게 많은 것을 보여주지 말고, 지금 필요한 것만 정확히 보여줘라.** 세션을 짧게 유지하고, 반복되는 설명은 문서로 외부화하고, 큰 태스크는 인덱스와 계획 단계로 쪼개고, 노이즈가 많은 작업은 별도 세션으로 격리해야 한다.
+바이브 코딩의 토큰 관리 전략은 결국 한 문장으로 요약된다. **모델에게 많은 것을 보여주지 말고, 지금 필요한 것만 정확히 보여줘라.** 세션을 짧게 유지하고, 반복되는 설명은 문서와 skill로 외부화하고, 큰 태스크는 인덱스와 계획 단계로 쪼개고, 노이즈가 많은 작업은 별도 세션으로 격리해야 한다.
 
 토큰을 아끼는 팀이 생산성이 높은 이유는 돈을 적게 써서가 아니다. 모델이 헷갈릴 여지를 줄였기 때문이다. 좋은 바이브 코더는 긴 프롬프트를 쓰는 사람이 아니라, **컨텍스트를 설계하는 사람**이다.
 
@@ -215,3 +259,6 @@ ideation 메모의 제안은 합리적이다. 투자 대비 효과 기준으로
 [^12]: Best practices for cost-efficient, high-quality context management in long AI chats: https://community.openai.com/t/best-practices-for-cost-efficient-high-quality-context-management-in-long-ai-chats/1373996
 [^13]: How to Leverage Gemini CLI's 1M Token Context Window: https://inventivehq.com/knowledge-base/gemini/how-to-leverage-1m-token-context
 [^14]: What Is the Token Limit for Codex Requests?: https://apidog.com/blog/token-limit-for-codex-requests/
+[^15]: The Complete Guide to Building Skills for Claude, Anthropic: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
+[^16]: Subagents, Anthropic Docs: https://docs.anthropic.com/en/docs/claude-code/sub-agents
+[^17]: SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks: https://www.skillsbench.ai/skillsbench.pdf