Clip 3: Hooks, Output Styles 설계하기
학습 목표
Claude Code Hooks의 실제 작동 원리 이해
PreToolUse와 PostToolUse 훅 구현
Output Styles로 맞춤형 AI 응답 설정
Hooks 이해하기
🪝 Hooks란?
정의: Claude Code가 도구를 사용할 때 자동으로 실행되는 스크립트
목적: 도구 호출 제어, 결과 로깅, 워크플로우 자동화
타이밍: 9가지 Hook 이벤트 타입 제공
🔔 Hook 이벤트 타입
1. PreToolUse (도구 실행 전)
Claude가 도구 파라미터를 생성한 후, 실제 실행 전에 트리거
도구 호출을 차단하거나 피드백 제공 가능
매처:
Task,Bash,Glob,Grep,Read,Edit,Write,WebFetch
2. PostToolUse (도구 실행 후)
도구가 성공적으로 완료된 직후 실행
결과 로깅, 후처리 작업에 활용
PreToolUse와 동일한 매처 사용
3. Notification (알림 발생 시)
Claude Code가 알림을 보낼 때 트리거
알림 상황:
Claude가 도구 사용 권한을 요청할 때
프롬프트 입력이 60초 이상 유휴 상태일 때
4. UserPromptSubmit (프롬프트 제출 시)
사용자가 프롬프트를 제출할 때 실행
컨텍스트 추가, 프롬프트 검증, 특정 타입 차단 가능
5. Stop (에이전트 응답 완료)
메인 Claude Code 에이전트가 응답을 완료했을 때
사용자 중단으로 인한 정지 시에는 실행되지 않음
6. SubagentStop (서브에이전트 완료)
Claude Code 서브에이전트(Task 도구 호출)가 응답을 완료했을 때
7. PreCompact (컴팩트 작업 전)
Claude Code가 컴팩트 작업을 수행하기 전에 실행
매처:
manual:/compact명령어로 호출auto: 컨텍스트 윈도우가 가득 차서 자동 실행
8. SessionStart (세션 시작)
새 세션 시작 또는 기존 세션 재개 시 실행
매처:
startup,resume,clear,compact
9. SessionEnd (세션 종료)
Claude Code 세션이 종료될 때 실행
정리 작업, 로깅, 세션 상태 저장에 활용
💡 Hook 핵심 개념
Matcher: 특정 도구나 이벤트에만 훅 적용 (예:
Bash,mcp__*,manual)설정 위치: User(~/.claude/settings.json) 또는 Project(.claude/settings.json)
차단 기능: PreToolUse와 UserPromptSubmit은 작업을 차단하고 피드백 제공 가능
비동기 처리: 백그라운드 작업에는
&를 사용하지 말고 설정에서 비동기 옵션 활용
Hook 빠른 시작
📋 전제 조건
명령줄에서 JSON 처리를 위해 jq 설치:
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq🚀 실습 1: Bash 명령어 로깅 훅 만들기
1단계: 훅 구성 열기
# Claude Code REPL에서 실행
/hooksPreToolUse 훅 이벤트 선택
2단계: 매처 추가
+ Add new matcher…선택매처에
Bash입력 (Bash 도구 호출에만 훅 실행)
3단계: 훅 명령어 추가
+ Add new hook…선택다음 명령어 입력:
jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt4단계: 구성 저장
저장 위치: User settings 선택
Esc를 눌러 REPL로 복귀
5단계: 훅 확인
~/.claude/settings.json 파일 내용:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
}
]
}
]
}
}6단계: 훅 테스트
# Claude에게 요청
"ls 명령어를 실행해줘"
# 로그 확인
cat ~/.claude/bash-command-log.txt실전 Hook 예제
🚀 실습 2: YouTube 자막 자동 저장 PostToolUse 훅
이 예제는 YouTube 자막을 가져올 때마다 자동으로 파일로 저장하는 실제 동작하는 훅입니다.
훅 구조
.claude/
├── hooks/
│ └── youtube_transcript.sh # PostToolUse 훅 스크립트
└── settings.json # 훅 설정 파일
logs/
└── {video_title}.txt # 자동 생성되는 자막 파일1. 훅 스크립트 작성
.claude/hooks/youtube_transcript.sh:
#!/bin/bash
# YouTube 자막을 자동으로 파일로 저장하는 PostToolUse 훅
# Input: JSON via stdin (PostToolUse 형식)
# Output: logs/{sanitized_title}.txt
set -euo pipefail
readonly OUTPUT_DIR="logs"
# 파일명 안전하게 변환
sanitize_filename() {
local filename="$1"
# " - YouTube" 접미사 제거
filename="${filename% - YouTube}"
# 특수문자를 언더스코어로 변환
filename=$(echo "$filename" | sed 's/[^a-zA-Z0-9가-힣]/_/g')
# 연속된 언더스코어 제거
filename=$(echo "$filename" | sed 's/__*/_/g')
# 앞뒤 언더스코어 제거
filename=$(echo "$filename" | sed 's/^_//;s/_$//')
# 길이 제한 (100자)
filename=$(echo "$filename" | cut -c1-100)
echo "$filename"
}
main() {
local json_input response_data title transcript sanitized_title output_file
# stdin에서 JSON 읽기
json_input=$(cat)
# tool_response 데이터 추출
response_data=$(echo "$json_input" | jq -r '.tool_response[0].text // empty')
# 제목과 자막 파싱
title=$(echo "$response_data" | jq -r '.title // empty')
transcript=$(echo "$response_data" | jq -r '.transcript // empty')
# 자막이 존재하면 파일로 저장
if [[ -n "$transcript" ]]; then
if [[ -n "$title" ]]; then
sanitized_title=$(sanitize_filename "$title")
output_file="${OUTPUT_DIR}/${sanitized_title}.txt"
else
output_file="${OUTPUT_DIR}/youtube-transcript.txt"
fi
mkdir -p "$OUTPUT_DIR"
echo "$transcript" > "$output_file"
# 저장 완료 메시지 (선택사항)
echo "✅ Transcript saved: $output_file" >&2
fi
}
main2. 실행 권한 부여
chmod +x .claude/hooks/youtube_transcript.sh3. 훅 설정
.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "mcp__youtube-transcript__get_transcript",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/youtube_transcript.sh"
}
]
}
]
}
}4. 훅 테스트
# Claude Code에서 YouTube 자막 요청
"https://www.youtube.com/watch?v=dQw4w9WgXcQ 이 영상의 자막을 가져와줘"
# 자동으로 logs/ 디렉토리에 자막 파일이 생성됨
ls -la logs/
cat logs/Rick_Astley_Never_Gonna_Give_You_Up.txt아래 프로젝트를 참고해서 자신만의 Hook 을 만드세요
Output Styles 설계
🎨 Output Styles란?
정의: Claude Code의 시스템 프롬프트를 수정하여 응답 스타일 변경
목적: 소프트웨어 엔지니어링 외 용도로 Claude Code 적응
핵심 기능 유지: 파일 읽기/쓰기, 스크립트 실행, TODO 추적 등
📚 내장 Output Styles
1. Default (기본)
소프트웨어 엔지니어링 작업에 최적화
간결한 응답, 효율적인 코드 생성
테스트 코드로 검증
2. Explanatory (설명형)
코딩하면서 교육적 "인사이트" 제공
구현 선택과 코드베이스 패턴 설명
형식:
★ Insight ─────────────────────────────────────
[2-3 key educational points]
─────────────────────────────────────────────────3. Learning (학습형)
협력적 실습 학습 모드
Claude가 TODO(human) 마커 추가
직접 코드 작성 기회 제공
🔧 Output Style 작동 원리
Claude Code의 시스템 프롬프트를 직접 수정
기본 스타일 외에는 코드 생성 관련 지침 제외
사용자 정의 지침을 시스템 프롬프트에 추가
Output Styles 실습
🚀 실습 4: Output Style 변경하기
방법 1: 대화형 메뉴 사용
# Claude Code REPL에서 실행
/output-style메뉴에서 원하는 스타일 선택 (Default, Explanatory, Learning)
또는
/config메뉴에서도 접근 가능
방법 2: 직접 스타일 지정
# Explanatory 스타일로 전환
/output-style explanatory
# Learning 스타일로 전환
/output-style learning
# Default 스타일로 전환
/output-style default설정 저장 위치: .claude/settings.local.json (프로젝트 수준)
🎨 실습 5: 사용자 정의 Output Style 만들기
Claude의 도움을 받아 새로운 Output Style 생성:
/output-style:new 다음과 같은 출력 스타일을 원합니다:
- 모든 응답을 마크다운으로 작성
- 코드 블록에는 항상 주석 추가
- 각 응답 끝에 관련 문서 링크 제공
- 전문적이고 간결한 톤 유지Output Style 파일 구조
사용자 정의 스타일은 마크다운 파일로 저장:
~/.claude/output-styles/
├── professional.md
├── tutorial.md
├── code-reviewer.md
└── research-assistant.md커스텀 스타일 예제
~/.claude/output-styles/deep-research.md:
@.claude/output-styles/deep-research.md참고:
강사 정보
작성자: 정구봉
LinkedIn: https://www.linkedin.com/in/gb-jeong/
이메일: bong@dio.so
강의 자료
강의 자료: https://goobong.gitbook.io/fastcampus
Github: https://github.com/Koomook/fastcampus-ai-agent-vibecoding
FastCampus 강의 주소: https://fastcampus.co.kr/biz_online_vibeagent
Last updated