장기 작업 컨텍스트 관리

확인 날짜 안내

확인 날짜가 섞인 페이지다. 기본은 원본 발행 2025-09-29 기준이고, Claude Code 공식 문서(메모리·스킬·권한 모드·컨텍스트 창·작동 방식)에서 온 문장에는 (2026-10-18 기준), 블로그 Steering Claude Code에서 온 문장에는 (2026-06-18 기준)을 적었다. Claude Code 컴팩션 동작(요약, 최근 파일 최대 5개 다시 읽기, 요약 전에 오래된 도구 출력부터 지우기)은 공식 문서 Claude Code 컨텍스트 창·Claude Code 작동 방식(원본 날짜 미상, 수집 2026-10-18)이 확인한다. 메모리 도구와 도구 결과 지우기(Claude Developer Platform 기능)는 2025-09-29 글에만 근거했으나, 2026-10-26 수집한 공식 Memory tool 문서 Claude 메모리 도구 문서(원본 날짜 미상)로 지금 상태를 갱신했다(메모리 도구는 베타 헤더 없이 쓰고, 컨텍스트 편집이 도구 결과를 지운다). 페이지 확인 날짜는 2026-06-18이다. 블로그 Steering Claude Code에만 근거한 "(2026-06-18 기준)" 문장(예: PreCompact 훅 백업 설명)이 남아 있기 때문이다.

토큰(용어 사전) 수가 컨텍스트 창을 넘는 작업에서 에이전트가 일관성과 목표를 유지하게 하는 세 기법이다. 원본이 드는 대상은 수십 분에서 몇 시간 이어지는 일, 예컨대 대규모 코드베이스 마이그레이션이나 종합 리서치 프로젝트다. 효과적인 컨텍스트 엔지니어링 배경 원리는 컨텍스트 엔지니어링.

어떤 기법을 고르나#

원본이 든 작업 성격별 예시다. 효과적인 컨텍스트 엔지니어링

1. 컴팩션(Compaction)#

컨텍스트 창 한계에 가까워진 대화를 요약하고, 그 요약으로 새 컨텍스트 창을 시작하는 것이다. 원본은 장기 일관성을 위한 첫 번째 지렛대로 보통 이것을 쓴다고 말한다. 효과적인 컨텍스트 엔지니어링

Claude Code의 예 (2025-09-29 원본 기준): 메시지 기록을 모델에 넘겨 가장 중요한 세부를 요약·압축한다. 아키텍처 결정, 해결되지 않은 버그, 구현 세부는 남기고 중복된 도구 출력이나 메시지는 버린다. 그 뒤 압축된 컨텍스트와 가장 최근에 접근한 파일 5개로 이어 간다. 효과적인 컨텍스트 엔지니어링 → Claude Code

Claude Code 공식 문서의 설명 (2026-10-18 기준): 컴팩션은 대화를 구조화된 요약으로 바꾼다. 요약은 사용자의 요청과 의도, 핵심 기술 개념, 살펴보거나 고친 파일과 중요한 코드 조각, 오류와 해결 방법, 남은 작업, 현재 작업을 남기고, 전체 도구 출력과 중간 추론은 사라진다. 컴팩션 직후 Claude가 읽거나 편집한 파일 중 최근 수정된 것부터 최대 5개를 다시 읽는다. 5,000토큰을 넘는 파일은 내용 없이 경로 참조(Referenced file)로 돌아온다. v2.1.198부터 요약 요청은 세션의 extended thinking 설정을 따른다. Claude Code 컨텍스트 창

한도에 가까워질 때의 순서 (공식 작동 방식 문서, 2026-10-18 기준): Claude Code는 먼저 오래된 도구 출력을 지우고, 그래도 필요하면 대화를 요약한다. 요청과 핵심 코드 조각은 남고, 대화 초반의 자세한 지시는 사라질 수 있다. 그래서 원본은 지속 규칙을 대화 기록에 기대지 말고 CLAUDE.md에 두라고 한다. Claude Code 작동 방식

