컨텍스트 엔지니어링 실전 가이드 — Claude Code로 배우는 4가지 전략

CLAUDE.md를 작성하고, rules를 정비하고, agents도 만들었다. 그런데도 Claude Code의 출력 정밀도가 안정되지 않는다——그런 경험은 없는가. 원인은 "프롬프트 작성법"이 아니라, 컨텍스트(Context) 설계에 있을 가능성이 높다. 본 기사에서는 업계에서 널리 채택되고 있는 4가지 설계 전략을 Claude Code의 구체적인 기능에 매핑하면서, "무엇을·언제·어느 정도의 입도(granularity)로 전달할 것인가"에 대한 판단 기준을 제시한다.

왜 "프롬프트"가 아니라 "컨텍스트"인가

Andrej Karpathy(전 Tesla AI 책임자)는 2025년 6월, 다음과 같이 말했다.

"Context engineering is the delicate art and science of filling the context window with just the right information for the next step."
(컨텍스트 엔지니어링은 다음 단계를 위해 컨텍스트 윈도우(Context Window)를 딱 적절한 정보로 채우는 섬세한 예술이자 과학이다.)

그의 비유는 심플하다. LLM은 CPU, 컨텍스트 윈도우는 RAM이다. RAM에 무엇을 로드하느냐에 따라 CPU의 처리 결과가 결정된다. 2026년 3월에는 Claude의 1M 컨텍스트 윈도우가 GA(General Availability)가 되어, 사용할 수 있는 "RAM"이 격단히 넓어졌다. 하지만 RAM이 늘어났다고 해서 설계 없이 정보를 채워 넣으면 되는 것은 아니다——오히려 설계의 중요성은 커지고 있다.

"프롬프트 엔지니어링 (Prompt Engineering)"이 명령문의 표현을 최적화하는 기술이라면, "컨텍스트 엔지니어링 (Context Engineering)"은 시스템 프롬프트(System Prompt)·RAG·도구 출력(Tool Output)·대화 이력(Conversation History)·메모리를 포함하는 윈도우 전체의 정보 설계다. Prompt Engineering은 컨텍스트 엔지니어링의 서브셋(Subset)에 불과하다.

관점	Prompt Engineering	Context Engineering
초점	지시문의 단어·구조	컨텍스트 윈도우 전체
...

현장의 과제: CLAUDE.md에 200줄을 썼는데 출력이 안정되지 않는다

이 문제는 "프롬프트가 나쁘다"가 아니라, 컨텍스트 설계가 결여되어 있는 것이 원인인 경우가 많다. 정보를 "넣는" 것만으로는 불충분하며, "무엇을 넣지 않을 것인가", "언제 넣을 것인가", "어느 정도의 입도로 넣을 것인가"를 설계해야 한다.

Chroma Research가 18개 모델을 대상으로 실시한 연구에서는 컨텍스트 길이가 증가하면 모델의 성능이 저하되는 경향이 관찰되고 있다 (Context Rot). 또한 Stanford의 연구(2023년, GPT-3.5/Claude 2 세대 대상)에서는 컨텍스트 중간 부분의 정보 정밀도가 15~20포인트 저하되는 "Lost in the Middle" 효과가 보고되었다. 다만 저하 정도는 태스크나 모델에 따라 다르며, 최신 모델에서는 개선이 진행되고 있다는 점에 유의할 필요가 있다.

게다가 컨텍스트의 비대화는 비용 측면에서도 직격탄을 맞는다. LLM API는 토큰 단가로 과금되기 때문에, 불필요한 정보를 컨텍스트에 포함하는 것만으로도 입력 비용이 불어난다. 멀티 에이전트(Multi-agent) 구성에서는 서브 에이전트(Sub-agent)마다 컨텍스트를 소비하므로, 비용 승수 효과도 무시할 수 없다.

즉, CLAUDE.md에 모든 것을 채워 넣는 것은 RAM을 무관한 데이터로 가득 채우는 것과 같다.

