컨텍스트 엔지니어링: 유한한 주의를 값어치 있는 곳에 쓰기 · 5 / 6강

레슨 5: 서브에이전트와 컨텍스트 격리

학습 목표:

서브에이전트가 왜 컨텍스트 관리의 수인지 설명하기: 깨끗한 윈도 하나에 요약본 하나를 돌려보내, '과정'을 메인 윈도 바깥에 두는 것

과정 토큰과 결론 토큰의 비율, 그리고 실측 비용 데이터를 써서 어떤 작업을 서브에이전트에 맡길 만한지 판단하기

이 시리즈의 코스 7에서 쓴 하네스 루프에 서브에이전트 파견을 배선해, 파견 한 번이 메인 윈도에 요약본을 정확히 하나만 돌려주게 하기

전제: 컴팩션과 노트를 다룬 레슨 4를 마쳤고, 이 시리즈의 코스 7 '에이전트 하네스 기초: 루프와 통제'에서 쓴 하네스 루프를 돌릴 수 있을 것 | 이전: 레슨 4 << | 다음: 레슨 6 >>

관점의 전환: 분업이 아니라 격리

서브에이전트는 이 시리즈의 코스 6 '멀티 에이전트 협업'에서 이미 만났습니다. 작업을 어떻게 나누는지, 결과를 어떻게 보고하는지, 여러 에이전트가 어떻게 조율하는지. 그 코스가 답한 것은 여러 에이전트가 어떻게 함께 일하는가라는 질문이었습니다. 이번 레슨이 답하는 것은 다른 질문입니다. 애초에 서브에이전트는 왜 컨텍스트 관리 기법인가?

달리 말하면, 리드 에이전트가 하나뿐이고 팀 조율이 전혀 필요 없더라도 여전히 서브에이전트에 손을 뻗고 싶어질 것이라는 뜻입니다 — 분업 때문이 아니라 격리 때문에.

레슨 1의 예산이라는 관점을 다시 떠올려 보세요. 모델이 컨텍스트를 해석할 때는 주의 예산에서 끌어다 쓰고, 컨텍스트에 새로 들어오는 토큰마다 그 예산을 조금씩 소모합니다¹. 토큰을 더 쌓을수록 그 컨텍스트에서 정보를 정확히 떠올리는 모델의 능력은 떨어집니다¹. 그리고 에이전트야말로 토큰이 가장 쌓이기 쉬운 무대입니다. 루프의 매 턴이 다음 추론에 관련될 수도 있는 새 데이터를 낳는데, 버리기도 어렵고 남기기도 어렵습니다¹.

탐색 작업이 이것의 가장 날카로운 형태입니다. 메인 에이전트가 수십만 줄짜리 저장소 전체에서 어떤 폐기 예정 API의 호출 지점을 모두 추적해야 한다고 해 봅시다. 열몇 번의 grep, 스무 개의 파일 열기, 수천 줄 읽기. 그 중간 내용은 수만 토큰에 이르는데, 남길 가치가 있는 결론은 다섯 줄일 수 있습니다. "호출 지점은 이 세 모듈에 몰려 있고, 권장 마이그레이션 순서는 이렇다." 그 모든 일이 메인 윈도 안에서 벌어진다면 주의 예산은 과정에 먹혀 버리고, 결론과 그 뒤에 이어질 작업에 남는 몫은 얼마 되지 않습니다.

서브에이전트는 바로 이 문제를 겨눈 칼입니다.

메커니즘: 깨끗한 윈도가 들어가고, 압축된 요약본이 나온다

메커니즘은 한 문장에 담깁니다. 특화된 서브에이전트가 깨끗한 컨텍스트 윈도에서 초점이 좁은 작업을 처리하고¹, 탐색이 낳는 방대한 양의 중간 내용 — 검색 결과, 날것의 파일 내용, 막다른 길 — 은 모두 서브에이전트 안에 머물며¹, 메인 에이전트에게 돌아가는 것은 작업의 압축되고 증류된 요약본, 흔히 1,000-2,000 토큰뿐입니다¹.