• 무엇을 남길지 정하는 두 방법: CLAUDE.md에 "Compact Instructions" 절을 더하거나, /compact focus on the API changes처럼 초점을 준다. 절의 형식은 원본에 없다. Claude Code 작동 방식 → CLAUDE.md 작성·구성
• 파일 하나나 도구 출력 하나가 너무 커서 요약 직후 컨텍스트가 다시 차면, Claude Code는 몇 번 시도한 뒤 자동 컴팩션을 멈추고 반복하는 대신 오류를 보여 준다. 복구 절차는 원본이 Troubleshooting의 thrashing 오류 항목으로 넘긴다. Claude Code 작동 방식
• 편집자 연결: 오래된 도구 출력을 먼저 지우는 순서는 아래 "가장 가벼운 형태"의 도구 결과 지우기(2025년 글)와 같은 발상으로 볼 수 있다. 근거는 두 원본의 "clears older tool outputs first"와 "tool result clearing" 문장이다. 다만 공식 문서는 Claude Code의 동작을 말하고, 2025년 글은 Claude Developer Platform 기능을 말한다. 둘이 같은 구현인지는 원본에 없다.

컴팩션 뒤 무엇이 다시 들어오나 (공식 문서, 2026-10-18 기준): 원본은 "어떻게 로드됐나"에 따라 갈린다고 말한다. 시작 때 로드된 것은 다시 들어오고, 대화 중 로드된 것은 대화와 함께 요약된다. Claude Code 컨텍스트 창

근거: Claude Code 컨텍스트 창. 원본이 짚은 실무 결론 두 가지: 컴팩션을 넘어 남아야 하는 규칙이면 paths: frontmatter를 빼거나 프로젝트 루트 CLAUDE.md로 옮기고, 스킬은 잘릴 때 앞부분이 남으므로 가장 중요한 지시를 SKILL.md 위쪽에 둔다. Claude Code 컨텍스트 창

컴팩션 뒤에 꼭 다시 알려야 할 것이 있으면 (2026-10-18 기준): 공식 훅 가이드는 compact matcher를 단 SessionStart 훅을 권한다. 명령이 stdout에 쓴 일반 텍스트가 컴팩션 뒤마다 Claude의 컨텍스트에 더해지고, echo 대신 git log --oneline -5 같은 동적 출력도 쓸 수 있다. 매 세션 시작 때 넣을 내용이면 CLAUDE.md를 고려하라고 한다. 설정 원문은 Claude Code 훅 설정 레시피. Claude Code 훅 가이드

Claude Code에서 컴팩션 뒤 지시가 남는 방식 (2026-10-18 기준): 프로젝트 루트 CLAUDE.md는 /compact 뒤 Claude가 디스크에서 다시 읽어 넣으므로 남는다. 하위 디렉터리 CLAUDE.md와 paths: 규칙은 필요할 때 다시 로드된다. 대화로만 준 지시는 사라질 수 있으니 계속 지켜야 할 지시는 CLAUDE.md에 적는다. Claude Code 메모리 → 메모리(CLAUDE.md), CLAUDE.md 문제 해결

대화로 말한 "하지 마"도 사라질 수 있다 (2026-10-18 기준): 자동 모드에서 "push하지 마", "배포 전에 내가 검토할 때까지 기다려"처럼 대화로 말한 경계는 분류기의 차단 신호가 된다. 하지만 규칙으로 저장되지 않고 분류기가 매번 대화 기록에서 다시 읽으므로, 컴팩션이 그 메시지를 지우면 사라질 수 있다. 확실히 보장하려면 deny 규칙을 쓴다. Claude Code 권한 모드 → 권한 모드

컴팩션 뒤 지시 방법별로 무엇이 남나 (2026-06-18 기준): 블로그 글은 "긴 세션에서 유지되는가"를 지시 방법을 고르는 세 축 중 하나로 둔다. Steering Claude Code

근거: Steering Claude Code. 출력 스타일·루트 CLAUDE.md·범위 없는 rules·스킬 행은 위 공식 문서 표(2026-10-18 기준)가 같은 방향으로 확인한다. Claude Code 컨텍스트 창

