Skills File 패턴

SectorFlow Engineering Series · 3부 중 2부 · 1부 먼저 읽기: Token Efficiency in Claude Code

CLAUDE.md에 계속 내용을 추가하는 것을 멈추고, 필요한 것만 가져오기(import) 시작한 방법.

2026년 6월 · SectorFlow Engineering

이 시리즈에서 1부: Token Efficiency in Claude Code (여기서 시작하세요). 3부: 모델 및 도구 선택 — 우리가 시도하고, 거절한 MCP(Model Context Protocol)들과 그 이유.

추가(append)의 루프

Claude Code를 한동안 사용하다 보면 아마 저희와 같은 상황에 직면하게 될 것입니다. 즉, CLAUDE.md 파일이 너무 커지고 내용이 서로 모순되어 더 이상 신뢰할 수 없게 되는 상황 말입니다.

처음에는 괜찮습니다. 앱이 무엇을 하는지, 서버가 어디에 있는지, API가 어떻게 생겼는지와 같은 기본 사항을 적어둡니다. 그러다 무언가 고장 납니다. Claude가 잘못된 모델 문자열을 선택하거나, 올바른 색상 없이 차트를 그리거나, 3주 전에 지나가는 말로 언급했던 캐시 규칙을 무시합니다. 그래서 당신은 그 규칙을 적고 파일 끝에 추가(append)합니다. 합리적인 행동이죠.

그리고 한동안은 잘 작동합니다. 그러다 파일은 커지고, 2주 차에 만든 규칙이 6주 차에 만든 규칙 위에 놓이게 됩니다. 그리고 요구 사항이 변하고 오래된 메모가 쓸모없어짐에 따라 두 규칙이 충돌하게 되면 — 반드시 충돌하게 됩니다 — 모델은 이를 형체 없는 것으로 화해시키거나 그냥 하나를 선택해 버립니다. 당신은 자신이 활성화되어 있다고 생각했던 규칙이 몇 달 전에 쓰고 잊어버린 무언가에 의해 덮어씌워졌다는 사실을 깨닫기 전까지, 출력을 디버깅하는 데 한 시간을 허비하게 됩니다.

더 큰 문제는 무엇일까요? 당신이 무엇을 하고 있든 상관없이 세션마다 파일 전체가 로드된다는 점입니다. 프론트엔드의 색상 수정 작업에 배포 런북(runbook)이 필요하지는 않습니다. API 경로 변경에 차트 색상 규칙이 필요하지도 않습니다. 관련 없는 모든 줄은 토큰(token)을 소모하고 노이즈를 추가합니다.

우리는 나중에 다시 필요할 내용들을 그냥 삭제하지 않고 이를 해결할 방법을 고민했고, 결국 우리가 'skills file 패턴'이라고 부르는 것에 도달했습니다. 컨텍스트(context)를 목적에 따라 별도의 파일로 분리하고, 작업에 필요한 것만 가져오기(import)하는 방식입니다.

구조

CLAUDE.md는 규칙서(rulebook)의 역할을 그만두고 목차(table of contents)가 됩니다. 실제 규칙들은 .claude/ 디렉토리 하위의 별도 파일들로 이동합니다.

파일	소유하는 내용	로드 시점
`core.md`	절대적 제약 사항: 모델 문자열, API 키 규칙, 캐시 TTL, 데이터 계약 (data contracts)	모든 세션 — 기초적인 제약 사항
...

CLAUDE.md에서의 가져오기(import) 구문은 특별할 것이 없습니다:

@sector-dashboard/.claude/core.md
@sector-dashboard/.claude/design.md
@sector-dashboard/.claude/workflow.md
...

따라서 UI 작업은 core + design + workflow를 로드합니다. 인프라(infra) 작업은 core + infrastructure + workflow를 로드합니다. architecture.md는 누군가가 실제로 확장 결정(scaling decision)이나 ADR(Architecture Decision Record)에 대해 물을 때만 나타납니다. 컨텍스트(context)는 작게 유지되며 주제에 집중된 상태를 유지합니다.

무엇을 어디에 넣을 것인가

core.md — 헌법 (the constitution)

core.md는 매 세션마다 로드되는 단 하나의 파일이므로, 그 안의 모든 내용은 사실이어야 하며 현재 강제되고 있어야 합니다. 우리는 이를 헌법처럼 취급합니다. 안정적이고, 권위 있으며, 결코 희망 사항을 담지 않습니다.

두 가지 종류의 내용이 들어갑니다:

우리가 검증한 사실들 — 작동을 확인한 모델 ID, 엔드포인트 형태(endpoint shapes), 캐시 키 이름, 엔드포인트당 정확한 토큰 제한(token limits).
엄격한 제약 사항 (Hard constraints) — 의도적이고 문서화된 결정 없이는 어길 수 없는 규칙들 (API 키의 위치, 모델 교체 금지, TTL 값 등).

core.md에 열망(aspirations)을 담지 마세요. "~을 시도해야 한다..." 또는 "이상적으로 모델은 ~해야 한다..."와 같은 내용은 workflow.md에 적합한 내용입니다. core.md는 오직 지금 현재 사실인 것들만을 위한 것입니다. 희망 사항을 넣는 순간, 결국 현실과 모순되게 되며, 당신의 가장 신뢰받는 파일에 거짓 정보가 자리 잡게 됩니다.

