"Context Engineering — 모델에게 무엇을 보여줄 것인가 (하네스 시리즈 2/6)"

-

시리즈 1/6에서 정의한 7가지 엔지니어링 문제 중 두 번째. 모델에게 무엇을 보여줄지 결정하는 일. 좋은 컨텍스트 → 좋은 답. 컨텍스트가 망가지면 GPT-5.5도 GPT-2처럼 답한다.

Part 1에서 Agent = Model + Harness 명제를 봤다. 이번 글은 그 하네스의 가장 중요한 한 축인 Context Engineering을 다룬다.

Context Engineering = "모델 입력에 무엇을 어떻게 채울지를 시스템적으로 설계하는 일." 단순히 길게 채우는 게 아니라 동적으로 조립한다.

이 글은 그 원리·기법·도구별 구현(Claude Code, Cursor, oMLX 등)을 다룬다.

시리즈 (6편)

  1. 하네스 엔지니어링이란 — 정의·역사·중요성
  2. Context Engineering ← 이 글
  3. Memory Systems — 세션/장기 메모리, 벡터 vs SQL
  4. Tools & Sandboxing — Tool spec, MCP, VM 격리
  5. Multi-Provider Routing — 비용/품질 라우팅, fallback
  6. Evaluation & Ops — Eval harness, observability, runner

1. 컨텍스트 윈도우 = 공유 예산

토큰 1개 ≈ 영어 0.75 단어. 128K 윈도우 = 약 96,000 단어. 100만 토큰 = 75만 단어 (장편소설 5권 분량).

이 예산을 다음이 함께 쓴다: - 시스템 프롬프트 - 검색된 문서 (RAG) - 대화 이력 - 모델의 출력 - 도구 호출 결과 (MCP 등)

핵심: "더 큰 컨텍스트 윈도우 = 더 좋은 결과"가 아니다. 예산을 어디에 쓰느냐가 결정.

2026년 주요 모델 컨텍스트

모델 컨텍스트
GPT-5.5 1.05M tokens (272K 초과 시 2× 요율)
Claude Opus 4.7 200K (1M 옵션)
DeepSeek V4 1M tokens
Kimi K2.6 256K tokens
Qwen3.6-27B 262K (YaRN으로 1M 확장 가능)

100만 토큰이 표준화됐지만 — 다 채우는 게 답이 아니다.

2. 왜 "다 채우면 안 되는가" — Lost in the Middle

대규모 컨텍스트 연구의 일관된 결과:

모델은 컨텍스트의 첫 부분과 마지막 부분을 가장 잘 사용한다. 중간은 약하다 (Lost in the Middle 문제).

그래서 1M 토큰을 다 채우면: - TTFT (Time To First Token) 길어짐 (prefill 비용 ↑) - 비용 ↑ - 정확도 ↓ (중간 정보 묻힘) - 추론 burn-out: 50-step 워크플로우 × 20K 토큰/call = 1M 누적, 추론 질이 떨어짐

결론: 컨텍스트는 작게, 정확하게 채우는 게 항상 낫다.

3. 5가지 핵심 기법

3-1. Auto-Compact (자동 압축)

컨텍스트 사용률이 한계에 가까워지면 자동으로 옛 내용을 요약해서 자리 비움.

Claude Code: 토큰 사용률이 약 98%에 도달하면 자동 compact 실행. 옛 이력을 요약해 새 자리 만든다.

oMLX는 SSD KV 캐시로 또 다른 접근 — 압축이 아니라 외부 저장.

3-2. Hierarchical Processing (계층적 처리)

오래된 컨텍스트를 추상으로 변환: - Raw: "사용자가 X 파일에서 line 42를 수정했다 → ..." - 1단계 요약: "사용자가 X 파일 인증 로직 수정" - 2단계 요약: "이번 세션에서 인증 + 라우팅 작업"

수준이 깊을수록 정보 압축률 ↑, 세부 손실 ↑. 균형 필요.