따라서 메인 에이전트의 윈도는 결론만 실어 나르고 과정은 결코 싣지 않습니다. 비대칭 설계입니다. 서브에이전트는 탐색하며 수만 토큰을 태울 수 있지만, 거기서 밖으로 나가는 것은 짧은 글 한 토막뿐입니다.

코드로 보면 이것은 코스 7에서 쓴 하네스의 새 첫수에 지나지 않습니다. 간결하게 두기 위해, 그 코스의 루프에서 거듭 등장했던 두 동작을 여기서는 헬퍼로 묶었습니다. textOf는 응답에서 텍스트 블록을 꺼내고, appendToolResults는 이번 턴의 도구를 실행해 tool_result 블록을 메시지 배열에 덧붙입니다(내부에서 하는 일은 그 코스에서 손으로 직접 쓴 것과 똑같습니다. 각 tool_use를 실행하고, 결과를 모아, 돌려보내기).

JAVASCRIPT

const SUBAGENT_SYSTEM = `당신은 리서치 서브에이전트입니다.
작업이 끝나면 최대 1500 토큰의 결론을 출력하세요:
핵심 발견, 관련된 파일 경로, 그리고 메인 에이전트를 위한 권장 조치.
읽은 원문을 그대로 되풀이하지 마세요.`;

async function runSubagent(client, task, maxTurns = 15) {
  // 요령의 전부가 이 줄이다: 완전히 새로운 메시지 배열, 메인 에이전트의 히스토리는 하나도 없다
  let messages = [{ role: "user", content: task }];
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 4096,
      system: SUBAGENT_SYSTEM, // 서브에이전트 자신의 시스템 프롬프트
      tools: SEARCH_TOOLS,     // 탐색에 필요한 도구만
      messages,
    });
    if (response.stop_reason === "end_turn") {
      return textOf(response); // 이 텍스트만 서브에이전트를 떠난다
    }
    // 도구를 실행하고 결과를 messages에 덧붙인다. 그 전부가 서브에이전트 안에 머문다
    messages = await appendToolResults(messages, response);
  }
  return "리서치가 턴 예산 안에 끝나지 않았습니다";
}

세 가지 세부에 주목하세요. 첫째, messages는 덩그러니 놓인 작업 설명 하나에서 시작하며 메인 에이전트의 히스토리는 한 마디도 지니지 않습니다 — 그것이 '깨끗한 윈도'의 의미 전부입니다. 둘째, 이 함수는 평범한 문자열인 textOf(response)를 반환합니다. 루프 안에서 쌓인 수십 번의 도구 왕복은 지역 변수 messages와 함께 사라집니다. 셋째, 서브에이전트의 시스템 프롬프트는 '읽은 원문을 그대로 되풀이하지 말라'고 명시적으로 요구합니다 — 요약본의 압축 품질은 바로 여기서 정해집니다.

메인 에이전트 쪽에서 파견 동작은 이미 갖고 있는 stop_reason 루프에 꽂히는 평범한 도구 하나일 뿐입니다.

JAVASCRIPT

const DISPATCH_TOOL = {
  name: "dispatch_research",
  description:
    "초점이 좁은 리서치 작업을 서브에이전트에 넘기고 발견에 대한 요약본을 돌려받는다. " +
    "탐색은 많이 필요하지만 결론은 짧게 진술할 수 있는 작업에 쓴다.",
  input_schema: {
    type: "object",
    properties: {
      task: {
        type: "string",
        description: "그 자체로 완결된 작업 설명. 서브에이전트는 이 대화의 히스토리를 볼 수 없다",
      },
    },
    required: ["task"],
  },
};

async function handleDispatch(mainMessages, toolCall) {
  const summary = await runSubagent(client, toolCall.input.task);
  mainMessages.push({
    role: "user",
    content: [{
      type: "tool_result",
      tool_use_id: toolCall.id,
      content: summary, // 메인 윈도가 얻는 것은 이 항목 하나뿐
    }],
  });
}

