컨텍스트 엔지니어링은 AI 에이전트의 효율성을 결정짓는 가장 중요한 요소 중 하나다. 이 문서에서는 컨텍스트가 무엇인지, 왜 중요한지, 그리고 Claude Code가 어떻게 정교한 컨텍스트 관리 시스템을 구축했는지 탐구한다.
하네스의 에이전트는 코드베이스를 읽고, 편집하고, 쓰기를 만들기 위해 많은 도구 호출을 능동적으로 수행할 수 있다. 이 과정에서 엄청난 양의 데이터가 생성되어 실행 중인 대화, 즉 컨텍스트 윈도우에 추가된다. Anthropic은 이 정보에서 제한된 컨텍스트 윈도우에 무엇을 넣을지 큐레이션하는 이 기술과 과학을 컨텍스트 엔지니어링이라고 부른다.
도구 호출이 어떻게 컨텍스트 윈도우에 토큰을 추가하는지 의문이 들 수 있다. 플로우는 다음과 같이 작동한다:
컨텍스트 윈도우:
├─ 사용자: "내 커피숍을 위한 랜딩 페이지를 만들어줘"
│
├─ 어시스턴트: [tool_call: web_search("모던 커피숍 랜딩 페이지 디자인")]
├─ 도구 결과: [스니펫, URL이 포함된 10개 결과] ← ~1.5K 토큰
│
├─ 어시스턴트: [tool_call: read_file("브랜드-가이드라인.pdf")]
├─ 도구 결과: [추출된 텍스트, 색상, 폰트] ← ~4K 토큰
│ (여기에 있어야 함, 모델은 stateless)
│
├─ 어시스턴트: "당신의 브랜드 색상을 사용한 따뜻하고 미니멀한 디자인을 만들겠습니다..."
├─ 어시스턴트: [tool_call: create_file("landing-page.html")]
├─ 도구 결과: [성공, 140줄] ← ~50 토큰
│
├─ 어시스턴트: [tool_call: generate_image("아늑한 커피숍 인테리어")]
├─ 도구 결과: [반환된 이미지 URL] ← ~30 토큰
│
├─ 어시스턴트: [tool_call: edit_file("landing-page.html")]
├─ 도구 결과: [diff: 히어로 이미지 + 메뉴 섹션 추가] ← ~300 토큰
│
└─ 어시스턴트: "완료! 히어로, 메뉴, 연락처 섹션이 있는 랜딩 페이지입니다."
총계: 한 작업에 ~6K+ 토큰. 모든 것이 컨텍스트에 남아 있음.여기서 주목해야 할 핵심은 도구 호출과 도구 호출 출력이 모두 컨텍스트에 추가된다는 것이다. 이는 LLM이 결과를 알 수 있도록 하기 위함이다. LLM은 stateless다 - 컨텍스트 윈도우 밖에는 메모리가 없다. 대화에 n개의 메시지가 있다고 가정하자. 다음 메시지를 보내면 요청은 LLM에서 n + 1개의 메시지를 다시 처리한다 ~ 단일 컨텍스트 윈도우.
선택한 도구 호출에 대한 정보를 추가하지 않으면 LLM은 알 수 없고, 출력을 연결하지 않으면 결과를 알 수 없다. 도구 호출 결과는 컨텍스트를 빠르게 채울 수 있으며 이것이 에이전트가 매우 비쌀 수 있는 이유이기도 하다.
Anthropic의 effective-context-engineering-for-ai-agents에서 직접 인용:
컨텍스트는 대규모 언어 모델(LLM)에서 샘플링할 때 포함되는 토큰 세트를 의미한다. 당면한 엔지니어링 문제는 일관되게 원하는 결과를 달성하기 위해 LLM의 고유한 제약에 대해 이러한 토큰의 유용성을 최적화하는 것이다. LLM을 효과적으로 다루려면 종종 컨텍스트로 생각해야 한다 - 다시 말해서: 주어진 시간에 LLM이 사용할 수 있는 전체적인 상태와 그 상태가 어떤 잠재적 행동을 유발할 수 있는지 고려해야 한다.
컨텍스트 엔지니어링은 "어떤 컨텍스트 구성이 모델의 원하는 동작을 생성할 가능성이 가장 높은가?"라는 질문에 답하는 것이다.
지금까지 논의한 모든 것이 컨텍스트 엔지니어링에 해당된다. 서브에이전트, 스크래치패드 사용, 컴팩션은 Claude Code에서 사용되는 컨텍스트 관리 방법의 명백한 예다.
제한된 컨텍스트 윈도우 - LLM의 컨텍스트 검색 성능은 새로운 토큰이 도입될 때마다 저하된다. 위 블로그를 의역하면 - 컨텍스트를 제한된 "어텐션 예산"으로 생각하라. 이것은 어텐션 메커니즘 자체의 결과로, 쌍별 관계를 모델링하기가 어려워진다 - 멀리 떨어진 것들에 집중하기가 어려워지는 것처럼 생각하면 된다.
GPT-5.2는 400K 입력 토큰의 컨텍스트 윈도우를 가지고 있다. Opus 4.5는 200K다. Gemini 3 Pro는 1M 컨텍스트 윈도우 길이를 가지고 있다. 이제 이러한 컨텍스트 윈도우의 효과는 다를 수 있으며, 길이만이 중요한 것은 아니다. 그렇긴 하지만 900K 길이의 입력에서 무언가를 묻고 싶다면 Gemini 3 Pro로만 가장 안정적으로 할 수 있을 것이다.
Chroma의 컨텍스트 부패 논문은 작업 난이도가 아닌 길이에 따른 성능 저하를 보여주는 일부 실험을 깊이 다룬다.
대략적으로 도출할 수 있는 결론은 효과적인 컨텍스트 윈도우는 아마도 50-60% 또는 그 이하일 것이다. 대화의 중간쯤에 복잡한 작업을 시작하지 마라. 컴팩션을 하거나 새로운 것을 시작하라.
프롬프트와 지금까지 본 코드에서 수행되는 모든 것은 다음을 위한 것이었다:
MCP 서버는 필자의 주력은 아니지만 다룰 가치가 있다. MCP 서버는 기계나 인터넷에서 원격으로 호스팅될 수 있는 서버다. 이것들은 파일시스템, 도구, CRM, Google Drive와 같은 통합을 노출할 수 있다. 본질적으로 모델이 외부 도구와 서비스에 연결하는 방법이다.
MCP 서버에 연결하려면 MCP 클라이언트를 수용할 수 있는 호스트(Claude)가 필요하다. MCP 클라이언트는 프로토콜을 호출하여 연결할 수 있다. 연결되면 MCP 클라이언트는 서버가 제공하는 도구, 리소스, 프롬프트를 노출한다.
도구 정의는 호스트의 컨텍스트 윈도우에 미리 로드되어 비대화시킨다.
코드 실행 with MCP의 아이디어가 마음에 든다. 비록 더 많은 토큰 소비를 위한 선전이긴 하지만.
Code execution with MCP에서 인용:
MCP 사용이 확대됨에 따라 에이전트 비용과 지연을 증가시킬 수 있는 두 가지 일반적인 패턴이 있다:
- 도구 정의가 컨텍스트 윈도우를 과부하시킨다;
- 중간 도구 결과가 추가 토큰을 소비한다.
더 많은 MCP 서버는 컨텍스트를 비대화시키는 더 많은 도구 정의를 의미한다.
MCP Code exec은 직접 도구 호출 대신 도구 호출 정의보다는 코드 API를 노출하고 Claude에게 파일시스템이 있는 샌드박스 실행 환경을 제공할 것을 제안한다. 그런 다음 도구 호출을 만들기 위한 코드를 작성하게 한다. 우아한 아이디어이며 "온디맨드 프롬프트"라는 점에서 스킬과 꽤 유사하다.
컨텍스트 저하를 방지하는 한 가지 기법은 컨텍스트에 목표를 반복적으로 주입하는 것이다. Manus는 Context Engineering 블로그에서 그들의 접근 방식을 공유했다:
암송을 통한 어텐션 조작
Manus로 작업해본 적이 있다면 이상한 것을 알아차렸을 것이다: 복잡한 작업을 처리할 때 todo.md 파일을 만드는 경향이 있고 - 작업이 진행됨에 따라 단계별로 업데이트하면서 완료된 항목을 체크한다.
이것은 단지 귀여운 행동이 아니라 - 어텐션을 조작하기 위한 의도적인 메커니즘이다.
Manus의 일반적인 작업은 평균적으로 약 50번의 도구 호출을 필요로 한다. 긴 루프다 - 그리고 Manus는 의사결정을 위해 LLM에 의존하기 때문에 특히 긴 컨텍스트나 복잡한 작업에서 주제에서 벗어나거나 이전 목표를 잊어버릴 위험이 있다.
todo 목록을 지속적으로 다시 작성함으로써 Manus는 컨텍스트 끝에 목표를 암송하고 있다. 이것은 글로벌 계획을 모델의 최근 어텐션 범위로 밀어넣어 "중간에 잃어버린" 문제를 피하고 목표 불일치를 줄인다. 사실상 특별한 아키텍처 변경 없이도 자연어를 사용하여 자체 초점을 작업 목표 쪽으로 편향시키고 있다.
Claude Code도 todo 목록을 가지고 있다. 이제 그것의 논리 일부를 안다.
Claude Code는 또한 사용자 메시지와 도구 결과에 <system-reminder> 태그를 연결하여 유사한 것을 시도한다. 일부는 도구 설명에 언급되고, 다른 리마인더는 코드를 통해 런타임에 추가된다.
Claude에게 시스템 프롬프트에 어떤 시스템 리마인더가 있는지 물어봤다. 도구 결과와 사용자 메시지에는 <system-reminder> 태그가 포함될 수 있다. 이러한 태그는 유용한 정보와 리마인더를 포함한다. 시스템에 의해 자동으로 추가되며, 나타나는 특정 도구 결과나 사용자 메시지와 직접적인 관련이 없다.
CC 2.0.56의 이전 버전에는 이러한 상세한 리마인더가 있었다. system-reminder-plan-mode-is-active를 참조.
Armin은 자신의 포스트 What Actually Is Claude Code's Plan Mode?에서 에이전트에게 상기시키는 반복 프롬프트를 언급할 때 이것에 대해 이야기하는 것으로 생각한다.
유출된 프롬프트를 보면 플랜 모드에 대해 2-3개의 프롬프트와 ENTRY_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL과 같은 2-3개의 도구 스키마가 있는 것을 알 수 있다. 후자는 출력을 /plan을 통해 액세스할 수 있는 마크다운 파일에 작성한다. 모든 것이 마크다운이다.
Anthropic은 최근 Agent Skills를 도입했고, 이것들은 최근 Codex에도 채택되었다. 스킬은 SKILL.md 파일, 기타 참조 가능한 파일, 그리고 사용자 정의 작업을 수행하는 코드 스크립트를 포함하는 폴더다.
SKILL.md는 LLM이 어떤 스킬이 사용 가능한지 알 수 있는 메타데이터를 포함한다(메타데이터는 시스템 프롬프트에 추가됨). Claude가 스킬이 관련이 있다고 느끼면 스킬의 내용을 읽기 위해 도구 호출을 수행하고 Matrix 1999의 Neo처럼 도메인 전문지식을 다운로드한다. 코드 스크립트는 Claude가 사용할 수 있는 도구를 포함할 수 있다.
일반적으로 도메인 전문지식을 가르치려면 시스템 프롬프트에 모든 정보를 작성하고 아마도 도구 호출 정의까지 작성해야 한다. 스킬을 사용하면 모델이 온디맨드로 로드하기 때문에 그렇게 할 필요가 없다. 이것은 특히 항상 해당 지시사항이 필요한지 확실하지 않을 때 유용하다.
플러그인은 스킬, 슬래시 명령, 서브에이전트, 훅, MCP 서버를 단일 배포 가능한 단위로 번들링하는 패키징 메커니즘이다. /plugins를 통해 설치할 수 있으며 충돌을 피하기 위해 네임스페이스가 지정된다(예: /my-plugin:hello). .claude/의 독립 실행형 구성은 개인/프로젝트별 사용에 좋지만, 플러그인은 프로젝트와 팀 간에 기능을 쉽게 공유할 수 있게 한다.
인기 있는 frontend-design 플러그인은 실제로 단지 스킬이다.
훅은 Claude Code와 Cursor에서 사용 가능하다(Codex는 아직 구현하지 않았다). 이것들은 에이전트 루프 라이프사이클의 특정 단계가 시작하거나 끝날 때 관찰하고 이전이나 이후에 bash 스크립트를 실행하여 에이전트 루프를 변경할 수 있게 한다.
Stop, UserPromptSubmit 등과 같은 훅이 있다. 예를 들어 Stop 훅은 Claude가 응답을 마친 후에 실행되고 UserPromptSubmit 훅은 Claude가 처리하기 전에 사용자가 프롬프트를 제출할 때 실행된다.
첫 번째로 만든 훅은 Claude가 응답을 멈췄을 때 애니메이션 알림 소리를 재생하는 것이었다. 분명히 Cursor의 알림 소리에서 영감을 받았다.
한 가지 재미있는 사용 사례는 Stop 훅을 통해 Claude가 현재 작업을 마치면 "더 해" 프롬프트를 실행하여 Claude를 몇 시간 동안 실행하게 하는 것이다.
연구 중 흥미로운 포스트를 발견했다. 이 사람은 지금까지 논의한 개념과 기능을 아름답게 결합했다. 모델에게 스킬을 상기시키기 위해 훅을 사용한다. 유틸리티/요구사항이 발생하면 많은 커스터마이징 공간이 있다. 그런 무거운 커스터마이징이 필요하지 않을 수 있지만 적어도 영감을 받을 수 있다.
Anthropic은 skill.md를 500줄 이하로 유지할 것을 권장하므로 별도의 파일로 나누고 훅과 결합하여 CLAUDE.md의 크기를 줄였다. 지시사항을 스킬 파일로 나누어 CLAUDE.md 크기를 줄이는 전략이다.
컨텍스트 엔지니어링은 단순히 토큰을 관리하는 것이 아니라, AI 에이전트가 효율적이고 정확하게 작동할 수 있도록 정보를 전략적으로 구성하는 것이다. Claude Code는 서브에이전트, 리마인더, 스킬, 훅 등 다양한 기법을 통해 정교한 컨텍스트 관리 시스템을 구축했다.
이러한 기법들을 이해하고 활용하면:
을 달성할 수 있다.
앞으로 모델이 발전하면서 일부 스캐폴딩은 줄어들 것이지만, 컨텍스트 엔지니어링의 핵심 원칙은 계속해서 중요할 것이다. 제한된 어텐션 예산을 최대한 활용하는 것은 여전히 AI 에이전트 개발의 핵심 과제로 남을 것이다.
작성 일자: 2025-12-29