3-3. Tool Output Limiting (도구 출력 제한)

도구 호출 결과가 컨텍스트를 빠르게 잡아먹는다.

Claude Code 기본값: MCP 도구 출력 25,000 토큰 한도, 10,000 토큰에서 경고. 서버가 명시적으로 허용하면 최대 500,000 문자까지 파일로 저장.

도구 결과를 전부 컨텍스트에 넣지 않고, 큰 결과는 디스크 저장 → 모델은 요약·인덱스만 본다.

3-4. Reference vs Inline (참조 vs 인라인)

코드 파일을 통째로 컨텍스트에 넣는 대신: - 파일 경로만 시스템 프롬프트에 - 모델이 필요할 때 Read 도구로 그때그때 가져옴

이렇게 하면 컨텍스트가 동적으로 채워진다. 100K 파일을 매번 안 들고 다닌다.

3-5. CLAUDE.md / 프로젝트 컨텍스트 파일

지속적인 프로젝트 정보를 별도 파일에 두고 매 세션 자동 로드.

Claude Code: 프로젝트 루트의 CLAUDE.md를 모든 세션에서 자동 로드. 사용자 정의 명령, 코딩 컨벤션, 금지 패턴 명시.

이 파일은 Guides (Part 1 분류)에 해당하며, 휘발되지 않고 누적된다.

4. Claude Code의 5-Layer Compaction Pipeline

arXiv 2604.14228 ("Dive into Claude Code")에 따르면 Claude Code는 컨텍스트 관리를 5단 파이프라인으로 한다:

  1. Live conversation buffer — 직전 대화 그대로
  2. Recent tool results — 최근 도구 호출 결과 (제한적 보존)
  3. Compacted history — 옛 이력 요약본
  4. Project context — CLAUDE.md + 프로젝트 메타
  5. System primitives — 핵심 시스템 프롬프트

각 레이어는 서로 다른 압축률과 수명을 가진다. 1번이 가득 차면 옛것을 2~3번으로 evict, 거기서 또 가득 차면 요약.

단순 FIFO와 차이

일반 챗봇은 그냥 가장 오래된 메시지를 버린다. Claude Code는 요약하고 보존한다 — 정보 손실 최소화하면서 자리 확보.

5. MCP (Model Context Protocol) — 표준 도구 인터페이스

Anthropic이 2024년 11월에 공개한 MCP는 도구 호출의 표준 프로토콜이다. 2026년 현재 Claude Code, Cursor, OpenAI Codex CLI 모두 MCP 서버를 사용한다.

핵심 컨텍스트 영향

  • MCP 서버는 외부 시스템 (DB, API, 파일시스템)을 도구로 노출
  • 도구 호출 결과는 컨텍스트 윈도우로 들어간다 → 압박 발생
  • Claude Code의 25K/500K 한도는 이 압박을 다스리는 메커니즘

잘 짠 MCP 서버 vs 나쁜 MCP 서버

  • 좋은 서버: 결과를 요약해서 반환, 큰 데이터는 ID만 주고 별도 fetch
  • 나쁜 서버: 50K 줄 SQL 결과를 통째로 토해서 컨텍스트 폭발

도구 작성자가 컨텍스트 엔지니어링을 공동 책임진다는 의미다.

6. 실전 패턴

6-1. 시스템 프롬프트 다이어트

  • 안 좋은 예: "당신은 매우 도움이 되는, 친절하고, 협조적이며, 깊이 사고하는, 정확하고..."
  • 좋은 예: "Goal-driven. State results directly. No filler."

설명적 미사여구 대신 행동 명령으로. 토큰 절약 + 모델이 명확한 행동 지침.

6-2. 진행 상태 외부화

긴 작업 중간 상태를 외부 파일(plan.md, tasks/)에 저장 → 컨텍스트 클리어 후 재로드.

