MemoryLake
모든 글로 돌아가기
Tutorial2026년 11월 13일·12 분 소요

Claude Code 훅(Hooks)이란 무엇인가요? Claude에 컨텍스트를 추가하는 훅, 재개된 세션에서 이전 출력이 반복되는 이유, CLAUDE.md가 더 적합한 경우 (2026)

프롬프트를 제출할 때마다 Claude Code에 현재 브랜치와 최신 CI 결과를 알려주는 작은 훅을 작성했다고 가정해 봅시다. 처음에는 잘 작동합니다. 그러다 다음 날 --continue로 세션을 재개하고 빌드에 대해 물으면, Claude는 자신 있게 어제의 CI 상태와 이미 교체된 커밋 정보를 보고합니다. 훅이 실패한 것이 아닙니다. Claude Code가 어제 말했던 내용을 그대로 재생(replay)한 것입니다.

Anthropic의 훅 레퍼런스에서는 이 현상을 다음과 같이 설명합니다: "PostToolUse 또는 UserPromptSubmit과 같은 세션 중간 이벤트의 경우, --continue 또는 --resume으로 재개할 때 Claude Code는 과거 턴에 대해 훅을 다시 실행하는 대신 저장된 텍스트를 재생하므로 타임스탬프나 커밋 SHA와 같은 값이 오래된 상태(stale)가 됩니다."

훅은 Claude Code에 컨텍스트를 제공하는 유연한 방법이지만, 오해하기 쉬운 부분이기도 합니다. 이 가이드에서는 훅의 정의, 정의 위치, Claude에 컨텍스트를 추가할 수 있는 훅 이벤트, 해당 컨텍스트가 저장되는 위치, 재개 및 컴팩션(compaction) 후 발생하는 현상, 훅이 컴팩션 요약에 미치는 영향, 그리고 동일한 정보에 대해 CLAUDE.md 파일이 더 나은 대안이 되는 경우를 다룹니다.

Claude Code 훅이란 무엇인가

Anthropic의 정의에 따르면: "훅은 Claude Code의 라이프사이클 중 특정 시점에 자동으로 실행되는 사용자 정의 쉘 명령, HTTP 엔드포인트, MCP 도구 호출, LLM 프롬프트 또는 서브에이전트입니다."

훅은 터미널뿐만 아니라 더 많은 곳에서 실행됩니다. "Claude Code는 터미널 세션, IDE 확장 프로그램, 데스크톱 앱, 클라우드 세션 등 실행되는 모든 곳에서 동일한 훅 이벤트를 발생시킵니다."

각 훅은 특정 이벤트에 연결됩니다. 레퍼런스에는 세션이 시작되거나 재개될 때의 SessionStart부터, 도구 호출 실행 전의 PreToolUse, 컴팩션 전후의 PreCompact 및 PostCompact, 세션이 종료될 때의 SessionEnd까지 수십 가지 이벤트가 나열되어 있습니다.

훅은 편집 후 파일 형식을 지정하거나, 위험한 명령을 차단하거나, 알림을 보내는 등의 부수 효과(side-effect) 작업도 수행할 수 있습니다. 이 가이드는 Claude의 컨텍스트에 텍스트를 주입하는 훅의 하위 집합에 집중합니다. 이 텍스트는 고유한 규칙을 가진 기억(memory)처럼 작동하기 때문입니다.

훅이 정의되는 위치

훅을 정의하는 위치에 따라 그 범위(scope)가 결정됩니다. 레퍼런스에 나열된 위치는 다음과 같습니다:

  • ~/.claude/settings.json: 로컬 머신의 모든 프로젝트에 적용됩니다.
  • .claude/settings.json: 단일 프로젝트용이며, 저장소(repo)에 커밋할 수 있습니다.
  • .claude/settings.local.json: 단일 프로젝트용이며, 공유되지 않습니다.
  • 관리형 정책 설정(Managed policy settings): 관리자가 제어하는 조직용 설정입니다.
  • 플러그인의 hooks/hooks.json: 해당 플러그인이 활성화된 동안 적용됩니다.
  • 스킬 또는 서브에이전트 프런트매터(frontmatter): 해당 스킬이나 서브에이전트가 사용되는 동안 적용됩니다.

