SectorFlow Engineering Series · 3부작 중 1부 · 상위 문서

우리의 컨텍스트 예산(context budget)이 실제로 어디로 가고 있었는지, 그리고 우리가 이에 대해 무엇을 했는지에 대한 기록.

2026년 6월 · SectorFlow Engineering

이 시리즈에서 2부: Skills File 패턴 — import를 통해 CLAUDE.md의 비대화를 해결하기. 3부: 모델 및 도구 선택 — 우리가 시도하고, 거부했던 MCP(Model Context Protocol)들과 그 이유.

아무도 경고해주지 않는 문제

Claude Code는 많은 일을 할 수 있습니다. 문제는 그 모든 것이 컨텍스트(context) 위에서 실행되는데, 우리에게 주어진 컨텍스트는 그리 많지 않다는 점입니다.

SectorFlow를 시작했을 때 우리는 당연한 일을 했습니다. 저장소(repo) 루트에 CLAUDE.md 파일을 유지했고, 잘못된 모델 문자열, 일치하지 않는 캐시 TTL, 모양이 이상하게 나온 차트 등 무언가 잘못될 때마다 규칙을 하나씩 써서 파일 끝에 붙여 넣었습니다. 파일은 계속 커졌습니다. 우리는 그것이 문제가 될 때까지 실제로 그것을 문제라고 인식하지 못했습니다.

6주 차쯤 되었을 때 파일은 400줄에 달했습니다. 매 세션마다 파일 전체를 로드했습니다. 프론트엔드(Frontend) 규칙이 배포 런북(deployment runbooks) 옆에 있고, 그 옆에 데이터베이스 결정 사항이 정렬되지 않은 채 놓여 있었습니다. 그리고 몇 주에 걸쳐 규칙을 하나씩 추가했기 때문에, 일부 규칙들은 서로 정면으로 충돌하기도 했습니다. Claude는 새로운 규칙을 따르거나, 이전 규칙을 따르거나, 혹은 그 중간 어디쯤을 시도했습니다. 어떤 경우든 우리는 무언가 잘못된 결과를 얻었습니다.

분명히 말씀드리자면 이것은 Claude Code의 문제가 아닙니다. 우리의 문제이며, 해결 가능합니다. 하지만 이를 해결하려면 CLAUDE.md를 잡동사니 서랍처럼 취급하는 것을 멈춰야 했습니다.

실제로 고통스러운 것은 토큰당 가격이 아닙니다. 컨텍스트를 로드하는 데 소비되는 모든 토큰은 실제 작업을 위해 사용할 수 없는 토큰이라는 점입니다. 설정에 30,000 토큰을 써버리면, 5,000 토큰을 썼을 때보다 코드를 작성할 수 있는 여유 공간이 훨씬 적어집니다. 파일 중간쯤에서 한계치(ceiling)에 도달하면, 당신이 작업하던 내용은 그냥 사라져 버립니다.

컨텍스트는 예산이다

이것이 변화의 핵심이며, 일단 깨닫고 나면 매우 단순합니다. Claude가 세션 시작 시점에 읽는 모든 것은 나중에 코드를 작성할 때 사용할 수 없는 정보가 됩니다. 대부분의 프로젝트는 언젠가 모델이 필요할지도 모른다는 이론 하에 모든 것을 CLAUDE.md에 쌓아둡니다. 우리는 질문을 뒤집었습니다. '모델이 이 작업을 수행하는 데 무엇이 필요한가?' 그것만 로드하고, 나머지는 건너뛰는 것입니다.

이를 통해 두 가지 규칙이 도출되었습니다:

• 완전성보다 정확성 (Precision over completeness). 모든 요소를 다루려고 시도하는 거대한 컨텍스트보다, 정확한 소규모 컨텍스트가 당신에게 더 많은 도움을 줍니다.
• 필요할 때 로드 (Load on demand). 주어진 작업에 관련 있는 부분만 나타나도록 구조화하십시오.

이 규칙들은 세 가지 실제 관행으로 변모했으며, 각 관행은 이 시리즈의 개별 기사로 다뤄질 예정입니다. 이번 글은 개요, 즉 우리가 무엇을 측정했는지와 그것이 왜 중요한지에 대한 내용입니다.

우리가 실제로 변경한 것

1. 세션 시작 비용 (Session startup cost)

모든 세션은 CLAUDE.md와 그 외 임포트(import)되는 항목들을 로드합니다. 이전에는 작업 내용과 상관없이 매번 400줄짜리 파일 하나를 통째로 불러왔습니다. 이를 별도의 스킬 파일(skill files)로 분리한 후에는, UI 작업 시 core.md(제약 사항)와 design.md(시각적 요소)만 불러오고 다른 것은 불러오지 않습니다. 인프라(infra) 작업 시에는 core.md와 infrastructure.md를 불러옵니다. 시작 비용이 약 60% 감소했습니다.

