Claude Code Hooks 완벽 가이드: AI가 맨날 까먹는 이유와 해결법

매번. 똑같은. 대화.

"TypeScript strict mode 써."
"함수마다 JSDoc 주석 달아."
".env 파일은 건드리지 마."
"API 호출 전에 나한테 물어봐."

저는 Claude Code 세션 시작할 때마다 첫 5분을 이런 얘기 반복하는 데 쓰고 있었습니다.

혹시 공감되시나요?

---

아무도 말 안 하는 문제

AI 코딩 어시스턴트는 정말 강력합니다. 근데 치명적인 약점이 하나 있어요.

세션 끝나면 다 잊어버림.

• 어제 1시간 동안 설명한 코딩 규칙? 사라짐.
• 그제 논의한 아키텍처 결정? 없던 일.
• "절대 자동 커밋하지 마"라고 했던 거? 기억 못함.

CLAUDE.md 파일도 써봤습니다. 도움은 되는데, Claude가 항상 먼저 읽지는 않더라고요. 시스템 프롬프트도 써봤는데 너무 번거롭고.

그러다가 모든 걸 바꾼 기능을 발견했습니다.

---

숨겨진 기능: Claude Code Hooks

Hooks는 Claude의 라이프사이클 특정 시점에 자동으로 실행되는 셸 명령어입니다. 제안이 아니에요. Claude가 따를 수도 있는 가이드라인이 아닙니다. 매번 무조건 실행되는 실제 코드입니다.

이렇게 생각하면 쉬워요

• CLAUDE.md = "Claude야, 이 규칙들 기억해줘" (정중한 부탁)
• Hooks = "이 규칙은 무조건 실행됨" (강제 자동화)

차이점? 하나는 AI의 협조에 의존하고, 다른 하나는 그냥... 작동합니다.

---

Hooks 작동 원리 (쉬운 설명)

Hooks는 특정 이벤트에서 발동됩니다:

이벤트	발동 시점	활용 예시
SessionStart	세션 시작	코딩 규칙 로드
PreToolUse	도구 실행 전	위험한 명령 차단
PostToolUse	도구 실행 후	코드 자동 포맷팅
PreCompact	컨텍스트 압축 전	중요 컨텍스트 보존
Notification	알림 필요 시	데스크톱 알림

설정은 .claude/settings.json에서 합니다:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '여기에 규칙 작성'"
          }
        ]
      }
    ]
  }
}

끝입니다. 매 세션마다 규칙이 자동으로 로드됩니다.

---

지금 바로 쓸 수 있는 실용적인 Hooks 5가지

1️⃣ 코딩 규칙 자동 로드

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[규칙] 1) TypeScript strict mode 2) 모든 함수에 JSDoc 3) 프로덕션에 console.log 금지'"
          }
        ]
      }
    ]
  }
}

매 세션이 규칙과 함께 시작됩니다. 더 이상 반복할 필요 없음.

---

2️⃣ 민감한 파일 보호

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(\\.env|credentials|secrets)'; then echo '차단됨: 민감한 파일 수정 불가' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

Claude가 .env 파일을 수정 못 합니다. "안 하는" 게 아니라 "못 하는" 겁니다.

---

3️⃣ 수정 후 자동 포맷팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.file_path'); if [[ \"$file\" == *.ts ]]; then npx prettier --write \"$file\"; fi"
          }
        ]
      }
    ]
  }
}

TypeScript 파일이 자동으로 포맷팅됩니다. "prettier 돌려줘" 안 해도 됨.

---

4️⃣ 데스크톱 알림 받기

{
  "hooks": {
    "Notification": [
      {
        "matcher": ".",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude가 응답을 기다리고 있습니다\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

자리 비워도 됩니다. Claude가 필요할 때 알림이 옵니다.

💡 Linux는 notify-send 사용

---

5️⃣ 컨텍스트 압축 후에도 규칙 유지

이거 중요합니다. 대화가 길어지면 Claude가 컨텍스트를 압축하는데, 이때 규칙을 종종 까먹습니다.

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[리마인더] 압축 후에도 기억할 것: TypeScript strict, JSDoc 필수, API 호출 전 확인'"
          }
        ]
      }
    ]
  }
}

압축 후에도 규칙이 살아남습니다. 매번.

---

설정 방법 (진짜 2분)

Step 1: 설정 파일 생성

mkdir -p .claude
touch .claude/settings.json

Step 2: Hooks 추가

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[내 코딩 규칙] 1) 규칙1 2) 규칙2'"
          }
        ]
      }
    ]
  }
}

Step 3: 레포에 커밋

git add .claude/settings.json
git commit -m "Add Claude Code hooks"