시스템 프롬프트 덧붙이기 행은 공식 CLI 문서가 다르게 적는다(2026-10-21 기준). 시스템 프롬프트는 대화의 첫 요청에서 플래그 텍스트를 반영해 한 번 만들어 세션에 기록하고, 컴팩션 전까지 --resume·--continue로 돌아온 나중 실행에서도 그 기록을 쓴다. 나중 실행에서 플래그를 바꾸거나 빼면 그 변화는 컴팩션 때나 새 대화에서 반영된다. 기본 동작이고, 기록하지 않는 예외(클라우드 세션 밖의 --bare 등)는 Claude Code CLI 플래그에 있다. 그래서 긴 작업을 재개하며 덧붙이기 문구를 바꿨다면, 컴팩션 전까지는 예전 문구가 쓰인다. 문구를 다듬는 중이면 --system-prompt-snapshot off로 매 요청 다시 만든다(v2.1.257 이상). 자동 컴팩션 지점은 저장된 설정을 바꾸지 않고 --autocompact <auto|tokens>로 이 세션만 정할 수 있다(v2.1.221 이상). Claude Code CLI 레퍼런스 → Claude Code CLI 플래그

원본끼리 달랐던 점(정리됨)--append-system-prompt 재개 동작

• Steering Claude Code (2026-06-18): 시스템 프롬프트 덧붙이기는 "applies only to that invocation"(그 실행에만 적용), 압축되지 않는다("Never compacted").
• Claude Code CLI 레퍼런스 (수집 2026-10-21): 기본 동작으로 첫 요청에서 만든 시스템 프롬프트를 세션에 기록하고, 컴팩션 전까지 --resume·--continue로 돌아온 나중 실행에서도 쓴다. 나중 실행의 다른 플래그 텍스트(또는 플래그 없음)는 컴팩션 때나 새 대화에서 반영된다.
• 설명과 실무는 공식 CLI 문서 기준. 블로그 문장은 출처와 함께 남긴다. 원문 인용·예외: Claude Code CLI 플래그

원본끼리 달랐던 점(정리됨)훅 출력과 컴팩션