task 필드의 description을 보세요. "그 자체로 완결된 작업 설명. 서브에이전트는 이 대화의 히스토리를 볼 수 없다." 그 줄은 메인 에이전트를 향해 쓰인 것입니다 — 반대편에 있는 것이 기억을 잃은 새 윈도이므로, 작업을 온전히 진술해야 합니다. 도구 설명에서 목적과 경계를 이만큼 또렷이 적어 두는 것이 바로 레슨 2의 '컨텍스트로서의 도구'라는 발상입니다. 도구는 그 자체로 완결되어야 하고, 에러에 강해야 하며, 의도된 용도에 대해 극도로 명확해야 합니다¹.

서브에이전트가 메인 에이전트의 히스토리를 얼마나 안고 출발해야 하는지 판단하기

당신은 리서치 서브에이전트의 파견 로직을 쓰고 있고, 동료가 이렇게 제안합니다. '메인 에이전트의 지금까지 메시지 히스토리 전체를 그냥 서브에이전트에 넘기자 — 큰 그림을 이해해서 더 잘할 거야.' 컨텍스트 경제학의 관점에서 이 제안을 어떻게 평가해야 할까요?

1차 데이터: 지능형 필터로서의 서브에이전트

메커니즘은 정리됐습니다. 이제 실측입니다. Anthropic은 자사의 멀티 에이전트 리서치 시스템 — Claude의 Research 기능 뒤에 있는 아키텍처 — 을 공개적으로 기록해 두었는데, 이는 드문 1차 엔지니어링 자료입니다².

거기서 얻은 것 가운데 셋이 이번 레슨과 곧바로 맞닿습니다.

서브에이전트는 각자 자신의 컨텍스트 윈도를 갖고 병렬로 동작함으로써 압축을 성립시킵니다². 각 서브에이전트는 자기 윈도 안에서 탐색하며 서로를 밀어내지 않습니다.
그들은 서브에이전트를 "intelligent filters"라 부릅니다. 리드 리서치 에이전트를 위해 가장 중요한 토큰을 응축하기 때문입니다². '필터'라는 말은 적확합니다. 들어가는 것은 코퍼스, 나오는 것은 요체입니다.
곱씹을 가치가 있는 한 문장이 있습니다. "The essence of search is compression: distilling insights from a vast corpus."² 이번 레슨의 맥락에서 읽으면, 서브에이전트가 돌리는 모든 탐색은 그 천 토큰짜리 증류물을 낳기 위해 존재합니다.

곁가지로, 병렬성은 속도도 사 줍니다. 여러 갈래의 리서치가 동시에 나아가니까요. 다만 그것은 오케스트레이션의 주제이고 이 시리즈의 코스 6에서 이미 다뤘습니다. 이번 레슨은 압축 쪽만 바라봅니다.

장부의 반대편: 격리는 비용 절감이 아니다

이점을 늘어놓았으면 청구서도 늘어놓아야 합니다. 같은 기록에 실측 수치가 있습니다 — 이것들은 Anthropic 리서치 시스템에서의 실측이지 보편 법칙이 아님에 주의하세요.

에이전트는 채팅 상호작용보다 대략 4× 많은 토큰을 씁니다².
멀티 에이전트 시스템은 채팅보다 대략 15× 많은 토큰을 씁니다².
성능이 어디서 오는지 분석했더니 토큰 사용량 그 자체가 분산의 80%를 설명했고, 도구 호출 횟수와 모델 선택이 나머지 대부분을 차지했습니다².

그들 자신의 결론은 솔직합니다. "Multi-agent systems work mainly because they help spend enough tokens to solve the problem."²

그러니 직설적으로 말합시다. 서브에이전트는 비용 절감책이 아닙니다. 총 토큰은 올라가기만 합니다 — 작업을 다시 진술해야 하고, 배경을 다시 깔아야 하고, 여러 윈도가 동시에 탑니다. 그것이 사는 것은 다른 것입니다. 모든 윈도가 저하되지 않은 구간에 머물러 주의 밀도가 끝까지 높게 유지된다는 것. 이것은 주의의 거래입니다 — 총 토큰을 더 쓰고, 각각 깨끗한 윈도를 얻는 것.