2. 티켓 읽기 (Reading tickets)

Claude가 직접 티켓을 읽을 수 있도록 Linear MCP를 연결해 두었습니다. 이론적으로는 훌륭합니다. 하지만 list_issues 호출 한 번에 약 3,500 토큰이 소모되며, '읽기 / 완료 표시 / 댓글 달기'로 이어지는 전체 루프는 약 9,000 토큰이 소모됩니다. 그래서 이제 엔지니어는 수락 기준(acceptance criteria)만 붙여넣습니다. 이는 약 400 토큰 정도입니다. 8,600 토큰의 차이는 60개 이상의 티켓에 곱해지기 전까지는 별것 아닌 것처럼 들릴 수 있지만, 이는 실제 작업에 돌려줄 수 있는 약 7~8개의 전체 컨텍스트 윈도우(context windows)와 맞먹는 양입니다.

3. 요청받지 않은 파일 읽기 (Reading files it was never asked to read)

그대로 두면 Claude는 상황 파악을 위해 파일을 읽는데, 때로는 코드 한 줄을 쓰기 전에 서너 개의 파일을 읽기도 합니다. 그래서 우리는 규칙을 만들었습니다: 작업(task)에서 명시된 파일만 읽을 것. 함수를 찾아야 하나요? grep으로 찾은 다음 해당 라인만 확인하세요. "컨텍스트 (context)"를 흡수하기 위해 파일을 열지 마세요. 실제로 정보가 부족하다면 질문하세요. 복잡한 작업에서 2,000~4,000개의 토큰을 절약할 수 있습니다.

4. 확인을 위한 개발 서버 구동 (Spinning up the dev server to check things)

눈으로 변경 사항을 검증한다는 것은 서버를 시작하고, 기다리고, 탐색하고, 스크린샷을 찍고, 평가하는—일련의 호출 체인을 의미합니다. 서버 로직, 데이터 계약 (data contracts), 또는 라우트 핸들러 (route handlers)와 같이 브라우저에서 볼 수 없는 것에 대해서는 그 체인이 아무런 정보도 주지 못합니다. 따라서 우리는 변경 사항이 사람이 브라우저에서 실제로 볼 수 있는 것일 때만 시각적 확인을 수행합니다. 구문 (syntax) 확인을 위해서는 node --check를 실행합니다. 단 한 번의 Bash 호출로 끝납니다.

수치 (The numbers)

오버헤드 원인	이전	이후	절감량
세션 컨텍스트 로드 (Session context load)	매 세션 ~400행	작업별 60–120행	~60%
...	...	...	...

이 각각은 단독으로는 괜찮으며 극적이지는 않습니다. 하지만 이들을 합치면 세션에 담길 수 있는 내용이 달라집니다. 이전에는 두세 번의 세션이 걸리던 작업이 이제는 보통 한 번의 세션 안에 들어옵니다. 이것이 핵심입니다.

구성 요소의 결합 (How the parts fit)

나머지 두 기사는 이 중 한 부분씩을 다룹니다:

• Part 2인 skills file 패턴은 시작 비용(startup cost)과 상충하는 규칙들의 혼란에 관한 것입니다. 여기서 온-디맨드 임포트 (import-on-demand) 구조가 탄생했습니다.
• Part 3인 모델과 도구 (models and tools)는 티켓 오버헤드(ticket overhead)와 파일 읽기 습관, 그리고 우리가 거절한 MCP들과 Haiku와 Sonnet 사이에서 선을 그은 기준을 다룹니다.

이유(why)를 알기 위해 이 글을 먼저 읽으세요. 그다음 방법(how)을 알기 위해 나머지 글 중 하나를 읽으시면 됩니다.

명심해야 할 한 가지

Claude Code는 컨텍스트가 작고 정확하며, 실제로 알고 있는 것과 사용자가 기대하는 것 사이의 차이를 정직하게 유지할 때 최선의 결과물을 냅니다. 모호하게 입력하면 모호하게 출력됩니다 (Vague in, vague out). 그리고 모든 것을 다 다루려고 시도하는 컨텍스트 파일은 결국 아무것도 제대로 다루지 못하게 됩니다.

계속 읽기

• Part 2: Skills File 패턴 (The Skills File Pattern) — import를 사용하여 CLAUDE.md의 비대화(bloat) 문제 해결하기.
• Part 3: 모델 및 도구 선택하기 (Picking Models and Tools) — 우리가 시도하고, 거부했던 MCP(Model Context Protocol)들과 그 이유.