컨텍스트 엔지니어링 (Context Engineering): 고성능 AI 에이전트 구축을 위한 개발자 가이드

목차

1. 프롬프트 엔지니어링 (Prompt Engineering) 시대는 끝났다
2. 컨텍스트 엔지니어링 (Context Engineering)이란 무엇인가?
   • 에이전트 (Agent)의 해부학
   • 왜 프롬프트 엔지니어링 (Prompt Engineering)만으로는 더 이상 충분하지 않은가
3. 프로덕션 하네스 (Production Harness)의 7가지 구성 요소
4. 메모리 아키텍처 (Memory Architecture): 단기 vs 장기 컨텍스트 (Context)
5. MCP: 세상을 당신의 에이전트 (Agent)에 연결하기
6. 래칫 패턴 (The Ratchet Pattern): 에이전트의 실수를 영구적인 규칙으로 전환하기
7. 멀티 에이전트 패턴 (Multi-Agent Patterns): 오케스트레이터 (Orchestrators), 서브 에이전트 (Sub-Agents), 그리고 스킬 (Skills)
8. 벤치마크 (Benchmarks) 및 실제 사례 증거
9. 시작하기: 첫 번째 컨텍스트 엔지니어링 (Context-Engineered) 에이전트 구축하기
10. 결론

프롬프트 엔지니어링 (Prompt Engineering) 시대는 끝났다

곰곰이 생각해 볼 만한 데이터 포인트가 있습니다. Terminal Bench 2.0에서 claude-opus-4.7을 실행하는 Cline의 CLI는 **74.2%**를 기록했습니다. Anthropic의 자체 모델인 Claude Code 역시 _동일한 모델_을 실행했을 때 **69.4%**를 기록했습니다. 경쟁력 있는 벤치마크에서 약 5점의 차이가 발생했는데, 이는 더 나은 모델이나 더 많은 파라미터(Parameters), 혹은 더 많은 학습 데이터(Training Data) 때문이 아니었습니다. 단지 더 나은 하네스 (Harness) 덕분이었습니다.

그 격차가 바로 컨텍스트 엔지니어링 (Context Engineering)을 해야 하는 이유 전체를 대변합니다.

지난 3년 동안 AI 개발의 지배적인 사고 모델은 '더 나은 프롬프트 (Prompt) → 더 나은 출력 (Output)'이었습니다. 시스템 메시지 (System Message)를 수정하고, 퓨샷 (Few-shot) 예시를 추가하며, 생각의 사슬 (Chain-of-thought)을 시도하는 방식입니다. LLM (Large Language Models)이 상태가 없고 (Stateless), 턴 단위로 작동하며, 한 번의 응답 후 종료되는 '어시스턴트'였을 때는 이 방식이 충분히 잘 작동했습니다. 하지만 AI는 진화했습니다. 에이전트 (Agents)는 수십 단계에 걸쳐 실행됩니다. 도구 (Tools)를 호출하고, 서브 에이전트 (Sub-agents)를 생성하며, 세션 전반에 걸쳐 메모리 (Memory)를 관리하고, 실패로부터 복구합니다. 플레이그라운드 (Playground)에서 수정한 정적인 프롬프트 (Static Prompt)만으로는 이러한 복잡성을 오케스트레이션 (Orchestrate)할 수 없습니다.

이 분야는 그 공백을 메우기 위해 새로운 학문적 영역으로 조용히 수렴하고 있습니다. 바로 **AI 에이전트를 위한 컨텍스트 엔지니어링 (Context Engineering)**입니다. 이는 에이전트의 실행 생명주기 (Execution Lifecycle) 동안 LLM의 컨텍스트 윈도우 (Context Window)에 들어가는 모든 토큰 (Token)을 의도적으로 형성하는 실무를 의미합니다. HuggingFace는 최근 이에 관한 6개 유닛 구성의 전체 인증 과정을 출시했습니다. O'Reilly는 Google Chrome 엔지니어인 Addy Osmani의 패턴에 관한 심층 분석 보고서를 발행했습니다. LangChain의 블로그는 하네스 (Harness) 아키텍처에 관한 게시물로 넘쳐나고 있습니다. 그리고 Viv Trivedy의 바이럴 된 방정식인 Agent = Model + Harness는 AI 에이전트가 실제로 무엇인지에 대한 합의된 정의가 되었습니다.