• Steering Claude Code (2026-06-18): 훅은 컴팩션을 완전히 우회한다(원본 표의 Compaction behavior 열).
• Claude Code 컨텍스트 창 (원본 날짜 미상, 수집 2026-10-18): 앞서 훅이 더한 컨텍스트는 나머지 대화와 함께 요약된다. compact 소스에 맞는 SessionStart 훅은 컴팩션 뒤 실행돼 출력을 더한다.
• 편집자 해석: 블로그는 훅 설정이 컨텍스트 밖에 있어 컴팩션과 무관하게 계속 실행된다는 뜻으로, 공식 문서는 훅이 이미 대화에 넣은 출력의 운명을 말한 것으로 볼 수 있다. 근거는 블로그의 "the configuration or instruction lives outside the main context window"와 공식 문서의 "Context that hooks added earlier" 행이다. 설명할 때는 "훅은 계속 돌지만, 훅이 남긴 출력은 요약된다"로 말하는 편이 안전하다.
• 참고(2026-10-19 수집): Claude Code 훅 가이드 (원본 날짜 미상, 수집 2026-10-18)는 이 상충을 직접 판정하지 않는다. 다만 컴팩션이 대화를 요약하며 "This can lose important details"라고 말하고, compact matcher를 단 SessionStart 훅으로 "after every compaction" 핵심 컨텍스트를 다시 넣으라고 한다. 편집자 해석: 이것은 훅 설정이 컴팩션 뒤에도 실행된다는 위 해석과 같은 방향으로 볼 수 있지만(근거: "after every compaction"), 훅이 앞서 넣은 출력이 요약되는지는 이 가이드가 말하지 않는다. 그래서 2026-10-19 시점에는 상충을 열어 두었다.
• 부분 해소 근거(2026-10-19 수집): Claude Code 훅 레퍼런스 (원본 날짜 미상, 수집 2026-10-18)도 상충을 직접 판정하지 않지만, 공식 컨텍스트 창 문서 쪽 설명을 뒷받침하는 문장이 있다. (1) additionalContext는 "inserts it into the conversation at the point where the hook fired"이고 트랜스크립트에 저장된다. 훅 출력이 대화의 일부로 들어간다는 뜻이다. (2) SubagentStart 훅이 서브에이전트에 넣은 컨텍스트는 "After auto-compaction discards that copy, Claude Code injects the next run's context again"이라고 적는다. 서브에이전트에서는 훅이 넣은 컨텍스트가 자동 컴팩션에서 그대로 남지 않는다는 직접 문장이다. (3) SessionStart에는 compact 소스(원본: ""compact" after compaction")가 있다. 편집자 해석: 원본은 이것을 컴팩션 상충과 연결하지 않지만, 이 소스와 SessionStart의 additionalContext를 합치면 컴팩션 뒤에 훅이 다시 돌아 컨텍스트를 다시 넣는 구조로 볼 수 있다. 반면 InstructionsLoaded의 compact 로드 이유는 "instruction files are re-loaded after a compaction event"라는 뜻일 뿐이고, 이 훅은 결정 제어가 없어 아무것도 넣지 못하고 기록만 한다(원본: "Use this event for audit logging, compliance tracking, or observability."). (4) PreCompact는 컴팩션 자체를 막을 수 있고, PostCompact는 요약(compact_summary)을 받는다.
• 편집자 해석: 위 근거는 "훅 설정은 컴팩션과 무관하게 계속 돌지만, 훅이 대화에 남긴 출력은 컴팩션을 그대로 지나가지 않는다"는 기존 해석과 같은 방향으로 볼 수 있다. 다만 메인 대화에서 훅 출력이 "요약"되는지 "버려지는지"는 레퍼런스가 서브에이전트 경우("discards")만 말하므로, 메인 대화에 대한 직접 판정은 여전히 없다. 그래서 2026-10-19 시점에는 콜아웃을 열어 두었다. 설명용 문장("훅은 계속 돌지만, 훅이 남긴 출력은 컴팩션 뒤 그대로 남지 않는다")은 세 공식 문서와 어긋나지 않는다.
• 설명과 실무는 공식 컨텍스트 창 문서 기준으로 정리한다. 훅 설정은 컴팩션과 상관없이 계속 실행되지만, 훅이 앞서 대화에 넣은 컨텍스트는 나머지 대화와 함께 요약되고, 컴팩션 뒤 다시 넣을 내용은 compact 소스에 맞는 SessionStart 훅으로 넣는다. 근거: "Context that hooks added earlier | Summarized with the rest of the conversation", "SessionStart hooks that match the compact source | Claude Code runs them and adds their output to the compacted context". 블로그 문장과 출처는 위에 그대로 두고, 정리에서 기준이 아닌 쪽이 된 블로그 주장은 페이지 날짜 계산에서 뺀다. 이 상충의 허브는 이 페이지이고, 훅·Claude Code 확장 기능 고르기에는 짧은 콜아웃만 둔다.

위 메모리 문서의 설명(루트 CLAUDE.md는 다시 읽고, 하위 디렉터리 CLAUDE.md와 경로별 규칙은 필요할 때 다시 로드)과 같은 방향이다. 컴팩션 전에 대화 기록을 남기고 싶으면 PreCompact 훅으로 백업할 수 있지만, 설정이 출력을 돌려주지 않으면 Claude는 어느 파일에 저장됐는지 모른다. Steering Claude Code 전체 비교: Claude Code 확장 기능 고르기

스킬이 컴팩션 뒤 어떻게 남나 (2026-10-18 기준): 위 표의 스킬 행은 공식 스킬 문서가 확인한다. 대화를 요약할 때 Claude Code는 스킬마다 가장 최근 호출을 요약 뒤에 다시 붙이되 앞 5,000토큰만 남기고, 다시 붙인 스킬 전체가 25,000토큰 예산을 나눈다. 가장 최근에 호출한 스킬부터 채우므로 한 세션에서 스킬을 많이 불렀다면 오래된 스킬은 통째로 빠질 수 있다. Claude Code 스킬 그래서 원본은 두 가지를 권한다. Claude Code 스킬