CLAUDE.md 패턴: 모든 작업 끝에 tasks/sessions/에 스냅샷 저장. 다음 세션 자동 로드.

6-3. Sub-agent 격리

긴 검색·분석은 sub-agent에게 위임 → 결과만 받음. 메인 컨텍스트가 검색 과정 details로 오염되지 않음.

Claude Code의 Agent 도구가 이 패턴.

6-4. RAG vs Long Context

  • RAG: 100K 문서를 외부 인덱스에 두고 질의별로 5K만 가져옴
  • Long Context: 100K를 그대로 컨텍스트에 채움

비교: | 항목 | RAG | Long Context | |---|---|---| | 비용 | 낮음 | 높음 (전체 prefill) | | 정확도 | 검색 품질에 의존 | 자체 attention | | 갱신 | 인덱스만 갱신 | 매번 다시 채움 | | 권장 | 정형 검색 | 한 번에 전체 추론 |

큰 모델 + 1M 컨텍스트가 표준화돼도 RAG는 비용 측면에서 우위가 사라지지 않는다.

7. 도구별 구현 비교

도구 Auto-compact Tool 결과 한도 프로젝트 컨텍스트 외부 메모리
Claude Code ✅ (~98%에서) 25K/500K CLAUDE.md ✅ (Skills, MCP)
Cursor 3 ✅ — .cursorrules ✅ (cloud agent)
OpenClaw ✅ — CLAUDE.md (호환) ✅ (memcore)
Hermes ✅ — 자체 ✅ (FTS5 + vector)
oMLX — (모델 레벨) — — SSD KV cache

oMLX는 모델이 아닌 추론 서버 레벨에서 KV cache를 SSD에 영속화 → 같은 시스템 프롬프트 반복 호출 시 prefill 비용 0에 가깝게.

8. Anti-patterns (자주 보는 실수)

8-1. "윈도우 큰 모델로 그냥 다 넣으면 됨"

1M 윈도우라도 다 채우면: - TTFT 폭발 (prefill 시간 ∝ N²) - 비용 폭발 (272K 초과 GPT-5.5는 2× 요율) - 중간 정보 손실 (Lost in the Middle)

8-2. "도구 결과 그대로 컨텍스트로"

SQL 50K 줄을 통째로 넣으면 다음 turn에 모든 토큰이 그걸 반복적으로 처리. 결과 요약 + 외부 저장 필수.

8-3. "CLAUDE.md에 다 넣자"

CLAUDE.md가 30K 토큰이면 매 세션 시작에 30K가 깎임. 핵심만 + 자주 안 쓰는 지식은 별도 docs/에 두고 필요 시 로드.

8-4. "대화 이력은 다 보존"

긴 대화는 압축 + 외부화. 챗봇 패러다임을 에이전트로 옮길 때 가장 흔한 실수.

정리

Context Engineering은 단순 윈도우 크기 게임이 아니다.

원칙 한 줄
작게 + 정확히 1M 채우는 것보다 5K 정확한 게 낫다
동적 조립 정적 prompt가 아닌 런타임 빌드
외부화 메모리·도구·파일을 컨텍스트 밖에 두고 그때 가져옴
Auto-compact 한계 도달 전 자동으로 압축
Layer 분리 시스템·프로젝트·세션·도구 결과는 서로 다른 수명

핵심 한 문장: "컨텍스트 윈도우는 공유 예산이다. 모든 토큰은 비용을 가진다."

다음 편(3/6)은 컨텍스트 밖에서 정보를 보존하는 방법 — Memory Systems를 다룬다.

참고 자료 (1차 출처)

  • "Dive into Claude Code": arxiv.org/abs/2604.14228 (Liu et al., 2026-04-14)
  • Anthropic MCP 명세: modelcontextprotocol.io
  • Lost in the Middle: arXiv:2307.03172
  • Martin Fowler 하네스 글: martinfowler.com/articles/harness-engineering.html

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »