Hook: AI가 알아서 다 해주는 마법의 비밀

Hook 시스템: AI가 모든 대화를 자동으로 기억하는 비밀

💡 Hook은 질문하면 자동 검색, 답변하면 자동 저장, 종료하면 자동 요약하는 Claude Code 이벤트 시스템입니다.

---

Hook이 뭔가요?

Hook은 LLM 이벤트에 자동 반응하는 쉘 스크립트입니다.

쉽게 말해:

• 사용자가 질문하면 → Hook이 먼저 실행됨
• AI가 답변하면 → Hook이 자동 저장함
• 세션 끝나면 → Hook이 요약함

사용자는 아무것도 안 해도 됩니다. 전부 자동입니다.

┌─────────────────────────────────────────────┐
│  사용자 질문 입력                               │
│       ↓                                     │
│  [UserPromptSubmit Hook] ← 라우팅 + 파이프라인  │
│       ↓                                     │
│  Claude/Gemini 응답 생성                      │
│       ↓                                     │
│  [Stop Hook]             ← 저장 + 검증 + 고도화 │
│       ↓                                     │
│  세션 종료 (exit)                             │
│       ↓                                     │
│  [SessionEnd Hook]       ← 세션 요약          │
└─────────────────────────────────────────────┘

---

3가지 Hook

Hook 트리거 역할

UserPromptSubmit	질문 입력	라우팅 + 파이프라인
Stop	응답 완료	저장 + 검증 + 고도화
SessionEnd	세션 종료	전체 대화 요약

---

1️⃣ UserPromptSubmit Hook

사용자가 질문을 입력하는 순간 실행됩니다.

실행 흐름

[1] 사용자 질문 받음
       ↓
[2] BrainAgent가 분석 (라우팅 결정)
       ├─ 규칙 기반 (80%) → $0, <10ms
       └─ LLM 기반 (20%) → Flash 호출
       ↓
[3] 파이프라인 실행 (RAG, Jira, Notion 등)
       ↓
[4] 결과를 Claude에게 전달
       ↓
[5] Claude가 답변 생성

라우팅 방식

규칙 기반 (80%): 키워드 매칭, 비용 $0, 10ms 이내

• "Jira" → jira 파이프라인
• "노션" → notion 파이프라인
• "코드 분석" → rag 파이프라인

LLM 기반 (20%): Gemini Flash 호출, 복잡한 의도 분석

• "지난주 했던 작업 알려줘" → 맥락 분석 필요

exec_type 5가지

exec_type 설명 파이프라인

direct	Claude 자체 지식	없음
tool	단일 도구 실행	단일
master	Master가 직접 처리	복수 가능
worker	Worker 병렬 실행	Worker별 할당
speckit	기획→구현 자동화	전체

---

📊 Status Line (상태 표시줄)

Hook 실행 결과를 한 줄로 요약해서 보여줍니다.

📊 [08:14·670db96] | claude/opus | work | 📚rag

각 부분의 의미

요소 설명 예시

시간·세션ID	현재 시각 + 세션 ID	08:14·670db96
LLM/모델	사용 중인 LLM	claude/opus
경로	작업 디렉토리	work
exec_type	실행 타입	📚rag

아이콘 의미

아이콘 의미

💬	direct (자체 지식)
📚	rag (지식 검색)
🔗	graph (관계 분석)
🎫	jira (이슈 조회)
📝	notion (문서 조회)
🎨	figma (디자인 분석)

이 한 줄만 봐도 지금 AI가 뭘 하고 있는지 알 수 있습니다.

---

📋 실행 로그

더 자세한 정보가 필요하면 실행 로그를 봅니다.

┌─ 라우팅 분석 ─────────────────────┐
│ 실행 타입  : master              │
│ 파이프라인 : rag                  │
│ 신뢰도     : 90%                 │
│ 이유       : 지식베이스 검색 필요    │
└────────────────────────────────┘

• 신뢰도: BrainAgent가 얼마나 확신하는지 (0~100%)
• 이유: 왜 이 경로를 선택했는지

---

2️⃣ Stop Hook

AI가 답변을 완료할 때마다 실행됩니다. 단순 저장만 하는 게 아니라, 자가 검증과 자가 고도화까지 자동으로 수행합니다.

하는 일 3가지

[1] 대화 저장
    transcript → chat_logs 테이블

[2] 자가 검증
    ├─ 라우팅 신뢰도 체크 (0.75 미만이면 경고)
    └─ 작업별 규칙 검증 (블로그/코드)

[3] 자가 고도화 (에러 감지 시)
    Tool Error/Traceback 발견 → 즉시 분석

1. 대화 저장

• 메시지 최대 10,000자 (초과 시 truncate)
• user, assistant 둘 다 있을 때만 저장

2. 자가 검증

매 응답마다 AI가 스스로 검증합니다.

라우팅 검증:

• BrainAgent 신뢰도가 0.75 미만이면 경고
• "라우팅이 불확실합니다" 알림

작업별 규칙 검증:

• 블로그: 구분선 1개, 표 3열, TL;DR 금지
• 코드: TODO/pass 금지, rm -rf/DROP 금지

위반 발견 시 즉시 경고 메시지가 표시됩니다.

3. 자가 고도화

Tool Error, Traceback, HTTP 4xx/5xx 에러가 발생하면 즉시 자동 분석합니다.

Tool Error 감지!
       ↓
failure_analyzer 실행 (패턴 분석)
       ↓
개선 제안 생성 (승인 후 적용)

더 이상 8일을 기다릴 필요 없습니다. 실패 발생 즉시 분석합니다.

저장 제한

• 메시지 최대 10,000자 (초과 시 truncate)
• user, assistant 둘 다 있을 때만 저장

---

3️⃣ SessionEnd Hook

세션이 정상 종료될 때 실행됩니다.

실행 조건

• reason = "exit" 일 때만 실행
• clear, logout 등은 스킵

하는 일

[1] 해당 세션의 모든 chat_logs 조회
       ↓
[2] Gemini Flash로 전체 대화 요약 생성
       ↓
[3] session_summary 테이블에 저장

Two-Tier 검색 전략

사용자: "지난주 뭐 했지?"
       ↓
[Tier 1] session_summary 검색 (요약본)
       → "지난주 GameLoungeK UI 작업, Jira PK-123 해결"
       ↓
[Tier 2] 필요시 chat_logs 상세 조회 (원본)
       → 전체 대화 내용

---

💾 데이터 보존 정책

데이터 보존 기간

chat_logs (원본)	30일
session_summary (요약)	30일

30일 후: chat_logs 삭제, session_summary만 유지

→ "3개월 전에 뭐 했지?" 도 요약본으로 검색 가능

---

📁 파일 위치

Claude Code:

• .claude/hooks/user-prompt-hook.sh
• .claude/hooks/save-conversation.sh
• .claude/hooks/session-end.sh

Gemini CLI:

• ~/.gemini/hooks/ (동일 구조)

원본 (Git 관리):

• knowledge_base/providers/claude/hooks/*.sh
• knowledge_base/providers/gemini/hooks/*.sh

---

핵심 포인트

1. 완전 자동: 사용자가 신경 쓸 거 없음
2. 비용 효율: 라우팅 80%는 $0
3. 데이터 보존: 30일 후 요약만 유지
4. 자가 검증: 규칙 위반 즉시 감지
5. 자가 고도화: 실패 즉시 분석

💡 사용자는 질문만 하면 됩니다. 나머지는 Hook이 알아서 합니다.

상세 기술 문서: knowledge_pillars/04-hook.md