컨텍스트는 우유다

Part I — Expiration Date

유통기한이 있는 자원

Tip 05 — Context Is Like Milk

AI 컨텍스트는 우유와 같다. 신선하고 응축된 상태가 최고다

새 주제마다 새 대화를 시작하라. 대화가 길어질수록 성능은 떨어진다. 신선한 컨텍스트가 가장 좋은 결과를 낸다.

Claude Code의 컨텍스트 윈도우는 200K 토큰이다. 영어 기준으로 약 15만 단어, 한글로는 그보다 적다. 넉넉해 보이지만 문제는 양이 아니라 질이다.

대화가 길어지면 세 가지 일이 동시에 일어난다.

주의력 분산

초반 대화의 맥락이 희미해진다. 5번째 요청에서 1번째 요청의 세부사항을 기억하지 못하는 경우가 생긴다.

노이즈 누적

시행착오, 잘못된 방향, 중간 결과물이 쌓인다. 이 노이즈가 새로운 응답의 품질을 낮춘다.

비용 증가

매 응답마다 전체 컨텍스트를 처리한다. 대화가 길수록 각 응답에 드는 토큰 비용과 시간이 늘어난다.

대화 길이에 따른 응답 품질 변화 (체감)

0-10K

100%

10-50K

~85%

50-100K

~65%

100-200K

~40%

GeekNews의 한 리뷰어는 이렇게 말했다. "Python, Ruby, TypeScript 50M+ 토큰 프로젝트에 Claude Code를 투입했는데, 압축 대신 새 채팅 시작과 Scratchpad 기반 기록 방식이 훨씬 나았다." 핵심 규칙은 단순하다. 하나의 대화에 하나의 주제.

컨텍스트는 우유와 같다.
신선하고 응축된 상태일 때 가장 좋다.

ykdojo — Tip 05

Part II — Manual Compaction

수동 압축의 기술

Tip 08 — Proactively Compact Your Context

자동 압축에 의존하지 마라. 직접 관리하라

자동 압축을 끄고, HANDOFF.md 파일로 진행 상황을 수동으로 정리한 뒤 새 대화를 시작하라. 또는 /plan 모드로 포괄적 계획을 세워라.

Claude Code에는 /compact 커맨드와 자동 압축 기능이 있다. 대화가 길어지면 자동으로 이전 내용을 요약하여 컨텍스트를 줄인다. 문제는 자동 압축이 무엇을 버릴지 당신이 통제할 수 없다는 것이다.

Before — Auto Compact

자동 압축의 한계

Claude가 알아서 요약한다. 하지만 "중요한 설계 결정"과 "시행착오 로그"를 구분하지 못할 수 있다. 정작 필요한 맥락이 날아가는 경우가 생긴다.

After — Manual Handoff

수동 핸드오프의 정밀함

직접 HANDOFF.md를 작성하여 현재 진행 상황, 핵심 결정사항, 다음 단계를 기록한다. 새 대화에서 이 파일을 참조하면 맥락이 정확하게 이어진다.

HANDOFF.md 템플릿

# 현재 상태 인증 모듈 리팩토링 중. JWT에서 세션 기반으로 전환. # 완료된 것 - auth/session.ts 생성 (Redis 세션 스토어) - middleware/auth.ts JWT 검증 로직 제거 - 테스트 12개 중 8개 통과 # 남은 것 - auth/refresh.ts 토큰 갱신 로직 → 세션 연장으로 변경 - 실패하는 테스트 4개 수정 - API 엔드포인트 3개에서 req.user 타입 변경 # 핵심 결정 - 세션 TTL: 30분 (refreshable) - Redis 키 패턴: sess:{userId}:{sessionId} - 기존 JWT 토큰은 24시간 유예 후 만료

HANDOFF.md의 핵심은 "다음 Claude가 알아야 할 것만" 적는 것이다. 시행착오 과정, 에러 로그, 시도했다 실패한 방법은 적지 않는다. 오직 현재 상태, 완료된 것, 남은 것, 핵심 결정만. 이것이 "응축된 컨텍스트"다.

Part III — Decomposition

큰 문제를 잘게 쪼개라

Tip 03 — Break Down Large Problems

어려운 작업은 점진적으로 더 작은 하위 문제로 분해하라

소프트웨어 엔지니어링의 기본 원칙이 AI 코딩에도 동일하게 적용된다. 큰 문제를 한 번에 던지면 Claude도 헤맨다.

많은 사용자가 "전체 앱을 리팩토링해줘"같은 요청을 한다. Claude는 열심히 시도하지만, 결과는 대부분 실망스럽다. 이유는 간단하다. 한 번의 대화에 담기엔 맥락이 너무 많고, 변경 범위가 너무 넓기 때문이다.

Bad — One Shot

"이 앱 전체를 TypeScript로 마이그레이션해줘"

50개 파일을 한 번에 바꾸려 한다. 중간에 타입 에러가 연쇄적으로 발생하고, 컨텍스트가 오염되어 뒷부분이 엉망이 된다.

Good — Decomposed

단계별로 분해한 접근

대화 1: tsconfig.json 설정과 마이그레이션 전략 수립
대화 2: 유틸리티 모듈(의존성 없는 파일) 변환
대화 3: 서비스 레이어 변환
대화 4: API 라우트 변환 + 타입 정합성 확인

