📌 참고: 이 문서는 awesome Claude Code 문서의 원문 + 레퍼런스입니다.

• 원문 링크를 방문하셔서 복사해서 사용하셔도 됩니다
• 이 파일을 .claude/skills/ 하위에 복사하여 스킬로 등록할 수도 있습니다

(26.03.15 기준)

훅 생성 커맨드

프로젝트를 분석하고, 실용적인 훅을 제안하며, 적절한 테스트와 함께 생성합니다.

작업 내용 (/create-hook)

1. 환경 분석 - 도구 및 기존 훅 감지
2. 훅 제안 - 프로젝트 설정을 기반으로 제안
3. 훅 구성 - 맞춤 질문을 하고 스크립트 생성
4. 테스트 및 검증 - 훅이 올바르게 작동하는지 확인

워크플로우

1. 환경 분석 및 제안

프로젝트 도구를 자동으로 감지하고 관련 훅을 제안합니다:

TypeScript가 감지된 경우 (tsconfig.json):

• PostToolUse 훅: "편집 후 파일 타입 체크"
• PreToolUse 훅: "타입 에러가 있는 편집 차단"

Prettier가 감지된 경우 (.prettierrc, prettier.config.js):

• PostToolUse 훅: "편집 후 자동 포맷팅"
• PreToolUse 훅: "포맷팅된 코드 필수화"

ESLint가 감지된 경우 (.eslintrc.*):

• PostToolUse 훅: "편집 후 린트 및 자동 수정"
• PreToolUse 훅: "린팅 에러가 있는 커밋 차단"

package.json에 스크립트가 있는 경우:

• test 스크립트 → "커밋 전 테스트 실행"
• build 스크립트 → "커밋 전 빌드 검증"

git 저장소가 감지된 경우:

• PreToolUse/Bash 훅: "비밀 정보가 포함된 커밋 방지"
• PostToolUse 훅: "파일 변경 시 보안 스캔"

결정 트리:

프로젝트에 TypeScript가 있는가? → 타입 체크 훅 제안
프로젝트에 포맷터가 있는가? → 포맷팅 훅 제안
프로젝트에 테스트가 있는가? → 테스트 검증 훅 제안
보안에 민감한가? → 보안 훅 제안
+ 추가 패턴을 스캔하고 다음을 기반으로 커스텀 훅 제안:
  - package.json의 커스텀 스크립트
  - 고유한 파일 패턴 또는 확장자
  - 개발 워크플로우 지표
  - 프로젝트별 도구 설정

2. 훅 구성

먼저 다음을 질문합니다: "이 훅이 무엇을 해야 하나요?" 그리고 분석에서 도출된 관련 제안을 제시합니다.

그런 다음 사용자의 설명에서 맥락을 파악하고 확신이 없는 세부 사항에 대해서만 질문합니다:

1. 트리거 타이밍: 언제 실행되어야 하나요?

   • PreToolUse: 파일 작업 전 (차단 가능)
   • PostToolUse: 파일 작업 후 (피드백/수정)
   • UserPromptSubmit: 요청 처리 전
   • 필요에 따른 기타 이벤트 유형

2. 도구 매처: 어떤 도구가 트리거해야 하나요? (Write, Edit, Bash, * 등)

3. 범위: global, project, 또는 project-local

4. 응답 방식:

   • 종료 코드만: 간단 (exit 0 = 성공, exit 2 = PreToolUse에서 차단)
   • JSON 응답: 고급 제어 (차단, 컨텍스트, 결정)
   • 복잡도에 따라 안내: 단순 통과/실패 → 종료 코드, 풍부한 피드백 → JSON

5. 차단 동작 (관련된 경우): "문제가 발견되면 작업을 중단해야 하나요?"

   • PreToolUse: 작업 차단 가능 (보안, 검증)
   • PostToolUse: 보통 피드백만 제공

6. Claude 통합 (중요): "Claude Code가 이 훅이 감지한 문제를 자동으로 확인하고 수정해야 하나요?"

   • 예인 경우: 에러 전달을 위해 additionalContext 사용
   • 아니오인 경우: 무음 작동을 위해 suppressOutput: true 사용

7. 컨텍스트 오염: "성공적인 작업이 노이즈를 피하기 위해 무음이어야 하나요?"

   • 포맷팅, 일상적인 검사에는 예를 권장
   • 보안 알림, 중요 에러에는 아니오를 권장

8. 파일 필터링: "이 훅이 어떤 파일 유형을 처리해야 하나요?"

3. 훅 생성

다음을 수행해야 합니다:

• 훅 디렉토리 생성: 범위에 따라 ~/.claude/hooks/ 또는 .claude/hooks/
• 스크립트 생성: 다음을 포함하는 훅 스크립트 생성:
  • 적절한 shebang과 실행 권한
  • 프로젝트별 명령어 (감지된 설정 경로 사용)
  • 훅의 목적을 설명하는 주석
