/clear를 할 때마다, 모든 것을 처음부터 다시 하고 계시나요?

Claude Code를 사용하다 보면 세션이 길어져 컨텍스트(Context)가 방대해집니다. /clear로 리셋하고 싶지만, 그렇게 하면 "이 프로젝트는 Nuxt3로...", "답변은 일본어로...", "테스트는 모크(Mock)를 사용하지 마세요..."와 같이 매번 똑같은 설명을 다시 해야 하는 상황에 처하게 됩니다.

이 문제는 파일에 적어두고, 세션 시작 시 자동으로 읽어오게 하는 것만으로 해결할 수 있습니다.

Claude Code의 Hook(SessionStart 이벤트)을 사용하면, 세션 시작 시 스크립트를 자동으로 실행하여 그 출력을 Claude의 컨텍스트에 주입할 수 있습니다. 즉, 정책(Policy) 파일을 준비해 두면 /clear를 하더라도 다음 세션에서 자동으로 복원됩니다.

이 기사에서는 실제로 동작하는 session-load Hook의 구현 방법을 공개합니다.

전제 지식

• Claude Code CLI를 사용 중임 (Anthropic 구독)
• CLAUDE.md를 작성해 본 적이 있음
• Windows + PowerShell 5.1을 상정 (macOS/Linux에서는 bash로 대체 가능)

메커니즘 개요

세션 시작 (/clear 후 또는 신규 실행)
↓
.claude/settings.json에 등록한 Hook이 자동 발화
...

사용자가 아무것도 하지 않아도 매 세션마다 정책이 읽히는 상태를 만들 수 있습니다.

Step 1: 정책 파일 만들기

먼저, Claude가 매번 기억해 주었으면 하는 내용을 Markdown 파일에 작성합니다.

프로젝트 루트/
└── ai-memory/
└── policies/
...

예를 들어 response-prefs.md는 다음과 같은 내용입니다:

---
type: response_rule
always_load: true
...

두 가지 포인트가 있습니다.

1. 영어의 전보(Telegraph) 형식으로 작성할 것. 정책 파일은 Claude가 읽는 것이므로, 사람을 향한 정중한 일본어(또는 한국어)는 필요하지 않습니다. 영어가 토큰 효율(Token efficiency)이 더 높으며, 동일한 정보량을 더 적은 토큰으로 전달할 수 있습니다.

"정확성과 안전성을 최우선으로 합니다. 그다음으로 실용성을 중시해 주세요." → PRIORITY: accuracy > practicality.

이것만으로도 토큰 소비가 60-70% 감소합니다. 세션 시작 시마다 읽어들이는 파일이므로 이 차이는 매우 큽니다.

2. 파일 수를 제한할 것. 상시 읽기 파일이 늘어나면 세션 시작 비용이 커집니다. 4개 이내의 파일로 유지하는 것을 권장합니다. 모든 것을 다 넣고 싶은 마음은 이해하지만, "여기에 적어두지 않으면 매번 사라지는 정보"로만 한정하세요. 프로젝트 고유의 규칙은 .claude/rules/에 경로 기반(Path-triggered)으로 작성하면 필요한 시점에만 읽어옵니다.

Step 2: session-load Hook 작성하기

문제: Hook의 stdout은 약 10,000자에서 잘림

정책 파일의 합계가 10KB 이상이 되면, 한 번의 Hook 실행으로는 전부를 출력할 수 없습니다.

해결책: 동일한 스크립트를 파트 번호를 바꿔가며 여러 번 병렬 실행하여, 각각이 담당하는 청크(Chunk)만 출력하도록 합니다.

코드

# .claude/hooks/session-load.ps1
param(
[int]$Part = 0,
...

settings.json에 등록

{
"hooks": {
"SessionStart": [
...

hooks 배열에 동일한 스크립트를 -Part 0과 -Part 1로 두 번 등록합니다. 이것들은 병렬 실행되므로 도착 순서는 불확정적입니다. 출력의 서두에 [session-load part 1/2]와 같은 헤더를 붙여 Claude가 순서를 재구성할 수 있도록 합니다.

정책이 늘어나 2개의 청크로 부족해지면, -Part 2 항목을 추가하기만 하면 됩니다.

macOS / Linux의 경우: powershell.exe를 bash로, .ps1을 .sh로 바꿔서 생각하세요. $1, $2로 Part와 Of를 받고, cat으로 파일을 읽어 echo로 출력하면 됩니다.

형태가 됩니다.

Step 3: 동작 확인

세션을 시작하여 컨텍스트에 [session-load part 1/2]와 같은 헤더가 포함되어 있다면 성공입니다.

포함되어 있지 않다면, 스크립트를 수동으로 실행하여 디버깅합니다:

powershell.exe -NoProfile -ExecutionPolicy Bypass `
-File .claude/hooks/session-load.ps1 -Part 0 -Of 2

출력이 없다면 스크립트에 에러가 있는 것입니다. try {} catch {}를 일시적으로 catch { $_ | Out-File error.log }로 변경하여 에러 내용을 확인하세요.

흔한 함정: PowerShell 5.1의 문자 인코딩 (Character Encoding)

Windows의 PowerShell 5.1은 기본적으로 일본어 환경에서 cp932 (Shift-JIS)를 사용합니다. UTF-8 파일을 읽으면 글자가 깨질 수 있습니다. 스크립트 서두에 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8를 넣는 것이 필수적입니다.

보너스: guard Hook으로 위험한 조작을 차단하기

session-load와 조합했을 때 효과적인 것이 PreToolUse 이벤트의 guard Hook입니다. force push나 --no-verify를 물리적으로 차단합니다.

# .claude/hooks/guard.ps1 (요점만)
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
...

settings.json에 추가:

{
"hooks": {
"PreToolUse": [
...

guard의 응답은 deny (완전 차단), ask (사용자 확인), allow (즉시 실행)의 3종류입니다. 아무것도 출력하지 않으면 일반적인 permission 흐름으로 진행됩니다.

설계 원칙: fail-open. 모든 Hook에 try {} catch {} + exit 0를 넣었습니다. Hook이 에러로 인해 중단되더라도 Claude Code는 멈추지 않습니다. 안전장치가 해제될 뿐, 사용할 수 없게 되는 것은 아닙니다.

앞으로 나아갈 방향

이 기사에서 소개한 것은 session-load와 guard라는 두 가지 Hook입니다. 실제로 운용 중인 시스템에서는 여기에 더해 다음과 같은 것들을 사용합니다:

• reminder Hook — 사용자가 메시지를 보낼 때마다 중요 규칙을 재주입 (긴 세션에서의 "망각" 방지)
• AI 기억 시스템 — 결정 기록, 실수의 교훈, 프로젝트 상태를 파일로 영속화. 확신도에 따라 Tier A / Tier B로 분류하여, 불확실한 정보는 인간의 필터를 거치게 함
• Skill (자작 커맨드) — /ingest로 외부 기사를 wiki로 증류, /daily-brief로 뉴스 요약
• Nightly 파이프라인 — 야간에 자동으로 뉴스 수집 → 기사 증류 → wiki 업데이트 → Git push

이것들을 조합하여, 세션 시작 시의 토큰 소비를 72KB → 23KB로 감소(69% 감소)시키면서도, /clear를 해도 지식이 사라지지 않는 시스템을 만들고 있습니다.

전체 설계 사상과 구현 코드는 Zenn의 책에 정리해 두었습니다:

제1장(Before/After)과 제2장(설계의 전체상)은 무료로 읽을 수 있습니다.

Discussion