분해의 기준은 "하나의 대화에서 검증 가능한 단위"다. 각 단계가 끝나면 테스트를 돌리거나 빌드를 확인할 수 있어야 한다. 검증 없이 다음 단계로 넘어가면, 에러가 눈덩이처럼 불어난다.

이것은 컨텍스트 관리와 직결된다. 분해된 각 작업은 하나의 신선한 대화에서 처리된다. 이전 작업의 노이즈가 없는 깨끗한 상태에서 시작하므로 응답 품질이 일정하게 유지된다.

Part IV — System Prompt Diet

시스템 프롬프트 다이어트

Tip 15 — Slim Down the System Prompt

쓰지 않는 기능은 꺼라. 토큰의 50%가 시스템 프롬프트에 쓰인다

안 쓰는 기능을 비활성화하고, MCP 도구를 레이지 로딩하고, 시스템 프롬프트를 필수 정보만으로 줄여라.

Claude Code가 시작될 때 로드되는 시스템 프롬프트에는 도구 설명, MCP 서버 목록, CLAUDE.md 내용 등이 포함된다. MCP 서버를 여러 개 연결하면 시스템 프롬프트만으로 수만 토큰을 차지할 수 있다. 매 응답마다 이 토큰이 소비된다.

ykdojo의 실험에 따르면, 불필요한 기능을 정리하는 것만으로 시스템 프롬프트 토큰을 50% 줄일 수 있었다. 이는 곧 매 응답의 비용과 속도 개선으로 직결된다.

MCP 레이지 로딩

모든 MCP 도구를 항상 로드하지 말고, 필요할 때만 로드하도록 설정한다. 안 쓰는 MCP 서버는 비활성화한다.

CLAUDE.md 경량화

CLAUDE.md에 프로젝트의 모든 것을 적지 않는다. Claude가 매번 읽어야 할 "핵심 규칙"만 남기고, 상세 가이드는 별도 파일로 분리한다.

미사용 기능 비활성화

settings.json에서 사용하지 않는 기능을 끈다. 브라우저 통합, 특정 도구 등을 비활성화하면 그만큼 시스템 프롬프트가 줄어든다.

Part V — CLAUDE.md Architecture

CLAUDE.md라는 아키텍처

Tip 25 + 30 — CLAUDE.md vs Skills vs Slash Commands

각각의 역할을 이해하고, CLAUDE.md는 간결하게 유지하라

CLAUDE.md는 영구적 지시사항, Skills는 조건부 로딩, Slash Commands는 빠른 실행, Plugins는 기능 확장. 각각 다른 목적을 가진다.

CLAUDE.md

영구적 지시사항

프로젝트 루트에 놓는 파일. Claude Code가 매번 읽는다. 코딩 컨벤션, 아키텍처 규칙, 테스트 방법 등 항상 지켜야 할 규칙을 적는다.

언제: 모든 작업에 적용되는 규칙

Skills

조건부 로딩 지시사항

특정 작업 유형에서만 필요한 상세 가이드. 필요할 때만 로드되므로 시스템 프롬프트를 불필요하게 늘리지 않는다.

언제: "CSS 수정할 때만" "테스트 작성할 때만"

Slash Commands

빠른 실행 단축어

/commit, /review 같은 반복 작업을 한 단어로 실행. 복잡한 프롬프트를 매번 타이핑하지 않아도 된다.

언제: 반복되는 작업 패턴

Plugins

기능 확장

외부 도구와의 통합, 커스텀 도구 추가 등 Claude Code의 기능 자체를 확장한다.

언제: 기본 기능으로 부족할 때

가장 흔한 실수는 CLAUDE.md에 모든 것을 적는 것이다. 프로젝트 히스토리, API 문서, 코딩 스타일 가이드, 배포 절차를 전부 때려넣으면 시스템 프롬프트가 비대해지고, 정작 중요한 규칙이 묻힌다.

CLAUDE.md 작성 원칙

10줄 이내의 핵심 규칙만 적는다. 상세 가이드는 Skills로 분리한다
주기적으로 리뷰한다. 오래되었거나 불필요한 지시사항을 삭제한다
"하지 마라" 규칙을 명시한다. Claude가 자주 실수하는 패턴을 금지한다
프로젝트의 기술 스택과 아키텍처 결정사항만 포함한다
구체적인 코드 예시는 넣지 않는다. 규칙만 적고, 예시는 코드베이스를 참조하게 한다

CLAUDE.md는 코드베이스의 아키텍처 문서와 같다. 잘 설계된 CLAUDE.md는 모든 대화의 품질을 올리고, 비대한 CLAUDE.md는 모든 대화의 성능을 낮춘다.

컨텍스트 관리는 코딩 실력만큼 중요하다.
같은 도구도 워크플로우에 따라 10배 차이가 난다.

GeekNews Korean Developer Review

신선하게, 응축하여, 구조화하라
그것이 전부다

다음 편 "자율 주행 모드"에서는 테스트와 검증 수단을 제공하여 Claude를 자율적으로 작업하게 만드는 법을 다룬다. 감독에서 위임으로 전환하는 핵심 기술.