• 가장 중요한 지시를 SKILL.md 위쪽에 둔다.
• 컴팩션 뒤 Claude가 스킬을 덜 따르면 스킬을 다시 불러 전체 내용을 복원한다.

→ 스킬, 스킬 문제 해결

Claude Code에서 컨텍스트가 차기 전에 할 일 (2026-10-18 기준): Claude Code는 한도에 가까워지면 자동으로 컴팩션하므로 창이 차도 세션이 끝나지 않는다. 원본은 그 전에 직접 손쓰는 방법 다섯 가지를 든다. Claude Code 컨텍스트 창

• 확인: /context로 지금 사용량을 카테고리별로 보고 최적화 제안을 받는다. Claude Code 컨텍스트 창
• (2026-10-26 기준) /compact의 비용과 때: 컴팩션은 설계상 대화 층의 프롬프트 캐시를 새 요약으로 바꾼다. 요약 요청은 캐시가 따뜻하면 앞부분을 캐시에서 읽어 컨텍스트 크기에 비해 적은 비용이 들지만, 캐시 수명보다 오래 쉬었다가 하면 기록 전체를 캐시 없이 다시 처리한다. 그래서 오래된 세션을 재개해 /compact할 때 가장 비싸다. 공식 문서는 자동 컴팩션이 작업 도중 돌기를 기다리지 말고 작업 사이 쉬는 지점에서 /compact를 돌리고, 버리고 싶은 길로 갔다면 이미 캐시된 앞부분으로 돌아가는 /rewind를 쓰라고 한다. Claude Code 프롬프트 캐싱 → 프롬프트 캐싱
• (2026-10-21 기준) 설정 키로 고정하기(settings reference): autoCompactEnabled(기본 true, false면 자동 컴팩션을 끄되 /compact는 계속 되고 idle compaction도 꺼진다. DISABLE_AUTO_COMPACT와 어느 쪽이 끄든 다른 쪽이 다시 켜지 못한다), autoCompactWindow(토큰 수 100000~1000000, 기본은 모델별 조정값. --autocompact 플래그가 이 키보다, CLAUDE_CODE_AUTO_COMPACT_WINDOW가 둘 다보다 우선. /autocompact는 모델별로 modelSettings에 저장), idleCompaction(기본 true. 대화형 터미널에서 1시간 프롬프트 캐시를 쓰고 기능 플래그를 받을 수 있으며 컨텍스트가 기본 200,000토큰 이상인 대화를 약 54분 유휴 뒤 캐시가 만료되기 직전에 컴팩션한다. 돌아오면 Compacted while idle, before the prompt cache expired로 시작하는 줄이 보인다. v2.1.290 이상). Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스
• 줄이는 대신 더 큰 창이 필요하면 100만 토큰 창을 지원하는 모델(원본 목록: Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.6 이상, Sonnet 4.6)의 [1m] 변형을 쓴다(플랜별 가용성은 원본이 Extended context 문서로 넘김). 큰 한도에서도 컴팩션은 같은 방식이다. Claude Code 컨텍스트 창 편집자 연결: 2025년 글은 더 큰 창을 기다리는 것이 답이 아닐 가능성이 높다고 본다(컨텍스트 엔지니어링). 근거 문장은 그 글의 "waiting for larger context windows might seem like an obvious tactic"으로 시작하는 문단이다. 두 원본을 함께 보면 큰 창은 컴팩션·노트·서브에이전트를 대신하기보다 그 위에 더하는 선택으로 볼 수 있다.
• 쓰지 않을 때: 원본은 /clear를 "관련 없는 작업으로 넘어갈 때"로 한정한다. 초점을 준 /compact는 컨텍스트가 성능에 영향을 주기 시작할 때나 긴 새 작업을 시작하기 전에 쓰라고 한다("when context starts affecting performance or before a long new task"). Claude Code 컨텍스트 창

컴팩션 프롬프트를 직접 만들 때의 단계:

1. 복잡한 에이전트 실행 기록(trace)으로 프롬프트를 조율한다.
2. 먼저 재현율(recall)을 최대로 올려, 기록 속 관련 정보를 빠짐없이 담게 한다.
3. 그다음 불필요한 내용을 빼며 정밀도(precision)를 올린다.

근거: 효과적인 컨텍스트 엔지니어링

주의: 너무 공격적으로 압축하면 나중에야 중요성이 드러나는 미묘한 맥락을 잃을 수 있다. 무엇을 남기고 버릴지 고르는 것이 핵심이다. 효과적인 컨텍스트 엔지니어링

가장 가벼운 형태: 도구 결과 지우기(tool result clearing). 메시지 기록 깊은 곳에서 이미 호출한 도구의 원래 결과를 다시 볼 이유가 거의 없다는 데서 출발한다. 원본은 이것을 가장 안전하고 가벼운 컴팩션 중 하나로 꼽고, 당시 Claude Developer Platform 기능으로 출시됐다고 적는다. 효과적인 컨텍스트 엔지니어링 (2026-10-26 기준) 공식 Memory tool 문서도 컨텍스트 편집(context editing)이 클라이언트에서 특정 도구 결과를 지우고, 서버 측 컴팩션은 대화 전체를 요약한다고 구분한다. 컨텍스트 편집의 설정 방법은 원본이 별도 문서로 넘긴다. Claude 메모리 도구 문서

2. 구조화된 노트(Structured note-taking)#

에이전트 메모리(agentic memory)라고도 한다. 에이전트가 컨텍스트 창 밖에 노트를 정기적으로 써 두고, 나중에 다시 컨텍스트로 불러온다. 적은 부담으로 지속 메모리를 준다. 효과적인 컨텍스트 엔지니어링

원본 예:

• Claude Code가 할 일 목록(to-do list)을 만드는 것, 직접 만든 에이전트가 NOTES.md 파일을 유지하는 것. 이렇게 하면 도구 호출 수십 번을 거치며 잃어버릴 진척과 의존 관계를 붙잡아 둔다. 효과적인 컨텍스트 엔지니어링 (2026-10-26 기준) Claude Code의 할 일 도구는 지금 Opus 4.7·Sonnet 4.6·Haiku 4.5 이하 모델에서만 기본으로 주어지고, 더 새 모델은 적어 둔 체크리스트 없이 여러 단계 일을 추적한다. 켜려면 CLAUDE_CODE_ENABLE_TODO_TOOLS=1. Claude Code 도구 레퍼런스 → Claude Code 내장 도구
• Claude가 포켓몬을 플레이하는 사례. 메모리 구조에 대한 프롬프트 없이도 수천 게임 스텝에 걸쳐 목표 진척을 세고, 탐색한 지역 지도와 달성한 업적, 상대별로 잘 통한 공격에 대한 전략 노트를 유지한다. 컨텍스트가 리셋된 뒤에는 자기 노트를 읽고 몇 시간짜리 훈련이나 던전 탐색을 이어 간다. 효과적인 컨텍스트 엔지니어링
• 메모리 도구: (2026-10-26 기준) Claude Developer Platform의 파일 기반 도구로, Claude가 /memories 디렉터리의 파일을 만들고 읽고 고치고 지워 대화를 넘어 정보를 쌓는다. 요청의 tools에 {"type": "memory_20250818", "name": "memory"}를 넣으면 되고, 도구 자체는 베타 헤더가 필요 없으며(SDK 도우미만 beta 네임스페이스) Claude 4 이후 모든 모델에서 쓴다. 클라이언트 측 도구라 실제 저장은 내 애플리케이션이 한다(아래 "메모리 도구로 여러 세션에 걸쳐 일하기"). Claude 메모리 도구 문서 2025년 글은 에이전트가 시간이 지나며 지식 베이스를 쌓고, 세션을 넘어 프로젝트 상태를 유지하고, 모든 것을 컨텍스트에 두지 않고 이전 작업을 참조하게 한다고 설명한다. 효과적인 컨텍스트 엔지니어링