그 거래가 값어치를 할 때는 언제일까요. 레슨 1의 예산이라는 관점으로 돌아갑니다. 컨텍스트는 한계 수익이 체감하는 유한한 자원입니다¹. 판단의 잣대는 둘입니다.

과정과 결론의 비율. 이 작업의 중간 내용은 얼마나 크고, 최종 결론은 얼마나 작은가. 비율이 기울수록 격리의 보상은 커집니다. 반대로 애초에 과정이 짧은 작업을 파견하면 순전한 인계 오버헤드입니다.
복잡함이 결과를 실증적으로 개선하는가. Anthropic의 지침은 복잡함을 더하는 일은 그것이 결과를 실증적으로 개선할 때에만 검토하라는 것입니다 — 원문의 단어는 "consider"이고, 이는 쇠붙이 같은 규칙이 아니라 분량의 문제입니다³. 추가 토큰이 더 나은 출력을 사 주지 않는다면 하나의 윈도로 돌아가세요.

긴 작업의 조합기: 노트를 바탕에, 핸드오프로 지구력을

서브에이전트의 윈도가 아무리 깨끗해도 그것 역시 유한합니다. 진짜로 시간 지평이 긴 작업에 대해 그 기록은 하나의 조합기를 묘사합니다. 에이전트는 완료된 작업 단계를 요약해 핵심 정보를 외부 메모리에 저장하고², 그런 다음 깨끗한 컨텍스트를 지닌 새 서브에이전트를 띄워 이어 가게 하며, 세심한 핸드오프를 통해 연속성을 유지합니다².

그러면 레슨 4와 이번 레슨이 하나의 수순으로 꿰어집니다.

레슨 4의 구조화된 노트는 '핵심 상태를 윈도 바깥에 두기'를 맡습니다 — NOTES.md, 작업 목록 — 그것들은 파일 시스템에 살며 어떤 윈도의 주의도 차지하지 않습니다.
이번 레슨의 격리는 '모든 작업 구간을 깨끗한 윈도 안에 두기'를 맡습니다 — 새 서브에이전트가 가장 먼저 하는 일은 노트를 읽는 것이며, 전임자의 히스토리 전체를 물려받을 필요 없이 전임자가 증류한 요체만 있으면 됩니다.

핸드오프 문서에는 무엇이 들어갈까요. 레슨 4의 컴팩션에서 쓴 것과 똑같은 맞바꿈 기준을 재활용하세요. 아키텍처 결정과 미해결 버그와 구현 세부는 남기고, 중복된 도구 출력은 버립니다¹. 핸드오프를 쓰는 일과 컴팩션 요약본을 쓰는 일은 같은 기술이며, 바뀌는 것은 읽는 이가 '미래의 나'에서 '다음 서브에이전트'로 바뀌는 것뿐입니다.

Claude Code에서는 이것이 어떤 모습인가

마지막으로, 매일 쓰는 구현에 이것을 대 보세요. Claude Code의 공식 베스트 프랙티스는 대놓고 말합니다. 컨텍스트 윈도는 빠르게 차고, 찰수록 성능은 저하됩니다. "The context window is the most important resource to manage."⁴ 컨텍스트가 근본 제약이므로 서브에이전트는 쓸 수 있는 가장 강력한 도구 가운데 하나입니다⁴.

그 구현은 이번 레슨이 묘사한 메커니즘과 맞아떨어집니다. 서브에이전트는 별도의 컨텍스트 윈도에서 돌고 요약본을 보고합니다⁴. Claude Code에게 '이 버그의 근본 원인을 찾아 달라'고 하면, 파견된 서브에이전트가 grep을 돌리고 파일을 읽고 호출 사슬을 따라갑니다 — 그 모든 탐색이 서브에이전트 자신의 윈도에서 일어나고, 메인 대화는 마지막에 조사 요약본만 받습니다. 조사의 범위를 좁게 잡거나 서브에이전트에 넘기면, 그 탐색은 메인 컨텍스트를 소모하지 않습니다⁴.