4가지 설계 전략과 Claude Code 매핑

LangChain이 "Context Engineering for Agents"에서 체계화한 4가지 전략이 있다. Anthropic도 공식 블로그에서 압축·선택적 주입·서브 에이전트와 같은 유사한 설계 원칙을 논하고 있다. 여기서는 각 전략을 Claude Code의 기능에 매핑하지만, 4가지 전략 자체는 도구에 의존하지 않는 범용 개념이다. Cursor, GitHub Copilot, Cline 등 다른 도구에서도 동일한 설계 사상을 적용할 수 있다. Claude Code 고유의 기능명을 외우는 것보다, 배후의 판단 기준을 이해하는 것이 중요하다.

전략 1: Write (영속화하기)

개념: 에이전트가 미래의 자신이나 다른 에이전트를 위해 정보를 기록해 남긴다.

Claude Code에서의 구현:

기능	Write의 역할	구체적인 예시
CLAUDE.md	프로젝트 지식의 영속화 (Persistence)	아키텍처 방침, 명령어, 명명 규칙
auto-memory	세션 간의 학습 결과를 MEMORY.md에 저장	"bun을 사용함", "테스트는 Vitest 사용"
핸드오프(Handoff) 파일	페이즈(Phase) 간의 정보 전달	.claude/handoff/에 중간 결과물을 기록

설계 판단: 무엇을 CLAUDE.md에 쓰고, 무엇을 memory에 맡길 것인가

판단 기준	CLAUDE.md에 작성	memory에 위임
변경 빈도	낮음 (월 단위로 변하지 않음)	높음 (세션마다 업데이트됨)
...

주의: CLAUDE.md는 간결하게 유지하는 것이 중요하다. 실무적인 기준으로 200행 이내로 유지하고, 이를 초과하는 정보는 rules/로 분리한다. 이는 다음인 「Select」 전략으로 이어지는 가교 역할을 한다.

전략 2: Select (선택적으로 주입하기)

개념: 필요한 정보만을 적절한 타이밍에 컨텍스트 (Context)에 주입한다.

Claude Code에서의 구현:

기능	Select의 역할	주입 타이밍
rules/	파일 패턴에 따른 규칙 주입	대상 파일을 열었을 때
skills	사용자의 호출에 따른 주입	/skill-name을 실행했을 때
MCP	외부 데이터 소스로부터의 동적 취득	도구 (Tool) 호출 시

설계 판단: rules에 쓸 것인가, skills에 쓸 것인가, MCP로 할 것인가

판단 기준	rules/	skills	MCP
트리거	파일 패턴에 자동 연동	사용자의 명시적인 호출	도구 호출
...	*.test.ts → 테스트 규약	/commit → 커밋 워크플로우	Context7 → 공식 문서

이 판단을 잘못하면 어떻게 되는가: 테스트 규약을 CLAUDE.md에 작성해 버리면, 테스트와 무관한 태스크를 수행할 때도 컨텍스트를 계속 소비하게 된다. rules/로 분리하면 테스트 파일에 접근했을 때만 주입된다. 이것이 Select 전략의 본질이다.

전략 3: Compress (압축하기)

개념: 중요도를 유지하면서 정보량을 줄인다.

Claude Code에서의 구현:

기능	Compress의 역할	발동 조건
자동 컴팩션 (Auto-compaction)	대화가 길어지면 과거의 상호작용을 자동 압축	컨텍스트 윈도우 (Context Window) 상한에 도달했을 때
/clear	명시적으로 컨텍스트를 리셋	사용자가 임의의 타이밍에 실행
핸드오프의 2층 구조	"요약 + 상세"로 정보를 계층화	페이즈 (Phase) 간의 인수인계 시

설계 판단: 언제 /clear를 할 것인가

/clear는 "컨텍스트의 수동 가비지 컬렉션 (Garbage Collection)"이다. 다음과 같은 타이밍에 실행하면 효과적이다.

