Post

AI 에이전트 컨텍스트 엔지니어링 — 메모리·하네스·다중 에이전트 통합 설계

Anthropic의 Context Engineering 개념을 중심으로 에이전트 메모리, 컨텍스트 컴팩션, Three-Agent Harness, Managed Agents를 하나의 설계 흐름으로 정리한다.

AI 에이전트 컨텍스트 엔지니어링 — 메모리·하네스·다중 에이전트 통합 설계

들어가며

이 블로그에서 에이전트 관련 글을 네 편 썼다 — 메모리 시스템, 서브에이전트 패턴, Plan Mode, 하네스 구축. 각각은 독립된 주제처럼 보이지만, 돌이켜 보면 모두 같은 질문을 다르게 묻고 있었다.

에이전트에게 무엇을 언제 얼마나 알게 할 것인가?

이 질문에 이름을 붙인 것이 컨텍스트 엔지니어링(Context Engineering) 이다. 단발성 프롬프트를 잘 쓰는 기술을 넘어, 에이전트가 처리하는 정보의 흐름 전체 — 무엇을 저장하고, 무엇을 압축하고, 무엇을 다음 단계에 넘길 것인가 — 를 설계하는 일이다.

이 글은 Anthropic의 공식 자료와 앞선 네 편의 포스트를 하나의 설계 프레임으로 묶으려는 시도다.


1. 컨텍스트 엔지니어링 — 개념 정의

Anthropic의 Building Effective Agents는 에이전트 성능의 핵심 레버 중 하나로 컨텍스트 품질을 꼽는다.1 이후 Anthropic 엔지니어링 블로그와 커뮤니티에서 정착된 정의를 요약하면 다음과 같다.

컨텍스트 엔지니어링은 AI 에이전트가 작업을 올바르게 수행할 수 있도록, 적절한 정보를 적절한 형식으로 적절한 시점에 컨텍스트 창에 배치하는 설계 작업이다.2

여기서 세 가지 “적절함”이 각각 독립적인 설계 결정이다.

  • 적절한 정보: 관련 있는 것만, 노이즈 없이
  • 적절한 형식: 모델이 소화하기 쉬운 구조로
  • 적절한 시점: 너무 일찍 주입하면 희석되고, 너무 늦으면 소용없다

기존 프롬프트 엔지니어링이 “어떻게 말할 것인가”를 다뤘다면, 컨텍스트 엔지니어링은 “무엇을 언제 알게 할 것인가”를 다룬다.

구분관심 영역
프롬프트 엔지니어링시스템 프롬프트 문구, 예시(shot) 구성, 지시 순서
컨텍스트 엔지니어링메모리 저장·검색, 도구 출력 관리, 컴팩션, 에이전트 간 상태 전달

에이전트가 단발성 Q&A를 처리할 때는 이 구분이 중요하지 않다. 하지만 수십 분에 걸쳐 수백 번의 도구 호출을 처리하는 장기 에이전트에서는, 컨텍스트 설계가 품질과 비용을 직접 결정한다.


2. 컨텍스트 창이 에이전트의 병목이 되는 이유

누적되는 노이즈

에이전트가 작업을 진행할수록 컨텍스트 창에는 다음이 쌓인다.

  • 완료된 도구 호출의 전체 출력
  • 탐색 중 읽은 파일 내용
  • 이미 반영된 중간 계획들
  • 수정·철회된 결정의 흔적

이 누적 정보는 “지금 무엇을 해야 하는가”에 대한 모델의 집중도를 흩트린다. 연구자들이 “Lost in the Middle” 현상으로 부르는 패턴 — 컨텍스트 중간부의 정보를 모델이 상대적으로 덜 활용하는 경향 — 이 이 문제를 악화시킨다.3

비용과 지연

컨텍스트 창 크기는 추론 비용과 지연에 직접 영향을 준다. 장기 에이전트에서 컨텍스트를 방치하면, 작업 후반부로 갈수록 단위 응답 비용이 누적 상승한다.

관련 정보의 희석

더 미묘한 문제는, 관련 없는 정보가 관련 있는 정보를 희석한다는 점이다. 모델이 모든 토큰에 균등한 주의를 기울이지 않는다는 것은 알려진 사실이다. 노이즈가 많을수록 중요한 신호의 영향력이 떨어진다.

컨텍스트 엔지니어링은 이 희석을 막는 적극적인 설계 작업이다.


3. 세 가지 대응 전략 — 메모리·컴팩션·툴 클리어링

컨텍스트 창 한계에 대응하는 주요 접근은 크게 셋이다.

3-1. 외부 메모리 — 창 밖으로 내보내기

에이전트가 학습한 사실·선호·프로젝트 맥락을 컨텍스트 창 밖 파일이나 데이터베이스에 저장하고, 필요할 때 검색해 주입하는 방식이다. AI 에이전트 메모리 시스템 설계 포스트에서 자세히 다뤘던 영역이다.

외부 메모리는 두 방향으로 작동한다.

  • 쓰기: 세션 중 의미 있는 사실을 장기 저장소로 내보낸다
  • 읽기: 세션 시작 시 또는 도중에 관련 기억을 불러와 컨텍스트에 주입한다

설계 원칙: 코드 패턴·컨벤션·파일 경로는 메모리에 저장하지 않는다. 코드베이스에서 직접 파생할 수 있는 것은 메모리 대상이 아니다. 메모리는 사용자 선호, 교정된 접근 방식, 프로젝트 맥락 — 코드에서 읽을 수 없는 것 — 을 위한 공간이다.

3-2. 컨텍스트 컴팩션 — 압축과 재구성

컴팩션(compaction)은 컨텍스트 창이 일정 임계값에 도달했을 때, 대화 히스토리를 요약·압축하는 기술이다. Claude Code와 Claude Agent SDK는 이를 네이티브로 지원한다.4

컴팩션의 핵심 과제는 무엇을 요약하고 무엇을 그대로 유지할 것인가의 결정이다.

  • 완료된 단계의 세부 도구 출력 → 핵심만 담은 요약으로 대체
  • 현재 진행 중인 작업의 필수 컨텍스트 → 원문 유지
  • 요약 자체 → 다음 단계에서 활용 가능한 형태로 구성

나쁜 컴팩션은 “방금 무엇을 했는지”를 잃어버려 에이전트가 같은 작업을 반복하게 만든다. 컴팩션은 사후 처리가 아니라 선행 설계 대상이다.

3-3. 툴 클리어링 — 도구 출력의 선택적 포함

파일 읽기, 웹 검색, 코드 실행 등의 도구 호출 결과는 컨텍스트에서 큰 비중을 차지한다. Anthropic의 하네스 가이드는 이 점을 명시한다.5

원시 도구 출력을 그대로 컨텍스트에 쌓는 대신, 다음 접근이 효과적이다.

  • 완료된 탐색 결과 → “무엇을 발견했는가”만 남긴 요약으로 대체
  • 더 이상 참조하지 않는 파일 내용 → 제거
  • 반복 패턴의 도구 출력 → 대표 예시 하나만 유지

세 전략은 계층적으로 작동한다.

graph TB
    subgraph Session["세션 수명 주기"]
        TC["툴 클리어링\n도구 출력 단위"]
        CC["컨텍스트 컴팩션\n세션 내 누적 관리"]
    end

    subgraph Persistent["세션 간 영속"]
        EM["외부 메모리\n장기 지식 저장·검색"]
    end

    TC --> CC
    CC --> EM
    EM -->|"세션 시작 시 로드"| Session

    style Session fill:#4a9eda,color:#fff,stroke:#2d7ab8
    style Persistent fill:#5cb85c,color:#fff,stroke:#3d8b3d

외부 메모리가 세션 간 지식을 다루고, 컴팩션이 세션 내 누적을 관리하며, 툴 클리어링이 단일 도구 호출 수준을 정리한다.


4. Three-Agent Harness — 역할 분리의 구조

세 전략을 단일 에이전트가 스스로 수행하는 것은 구조적 한계가 있다. Anthropic이 권장하는 하네스 패턴은 작업을 역할 기반으로 분리하는 것이다.1

Three-Agent Harness의 기본 구조는 세 역할이다.

graph LR
    subgraph Init["1단계: 초기화"]
        I["Initializer\n코드베이스 탐색\n계획 수립\n컨텍스트 정제"]
    end

    subgraph Code["2단계: 구현"]
        C["Coding Agent\n순수 구현\n정제된 컨텍스트로 작업"]
    end

    subgraph Eval["3단계: 평가"]
        E["Evaluator\n결과 검증\n품질 측정\n재작업 여부 판단"]
    end

    I -->|"계획서\n+ 정제 컨텍스트"| C
    C -->|"구현 산출물"| E
    E -->|"재작업 요청"| C
    E -->|"승인"| Done["완료"]

    style I fill:#6c5ce7,color:#fff
    style C fill:#0984e3,color:#fff
    style E fill:#00b894,color:#fff
    style Done fill:#636e72,color:#fff

각 에이전트는 자신의 역할에 최적화된 컨텍스트만 가진다.

역할컨텍스트 내용금지 사항
Initializer전체 코드베이스 탐색 결과, 요구사항 원문파일 수정
Coding Agent초기화된 계획서 + 핵심 컨텍스트만코드베이스 재탐색
Evaluator구현 산출물, 검증 기준구현 과정의 내막

이 분리가 컨텍스트 엔지니어링의 원칙을 구조적으로 구현한다: 각 에이전트에게 자신의 역할에 필요한 정보만 전달하고, 나머지는 차단한다.

Evaluator가 Initializer의 탐색 로그를 알 필요가 없고, Coding Agent가 이전 탐색 중 폐기된 가설을 알 필요가 없다.


5. Initializer와 Coding Agent — 분리가 품질을 높이는 이유

탐색 오염 차단

코드베이스를 탐색하는 과정에서 에이전트는 많은 노이즈를 쌓는다. 관련 없는 파일 내용, 중간에 바꾼 가설, 폐기한 접근 방식의 흔적이다. 이 노이즈가 구현 컨텍스트에 섞이면 Coding Agent의 집중도가 떨어진다.

Initializer가 탐색을 완료한 뒤 정제된 컨텍스트만 Coding Agent에게 넘기면, Coding Agent는 “무엇을 왜 해야 하는가”에 대한 깨끗한 시작점에서 작업한다.

Plan Mode — Initializer 역할의 실용적 구현

이 블로그의 Claude Code Plan Mode 실전 활용에서 다룬 Plan Mode가 이 구조의 실용적 구현이다. Plan Mode는 읽기 전용으로 코드베이스를 이해하고 계획을 수립한 뒤, ExitPlanMode 호출로 사용자 승인을 받는 단계 — 즉 Initializer 역할 — 를 Claude Code에서 기본 제공하는 방식이다.

1
2
3
4
5
6
7
8
Plan Mode (Initializer 역할)
  ├── 코드베이스 읽기 전용 탐색 (Edit·Write 차단)
  ├── 계획서 작성 (목표·범위·단계·검증)
  └── ExitPlanMode → 사용자 승인 게이트

일반 모드 (Coding Agent 역할)
  ├── 승인된 계획서 기반 구현
  └── 파일 수정·명령 실행

ExitPlanMode가 단순한 모드 전환이 아니라 사람의 확인을 강제하는 게이트라는 점 — 이것이 Plan Mode의 컨텍스트 엔지니어링 관점에서의 핵심 가치다. 탐색(Initializer)과 구현(Coding Agent) 사이에 명시적 경계를 둔다.

서브에이전트로의 완전한 격리

Claude Code 서브에이전트 설계 패턴의 컨텍스트 격리 원칙이 Three-Agent Harness에도 동일하게 적용된다. 서브에이전트는 부모 에이전트의 대화 히스토리를 공유하지 않는다 — 이것이 제약이면서 동시에 컨텍스트 엔지니어링의 핵심 도구다.

Initializer를 서브에이전트로 실행하면:

  1. Initializer의 탐색 과정(노이즈 전체)이 Coding Agent에게 전달되지 않는다
  2. 오케스트레이터가 Initializer 결과에서 계획서만 추출해 Coding Agent 프롬프트에 삽입한다
  3. Coding Agent는 정제된 컨텍스트만으로 시작한다

Anti-pattern: Initializer와 Coding Agent를 같은 컨텍스트에서 순차 실행하는 것. 탐색 중 쌓인 노이즈가 구현 단계까지 이어진다. 에이전트 스스로도 “지금 탐색 중인가, 구현 중인가”를 혼동하게 된다.


6. Managed Agents — 상태와 턴을 관리하는 하네스

에이전트 상태 관리의 문제

멀티-턴 에이전트에서 상태 관리는 생각보다 복잡하다.

  • 도구 호출을 반복하는 동안 중간 상태를 어떻게 유지할 것인가?
  • 에러가 발생했을 때 어디서부터 재시작할 것인가?
  • 에이전트가 “실패”와 “완료”를 어떻게 구분할 것인가?

직접 상태 머신을 구현하면 이 물음들에 일일이 답해야 한다. Claude Agent SDK의 Managed Agents 개념은 이 책임을 SDK 레벨에서 처리하는 접근이다.4

컨텍스트 엔지니어링 관점에서의 Managed Agents

Managed Agents가 컨텍스트 엔지니어링에서 중요한 이유는, 턴 사이의 컨텍스트를 SDK가 구조적으로 관리하기 때문이다.

  • 각 턴에서 어떤 정보를 다음 턴에 전달할지를 SDK가 추상화한다
  • 컴팩션 전략을 에이전트 코드가 아닌 하네스 설정에서 정의할 수 있다
  • 에이전트 간 메시지 형식과 상태 전달 구조가 표준화된다

Managed Agent의 생명 주기를 설계 관점에서 보면:

1
2
3
4
5
6
Managed Agent 생명 주기
  ├── 초기화: 초기 컨텍스트 구성 — 외부 메모리 로드
  ├── 턴 실행: 도구 호출 · 응답 생성
  ├── 컴팩션: 임계값 도달 시 히스토리 압축
  ├── 에러 처리: 실패 격리 · 재시도 정책
  └── 종료: 최종 상태 저장 — 외부 메모리 쓰기

각 생명 주기 지점이 컨텍스트 엔지니어링의 개입 지점이기도 하다. 초기화에서 어떤 메모리를 로드할지, 컴팩션에서 무엇을 보존할지, 종료에서 무엇을 저장할지가 모두 설계 결정이다.

이것이 AI 코딩 하네스 구축 가이드에서 다룬 하네스 개념의 SDK 레벨 구현이다. 하네스가 에이전트를 올바른 방향으로 이끄는 틀이라면, Managed Agents는 그 틀을 코드 수준에서 제공한다.

참고: Claude Agent SDK는 지속적으로 발전 중이다. 구체적인 구현 전 공식 문서에서 현재 기능을 확인하길 권한다.


7. 실무 적용 — 통합 설계 원칙

앞의 여섯 섹션에서 다룬 개념을 에이전트 시스템 설계에 통합할 때의 원칙을 정리한다.

원칙 1: 에이전트는 자신의 역할에 필요한 것만 알아야 한다

“혹시 필요할 수도 있는” 정보를 미리 주입하는 것은 컨텍스트를 오염시킨다. Evaluator에게 Initializer의 탐색 로그가 필요 없듯, 각 역할의 입력을 최소화하는 것이 품질과 비용 모두를 개선한다.

원칙 2: 상태 전환 지점을 명시적으로 설계하라

Initializer → Coding Agent, Coding Agent → Evaluator 전환에서 무엇이 전달되고 무엇이 차단되는지를 명시적으로 정의해야 한다. 암묵적인 상태 전달은 컨텍스트 오염의 주요 경로다.

Plan Mode의 ExitPlanMode가 좋은 사례다 — 계획 단계와 실행 단계 사이에 사람의 승인이라는 명시적 게이트를 두는 것이 컨텍스트 전환 설계다.

원칙 3: 컴팩션은 사후 처리가 아니라 선행 설계다