Claude Code의 자동 메모리(Auto memory)는 Claude가 사용자의 교정과 선호를 창 밖 파일(~/.claude/projects/<project>/memory/)에 써 두고, 색인 MEMORY.md만 매 대화 시작 때 읽고 주제 파일은 필요할 때 읽는 기능이다(2026-10-18 기준). Claude Code 메모리

헷갈리기 쉬운 점: 위 메모리 도구는 API로 앱을 만드는 개발자가 쓰는 Developer Platform 기능이고, Claude Code의 CLAUDE.md·자동 메모리와는 다른 장치다. Memory tool 문서는 Claude Code를 말하지 않는다. Claude 메모리 도구 문서 → 메모리(CLAUDE.md)

메모리 도구로 여러 세션에 걸쳐 일하기 (2026-10-26 기준, 개발자용)#

공식 Memory tool 문서의 사용법과 "여러 세션에 걸친 소프트웨어 개발 패턴"이다. Claude 메모리 도구 문서

준비물: Claude API를 부르는 내 애플리케이션, 메모리를 둘 저장소(디스크 폴더, 데이터베이스 등). Python·TypeScript SDK는 바로 쓰는 로컬 파일 구현 BetaLocalFilesystemMemoryTool을 준다. Claude 메모리 도구 문서

1. 요청의 tools에 메모리 도구를 넣는다. 이 한 줄이 설정 전부다(name은 반드시 memory):

   {"type": "memory_20250818", "name": "memory"}

2. 명령 여섯 가지(view, create, str_replace, insert, delete, rename)를 처리하는 핸들러를 만든다. Claude는 작업을 요청만 하고, 내 애플리케이션이 실행해 tool_result로 돌려준다. 핸들러는 /memories 밖의 경로를 반드시 거부해야 한다. Claude 메모리 도구 문서

3. 첫 세션(initializer)에서 본 작업 전에 메모리 파일을 만든다: 진행 로그(한 일과 다음 할 일), 기능 체크리스트(작업 범위), 시작·초기화 스크립트 참조. Claude 메모리 도구 문서

4. 다음 세션들은 그 파일을 읽고 시작한다. 코드베이스를 다시 훑거나 앞선 결정을 되짚지 않고 상태를 되살린다. Claude 메모리 도구 문서

5. 세션이 끝나기 전에 진행 로그를 갱신한다. 원본의 핵심 원칙: 한 번에 기능 하나, 코드를 썼을 때가 아니라 끝에서 끝까지 확인한 뒤에만 완료로 표시한다. Claude 메모리 도구 문서

• 메모리 도구를 켜면 API가 "작업 전에 메모리 디렉터리를 먼저 보라, 진행을 기록하라, 컨텍스트 창이 언제든 리셋될 수 있다고 가정하라"는 지시를 시스템 프롬프트에 자동으로 더한다. 직접 보낼 필요가 없다. Claude 메모리 도구 문서
• 오래 도는 에이전트에는 서버 측 컴팩션과 메모리를 함께 쓰라고 권한다. 컴팩션은 활성 컨텍스트를 작게 두고, 요약을 넘어 남아야 할 정보는 메모리가 지킨다. Claude 메모리 도구 문서

보안은 내 애플리케이션 책임이다(원본 "Security considerations"). Claude는 보통 민감 정보를 메모리에 쓰기를 거부하지만, 더 강한 보장이 필요하면 핸들러가 쓰기 전에 걸러낸다. 파일 크기 상한, 오래 안 쓴 파일 삭제도 내가 정한다. /memories/../../secrets.env 같은 경로가 디렉터리 밖에 닿을 수 있으므로, 모든 명령의 모든 경로를 검증한다(/memories로 시작하는지, 정규화한 경로가 디렉터리 안인지, ../·URL 인코딩된 %2e%2e%2f 같은 패턴 거부). Claude 메모리 도구 문서

됐는지 확인하는 법: 원본에는 별도 점검 절차가 없다. 원본 예시에서 메모리 도구가 켜진 Claude의 첫 동작은 {"command": "view", "path": "/memories"} 호출이므로, 응답에 이 tool_use가 오는지로 연결을 볼 수 있다. Claude 메모리 도구 문서