• 태스크 전환 시: 리팩터링에서 테스트 작성으로 넘어갈 때
• 큰 페이즈(Phase) 완료 시: 리서치 → 설계 → 구현의 각 페이즈 경계
• 컨텍스트가 비대해졌을 때: Lost in the Middle 현상이 나타나기 전에 리셋

Context Rot을 방지하는 핸드오프 패턴: 서브 에이전트의 결과를 받을 때, 전체 내용이 아니라 요약만 메인 컨텍스트에 포함한다. 상세 내용은 파일로 기록하고, 필요할 때만 참조한다.

# 핸드오프 파일의 2층 구조
## 요약 (다음 Phase는 여기만 읽음 — 2,000 토큰 이내)
- 주요 발견 사항: 3-5개 항목
...

전략 4: Isolate (격리하기)

개념: 독립된 작업을 별도의 컨텍스트로 분리하여, 서로의 정보 오염을 방지한다.

Claude Code에서의 구현:

기능	격리 (Isolate)의 역할	유스케이스
Agent 도구	서브 에이전트 (Sub-agent)를 독립된 컨텍스트로 실행	리서치, 코드 리뷰, 테스트 실행
worktree 격리	git worktree로 물리적으로 파일을 분리	파괴적인 변경 시도
run_in_background	백그라운드에서 비동기 실행	빌드, 테스트, 장시간 처리

설계 판단: 메인에서 처리할 것인가, 서브 에이전트에게 위임할 것인가

결과에 대한 의존도: 높음	결과에 대한 의존도: 낮음
태스크 독립성: 높음
서브 에이전트 (foreground)	서브 에이전트 (background)
태스크 독립성: 낮음
메인 컨텍스트에서 처리	메인 컨텍스트에서 처리

멀티 에이전트 (Multi-agent) 설계에서는 컨텍스트 격리가 성능에 큰 영향을 미친다. 루트 에이전트 (Root agent)가 모든 이력을 서브 에이전트에게 전달하는 설계는 컨텍스트 부패 (Context Rot)를 가속화하는 안티 패턴 (Anti-pattern)이다. 서브 에이전트에게는 태스크에 필요한 최소한의 정보만 전달하고, 결과는 요약하여 반환하는 것이 철칙이다.

설계 판단 프레임워크: 5단계

새로운 프로젝트에서 컨텍스트를 설계할 때는 다음 5단계를 통해 판단한다.

Step 1: 프로젝트의 불변 지식을 식별한다 → CLAUDE.md (Write)
"빌드 명령은?" "디렉토리 구조는?" "명명 규칙은?"
Step 2: 파일 유형별 규칙을 정리한다 → rules/ (Select)
...

실례: 이 프로젝트 (zenn_post)의 설계 해부

본 기사가 작성되고 있는 프로젝트 자체가 4가지 전략의 구현 사례이다.

전략	구현	내용
Write	CLAUDE.md	프로젝트 개요, 명령어, frontmatter 규칙
Write	MEMORY.md	과거 집필을 통해 학습한 패턴, 금지 문구
Select	.claude/rules/article-conventions.md	slug 명명, topics 태그, 구성 패턴
Select	.claude/skills/zenn-article-writing/	기사 집필 워크플로우 전체 (Phase 0~7)
Compress	핸드오프 (Handoff) 2층 구조	각 Phase의 결과를 "요약 + 상세"로 분리
Compress	5곳의 /clear 포인트	Phase 완료 시마다 컨텍스트를 리셋
Isolate	병렬 서브 에이전트	리서치 에이전트 3개, 리뷰 페르소나 3개를 동시에 실행

팀 규모별 설계 가이드라인

4가지 전략을 처음부터 모두 도입할 필요는 없다. 팀 규모에 따라 단계적으로 설계하면 된다.