컨텍스트가 가득 찼을 때 컴팩션하는 것이 아니라, 에이전트 설계 초기부터 “이 단계의 출력은 다음 단계에서 어떤 형태로 필요한가”를 고려해야 한다. 컴팩션을 염두에 두고 도구 출력 형식을 설계하면, 요약이 훨씬 자연스러워진다.

원칙 4: 메모리는 코드베이스에서 파생할 수 없는 것만 저장한다

코드 패턴, 컨벤션, 파일 경로는 메모리에 저장하지 않는다. 메모리는 사용자 선호, 교정된 접근 방식, 프로젝트 결정 맥락 — 코드에서 읽을 수 없는 것 — 을 위한 공간이다. 저장 기준이 없는 메모리는 노이즈 저장소가 된다.

원칙 5: 검증자는 작성자와 컨텍스트를 공유해서는 안 된다

서브에이전트 설계 패턴의 Reviewer-Verifier 원칙이 여기서도 동일하게 적용된다. 작성자의 의도와 맥락을 아는 상태에서 검증하면 확증 편향이 생긴다. Evaluator는 구현 결과물만 보고 독립적으로 판단해야 한다.

설계 체크리스트

에이전트 시스템을 설계하거나 점검할 때 다음을 확인한다.

  • 각 에이전트에게 역할에 필요한 컨텍스트만 전달되고 있는가?
  • 에이전트 간 상태 전환이 명시적으로 정의되어 있는가?
  • 장기 작업에서 컴팩션 전략이 사전에 설계되어 있는가?
  • 외부 메모리의 저장 기준이 명확하게 정의되어 있는가?
  • Evaluator가 구현 과정의 내막을 모르는 상태에서 검증하고 있는가?
  • 실패 시 재시도 범위가 에이전트 단위로 격리되어 있는가?

마치며

컨텍스트 엔지니어링은 새로운 유행어가 아니다. 에이전트가 수십 분에 걸친 복잡한 작업을 처리하게 되면서 어쩔 수 없이 해결해야 하는 엔지니어링 문제다.

이 블로그에서 개별적으로 다뤘던 메모리 시스템, 서브에이전트 패턴, Plan Mode, 하네스 구축은 모두 이 문제를 다른 각도에서 다루고 있었다. 컨텍스트 엔지니어링은 그 개별 해법들을 하나의 설계 원칙 아래 묶는 프레임이다.

“에이전트에게 무엇을 언제 얼마나 알게 할 것인가” — 이 질문이 앞으로 에이전트 시스템 설계의 핵심 질문으로 계속 남을 것이다.


관련 글:


출처

  1. Anthropic. (2024, December). Building Effective Agents. Anthropic Research Blog. — 에이전트 패턴 분류(Orchestrator-Workers, Evaluator-Optimizer 등), 컨텍스트 품질을 핵심 성능 레버로 제시. A등급 (Anthropic 공식 발행물). ↩︎ ↩︎2

  2. Anthropic Engineering. “Effective context engineering for AI agents”. — 적절한 정보를 적절한 형식으로 적절한 시점에 제공하는 컨텍스트 엔지니어링의 정의와 구성 요소. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents. A등급 (Anthropic 공식 발행물). ↩︎

  3. Liu et al. (2023). Lost in the Middle: How Language Models Use Long Contexts. arXiv. — 컨텍스트 길이 증가에 따라 중간 위치 정보의 활용도가 하락하는 현상 실증. B등급 (학술 논문, 동료 검토 완료). ↩︎

  4. Anthropic Engineering. “Building agents with the Claude Agent SDK”. — 에이전트 빌드의 기본 구조와 컨텍스트·도구 통합 방식을 설명한 공식 글. https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk. A등급 (Anthropic 공식 발행물). ↩︎ ↩︎2

  5. Anthropic Engineering. (2025). Effective Harnesses for Long-Running Agents. Anthropic Engineering Blog. — 장기 에이전트에서의 컨텍스트 관리, 도구 출력 처리, 에러 복구 전략. A등급 (Anthropic 공식 발행물). ↩︎

This post is licensed under CC BY 4.0 by the author.