훅 항목은 서로 대체되는 것이 아니라 결합됩니다. "훅 항목은 설정 수준에 따라 대체되지 않고 병합됩니다. 사용자, 프로젝트 및 로컬 설정은 관리형 훅을 제거하지 않고 자체 훅을 추가합니다."

원격 작업 시 알아두어야 할 제한 사항이 하나 있습니다: "클라우드 세션은 로컬의 ~/.claude/settings.json을 읽지 않습니다." 로컬에서 의존하는 훅은 클라우드 세션이 읽을 수 있는 위치에 정의되어 있지 않으면 클라우드 세션에서 실행되지 않습니다.

구성된 내용을 확인하려면 /hooks를 입력하세요. Anthropic은 이를 각 훅의 출처를 표시하는 "구성된 훅을 위한 읽기 전용 브라우저"라고 설명합니다.

Claude에 컨텍스트를 추가할 수 있는 훅

모든 훅이 Claude와 대화할 수 있는 것은 아닙니다. 대화가 가능한 훅은 additionalContext라는 필드를 사용합니다. Anthropic은 다음과 같이 설명합니다: "additionalContext 필드는 훅의 문자열을 Claude의 컨텍스트 창으로 전달합니다."

텍스트가 나타나는 위치는 이벤트에 따라 다릅니다:

  • SessionStart 및 SubagentStart: "대화 시작 시, 첫 번째 프롬프트 이전"
  • UserPromptSubmit 및 UserPromptExpansion: "제출된 프롬프트와 함께"
  • PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch: "도구 결과 옆에"
  • Stop 및 SubagentStop: 턴의 끝에 위치하여 Claude가 피드백에 따라 행동할 수 있게 함
  • PostModelSwitch: "모델 전환 후 다음 요청과 함께"

UserPromptSubmit의 경우 일반 출력도 작동합니다. 레퍼런스에서는 일반 표준 출력(stdout)과 additionalContext라는 두 가지 채널을 설명하며 다음과 같이 명시합니다: "두 채널 모두 가시적인 트랜스크립트 항목을 생성하지 않습니다."

이 부분이 사람들을 놀라게 하는 부분입니다. Claude Code는 텍스트를 시스템 리마인더(system reminder)로 감쌉니다: "Claude는 다음 모델 요청 시 리마인더를 읽지만, 인터페이스에는 채팅 메시지로 표시되지 않습니다." Claude는 이를 보지만, 채팅창에는 나타나지 않습니다.

훅이 추가한 내용을 확인하고 싶다면, 트랜스크립트 뷰(transcript view)를 통해 채팅보다 더 많은 세션 내용을 볼 수 있습니다. 이에 대해서는 Claude Code의 트랜스크립트 뷰가 보여주는 것 가이드에서 다룬 바 있습니다.

훅이 추가할 수 있는 컨텍스트의 양

크기 제한이 있습니다. "값이 10,000자를 초과하면 Claude Code는 텍스트를 세션 디렉토리의 파일에 쓰고, 대신 Claude에게 파일 경로와 최대 처음 2,000자의 미리보기를 전달합니다. Claude는 파일을 읽을 수 있지만, Claude Code가 읽으라고 명시적으로 요청하지는 않습니다."

따라서 긴 보고서를 덤프하는 훅은 보고서 전체를 Claude 앞에 두지 않습니다. 미리보기와 경로만 제공하며, Claude가 파일을 열지 여부는 Claude의 판단에 달렸습니다.

동일한 이벤트에 여러 훅이 실행될 때 모두 합산됩니다. "여러 훅이 동일한 이벤트에 대해 additionalContext를 반환하면 Claude는 모든 값을 수신합니다."

훅이 추가하는 컨텍스트 작성 방법

Anthropic은 문구 선택에 대해 구체적인 조언을 제공합니다: "텍스트를 명령형 시스템 지침이 아닌 사실적 진술로 작성하십시오."

그 이유는 보안 때문입니다. 대화 외부에서 온 명령처럼 들리는 텍스트는 프롬프트 인젝션(prompt injection)처럼 보일 수 있습니다. Anthropic은 이러한 프레임워크가 "Claude의 프롬프트 인젝션 방어 기제를 트리거할 수 있으며, 이로 인해 Claude가 텍스트를 컨텍스트로 처리하는 대신 사용자에게 노출하게 된다"고 경고합니다.

제공된 예시는 평범한 사실로 읽힙니다: "배포 대상은 프로덕션입니다" 또는 "이 저장소는 bun test를 사용합니다". 또한 훅이 사용되기 좋은 정보 유형도 나열되어 있습니다:

  • 환경 상태: 현재 브랜치, 배포 대상 또는 피처 플래그(feature flags)
  • 조건부 프로젝트 규칙: 방금 편집한 파일에 적용되는 테스트 명령, 작업 트리(worktree)에서 읽기 전용인 디렉토리
  • 외부 데이터: 열려 있는 이슈, 최근 CI 결과, 내부 서비스의 콘텐츠

이들의 공통점은 '변한다'는 것입니다. 이것이 파일 대신 훅을 사용해야 하는 이유입니다.

재개된 세션에서 왜 오래된 훅 출력이 재생되는가

서론에서 언급한 동작의 전체 내용입니다. "Claude Code는 주입된 텍스트를 세션 트랜스크립트에 저장합니다."

세션으로 돌아왔을 때 과거의 턴은 다시 실행되지 않습니다. "PostToolUse 또는 UserPromptSubmit과 같은 세션 중간 이벤트의 경우, --continue 또는 --resume으로 재개할 때 Claude Code는 과거 턴에 대해 훅을 다시 실행하는 대신 저장된 텍스트를 재생하므로 타임스탬프나 커밋 SHA와 같은 값이 오래된 상태가 됩니다."

실제로 Claude는 훅이 실행된 당시의 내용을 보게 됩니다. 어제 훅이 CI 상태, 브랜치 또는 이슈 목록을 보고했다면, 재개된 대화의 기록 중 해당 훅이 실행된 턴 옆에 그 내용이 그대로 남아 있습니다.

SessionStart는 예외입니다. Anthropic은 SessionStart 훅이 재개 시 다시 실행된다고 말하며, source 필드가 resume으로 설정되거나 --fork-session을 추가한 경우 fork로 설정되어 "컨텍스트를 새로 고칠 수 있게 한다"고 설명합니다.

따라서 재개된 세션에서 최신 값을 원한다면 resume 매처(matcher)가 있는 SessionStart 훅이 공식적인 위치입니다. 이전 값은 여전히 기록에 남아 있으므로, 새 텍스트에 무엇이 현재 상태인지 명시하는 것이 도움이 됩니다.

컴팩션 시 훅 컨텍스트에 일어나는 일

컴팩션(Compaction)은 공간을 확보하기 위해 대화의 이전 부분을 요약합니다. Anthropic의 훅 가이드는 그 위험성을 직접적으로 언급합니다: "이 과정에서 중요한 세부 정보를 잃을 수 있습니다."

훅 텍스트는 대화 기록에 포함되며, 컴팩션은 바로 이 기록을 요약합니다. 훅은 이를 관리하는 두 가지 방법을 제공합니다.

컴팩션 후 재주입. SessionStart에는 자동 또는 수동 컴팩션 후에 실행되는 compact 매처가 있습니다. 가이드의 권장 사항은 다음과 같습니다: "모든 컴팩션 후에 중요한 컨텍스트를 다시 주입하려면 compact 매처가 있는 SessionStart 훅을 사용하십시오."

요약 자체의 형태 결정. PreCompact는 컴팩션 전에 실행되며, 그 출력은 특별한 역할을 합니다. "PreCompact 훅이 0을 반환하며 종료되고 차단되지 않으면, Claude Code는 해당 표준 출력을 컴팩션 요약을 위한 지침으로 사용합니다." 동일한 10,000자 제한이 적용되며, 더 긴 출력은 제한 지점에서 잘립니다.

PreCompact는 타이밍에 따라 다른 결과로 컴팩션을 차단할 수도 있습니다. 컴팩션이 선제적으로 트리거된 경우, 이를 차단하면 대화가 컴팩션되지 않은 상태로 계속됩니다. 컨텍스트 제한 오류를 복구하기 위해 트리거된 경우, "기저 오류가 표면화되고 현재 요청이 실패합니다."

PostCompact는 생성된 요약을 compact_summary라는 필드로 수신하며, 이는 Claude Code 외부에서 로그를 기록하거나 노트를 업데이트하는 데 유용합니다. 레퍼런스에는 결정 제어권 없이 로깅과 같은 부수 효과용으로 나열되어 있습니다.

SessionStart 매처(Matchers)

SessionStart는 훅이 컨텍스트를 새로 고치는 주요 방법이므로, 해당 매처를 알아둘 가치가 있습니다. 레퍼런스에는 5가지가 나열되어 있습니다:

  • startup: 새 세션용
  • resume: --resume, --continue 또는 /resume용
  • clear: /clear용
  • compact: 자동 또는 수동 컴팩션용
  • fork: 기존 세션에서 분기된 새 세션용

타이밍에 대한 세부 사항도 있습니다. 실행 시 및 /clear 후에는 SessionStart 훅이 백그라운드에서 실행되므로 바로 타이핑을 시작할 수 있지만, "Claude의 첫 번째 응답은 여전히 훅이 끝날 때까지 기다리므로 컨텍스트가 Claude에게 전달됩니다." 또한 백그라운드 훅이 실행되는 동안 /clear를 실행하거나 대화를 전환하면 훅이 반환하는 어떤 내용도 세션에 적용되지 않는다고 명시되어 있습니다.

CLAUDE.md가 더 적합한 경우

Anthropic은 레퍼런스에서 이에 대해 직접 답변합니다: "절대 변하지 않는 지침의 경우 CLAUDE.md를 선호하십시오. 스크립트를 실행하지 않고 로드되며 정적인 프로젝트 컨벤션을 위한 표준 장소입니다."

SessionStart 섹션에서도 동일하게 언급합니다: "스크립트가 필요 없는 정적 컨텍스트의 경우 대신 CLAUDE.md를 사용하십시오."

간단한 테스트: 훅이 실행될 때마다 텍스트가 동일하다면 CLAUDE.md에 속합니다. 브랜치, 시간 또는 최신 빌드와 같이 순간에 따라 달라진다면 훅이 적합한 도구입니다.

CLAUDE.md는 컴팩션과 관련하여 고유한 동작을 가집니다. 레퍼런스에는 컴팩션 후 지침 파일이 다시 로드될 때 발생하는 compact라는 InstructionsLoaded 로드 사유가 언급되어 있습니다. 컴팩션에서 살아남게 하려고 정적 규칙을 훅에 넣어왔다면, CLAUDE.md가 문서화된 정식 위치입니다. CLAUDE.md 파일이 어떻게 로드되고 비용이 얼마나 드는지 확인하려면 Claude Code에서 /doctor가 확인하는 것 가이드를 참조하세요.

훅 끄기

훅을 제거하려면 설정 파일에서 해당 항목을 삭제하세요. 모든 훅을 일시적으로 끄려면 레퍼런스에 설명된 disableAllHooks 설정을 사용하며, 이는 설정 우선순위를 따릅니다. 관리자는 더 강력한 버전을 가집니다. 관리형 설정에서 allowManagedHooksOnly를 사용하면 사용자, 프로젝트, 로컬 및 플러그인 훅이 모두 차단됩니다.

훅의 컨텍스트가 사라진 것 같다면 스크립트를 디버깅하기 전에 이 두 설정을 확인하세요.

사람들이 처음에 실수하는 것들

재개된 세션의 값을 맹신함. 세션 중간 훅 출력은 트랜스크립트에서 재생되므로 타임스탬프와 커밋 SHA가 오래된 것일 수 있습니다.

채팅에서 훅 출력을 찾음. 추가된 컨텍스트는 채팅 메시지로 나타나지 않습니다.

정적 규칙을 훅에 넣음. Anthropic은 절대 변하지 않는 지침에 대해 CLAUDE.md를 권장합니다.

훅 텍스트를 명령으로 작성함. 명령형 프레임워크는 프롬프트 인젝션 방어 기제를 트리거할 수 있습니다.

긴 보고서를 반환함. 10,000자가 넘으면 Claude는 미리보기와 파일 경로만 받게 됩니다.

클라우드 세션에서 로컬 훅을 기대함. 클라우드 세션은 로컬 사용자 설정을 읽지 않습니다.

해결책: 오래된 잔재 없이 Claude에게 현재 컨텍스트 제공하기

1단계: 정적 규칙을 CLAUDE.md로 이동

훅이 항상 같은 내용을 말한다면, 그 텍스트를 CLAUDE.md에 넣으세요.

2단계: 재개 및 컴팩션 후 새로 고침

변하는 값에 대해서는 resume 및 compact 매처와 함께 SessionStart를 사용하세요.

3단계: 사실을 작성하고 짧게 유지

훅 출력을 사실적 진술로 표현하고, 무엇이 현재 상태인지 라벨을 붙이고, 10,000자 미만으로 유지하세요.

4단계: 이유를 기록하기

특정 디렉토리가 왜 읽기 전용인지 또는 왜 테스트 명령이 다른지와 같은 컨벤션 뒤에 숨겨진 결정 사항들을 매 세션마다 재생성되지 않는 곳에 보관하세요.

MemoryLake에서 설정하기

훅은 현재 시제에 강합니다: 현재 어떤 브랜치에 있는지, 지금 CI가 무엇을 말하는지 등입니다. CLAUDE.md는 고정된 컨벤션에 강합니다. 하지만 팀이 왜 특정 마이그레이션 순서를 선택했는지 또는 어떤 접근 방식이 이미 제외되었는지와 같이, 천천히 변하면서 여러 도구에 전달되어야 하는 결정 사항들을 위해 만들어진 것은 아닙니다.

MemoryLake는 결정, 제약 조건, 컨벤션과 같은 프로젝트 컨텍스트를 위한 기억 계층(memory layer)입니다. 사용자가 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 모든 어시스턴트가 사용할 수 있습니다.

사용자는 자신의 언어로 직접 항목을 작성합니다. 훅, 설정 파일, CLAUDE.md 파일, 세션 트랜스크립트, 컴팩션 요약 또는 벤더의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. 훅, 컴팩션, 재개 기능은 Anthropic이 설명한 방식 그대로 작동합니다.

1단계: API 키 생성

로그인 후 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부 및 훅 스크립트 외부에 보관하세요.

에이전트에서 사용하기 위해 새 키를 생성하고 복사하는 API 키 화면을 보여주는 MemoryLake 콘솔
에이전트에서 사용하기 위해 새 키를 생성하고 복사하는 API 키 화면을 보여주는 MemoryLake 콘솔

2단계: 첫 번째 기억 업로드

해결책의 4단계에서 작성한 내용부터 시작하세요: 컨벤션 뒤에 숨겨진 이유와 훅이 가정하는 결정 사항들입니다. 항목당 하나의 결정을 담으세요.

첫 번째 문서가 업로드되어 각 파일이 검색 가능한 기억이 되는 과정을 보여주는 MemoryLake 워크스페이스
첫 번째 문서가 업로드되어 각 파일이 검색 가능한 기억이 되는 과정을 보여주는 MemoryLake 워크스페이스

3단계: AI 및 에이전트 연결

Claude Code 및 사용하는 다른 어시스턴트를 연결하세요. 훅은 계속해서 현재 상태를 공급하고, 그와 함께 의사 결정 근거를 사용할 수 있게 됩니다.

기억 계층에 연결할 수 있는 AI 클라이언트 및 에이전트 프레임워크를 나열한 MemoryLake 통합 화면
기억 계층에 연결할 수 있는 AI 클라이언트 및 에이전트 프레임워크를 나열한 MemoryLake 통합 화면

실제로 바뀌는 점

첫 번째 차이점은 더 깔끔한 분리입니다. 훅은 분 단위로 변하는 내용을 전달하고, CLAUDE.md는 고정된 컨벤션을 전달하며, 더 느리게 변하는 결정 사항들은 그들만의 자리를 갖게 됩니다.

두 번째는 덜 오래된(stale) 컨텍스트입니다. 결정 사항들은 훅이 실행된 순간의 트랜스크립트에 고정되지 않습니다.

세 번째는 도구 간의 연속성입니다. 동일한 저장소에서 작업하는 Codex나 다른 어시스턴트가 자체적인 훅 설정 없이도 동일한 결정 사항들을 사용할 수 있습니다.

Claude Code 훅을 위한 베스트 프랙티스

변하는 것에 훅을 사용하세요. 고정된 규칙이 아니라 브랜치, 빌드, 이슈 목록 등에 사용하세요.

고정된 규칙은 CLAUDE.md에 넣으세요. 스크립트 실행 없이 로드됩니다.

재개 시 새로 고침하세요. 재개할 때 다시 실행되는 것은 SessionStart뿐입니다.

컴팩션을 고려하세요. 중요한 내용을 다시 주입하려면 compact 매처를 사용하고, 요약을 가이드하려면 PreCompact를 사용하세요.

명령이 아닌 사실을 작성하세요. 훅 텍스트가 인젝션처럼 보이지 않게 해줍니다.

크기 제한을 지키세요. 긴 출력은 파일 경로와 미리보기가 됩니다.

무언가 빠졌을 때는 /hooks를 확인하세요. 각 훅의 출처를 보여줍니다.

결론

Claude Code 훅은 세션 라이프사이클의 특정 시점에 자동으로 실행되며, SessionStart, SubagentStart, UserPromptSubmit, 도구 이벤트, Stop, PostModelSwitch 등 여러 훅이 additionalContext를 통해 Claude에게 컨텍스트를 추가할 수 있습니다. 이 텍스트는 시스템 리마인더로 Claude에게 전달되며 채팅 메시지로는 나타나지 않습니다.

Claude Code는 훅 텍스트를 트랜스크립트에 저장하고 재개 시 과거 턴에 대해 이를 재생하므로 값이 오래될 수 있으며, 오직 SessionStart만 다시 실행됩니다. SessionStart 매처와 PreCompact를 사용하여 재개 및 컴팩션 전반의 컨텍스트를 관리하고, 정적 규칙은 CLAUDE.md에 보관하며, 설정 뒤에 숨겨진 결정 사항들은 매 세션마다 재생성되지 않는 곳에 보관하세요.

자주 묻는 질문

Claude Code에서 훅(hooks)이란 무엇인가요?

Claude Code의 라이프사이클 중 특정 시점에 자동으로 실행되는 사용자 정의 쉘 명령, HTTP 엔드포인트, MCP 도구 호출, LLM 프롬프트 또는 서브에이전트입니다.

훅이 Claude에게 컨텍스트를 추가할 수 있나요?

네. SessionStart, UserPromptSubmit 및 도구 이벤트를 포함한 여러 이벤트가 additionalContext를 반환할 수 있으며, Claude는 이를 시스템 리마인더로 읽습니다.

세션을 재개한 후 왜 Claude가 오래된 훅 출력을 보게 되나요?

Claude Code가 주입된 텍스트를 트랜스크립트에 저장하고 훅을 다시 실행하는 대신 과거 턴에 대해 이를 재생하기 때문입니다. 이로 인해 타임스탬프나 커밋 SHA와 같은 값이 오래된 상태가 될 수 있습니다.

세션을 재개할 때 훅이 다시 실행되나요?

SessionStart 훅은 재개 시 다시 실행됩니다. 과거 턴에 대한 세션 중간 훅은 다시 실행되지 않고 재생됩니다.

컴팩션 후에도 컨텍스트를 유지하려면 어떻게 해야 하나요?

컨텍스트를 다시 주입하려면 compact 매처가 있는 SessionStart 훅을 사용하거나, 컴팩션 요약에 대한 지침을 제공하려면 PreCompact 훅을 사용하세요.

훅과 CLAUDE.md 중 무엇을 사용해야 하나요?

Anthropic은 절대 변하지 않는 지침에 대해 CLAUDE.md를 권장합니다. 현재 브랜치나 CI 결과와 같이 변하는 컨텍스트에는 훅을 사용하세요.

왜 클라우드 세션에서 내 훅이 실행되지 않나요?

클라우드 세션은 로컬의 ~/.claude/settings.json 파일을 읽지 않기 때문입니다.