이 포스트는 해당 분야에 대한 엔지니어를 위한 가이드입니다. 이 글을 다 읽을 때쯤이면, 여러분은 이 분야가 무엇인지, 프로덕션 하네스를 7가지 핵심 구성 요소로 어떻게 분해하는지, MCP를 통해 외부 도구를 어떻게 연결하는지, 단기 및 장기 메모리를 어떻게 관리하는지, 그리고 에이전트가 매 실패를 겪을 때마다 측정 가능할 정도로 개선되도록 래칫 패턴 (Ratchet Pattern)을 어떻게 구현하는지 이해하게 될 것입니다.

컨텍스트 엔지니어링이란 무엇인가?

**컨텍스트 엔지니어링 (Context Engineering)**은 에이전트의 컨텍스트 윈도우에 매 단계마다 들어가는 내용을 설계하는 학문입니다. 여기에는 시스템 프롬프트 (System Prompt), 도구 설명 (Tool Descriptions), 대화 기록 (Conversation History), 검색된 지식 (Retrieved Knowledge), 중간 추론 (Intermediate Reasoning), 메모리 주입 (Memory Injections), 그리고 출력 형식 지침 (Output Format Instructions)이 포함됩니다. 이는 엔터를 치기 전에 내리는 일회성 결정이 아닙니다. 에이전트의 전체 실행 생명주기 동안 모든 모델 호출 (Model Call)을 형성하는 능동적인 엔지니어링 프로세스입니다.

HuggingFace의 정의는 명확합니다:

_"컨텍스트 엔지니어링: 에이전트가 생성된 출력을 개선하기 위해 필요한 것을 필요한 시점에 효율적으로 찾을 수 있도록 지식을 구조화하는 것."

말은 간단해 보이지만, 그렇지 않습니다. 에이전트의 컨텍스트 윈도우 (Context Window)는 희소하며 리스크가 큰 자원입니다. 관련 없는 이력, 중복된 도구 스키마 (Tool Schemas), 부정확한 지침 등으로 컨텍스트를 잘못 채우면, 모델은 작업의 흐름을 놓치거나, 존재하지 않는 제약 조건을 환각 (Hallucination)하거나, 아무런 성과 없는 추론에 토큰을 낭비하게 됩니다. 반면 컨텍스트를 잘 채운다면, 40단계의 작업을 수행하며 고전하던 동일한 모델이 단 한 번의 시도로 깔끔하게 작업을 완료할 수 있습니다.

에이전트의 구조 (The Anatomy of an Agent)

이 관행을 숙달하기 위해서는 먼저 모든 현대적 AI 에이전트가 공유하는 3계층 아키텍처 (Three-layer architecture)를 이해해야 합니다.

그림 1: 프로덕션 AI 에이전트의 3계층 구조 — 핵심에 위치한 모델 (Model), 중간의 스캐폴딩 (Scaffolding), 그리고 전체 실행 환경으로서의 하네스 (Harness).

**모델 (The Model)**은 중심에 있는 LLM (Large Language Model)입니다: Claude, GPT, Qwen, DeepSeek 등입니다. 모델은 텍스트를 입력받아 텍스트를 출력합니다. 모델 자체만으로는 호출 간의 메모리 (Memory)가 없고, 루프 (Loop)가 없으며, 무엇인가를 실행할 능력도 없습니다. 모델은 도구를 호출하려는 '의도 (Intent)'를 생성할 뿐, 도구 자체를 직접 호출할 수는 없습니다.

**스캐폴딩 (Scaffolding)**은 모델을 감싸고 있는 행동 정의 계층입니다. 여기에는 시스템 프롬프트 (System Prompt), 도구 설명 (Tool Descriptions), 모델의 응답이 파싱 (Parsing)되는 방식, 출력이 따라야 하는 형식, 그리고 단계 간에 상태 (State)가 유지되는 방식 등이 포함됩니다. 스캐폴딩은 모델이 세상을 '인지 (Perceive)'하는 방식을 형성합니다.

**하네스 (The Harness)**는 실행 계층입니다. 모델을 호출하고, 도구 호출을 처리하며, 출력을 라우팅 (Routing)하고, 중단 시점을 결정하며, 오류를 관리하고, 결과를 다시 컨텍스트에 피드백하는 코드입니다. 하네스는 에이전트를 실제로 '작동 (Run)'하게 만드는 요소입니다.

Viv Trivedy의 방정식은 이를 명확하게 보여줍니다:

Agent = Model + Harness

당신이 모델이 아니라면, 당신은 하네스입니다. 그리고 바로 이곳에 진정한 엔지니어링 작업이 존재합니다. 하네스가 바로 당신의 작업 영역 (Surface area)입니다.

프롬프트 엔지니어링 (Prompt Engineering)만으로는 더 이상 충분하지 않은 이유

전형적인 프롬프트 엔지니어링 (Prompt Engineering)은 _단일 추론 호출 (single inference call)_을 최적화합니다. 더 나은 지침을 작성하면 더 나은 응답을 얻습니다. 피드백 루프가 즉각적이며 다루는 영역 (surface area)이 작습니다.

에이전트 시스템 (Agentic systems)은 이 모델을 완전히 깨뜨립니다. "적절한 에러 핸들링 (error handling)을 추가하도록 이 서비스를 리팩토링하라"는 임무를 맡은 코딩 에이전트를 생각해 보십시오. 이 에이전트는 다음과 같은 과정을 수행할 것입니다:

1. 코드베이스를 이해하기 위해 여러 파일을 읽음
2. 최선의 에러 핸들링 전략에 대해 추론 (Reasoning)
3. 잠재적으로 수십 개의 파일에 걸쳐 코드 변경 사항을 작성
4. 테스트를 실행하고 그 결과를 해석
5. 실패를 수정 — 잠재적으로 여러 번의 반복 (iterations)을 통해 수행
6. 원래의 사양 (spec)에 따라 최종 결과 검증

이 각 단계는 별도의 모델 호출입니다. 각 호출에는 신중하게 큐레이션되어야 하는 컨텍스트 윈도우 (context window)가 있습니다. 즉, 관련 히스토리를 포함하고, 무관한 토큰 (tokens)을 가지치기(pruning)하며, 도구 (tool) 결과를 소비하기 적합한 형태로 포맷팅하고, 이전 세션의 메모리 (memory)를 검색하여 주입해야 합니다. 프롬프트 엔지니어링이 1단계 중 1단계만을 다룬다면, 컨텍스트 엔지니어링 (Context Engineering)은 모든 루프의 모든 단계를 다룹니다.

프로덕션 하네스 (Production Harness)의 7가지 구성 요소

프로덕션급 에이전트 하네스 (agent harness)는 시스템 프롬프트가 담긴 단일 파일이 아닙니다. 이는 에이전트 동작의 특정 측면을 각각 담당하는 7가지의 뚜렷한 구성 요소로 이루어진 설계된 시스템입니다.

1. 시스템 프롬프트 및 에이전트 설정 파일 (System Prompts & Agent Configuration Files)

이것은 여러분의 AGENTS.md, CLAUDE.md 또는 그에 상응하는 파일들입니다. 이 파일들은 에이전트의 정체성, 제약 조건, 관례(conventions), 그리고 작업 특화 지식을 인코딩합니다. 이것들은 정적인 문서가 아니라, 모든 모델 호출을 형성하는 _활성 설정 (active configuration)_입니다. 잘 관리된 AGENTS.md는 에이전트의 전체 실패 이력의 정수(distilled product)입니다 (이에 대한 자세한 내용은 Ratchet Pattern 섹션에서 다룹니다).

2. 도구 설명 및 스키마 (Tool Descriptions & Schemas)

도구 (Tools)는 에이전트가 자신의 컨텍스트 창 (Context Window) 외부로 확장하는 방법입니다: 파일 시스템 (Filesystems), 데이터베이스 (Databases), REST API, 코드 실행 환경 (Code Execution Environments), 웹 검색 (Web Search) 등이 이에 해당합니다. 각 도구의 설명 (Description) — 즉, 도구가 무엇을 하는지, 언제 사용해야 하는지, 그리고 파라미터 (Parameters)가 무엇을 의미하는지에 대한 자연어 설명 — 은 도구 자체만큼이나 중요합니다. 설명이 부실한 도구는 잘못 사용되거나 무시될 것입니다. 도구 스키마 렌더링 (Tool Schema Rendering, 설명이 모델이 보는 토큰으로 변환되는 방식)은 모델 제공자마다 크게 다르며, 이는 상당한 성능 차이를 유발할 수 있습니다.

3. 컨텍스트 창 정책 (Context Window Policy)

컨텍스트 창 정책은 각 단계에서 무엇을 포함하고, 잘라내고 (Truncated), 요약하고 (Summarised), 또는 폐기할지를 결정하는 규칙 세트입니다. 주요 결정 사항에는 다음이 포함됩니다: 대화 기록을 몇 턴까지 유지할 것인지, 원문 그대로 유지하는 대신 언제 요약할 것인지, 도구 결과 (Tool Results)를 어떻게 포맷팅할 것인지, 그리고 언제 컨텍스트 압축 (Context Compaction, 긴 컨텍스트를 짧고 충실도가 높은 요약본으로 줄이는 것)을 트리거할 것인지 등이 있습니다. 이는 대부분의 에이전트 구현에서 가장 설계가 미흡한 구성 요소 중 하나입니다.

4. 메모리 아키텍처 (Memory Architecture)

단기 메모리 (Short-term memory, 인컨텍스트 (In-context))와 장기 메모리 (Long-term memory, 외부에서 필요 시 검색됨)는 서로 다른 엔지니어링 요구 사항을 가진 별개의 시스템입니다. 아래의 전용 섹션을 참조하십시오.

5. 피드백 루프 및 백프레셔 (Feedback Loops & Backpressure)

실패를 감지하지 못하는 에이전트는 물리적 한계에 부딪힐 때까지 잘못된 방향으로 자신 있게 실행될 것입니다. 피드백 루프 (Feedback Loops)는 테스트 실패, 린트 에러 (Lint Errors), 타입 체크 결과 (Type Check Results), 어설션 위반 (Assertion Violations), CI/CD 출력과 같이 실행을 중단하고 방향을 재설정하는 신호입니다. 백프레셔 (Backpressure) (모든 품질 신호가 녹색(정상)이 될 때까지 에이전트가 성공을 선언하는 것을 방지하는 메커니즘)는 에이전트가 정직함을 유지하게 만드는 핵심 요소입니다. 이것이 없다면, 에이전트는 망가진 코드를

훅(Hooks)은 도구 실행 전, 모델 출력 후, 오류 발생 시 등 정의된 시점에서 에이전트 루프(agent loop)를 가로채어 결정론적 정책(deterministic policies)을 강제합니다. 예시: git push --force를 차단하는 실행 전 훅(pre-execution hook); 응답이 로그에 기록되기 전 개인 식별 정보(PII)를 제거하는 출력 후 훅(post-output hook); 컨텍스트 압축(context compaction)이 트리거될 때 실행되는 지속 훅(continuation hook). 훅은 모델의 동작에 영향을 받지 않는 제어 지점을 제공합니다. 즉, 모델이 무엇을 결정하든 상관없이 결정론적으로 실행됩니다.

7. 관찰 가능성 (Observability): 트레이스(Traces), 비용, 그리고 지연 시간 (Latency)