규모	Write	Select	Compress	Isolate
개인 개발	CLAUDE.md만 사용	불필요 또는 최소한	/clear로 충분	불필요
3~5명	CLAUDE.md + MEMORY.md	rules/ 5~10개 파일	핸드오프 2층 구조	태스크 단위의 서브 에이전트
10명 이상	서비스별로 CLAUDE.md 분할	rules/를 도메인별로 계층화	Phase 설계 필수	멀티 에이전트 설계

개인 개발에서 rules/를 10개나 만드는 것은 과잉 설계이며, 10명 규모의 팀에서 CLAUDE.md 파일 하나에 모든 정보를 집약하는 것은 시스템의 붕괴를 초래한다. 자신의 팀이 어느 단계에 있는지를 파악한 후 설계를 시작하는 것이 중요하다.

현장에서 마주하는 4가지 함정

함정 1: 컨텍스트 과적재 (Context Overload)

증상: CLAUDE.md에 프로젝트의 모든 것을 기록한다. 그 결과, 중요한 규칙이 컨텍스트 중간에 파묻혀 무시된다 (Lost in the Middle 효과).

대책: CLAUDE.md는 간결하게 유지한다 (기준 200행 이내). 초과분은 rules/로 분리하여 파일 패턴을 통해 Select 주입한다. "모두가 항상 알아야 하는 것"만을 CLAUDE.md에 남긴다.

하지만 반대 방향의 함정도 존재한다. rules/로 너무 많이 몰아내면, 파일 패턴에 일치하지 않는 태스크에서 규칙이 적용되지 않는 "Select 누락 (Select 漏れ)"이 발생한다. 이 판단은 가역적이므로, 망설여진다면 우선 분리해 보고 누락이 발생하면 다시 CLAUDE.md로 되돌리면 된다.

함정 2: 컨텍스트 모순 (Context Contradiction)

증상: CLAUDE.md에는 "테스트는 Jest"라고 적혀 있는데, rules/에서는 "Vitest를 사용"하도록 지시하고 있다. 모델의 출력이 세션마다 달라진다.

대책: 계층의 우선순위를 명확히 한다. Claude Code에서는 파일 고유 규칙 (File-specific rules) > 프로젝트 규칙 (Project rules) > 글로벌 규칙 (Global rules) 순으로 적용된다. 동일한 주제의 지시는 한 곳으로 집약한다.

함정 3: 컨텍스트 부패 (Context Decay)

증상: 반년 전에 작성한 CLAUDE.md의 정보가 오래되었음에도 불구하고, 모델은 이를 "현재의 사실"로 계속 취급한다.

대책: 메모리 (memory)의 정기적인 리뷰를 습관화한다. auto-memory가 작성한 MEMORY.md를 월 단위로 검토하여, 오래된 정보를 업데이트하거나 삭제한다. "이 정보는 언제 시점의 것인가"를 메타 정보로 기록하는 것도 유효하다.

함정 4: 전략 간의 트레이드오프 (Trade-off) 간과

증상: 4가지 전략을 개별적으로 최적화한 결과, 전략 간에 모순이 발생한다. 예를 들어, Compress를 위해 /clear를 실행한 직후, Write로 남겨두어야 할 정보가 손실된다. 또는 Isolate를 통해 서브 에이전트 (sub-agent)를 3개 병렬로 구동한 결과, 총 토큰 비용이 대략 3배가 되었다는 사실을 인지하지 못한다.

대책: 4가지 전략은 독립적인 것이 아니라 연동되어 있다. Compress를 한다면 Write (핸드오프, hand-off)를 먼저 설계한다. Isolate를 한다면 비용 승수 효과를 예측한다. 하나의 전략을 강화할 때, 인접한 전략에 미치는 영향을 확인하는 습관을 들인다.

한계와 마주하기

컨텍스트 엔지니어링 (Context Engineering)은 "만능약"이 아니다.

해결되지 않는 문제:

• LLM의 할루시네이션 (Hallucination) — 컨텍스트가 완벽해도 발생한다. 오히려 컨텍스트 모순이나 컨텍스트 부패는 할루시네이션의 리스크를 증폭시킨다. 모순된 정보를 받은 모델은 "앞뒤를 맞추기" 위해 사실을 날조하기 쉬워진다.
• 추론의 불안정성 (동일한 컨텍스트에서도 출력이 달라질 수 있음)
• 도메인 지식의 결여 (컨텍스트에 포함되지 않은 전문 지식은 보완할 수 없음)

비용:

• 설계 및 유지보수에 공수가 들어간다. CLAUDE.md / rules/ / agents의 정비는 "쓰면 끝"이 아니라, 프로젝트와 함께 진화시켜 나가야 한다.
• 과잉 설계의 리스크. 소규모 프로젝트나 개인 개발에서는 CLAUDE.md 파일 하나로 충분한 경우가 많다.
• 토큰 비용 (Token cost): 컨텍스트가 클수록 API 요금이 증가한다. 특히 멀티 에이전트 (multi-agent) 구성에서는 각 서브 에이전트의 컨텍스트 소비를 합산한 총 비용을 예측하는 것이 중요하다.

벤더 락인 (Vendor Lock-in) 리스크:

• CLAUDE.md / rules/ / skills 구조는 Claude Code 고유의 방식이다. 다른 도구로 이전할 때는 이러한 설계 자산을 재구축해야 한다.
• 단, 4가지 전략의 "판단 기준" 자체는 도구에 의존하지 않는다. 설계 사상을 이해하고 있다면 도구가 바뀌어도 응용이 가능하다.

프라이버시 주의사항:

• CLAUDE.md에 기밀 정보 (API 키, 사내 URL, 고객 데이터)를 작성하지 마라. 컨텍스트에 포함된 정보는 LLM으로 전송된다.
• auto-memory가 개인정보나 기밀 정보를 자동으로 저장할 리스크에도 주의가 필요하다. MEMORY.md의 내용은 정기적으로 리뷰해야 한다.

설계를 과하게 하지 않기 위한 판단 기준:

• 팀 멤버가 소수라면 → CLAUDE.md만으로 충분한 경우가 많다.
• 태스크가 단발성 (1세션 내 완결)이라면 → rules/는 불필요하다.
• 병렬 처리할 태스크가 없다면 → Isolate는 불필요하다.

요약: 오늘부터 할 수 있는 3가지 액션

• CLAUDE.md를 점검(Inventory)하라: 각 행이 Write / Select 중 어디에 속하는지 분류하고, Select에 해당하는 것을 rules/

이동시킨다.

상시 로드 (Always-on) vs 온디맨드 (On-demand) 분리: 「테스트 규약」, 「리뷰 기준」, 「배포 절차」 등 특정 태스크에서만 사용하는 정보를 rules/나 skills/로 분리한다.

장시간 태스크를 위한 /clear 포인트 설계: 워크플로우 (Workflow)의 페이즈 (Phase) 경계를 식별하고, "여기서 컨텍스트 (Context)를 리셋한다"라는 포인트를 결정한다.

컨텍스트 엔지니어링 (Context Engineering)의 본질은 LLM에게 "무엇을 알려줄 것인가"가 아니라 "무엇을 알려주지 않을 것인가"를 설계하는 것이다. 정보를 뺄셈하는 용기가 출력의 정밀도를 안정시킨다.

참고 문헌

• Andrej Karpathy, "Context engineering is the delicate art and science of filling the context window with just the right information for the next step.", 2025년 6월
• Anthropic, Effective context engineering for AI agents, 2025년 9월
• Chroma Research, Context Rot: How Increasing Input Tokens Impacts LLM Performance, 2025년
• LangChain, Context Engineering for Agents, 2025년
• Stanford NLP, Lost in the Middle: How Language Models Use Long Contexts, 2023년
• Anthropic, 1M context is now generally available, 2026년 3월

Discussion