Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code의 라이프사이클 후크를 사용하여 세션 시작, 도구 실행 전후 등의 이벤트를 자동화하는 방법을 설명합니다. 쉘 커맨드나 프롬프트를 삽입하여 워크플로우를 최적화하고 보안 가드레일을 구축할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code를 사용하기 시작하면, "매번 세션 시작 시에 같은 사전 작업을 하고 있다", "도구가 실행되기 전에 자동으로 체크를 넣고 싶다"라는 상황에 직면하게 된다. 그 니즈에 부응하는 것이 바로 **라이프사이클 후크 (Lifecycle Hooks)**다.
후크를 사용하면 Claude Code의 내부 이벤트(세션 시작·도구 실행 전후·컴팩트 전후 등)에 대해 쉘 커맨드(Shell Command)나 프롬프트 인젝션(Prompt Injection)을 삽입할 수 있다. CI의 후크나 Git 후크와 개념은 같지만, AI 에이전트의 워크플로우에 통합되어 있다는 점이 특징이다.
본 기사에서는 후크의 설정 방법, 이용 가능한 이벤트 종류, 실전 유스케이스를 차례대로 해설한다.
2025년 시점에서 이용 가능한 후크 이벤트는 다음과 같다.
| 이벤트 | 트리거 타이밍 |
|---|---|
SessionStart | Claude Code의 세션이 시작되었을 때 |
Stop | Claude Code가 사용자에 대한 응답을 정지할 때 |
PreCompact | 컨텍스트 압축 (/compact)이 실행되기 직전 |
PostCompact | 컨텍스트 압축이 완료된 직후 |
UserPromptSubmit | 사용자가 프롬프트를 전송했을 때 |
PreToolUse | 도구 (Bash, Read, Edit 등)가 실행되기 직전 |
PostToolUse | 도구 실행이 완료된 직후 |
각 후크는 type으로서 command (쉘 커맨드 실행) 또는 prompt (프롬프트 삽입)를 선택할 수 있다.
후크는 ~/.claude/settings.json (글로벌) 또는 프로젝트 직하의 .claude/settings.json (프로젝트 로컬)에 기술한다.
{
"hooks": {
"SessionStart": [
...
| 키 | 필수 | 설명 |
|---|---|---|
type | ✓ | command 또는 prompt |
command | type=command 시 | 실행할 쉘 커맨드 |
prompt | type=prompt 시 | Claude에게 삽입할 프롬프트 텍스트 |
timeout | — | 타임아웃 초 단위 (기본 30초) |
matcher | — | PreToolUse/PostToolUse에서 도구 이름을 필터링 |
PreToolUse와 PostToolUse에서는 matcher를 통해 후크를 필터링할 수 있다.
{
"matcher": "Bash"
}
matcher에 MCP 도구 이름도 지정할 수 있다.
{
"matcher": "mcp__some-mcp__some_tool"
}
matcher를 생략하면 모든 도구에 적용된다. 무거운 체크를 모든 도구에 적용하면 성능에 영향을 줄 수 있으므로 주의해야 한다.
command 후크의 종료 코드에는 의미가 있다.
| 종료 코드 | 동작 |
|---|---|
0 | 정상 계속 |
1 | 에러 로그 (계속 진행) |
2 | 차단 (도구 실행 또는 응답을 중지) |
종료 코드 2를 사용하면 "이 Bash 커맨드는 실행 금지"라는 안전장치를 만들 수 있다.
rm -rf, git push --force origin main, DROP TABLE 등을 검출하여 차단한다.
#!/bin/bash
# ~/.claude/hooks/bash-guard.sh
INPUT="$CLAUDE_TOOL_INPUT"
...
settings.json에 등록:
"PreToolUse": [
{
"matcher": "Bash",
...
CLAUDE_TOOL_INPUT
환경 변수에 도구로의 입력 내용이 JSON 문자열로서 전달된다. Bash 도구의 경우 명령 문자열이 여기에 들어간다.
매번 수동으로 "이 프로젝트는 ~"라고 설명하는 것은 비효율적이다. SessionStart 후크를 통해 필요한 파일을 자동으로 읽어오게 한다.
#!/bin/bash
# ~/.claude/hooks/session-start.sh
# 최근 프로젝트 상황을 표준 출력(stdout)으로 출력 → Claude의 컨텍스트에 주입됨
...
SessionStart 후크의 표준 출력(stdout)은 그대로 Claude의 시스템 프롬프트(System Prompt)에 주입된다. 이를 사용하면 일일 정보, 프로젝트 상태, 규칙 등을 매번 자동으로 삽입할 수 있다.
Stop 이벤트로 작업 종료 타이밍을 감지하여, 자동으로 git commit을 실행한다.
#!/bin/bash
# ~/.claude/hooks/stop-check.sh
# 변경 사항이 있으면 커밋
...
주의: Stop 후크는 응답이 완료될 때마다 실행된다. 빈도가 높을 경우 git diff --quiet 등을 사용하여 변경 사항이 없을 때는 스킵하도록 구현한다.
UserPromptSubmit은 사용자가 프롬프트를 전송하는 순간에 실행된다. 후크 측에서 특정 키워드를 감지하여 처리를 삽입할 수 있다.
#!/bin/bash
# ~/.claude/hooks/prompt-gate.sh
PROMPT="$CLAUDE_USER_PROMPT"
...
CLAUDE_USER_PROMPT 환경 변수에 사용자의 프롬프트 텍스트가 전달된다.
특정 도구가 호출되기 전에 Claude 스스로에게 확인 프롬프트를 삽입할 수 있다.
"PreToolUse": [
{
"matcher": "mcp__someservice__delete_resource",
...
type: prompt인 경우, command 대신 prompt 필드에 텍스트를 작성한다. Claude가 해당 텍스트를 받아 사용자에게 확인 다이얼로그(Dialog)로서 기능한다.
/compact로 컨텍스트가 압축되기 전에 중요한 정보를 파일에 기록해 둔다.
#!/bin/bash
# ~/.claude/hooks/pre-compact-save.sh
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
...
후크가 행(Hang) 상태에 빠지면 Claude Code 전체가 멈춘다. 무거운 처리는 비동기화하고, timeout으로 중단 설정을 한다.
{
"type": "command",
"command": "bash ~/.claude/hooks/my-hook.sh",
...
의도하지 않은 데이터가 컨텍스트에 섞이지 않도록, 로그는 >&2를 사용하여 stderr로 보낸다.
후크 실행 시 Claude Code로부터 전달되는 주요 환경 변수:
| 변수 | 내용 |
|---|---|
CLAUDE_TOOL_INPUT | 도구로의 입력 (JSON 문자열) |
CLAUDE_TOOL_NAME | 도구 이름 (PreToolUse/PostToolUse) |
CLAUDE_USER_PROMPT | 사용자 프롬프트 (UserPromptSubmit) |
CLAUDE_SESSION_ID | 세션 ID |
PreToolUse의 matcher
없이 무거운 처리를 작성하면, 모든 도구 호출 (Read, Grep, Glob, Edit 등) 시 매번 실행된다. 반드시 matcher를 사용하여 대상 도구를 좁혀야 한다.
Claude Code의 라이프사이클 후크 (Lifecycle Hooks)를 능숙하게 사용하면 다음과 같은 것들을 실현할 수 있다:
PreToolUse + exit 2로 차단SessionStart로 컨텍스트 자동 로드, Stop으로 자동 커밋type: prompt를 통해 AI가 자율적으로 확인 다이얼로그를 삽입PreCompact / PostCompact로 세션 상태를 영속화후크는 작은 쉘 스크립트 (Shell Script)로 시작할 수 있지만, 이를 쌓아 올리면 Claude Code의 동작을 대폭 커스터마이징할 수 있다. 우선 SessionStart를 통해 자주 사용하는 정보를 자동으로 로드하는 것부터 시도해 보자.
