DEV Community

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

Posted on

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

#ai #claudecode #programming #webdev

매번. 똑같은. 대화.

"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 '여기에 규칙 작성'"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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

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

1️⃣ 코딩 규칙 자동 로드 

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

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

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"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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

4️⃣ 데스크톱 알림 받기 

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

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

💡 Linux는 notify-send 사용

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

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

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

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

설정 방법 (진짜 2분)

Step 1: 설정 파일 생성

mkdir -p .claude
touch .claude/settings.json
Enter fullscreen mode Exit fullscreen mode

Step 2: Hooks 추가

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

Step 3: 레포에 커밋

git add .claude/settings.json
git commit -m "Add Claude Code hooks"
Enter fullscreen mode Exit fullscreen mode

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

근데 아직 문제가 하나 남음

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

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

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

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

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

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

GitHub logo 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.

npm version License GitHub stars

한국어 | 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

CodeSyncer 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"
Enter fullscreen mode Exit fullscreen mode

Upgrade

npm install -g codesyncer@latest
Enter fullscreen mode Exit fullscreen mode

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)
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

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

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

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

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

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

Hooks + CodeSyncer = 완벽한 조합

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

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

npx codesyncer init
Enter fullscreen mode Exit fullscreen mode

이렇게 생성됩니다:

  • ✅ .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
Enter fullscreen mode Exit fullscreen mode

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

npx codesyncer init
Enter fullscreen mode Exit fullscreen mode

요약

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

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

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

링크

🔗 Claude Code Hooks 공식 문서
🔗 CodeSyncer GitHub

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

👇 댓글로 공유해주세요!

Top comments (0)