인터페이스에서 하위 작업이 뒤에서 돌고 있는 것을 보고, 그것이 끝났을 때 메인 대화가 짧은 보고만 얻는다면, 그것이 바로 이번 레슨이 처음부터 묘사해 온 '깨끗한 윈도가 들어가고, 압축된 요약본이 나온다'입니다.

여기까지 긴 작업 도구함의 세 조각을 모두 봤습니다. 컴팩션(레슨 4), 구조화된 노트(레슨 4), 그리고 멀티 에이전트 아키텍처(이번 레슨). 이들이 함께 겨누는 목표는 에이전트가 일련의 행동에 걸쳐 일관성과 컨텍스트와 목표 지향적 행동을 유지하게 하는 것입니다¹. 레슨 6에서는 이 셋을 당신의 하네스에 배선합니다.

정리

서브에이전트는 컨텍스트 관리 기법이다. 초점이 좁은 작업은 깨끗한 컨텍스트 윈도에서 돌고, 탐색의 중간 내용은 서브에이전트 안에 격리되며, 돌아오는 것은 흔히 1,000-2,000 토큰의 증류된 요약본뿐이다 — 메인 윈도가 싣는 것은 결론이지 과정이 아니다¹.
Anthropic의 멀티 에이전트 리서치 시스템에서 서브에이전트들은 각기 별도의 컨텍스트 윈도에서 병렬로 돌며 그것을 통해 압축을 이루고, 리드 에이전트를 위해 가장 중요한 토큰을 응축하는 "intelligent filters"로 작동한다. "The essence of search is compression"².
같은 시스템의 실측 수치: 에이전트는 채팅보다 대략 4×, 멀티 에이전트 시스템은 대략 15× 많은 토큰을 쓰고, 토큰 사용량 그 자체가 성능 분산의 80%를 설명한다 — 격리는 주의의 거래이며 '총 토큰을 더 쓰고 저하되지 않는 윈도를 얻는 것'이지 비용 절감책이 아니다².
격리가 값어치를 하는지는 과정과 결론의 비율, 그리고 더해진 복잡함이 결과를 실증적으로 개선하는지에 달렸다 — Anthropic의 단어는 "consider"이고, 쇠붙이 같은 규칙이 아니라 분량의 문제다³.
긴 작업의 조합기: 한 단계가 끝나면 요약해 요체를 외부 메모리에 저장하고, 그런 다음 깨끗한 컨텍스트를 지닌 새 서브에이전트를 띄워 세심한 핸드오프로 연속성을 유지한다 — 레슨 4의 노트와 이번 레슨의 격리는 한 쌍이다².
Claude Code에서 컨텍스트 윈도는 관리해야 할 가장 중요한 자원이고, 그 때문에 서브에이전트는 쓸 수 있는 가장 강력한 도구 가운데 하나가 된다. 서브에이전트는 별도의 컨텍스트 윈도에서 돌고 요약본만 보고한다⁴.

>> 레슨 6: 실습: 하네스에 컨텍스트 관리 배선하기

Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩²
Best practices for Claude Code — Claude Code Docs — https://code.claude.com/docs/en/best-practices ↩ ↩² ↩³ ↩⁴ ↩⁵

연습

당신의 메인 에이전트가 세 가지 작업을 맡습니다.

레벨 1: 세 작업에 대해 격리 여부 판단하기

작업 A: 수십만 줄짜리 저장소에서 폐기 예정인 LegacyLedgerReader API를 아직 쓰고 있는 호출 지점을 모두 찾고, 마이그레이션 순서를 제안한다.
작업 B: 메인 에이전트가 방금 80줄짜리 함수를 컨텍스트로 읽어 들였다. 사용자가 그 안의 off-by-one 버그를 지적하며 수정을 요청한다.
작업 C: 라이브러리 선정 결정을 위해 후보 파싱 라이브러리 세 개를 조사한다 — 각각의 문서를 읽고, 이슈 트래커를 파헤치고, 나란히 비교한다.