• 설정 업데이트: 적절한 settings.json에 훅 설정 추가
• 절대 경로 사용: 스크립트와 실행 파일에 상대 경로 사용 금지. 프로젝트 루트를 참조하려면 $CLAUDE_PROJECT_DIR 사용
• 검증 제안: 사용자에게 훅 테스트를 원하는지 질문

주요 구현 표준:

• stdin에서 JSON 읽기 (argv 사용 금지)
• Claude 통신을 위해 최상위 additionalContext/systemMessage 사용
• 성공적인 작업에 suppressOutput: true 포함
• 구체적인 에러 수와 실행 가능한 피드백 제공
• 전체 코드베이스가 아닌 변경된 파일에 집중
• 일반적인 개발 워크플로우 지원

주의: 입출력 형식

대부분의 훅 구현이 실패하는 부분입니다. 다음에 특히 주의하세요:

• 입력: stdin에서 JSON을 올바르게 읽기 (argv가 아님)
• 출력: Claude 통신을 위한 올바른 최상위 JSON 구조 사용
• 문서: 정확한 스키마가 의심될 때 공식 문서 참조

4. 테스트 및 검증

중요: 성공 경로와 실패 경로 모두 테스트하세요:

성공 경로 테스트:

1. 예상 성공 시나리오 테스트 - 훅이 통과해야 하는 조건 생성
   • 예시: TypeScript (유효한 코드), 린팅 (포맷된 코드), 보안 (안전한 명령)

실패 경로 테스트: 2. 예상 실패 시나리오 테스트 - 훅이 실패/경고해야 하는 조건 생성

• 예시: TypeScript (타입 에러), 린팅 (포맷되지 않은 코드), 보안 (위험한 작업)

검증 단계: 3. 예상 동작 확인: 의도한 대로 차단/경고/컨텍스트를 제공하는지 확인

테스트 프로세스 예시:

• 파일 삭제를 방지하는 훅의 경우: 테스트 파일을 생성하고, 보호된 작업을 시도하며, 훅이 이를 방지하는지 확인

문제가 발생하면 다음을 수행해야 합니다:

• 설정에서 훅 등록 확인
• 스크립트 권한 확인 (chmod +x)
• 단순화된 버전으로 먼저 테스트
• 상세한 훅 실행 분석으로 디버그

훅 템플릿

타입 체크 (PostToolUse)

#!/usr/bin/env node
// stdin JSON 읽기, .ts/.tsx 파일만 확인
// 실행: npx tsc --noEmit --pretty
// 출력: 에러에 대한 additionalContext가 포함된 JSON

자동 포맷팅 (PostToolUse)

#!/usr/bin/env node
// stdin JSON 읽기, 지원되는 파일 유형 확인
// 실행: npx prettier --write [file]
// 출력: suppressOutput: true가 포함된 JSON

보안 스캔 (PreToolUse)

#!/bin/bash
# stdin JSON 읽기, 비밀 정보/키 확인
# 위험한 패턴이 발견되면 차단
# 차단하려면 Exit 2, 계속하려면 0

전체 템플릿 제공 위치: https://docs.claude.com/en/docs/claude-code/hooks#examples

빠른 참조

공식 문서: https://docs.claude.com/en/docs/claude-code/hooks.md

일반적인 패턴:

• stdin 입력: JSON.parse(process.stdin.read())
• 파일 필터링: 처리 전 확장자 확인
• 성공 응답: {continue: true, suppressOutput: true}
• 에러 응답: {continue: true, additionalContext: "error details"}
• 작업 차단: PreToolUse 훅에서 exit(2)

사용 사례별 훅 유형:

• 코드 품질: 피드백과 수정을 위한 PostToolUse
• 보안: 위험한 작업을 차단하는 PreToolUse
• CI/CD: 커밋 전 검증을 위한 PreToolUse
• 개발: 자동화된 개선을 위한 PostToolUse

훅 실행 모범 사례:

• 훅은 병렬로 실행됩니다 (공식 문서 기준)
• 독립적으로 설계하세요 (실행 순서가 보장되지 않으므로)
• 여러 훅이 같은 파일에 영향을 미칠 때 훅 상호작용을 신중하게 계획하세요

성공 기준

훅이 성공적으로 생성된 경우:

• 스크립트에 실행 권한이 있음
• 올바른 settings.json에 등록됨
• 테스트 시나리오에 올바르게 응답함
• 자동 수정을 위해 Claude와 적절히 통합됨
• 프로젝트 규칙과 감지된 도구를 따름

결과: 사용자는 지능형 자동화와 품질 검사를 통해 개발 워크플로우를 향상시키는 작동하는 훅을 얻게 됩니다.