질문 한 줄에 20만 토큰 — Claude Code 스킬이 삼키던 컨텍스트

Claude Code의 내장 /claude-api 스킬이 질문에 답하기 시작하기도 전에 약 20만 토큰을 쓰고 있었고, Anthropic이 이를 2.5만 토큰 수준으로 줄였습니다.

무엇이 문제였나

스킬은 Claude에게 특정 작업의 절차와 참고 자료를 쥐여주는 장치입니다. 문제는 그 자료를 언제 읽느냐였습니다.

기존 /claude-api 스킬은 참조 문서를 스킬 본문에 그대로 박아두고 있었습니다. 스킬이 켜지는 순간 그 전부가 컨텍스트로 들어갔습니다.

개발자들이 GitHub 이슈로 먼저 짚어낸 수치는 이렇습니다.

8월 4일 보고가 특히 비쌌습니다. 프로젝트 언어를 감지하지 못하면 C#·cURL·Go·Java·PHP·Python·Ruby·TypeScript 문서를 전부 불러오고, 공용 마크다운 26개까지 얹었습니다. 대부분이 그 작업과 무관한 자료였습니다.

왜 이런 낭비가 조용히 지나갔나

일반 소프트웨어라면 이 정도 낭비는 메모리나 실행 시간으로 금방 드러납니다. LLM 도구는 다릅니다. 청구서나 지연 시간에 나타나기 전까지 아무도 모릅니다.

게다가 개발자 눈에 보이는 것은 자기가 친 질문과 돌아온 답변뿐입니다. 스킬 본문은 한 번 로드되면 이후 턴에도 컨텍스트에 계속 남는 고정 비용이 되는데, 그 존재 자체가 화면에 드러나지 않습니다.

비용만의 문제도 아닙니다. Anthropic의 Claude Code 모범 사례 문서는 컨텍스트 창이 찰수록 모델이 앞선 지시를 잊거나 실수할 가능성이 커진다고 경고합니다. 20만 토큰을 서두에 깔고 시작하면, 정작 저장소와 실제 작업에 쓸 자리가 남지 않습니다.

무엇이 바뀌었나

변경은 Claude Code 체인지로그에 올라왔습니다. 핵심은 참조 문서를 미리 읽지 않고 필요할 때 읽는 것입니다. 초기 컨텍스트 비용이 최소 85.7% 줄었습니다.

Anthropic의 스킬 문서가 원래 권하던 구조가 이것입니다. 로드는 세 단계로 나뉩니다.

1. 메타데이터 — 항상 컨텍스트에 있는 소량의 정보
2. SKILL.md 본문 — 스킬이 발동할 때 로드
3. 번들 자료 — 작업 도중 필요할 때 로드

기존 /claude-api는 2단계와 3단계를 뭉개고 있었습니다. 스킬이 켜지는 순간 번들 자료까지 전부 읽어버린 것입니다.

스킬을 직접 만든다면

이 사건은 남의 버그가 아니라 스킬을 쓰는 사람 모두의 설계 문제입니다. 확인할 것은 세 가지입니다.

1. SKILL.md 본문에 문서 전문을 붙여넣지 않았는지 — API 명세, 긴 예제, 마이그레이션 가이드는 본문이 아니라 별도 파일로 뺍니다.
2. 본문에는 핵심 지시와 링크만 남겼는지 — Claude가 "필요하면 이 파일을 열면 된다"를 알 수 있으면 충분합니다.
3. 감지 실패 시 전부 읽는 경로가 없는지 — 이번 사고의 가장 비싼 부분이 여기였습니다. 조건 분기가 실패했을 때 기본값이 "전부"면 안 됩니다.

모델의 성능보다 문맥을 어떻게 쥐여주느냐가 비용과 품질을 좌우한다는 것을, 이번 건은 숫자로 보여줬습니다.

출처

• Claude Codeの「見えない重さ」に驚いた — claudenewsjp
• A Claude Code skill was eating 200,000 tokens before answering a single question — Amanda Caswell, The New Stack (2026-08-18)