각 작업에 대해 격리할지(서브에이전트를 파견할지) 하지 않을지(메인 윈도에서 처리할지) 판단을 적고, 해당되는 곳에서는 병렬성을 짚으며, 이번 레슨의 기준으로 한두 문장의 근거를 대세요.

완료 기준 · 로컬에서 확인

세 판단 모두 과정 토큰과 결론 토큰의 비율에 기댄다: 과정이 무겁고 결론이 작을수록 격리할 값어치가 크다작업 B는 격리하지 않는 것으로 판단하고, 근거에 비용 쪽이 포함된다: 함수가 이미 메인 윈도에 있으므로 새 서브에이전트는 함수와 작업 배경을 다시 전달해야 하고, 격리 오버헤드가 이득을 넘어선다작업 C는 세 조사 갈래가 서로 의존하지 않으므로 각기 다른 윈도를 병렬로 차지할 수 있고, 각자 비교에 필요한 논점만 돌려주면 된다는 점을 짚는다

당신은 이 시리즈의 코스 7의 하네스에 서브에이전트를 배선하면서 파견 로직을 이렇게 썼습니다.

레벨 2: '가짜 격리' 파견 함수 고치기

JAVASCRIPT

async function runSubagent(client, task, maxTurns = 15) {
  let messages = [{ role: "user", content: task }];
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 4096,
      system: SUBAGENT_SYSTEM,
      tools: SEARCH_TOOLS,
      messages,
    });
    if (response.stop_reason === "end_turn") {
      // 마지막 응답까지 덧붙여서 히스토리 전체를 반환한다
      return [
        ...messages,
        { role: "assistant", content: textOf(response) },
      ];
    }
    messages = await appendToolResults(messages, response);
  }
  return messages;
}

async function handleDispatch(mainMessages, toolCall) {
  const subHistory = await runSubagent(client, toolCall.input.task);
  mainMessages.push({
    role: "user",
    content: [{
      type: "tool_result",
      tool_use_id: toolCall.id,
      // 히스토리 전체를 텍스트로 렌더링해 메인 윈도에 도로 밀어 넣는다
      content: renderAsText(subHistory),
    }],
  });
}

증상: 세 번의 리서치 파견 뒤 메인 에이전트의 컨텍스트 사용량이 윈도 한계에 가까워지고, 레슨 4에서 설치한 컴팩션 로직이 억지로 일찍 발동합니다. 메인 에이전트의 메시지 배열을 들여다보면 토큰의 압도적 대부분이 서브에이전트의 원본 도구 반환값임을 알게 됩니다.

근본 원인을 짚고, 파견 한 번이 메인 윈도에 요약본 하나만 더하도록 코드를 고치세요.

완료 기준 · 로컬에서 확인

근본 원인을 `runSubagent`의 반환값과 `handleDispatch`의 되쓰기에서 찾는다: 서브에이전트의 메시지 히스토리 전체(그 안의 모든 도구 반환값과 함께)가 통째로 텍스트로 렌더링되어 메인 윈도에 밀어 넣어지므로, 격리는 속 빈 껍데기가 된다수정 뒤 `runSubagent`는 최종 요약본 텍스트만 반환하고, `tool_result`의 content가 그 요약본이며, 파견 한 번이 메인 윈도에 메시지 하나를 더한다레슨 4와의 연결을 설명한다: 메인 윈도가 더는 서브에이전트의 과정 내용에 잠기지 않으므로 컴팩션 로직의 발동 빈도가 줄어든다

레슨 5: 서브에이전트와 컨텍스트 격리

관점의 전환: 분업이 아니라 격리

메커니즘: 깨끗한 윈도가 들어가고, 압축된 요약본이 나온다

1차 데이터: 지능형 필터로서의 서브에이전트

장부의 반대편: 격리는 비용 절감이 아니다

긴 작업의 조합기: 노트를 바탕에, 핸드오프로 지구력을

Claude Code에서는 이것이 어떤 모습인가

정리

Footnotes

연습

당신의 메인 에이전트가 세 가지 작업을 맡습니다.

당신은 이 시리즈의 코스 7의 하네스에 서브에이전트를 배선하면서 파견 로직을 이렇게 썼습니다.