design.md — 시각적 계약 (the visual contract)

모든 헥스 값(hex value), 모든 차트 유형 할당, 모든 로딩 상태(loading-state) 패턴은 design.md에 들어갑니다. 이것이 효과적인 세 가지 이유는 다음과 같습니다:

새로운 엔지니어나 새로운 Claude 세션이 컴포넌트 코드로부터 시각적 관례(visual conventions)를 역공학(reverse-engineer)할 필요가 없습니다.
52주 범위 바(52-week range bar)의 색상 로직을 변경했을 때, 우리는 design.md에 있는 테이블 하나만 수정했습니다. 규칙을 기록하기 위해 컴포넌트 파일을 변경할 필요가 없었습니다.
Claude가 문서화된 토큰(token)을 사용하는 대신 헥스(hex) 코드를 하드코딩한 PR(Pull Request)을 거절할 수 있습니다. 규칙이 문서로 작성되어 있기 때문입니다.

design.md는 무엇을 건드리지 말아야 하는지를 나열하는 곳이기도 합니다. TradingViewChart.jsx는 래퍼(wrapper) 전용입니다. signals.js는 자체적인 색상 시스템을 가지고 있으며 새로운 --sf- 변수를 사용해서는 안 됩니다. 이러한 "하지 마시오" 규칙은 관례만큼이나 중요합니다.

workflow.md — 누가 무엇을 하는가

이 파일은 일상 업무에서 가장 중요한 파일입니다. Claude가 하는 일과 엔지니어가 하는 일을 의문이 생길 여지가 없을 정도로 충분히 상세하게 설명합니다. Part 1에 전체적인 논거가 들어있지만, 요약하자면 다음과 같습니다: 만약 엔지니어가 터미널에서 2분 이내에 할 수 있는 일이라면, MCP를 통해 Claude에게 전달해서는 안 됩니다.

workflow.md에는 엔지니어가 Claude에게 작업을 넘길 때 사용하도록 만든 작업 형식(task format)도 포함되어 있습니다:

필수 필드	존재하는 이유
`Branch: {name}`	Claude가 묻거나 추측하는 것을 방지 — 도구 호출(tool call) 횟수 감소
...

만약 이러한 필드 중 하나라도 누락되면, Claude는 파일에 손을 대기 전에 질문을 합니다. 이는 Claude가 단 한 줄을 쓰기 전에 "코드베이스를 이해하기 위해" 서너 개의 파일을 읽어버리는 일반적인 실패 모드(failure mode)를 차단합니다.

architecture.md — 결정과 그 이유

아키텍처 결정은 ADR(Architecture Decision Records)로 기록됩니다 — 결정 사항, 결정에 이르게 된 배경, 그리고 그에 따른 비용입니다. 거절된 결정들도 함께 기록하며, 이들이 결과적으로 더 유용한 부분이 되기도 합니다.

미래의 어떤 세션에서 "왜 GraphQL을 사용하지 않았나요?" 또는 "실시간 데이터를 위해 WebSockets를 추가해야 할까요?"라고 물을 때, 답변은 이미 그곳에 놓여 있습니다: 검토되었고, 거절되었으며, 그 이유는 다음과하다는 식입니다. Claude도 이를 다시 열지 않고, 우리도 마찬가지입니다.

부패를 방지하는 규칙

하나의 규칙이 분리된 파일들이 과거의 모놀리스(monolith)처럼 모순된 난장판으로 변하는 것을 막아줍니다:

하나의 파일은 하나의 도메인(domain)을 소유합니다. 만약 하나의 규칙이 두 개의 파일에 존재할 수 있다면, 더 제약이 많은 파일 — 보통 core.md — 에 넣습니다. 그리고 어떤 파일에 규칙이 속해야 하는지 판단할 수 없다면, 그 규칙은 규칙이라고 하기에는 너무 모호한 것일 가능성이 높습니다.

실제 사례: 컬러 토큰(color tokens)은 core.md가 아니라 design.md에 들어갑니다. 캐시 TTL(Cache TTLs)은 architecture.md가 아니라 core.md에 들어갑니다. 업무 분담(Division of labor)은 core.md가 아니라 workflow.md에 들어갑니다. 도메인이 명확해지면 모순이 눈에 띄게 됩니다. 만약 동일한 내용이 두 파일에 나타난다면, 둘 중 하나는 틀린 것입니다.

이후 변화된 점

일반적인 작업에서 시작 토큰(Startup token) 비용이 약 60% 감소했습니다.
이제 모순을 찾아낼 수 있습니다. 두 파일에 동일한 주제가 나타나면 플래그(flag)가 지정됩니다.
새로운 규칙이 들어갈 위치가 명확해졌으며, 위치를 결정하는 과정에서 해당 규칙이 어떤 종류인지 스스로 명확히 정의하게 됩니다.
파일들을 개별적으로 검토할 수 있습니다. 프론트엔드 변경 사항은 design.md와만 대조하면 됩니다.

복잡한 설정은 아닙니다. 6개의 파일과 매니페스트(manifest)뿐입니다. 핵심은 '하나의 도메인' 원칙을 고수하는 것입니다. 파일이 두 가지 주제를 다루는 것처럼 느껴지는 순간, 파일을 분리하십시오.

계속 읽기

Part 3: Picking Models and Tools — 우리가 시도했거나 거부했던 MCP들, 그리고 그 이유.