✅ 끝. 이제 팀원 모두가 같은 규칙을 공유합니다.

---

근데 아직 문제가 하나 남음

Hooks는 "규칙" 문제를 아름답게 해결합니다. 하지만 못하는 게 있어요:

왜 그렇게 만들었는지는 기억 못함.

이런 상황 상상해보세요

• 월요일: Claude랑 JWT를 쓰기로 결정. 충분한 논의 끝에.
• 수요일: 새 세션. Claude가 세션 방식을 제안함.
• 나: "우리 JWT 쓰기로 했잖아!"
• Claude: "아, 몰랐어요."

Hooks는 규칙을 상기시킬 수 있습니다. 하지만 아키텍처 결정의 이유는 보존하지 못해요.

---

빠진 퍼즐 조각: 코드 안의 컨텍스트

그래서 CodeSyncer를 만들었습니다.

bitjaru / codesyncer

Claude forgets everything when the session ends. CodeSyncer makes it remember.

CodeSyncer

Claude forgets everything when the session ends. CodeSyncer makes it remember.

한국어 | English

---

The Problem → The Solution

Problem	Without CodeSyncer	With CodeSyncer
Context loss	Every session = start from scratch	@codesyncer-* tags = permanent memory
Forgot to tag	Changes go untracked	codesyncer watch catches everything
Rules forgotten	AI forgets guidelines mid-session	Hooks auto-remind at optimal moments
Dangerous inference	AI guesses prices, security, APIs	Auto-pause on critical keywords

---

Demo

---

Quick Start

# 1. Install
npm install -g codesyncer

# 2. Initialize
cd /path/to/your/project
codesyncer init

# 3. Let AI set up (say this to Claude)
"Read .claude/SETUP_GUIDE.md and follow the instructions"

# 4. Start coding (say this each session)
"Read CLAUDE.md"

---

Core Features

🏷️ Tag System

Put context IN your code. AI reads code, so it recovers context automatically.

// @codesyncer-decision: [2024-01-15] Using JWT (session management is simpler)
// @codesyncer-inference: Page size

…

View on GitHub

아이디어는 간단해요: 코드 주석에 컨텍스트를 직접 저장하는 겁니다.

/**
 * 인증 서비스
 *
 * @codesyncer-decision [2026-01-15] 세션 대신 JWT 선택 (stateless, 스케일링 용이)
 * @codesyncer-inference 토큰 만료 24시간 (웹앱 표준)
 */
export class AuthService {
  // @codesyncer-rule 디버그 모드에서도 토큰 로깅 금지
  async login(credentials: Credentials) {
    // ...
  }
}

다음 세션에서 Claude가 코드를 읽으면 즉시 알게 됩니다:

• ✅ 뭘 결정했는지
• ✅ 왜 그렇게 결정했는지
• ✅ 어떤 규칙이 적용되는지

반복 없음. 까먹음 없음. 컨텍스트가 코드 자체에 살아있습니다.

---

Hooks + CodeSyncer = 완벽한 조합

문제	해결책
AI가 코딩 규칙을 까먹음	Hooks → 매 세션 자동 로드
AI가 결정을 까먹음	@codesyncer-decision → 코드에 남음
AI가 추론함	@codesyncer-inference → 근거 문서화
AI가 민감한 로직 건드림	@codesyncer-rule → 명시적 경고

CodeSyncer는 Hooks도 자동으로 설정해줍니다:

npx codesyncer init

이렇게 생성됩니다:

• ✅ .claude/settings.json - SessionStart, PreCompact hooks 포함
• ✅ .claude/CLAUDE.md - 코딩 규칙
• ✅ 태그 시스템 바로 사용 가능

---

빠른 시작

🚀 CodeSyncer 시작하기

⭐ CodeSyncer GitHub에서 스타 누르기

옵션 1: Hooks만 (수동)

mkdir -p .claude
echo '{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"echo [규칙] 여기에 규칙"}]}]}}' > .claude/settings.json

옵션 2: 전체 설정 (추천)

npx codesyncer init

---

요약

Hook	용도
SessionStart	매 세션 규칙 로드
PreCompact	압축 후에도 규칙 유지
PreToolUse	위험한 작업 차단
PostToolUse	자동 포맷팅, 린팅
Notification	데스크톱 알림

Hooks는 "규칙"을 담당합니다.
CodeSyncer는 "이유"를 담당합니다.

둘을 같이 쓰면, AI가 드디어 까먹지 않습니다.

---

링크

🔗 Claude Code Hooks 공식 문서
🔗 CodeSyncer GitHub

---

Hooks 써보셨나요? 어떤 규칙을 자동화하고 계신가요?

👇 댓글로 공유해주세요!