Claude Code 커뮤니티 Hook/거버넌스 프로젝트 비교 분석
### 확인 범위
research docs/research/2026-04-06-community-hooks-analysis.md
작성일: 2026-04-06 관련 문서: Anthropic 공식 vs ai-rules 비교는 2026-04-06-claude-code-vs-ai-rules-analysis.md 참조
0. 분석 방법 및 한계
확인 범위
| 레포 | 저자 | 로컬 경로 | 확인 범위 |
|---|---|---|---|
| karanb192/claude-code-hooks | karanb192 | D:\dev-reference\claude-code-hooks |
hook-scripts/ 4개 hook + 1개 유틸리티, tests/ 262개 테스트, README, CONTRIBUTING |
| johnlindquist/claude-hooks | johnlindquist | D:\dev-reference\claude-hooks |
src/, templates/hooks/ (lib.ts 526줄, index.ts 182줄, session.ts), test/, README, CLAUDE.md, CONTRIBUTING |
| disler/claude-code-hooks-mastery | disler | D:\dev-reference\claude-code-hooks-mastery |
.claude/hooks/ 13개 hook, .claude/agents/, .claude/commands/, README 930줄, ai_docs/ |
| garrytan/gstack | garrytan (YC) | D:\dev-reference\gstack |
careful/, freeze/, guard/, cso/, bin/, test/, README, CLAUDE.md, ARCHITECTURE.md, ETHOS.md |
| hesreallyhim/awesome-claude-code | hesreallyhim | D:\dev-reference\awesome-claude-code |
README 전체 (202개 리소스, 9개 카테고리), CONTRIBUTING, 훅 관련 14개 항목 |
주의
- 각 레포의 소스 코드를 직접 확인한 결과이며, 실제 런타임 동작은 검증하지 않음
- "발견되지 않음"은 확인 범위 기준이며, 비공개 브랜치나 미병합 PR은 포함하지 않음
- awesome-claude-code는 큐레이션 목록이므로 직접 구현체가 아닌 메타 분석 대상
1. 프로젝트 개요
| 항목 | karanb192 | johnlindquist | disler | garrytan (gstack) | awesome-claude-code |
|---|---|---|---|---|---|
| 성격 | Hook 구현 키트 | TypeScript hook 프레임워크 | Hook 마스터 가이드 | 스킬 기반 거버넌스 도구 | 큐레이션 목록 |
| 언어 | JavaScript (Node.js) | TypeScript (Bun) | Python (UV single-file) | Bash + TypeScript | Markdown |
| 라이선스 | MIT | MIT | MIT | 비공개 (상용) | 비공개 |
| Hook 수 | 4개 | 8개 (템플릿) | 13개 | 2개 (careful + freeze) | 14개 (목록) |
| 테스트 | 262개 | Mocha + Chai (coverage 80%+) | 확인 범위에서 미발견 | 100+ (bun test) | 해당 없음 |
| 핵심 가치 | 패턴 커버리지 + 테스트 | 타입 안전성 + DX | 전체 라이프사이클 커버 | 운영 철학 + 스킬 시스템 | 생태계 지도 |
2. 프로젝트별 상세 분석
2.1 karanb192/claude-code-hooks
포지셔닝: 실전 검증된 패턴 매칭 hook 키트
Hook 구현:
| Hook | 이벤트 | 기능 |
|---|---|---|
block-dangerous-commands.js |
PreToolUse (Bash) | 58개 위험 명령 패턴 차단 |
protect-secrets.js |
PreToolUse (Read/Edit/Write/Bash) | 67개 시크릿 패턴 보호 |
auto-stage.js |
PostToolUse (Edit/Write) | 수정 파일 자동 git add |
notify-permission.js |
Notification | Slack webhook 알림 |
3단계 Safety Level:
critical— 치명적만 (9패턴, rm -rf /, fork bomb 등)high— + 위험 (19패턴, force push main, git reset --hard 등) 기본값strict— + 주의 (22패턴, 모든 force push, docker prune 등)
강점:
- 125개 정규식 패턴 + 262개 테스트 — 오탐/미탐 검증이 자동화됨
- JSONL 로깅 (
~/.claude/hooks-logs/YYYY-MM-DD.jsonl) — jq 쿼리 가능 - Allowlist 패턴 (
.env.example,.env.sample등 안전 파일 허용) - JSON 프로토콜 (
permissionDecision: "deny") — exit code보다 표현력 높음
한계: 정책 프레임워크 없음 (왜 차단하는가의 체계 없음), DB 특화 규칙 없음, 단일 도구 대상
2.2 johnlindquist/claude-hooks
포지셔닝: TypeScript 타입 안전성 기반 hook 프레임워크
아키텍처: npx claude-hooks로 원커맨드 설치. Bun 런타임 필수. .claude/hooks/ 디렉토리에 TypeScript 파일 생성.
8개 Hook 타입 (전체 라이프사이클 커버):
| Hook | 특징 |
|---|---|
| SessionStart | 세션 시작 시 초기화 (source: vscode/web 감지) |
| PreToolUse | 도구 실행 전 차단 (allow/deny/ask) |
| PostToolUse | 도구 실행 후 반응 |
| UserPromptSubmit | 사용자 프롬프트 가로채기 (updatedPrompt, contextFiles 자동 추가) |
| PreCompact | 컨텍스트 압축 전 제어 |
| Stop | 세션 종료 제어 (차단 가능) |
| SubagentStop | 서브에이전트 완료 제어 |
| Notification | 알림 수신 |
강점:
- 완전한 TypeScript 타입 정의 — 모든 payload/response에 IntelliSense 지원
- Transcript 분석 유틸리티 —
getConversationHistory(),getToolUsage(),getAllMessages() - 세션 데이터 영속화 —
<tmpdir>/claude-hooks-sessions/{session_id}.json에 이벤트 축적 - UserPromptSubmit의
updatedPrompt+contextFiles— 프롬프트 수정 + 자동 컨텍스트 파일 주입 - Semantic Release + CI/CD (GitHub Actions, 멀티 플랫폼)
한계: Bun 런타임 의존 (Node.js만으로 실행 불가), 패턴 매칭 구현은 사용자 몫 (프레임워크만 제공)
2.3 disler/claude-code-hooks-mastery
포지셔닝: 13개 hook 전체 구현 + 에이전트/커맨드/TTS 통합 마스터 가이드
13개 Hook (Claude Code가 지원하는 모든 이벤트):
| Hook | 고유 기능 |
|---|---|
| SessionStart | git status + GitHub issues 로딩, 컨텍스트 파일 자동 주입 |
| PreToolUse | 위험 rm 패턴 + .env 접근 차단 |
| PostToolUse | JSONL 트랜스크립트 변환, 결과 검증 |
| PostToolUseFailure | 실패 로깅 (타임스탬프 포함) |
| Stop | AI 생성 완료 메시지 + TTS 음성 안내 |
| PermissionRequest | 읽기 전용 작업 자동 허용 (17개 안전 패턴) |
| SubagentStart/Stop | 서브에이전트 시작/완료 로깅 + TTS |
| PreCompact | 트랜스크립트 백업 |
| SessionEnd | 정리 + 선택적 태스크 실행 |
| Setup | 환경 영속화, 의존성 설치 |
| Notification | 로깅 + TTS 알림 |
UV Single-File Scripts: 각 hook이 자체 의존성을 인라인으로 선언하는 독립 Python 파일. 가상환경 관리 불필요.
고유 기능:
- TTS 다중 프로바이더 — ElevenLabs > OpenAI > pyttsx3 우선순위 폴백
- LLM 다중 프로바이더 — OpenAI > Anthropic > Ollama 우선순위 폴백
- 코드 품질 검증기 — PostToolUse에서 ruff + ty 자동 실행, 실패 시 차단
- 팀 기반 검증 — builder agent (구현) + validator agent (검증) 분리
- Meta-Agent — "에이전트를 생성하는 에이전트" 패턴
- 자기 검증 커맨드 —
/plan_w_team이 Stop hook으로 자체 출력 검증 - 9개 Status Line 버전 — 컨텍스트 윈도우 시각화, 비용 추적, 토큰 통계
한계: 복잡도가 높음 (13 hook + TTS + LLM + agents), 확인 범위에서 자동화된 테스트 미발견
2.4 garrytan/gstack
포지셔닝: YC 출신 창업자의 운영 철학 기반 스킬 시스템
아키텍처: 34개 스킬(/qa, /ship, /review, /cso 등) + PreToolUse hook 2개 + 설정 시스템
Hook 구현 (2개, 역할 분리 명확):
| Hook | 결정 타입 | 기능 |
|---|---|---|
/careful (check-careful.sh) |
ask (경고, 사용자 override 가능) |
위험 명령 감지 (rm -rf, DROP TABLE, force push, kubectl delete 등) + 안전 예외 (node_modules, dist 등) |
/freeze (check-freeze.sh) |
deny (하드 차단) |
지정 디렉토리 외 Edit/Write 차단. ~/.gstack/freeze-dir.txt로 경계 설정 |
운영 철학 (ETHOS.md):
- Boil the Lake — 한계비용이 0에 가까우면 완결하라
- Search Before Building — 3계층 탐색 (기존 해법 → 새로운 인기 해법 → 첫 원칙)
- User Sovereignty — AI가 추천, 사용자가 결정. 멀티 AI 합의도 사용자 확인 없이 자동 실행 금지
고유 기능:
/cso(Chief Security Officer) — OWASP Top 10 + STRIDE + 시크릿 탐사 + 의존성 공급망 + CI/CD 보안 + LLM 보안 감사- Learnings 시스템 — 프로젝트별
~/.gstack/projects/{slug}/learnings.jsonl에 운영 교훈 축적, 다음 세션에 자동 표면화 - Freeze/Unfreeze — 디렉토리 단위 편집 경계 (production 작업 시 안전 영역 설정)
- Skill Routing — CLAUDE.md에
## Skill routing섹션 추가로 사용자 의도 → 스킬 자동 매핑 - 100+ hook 테스트 — careful/freeze 패턴의 edge case, 안전 예외, 멀티라인 JSON 처리
한계: 상용 제품 (MIT가 아님), gstack 생태계 내에서만 작동, 범용 hook 프레임워크가 아님
2.5 hesreallyhim/awesome-claude-code
포지셔닝: Claude Code 생태계 전체 지도 (큐레이션 목록)
규모: 202개 리소스, 9개 카테고리
Hook 관련 14개 항목 (확인 범위에서 주목할 만한 것):
| 프로젝트 | 고유 기능 |
|---|---|
| Dippy | AST 기반 파싱으로 위험 명령 탐지 (정규식보다 정확) |
| parry | 프롬프트 인젝션 공격 + 데이터 유출 탐지 |
| TDD Guard | TDD 원칙 위반 시 코드 변경 차단 |
| HCOM | hook 기반 에이전트 간 통신 프로토콜 |
| Trail of Bits Security Skills | 12+ 전문 보안 감사 스킬 (CodeQL, Semgrep) |
거버넌스 관련 관찰:
- agnix — CLAUDE.md, AGENTS.md, SKILL.md, hooks, MCP 설정의 린터
- Ralph Wiggum Pattern — 자율 루프 개발 + circuit breaker + rate limiting 안전 장치
- Agent Teams: Exercises — 팀 생성, 태스크 조정, 품질 hook, 병렬 코드 리뷰 실습 6개 + 캡스톤 2개
3. 횡단 비교
3.1 Hook 이벤트 커버리지
| 이벤트 | karanb192 | johnlindquist | disler | gstack |
|---|---|---|---|---|
| SessionStart | - | O | O | - |
| SessionEnd | - | - | O | - |
| UserPromptSubmit | - | O | O | - |
| PreToolUse | O | O | O | O |
| PostToolUse | O | O | O | - |
| PostToolUseFailure | - | - | O | - |
| Stop | - | O | O | - |
| SubagentStart | - | - | O | - |
| SubagentStop | - | O | O | - |
| PreCompact | - | O | O | - |
| Notification | O | O | O | - |
| PermissionRequest | - | - | O | - |
| Setup | - | - | O | - |
| 합계 | 3 | 8 | 13 | 1 |
3.2 설계 철학 비교
| 차원 | karanb192 | johnlindquist | disler | gstack |
|---|---|---|---|---|
| 접근법 | 패턴 매칭 (무엇을 차단) | 타입 시스템 (어떻게 안전하게 작성) | 전체 커버 (모든 이벤트에 구현) | 운영 철학 (왜 차단하는가) |
| 사용자 | 즉시 복사해서 사용 | 프레임워크 위에 직접 구현 | 학습 + 참고 + 복사 | gstack 사용자 |
| 안전 모델 | 3단계 severity | allow/deny/ask 응답 | exit code 2 차단 + JSON | ask (경고) vs deny (하드 차단) |
| 확장성 | 패턴 추가 | 핸들러 추가 | 스크립트 추가 | 스킬 추가 |
3.3 ai-rules와의 교차점
| ai-rules 기능 | karanb192 대응 | johnlindquist 대응 | disler 대응 | gstack 대응 |
|---|---|---|---|---|
| R0/R1/R2 가역성 | Safety Level (유사하지만 가역성 기준은 아님) | 확인 범위에서 없음 | 확인 범위에서 없음 | careful=ask(R1급) vs freeze=deny(R2급) |
| MUST-HOOK/SHOULD-HOOK | 확인 범위에서 없음 | 확인 범위에서 없음 | 확인 범위에서 없음 | 확인 범위에서 없음 |
| 세션 핸드오프 | 확인 범위에서 없음 | Session 영속화 (유사) | Session 로깅 (유사) | Learnings 시스템 (유사) |
| DB 안전 규칙 | 확인 범위에서 없음 | 확인 범위에서 없음 | 확인 범위에서 없음 | DROP TABLE/TRUNCATE 감지 |
| 멀티 도구 배포 | 확인 범위에서 없음 | 확인 범위에서 없음 | 확인 범위에서 없음 | 확인 범위에서 없음 |
| 규칙 충돌 해결 | 확인 범위에서 없음 | 확인 범위에서 없음 | 확인 범위에서 없음 | ETHOS.md (User Sovereignty) |
4. ai-rules에 채택할 만한 것
즉시 도입 가능 (ai-rules 자체 변경으로 완결)
| 우선순위 | 원천 | 항목 | 구체적 작업 |
|---|---|---|---|
| P1 | karanb192 | 패턴 커버리지 확대 | 125개 패턴 중 시크릿 유출(41개) + 크리덴셜 파일(24개)을 guard-secrets.sh에 포팅. MIT 라이선스로 즉시 활용 가능 |
| P2 | karanb192 | 3단계 Safety Level | governance/presets/에 safety level 매핑: solo=critical, small-team=high, saas=strict |
| P3 | karanb192 | Hook 테스트 인프라 | shouldBlock/shouldAllow 패턴으로 최소 50개 테스트. bats 또는 Node.js 테스트 러너 |
| P4 | karanb192 + disler | JSONL 로깅 | 모든 hook에 ~/.claude/hooks-logs/YYYY-MM-DD.jsonl 구조화 로깅 추가 |
| P5 | johnlindquist | JSON 프로토콜 전환 | exit code → JSON stdout (permissionDecision: "deny") 마이그레이션. deny 사유 + 대안 제안 가능 |
플랫폼/도구 지원 전제
| 우선순위 | 원천 | 항목 | 전제 조건 |
|---|---|---|---|
| P6 | johnlindquist | UserPromptSubmit hook | contextFiles 자동 주입으로 세션 시작 시 INTENT.md/SESSION.md 자동 로딩. Bun 불필요 — bash/node로 재구현 가능하나 updatedPrompt + contextFiles 응답 필드는 Claude Code 런타임 지원 확인 필요 |
| P7 | gstack | Freeze/Unfreeze 패턴 | 디렉토리 단위 편집 경계 설정. governance/templates/hooks/guard-freeze.sh로 구현 가능하나 ~/.gstack/freeze-dir.txt 같은 상태 파일 관리 방법 결정 필요 |
| P8 | gstack | Learnings 시스템 | 프로젝트별 운영 교훈 축적 + 자동 표면화. ai-rules의 FAILURE_LOG.md와 유사하지만 JSONL 기반 자동화가 차별점. 세션 hook 아키텍처 확장 필요 |
| P9 | disler | 코드 품질 검증기 | PostToolUse에서 ruff/tsc 자동 실행 + 실패 시 차단. ai-rules의 lint-staged는 커밋 시점이지만 이건 파일 수정 시점 — 더 빠른 피드백 |
5. 종합 평가
| 평가 축 | karanb192 | johnlindquist | disler | gstack | ai-rules |
|---|---|---|---|---|---|
| 패턴 커버리지 | 125개 + 테스트 | 프레임워크만 | 위험 rm + .env | rm + DROP + force push | 패턴 수 미공개 |
| 타입 안전성 | JS (타입 없음) | TS 완전 타입 | Python | Bash | Bash |
| 이벤트 커버리지 | 3개 | 8개 | 13개 (전체) | 1개 | 2개 |
| 테스트 | 262개 | CI/CD 80%+ | 미확인 | 100+ | 미확인 |
| 로깅 | JSONL | 세션 JSON | JSON 배열 | 미확인 | 미확인 |
| 정책 프레임워크 | 없음 | 없음 | 없음 | ETHOS.md | R0/R1/R2 + 충돌 해결 |
| 멀티 도구 | 없음 | 없음 | 없음 | 없음 | 7개 도구 |
| 세션 연속성 | 없음 | 세션 영속화 | 세션 로깅 | Learnings | HANDOFF 프로토콜 |
| 설치 편의성 | 수동 복사 | npx claude-hooks |
수동 복사 | npx gstack |
npm run sync |
| 고유 가치 | 패턴 깊이 | DX + 타입 | 전체 커버 + TTS | 운영 철학 | 정책 체계 + 멀티 도구 |
6. 결론
커뮤니티 프로젝트들은 각각 다른 축에서 강점을 가진다:
karanb192 = 패턴 매칭의 깊이 (125개 + 262개 테스트)
johnlindquist = 개발자 경험 (TypeScript + 원커맨드 설치)
disler = 라이프사이클 커버리지 (13개 이벤트 전체 구현)
gstack = 운영 철학 + 스킬 시스템 (Boil the Lake, User Sovereignty)
ai-rules와의 관계:
- 경쟁하지 않는 영역: 멀티 도구 동기화, 프로젝트 프로파일, R0/R1/R2 가역성, 규칙 충돌 해결 — 커뮤니티 프로젝트에서 확인 범위 내 대응하는 기능 미발견
- 보완 가능한 영역: 패턴 커버리지(karanb192), JSON 프로토콜(johnlindquist), JSONL 로깅(karanb192+disler), Safety Level(karanb192), Freeze 패턴(gstack)
- 영감을 줄 수 있는 영역: UserPromptSubmit의 contextFiles 주입(johnlindquist), Learnings 시스템(gstack), 코드 품질 검증기(disler)
가장 즉시 ROI가 높은 채택은 karanb192의 패턴 + 테스트 (MIT, bash 변환 가능)와 JSON 프로토콜 전환 (Claude Code가 이미 지원)이다.