이 위키 자체도 창 밖에 쌓는 노트의 한 형태로 볼 수 있다(편집자 해석, 원본은 LLM Wiki를 언급하지 않는다). → LLM Wiki

3. 서브에이전트 구조(Sub-agent architectures)#

에이전트 하나가 프로젝트 전체 상태를 붙들고 있는 대신, 전문 서브에이전트가 깨끗한 컨텍스트 창에서 초점 있는 작업을 맡는다. 메인 에이전트는 상위 계획을 들고 조율하고, 서브에이전트는 깊은 기술 작업을 하거나 도구로 관련 정보를 찾는다. 효과적인 컨텍스트 엔지니어링

• 서브에이전트 하나가 수만 토큰 이상을 쓰며 넓게 탐색해도, 돌려주는 것은 압축된 요약이다(보통 1,000~2,000 토큰). 효과적인 컨텍스트 엔지니어링
• 관심사가 분리된다. 세부 검색 맥락은 서브에이전트 안에 갇히고, 리드 에이전트는 결과를 종합·분석하는 데 집중한다. 효과적인 컨텍스트 엔지니어링
• Anthropic의 멀티에이전트 리서치 시스템에서 이 패턴은 복잡한 리서치 과제에서 단일 에이전트보다 상당한 개선을 보였다. 효과적인 컨텍스트 엔지니어링

Claude Code의 예 (2026-10-18 기준): 공식 작동 방식 문서는 서브에이전트가 자기 컨텍스트 창에서 일하고, 포크가 아니면 새로 시작하며(포크는 지금까지 대화의 사본으로 시작), 어느 쪽이든 서브에이전트의 도구 호출은 메인 컨텍스트에 들어오지 않고 끝나면 요약이 돌아온다고 말한다. Claude Code 작동 방식 공식 컨텍스트 창 문서 시뮬레이션에서 서브에이전트는 자기 창에서 읽기를 세 번 하고(session.ts, timeouts.ts, 여러 파일일 수 있는 config/*.ts), 메인에는 최종 텍스트 응답과 토큰 수·소요 시간을 담은 작은 메타데이터만 돌아온다(원본 예시: 읽은 6,100토큰, 돌려준 420토큰. 원본은 토큰 수가 예시라고 밝힌다). Claude Code 컨텍스트 창

(2026-10-18 기준) 공식 서브에이전트 문서가 더하는 장기 작업 세부: 서브에이전트도 자기 창이 차면 자동 컴팩션되고 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE가 적용되며, 트랜스크립트에 compact_boundary 이벤트와 컴팩션 전 토큰 수 preTokens가 남는다. 한 서브에이전트만 일찍 컴팩션하려면 frontmatter autoCompactWindow(100000~1000000, v2.1.296 이상)를 둔다. 서브에이전트 트랜스크립트는 별도 파일이라 메인 대화 컴팩션의 영향을 받지 않고, 같은 세션을 재개하면 재시작 뒤에도 서브에이전트를 재개할 수 있다(cleanupPeriodDays 기본 30일 뒤 삭제). 다시 설명하기엔 맥락이 큰 곁가지 일은 지금까지 대화를 물려받는 포크(/subtask)로 맡긴다. Claude Code 서브에이전트 → Claude Code 서브에이전트 만들기·운영

Claude Code에서 서브에이전트를 쓰는 방법은 서브에이전트. 같은 모양의 일반 패턴(중앙 LLM이 작업을 나눠 워커 LLM에 맡기고 종합하는 오케스트레이터-워커)과 그 패턴을 언제 쓰는지는 에이전트 시스템 패턴 고르기에 있다(편집자 연결. 그 원본 효과적인 에이전트 만들기는 컨텍스트 창 한계를 이유로 들지 않는다).

언제 쓰지 않는가#

원본은 세 기법을 쓰지 말아야 할 경우를 따로 들지 않는다. 고르는 기준은 위 표의 작업 성격이고, 컨텍스트 창 안에서 끝나는 짧은 작업은 원본이 말하는 장기 작업의 대상이 아니다. 효과적인 컨텍스트 엔지니어링