관찰할 수 없는 에이전트는 디버깅할 수 없는 에이전트입니다. 프로덕션 하네스(Production harnesses)는 모든 모델 호출에 대해 입력 토큰(input tokens), 출력 토큰(output tokens), 수행된 도구 호출(tool calls), 수신된 도구 결과(tool results), 단계별 지연 시간(latency per step), 실행당 총 비용을 측정합니다. LangSmith, Langfuse, 그리고 Helicone이 이를 위한 선도적인 플랫폼입니다. 트레이스(traces)가 없다면 실패하는 에이전트는 블랙박스(black box)와 같습니다. 트레이스가 있다면 모든 실패는 재현하고 수정할 수 있는 읽기 가능한 이벤트 시퀀스가 됩니다.

메모리 아키텍처 (Memory Architecture): 단기 vs. 장기 컨텍스트

메모리는 에이전트 하네스(agent harness) 설계에서 가장 오해받는 구성 요소이며, 이를 잘못 설계하면 매우 좌절스러운 에이전트 버그가 발생합니다. 예를 들어 에이전트가 전달받은 제약 사항을 "망각"하거나, 이미 완료한 작업을 반복하거나, 이전 세션의 지식을 적용하지 못하는 경우입니다.

아키텍처는 두 가지 뚜렷한 계층으로 나뉩니다:

**단기 메모리 (Short-term memory)**는 단일 에이전트 실행 동안 컨텍스트 윈도우(context window) 내에 존재하는 모든 것을 의미합니다. 여기에는 대화 기록(이전 턴, 도구 호출, 도구 결과), 중간 추론(intermediate reasoning), 그리고 에이전트가 현재 작업을 위해 로드한 모든 문서나 코드가 포함됩니다. 단기 메모리는 빠르고 즉각적으로 접근 가능하지만, 유한하고 비용이 많이 들며 휘발적(ephemeral)입니다. 실행이 종료되면 사라집니다.

**장기 메모리 (Long-term memory)**는 세션 전반에 걸쳐 지속됩니다. 이는 벡터 데이터베이스 (vector databases), 키-값 저장소 (key-value stores), 또는 구조화된 데이터베이스 (structured databases)와 같은 외부 저장소에 저장되며, 필요할 때 검색되어 관련성이 있을 경우 컨텍스트 창 (context window)에 주입됩니다. 이를 통해 에이전트는 귀하의 팀이 프로덕션 코드에서 console.log를 절대 사용하지 않는다는 사실이나, 특정 API에 알려진 속도 제한 (rate-limiting) 버그가 있다는 사실을 "기억"할 수 있습니다.

엔지니어링 측면의 과제는 주입 계층 (injection layer)입니다. 즉, 어떤 장기 메모리를 검색할지, 언제 검색할지, 그리고 모델이 이를 노이즈가 아닌 높은 신뢰도의 컨텍스트로 취급할 수 있도록 어떻게 포맷팅하여 주입할지를 결정하는 것입니다.

다음은 컨텍스트 인식 메모리 관리자 (context-aware memory manager)를 위한 실용적인 Python 패턴입니다:

import json
from typing import Any
from openai import OpenAI
...

핵심 통찰: 컨텍스트 창 관리 (context window management)는 수동적이지 않습니다. 에이전트 루프 (agent loop)의 모든 단계에서, 여러분의 하네스 (harness)는 무엇을 유지할지, 무엇을 압축할지, 그리고 무엇을 검색할지를 능동적으로 결정해야 합니다.

MCP: 세상을 당신의 에이전트에 연결하기

**모델 컨텍스트 프로토콜 (Model Context Protocol, MCP)**은 사용 중인 모델이나 프레임워크에 관계없이 외부 도구, API, 데이터 소스를 모든 AI 에이전트에 연결하기 위한 신흥 표준입니다. 이를 에이전트 통합의 USB-C라고 생각하십시오. 하나의 프로토콜로 모든 도구를 연결합니다.