# repo 훅 Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.claude/settings.json`, 본체는 `hooks.py` 하나, 시험은 `scripts/tests/test_hooks.py`다. 모델이 잊어도 돈다. ```text Edit·Write 직전 ──> pre-edit ──> H13 적용된 migration이면 막는다(종료 코드 2) Edit·Write 직후 ──> post-edit ──> Java면 포맷 → N1 레이어 의존 알림, 문서면 N2 문서 검사 알림 Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 N5 기록을 비운다 턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 한 번 알린다 ``` ## 1. 원칙 - 되돌릴 수 없는 것만 막는다. 나머지는 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다. - 훅은 게이트의 일부만 본다. 정본은 게이트(desktop `architectureCheck`, `spotlessCheck`, 문서 검사)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다. - 노트북에서 Gradle·Docker를 돌리지 않는다. 포매터는 Gradle 없이 JVM 하나로 파일 하나만 맞춘다(소유자 결정 2026-11-07). - 받거나 설치하지 않는다. 포매터 jar는 Gradle이 이미 캐시에 받아 둔 것만 쓴다. 없으면 건너뛰고 세션에 한 번 알린다. - 표준 라이브러리만 쓴다. 되돌릴 수 없는 명령 차단(force push, 범위 밖 `rm -rf`, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 몫이다. ## 2. 훅마다 | ID | 때 | 하는 일 | 결과 | | --- | --- | --- | --- | | H13 | PreToolUse `Edit\|Write\|MultiEdit` | `src/**/src/main/resources/db/migration/<키>`의 `<키>`가 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 있으면 막는다 | 종료 코드 2와 「새 버전 파일을 더한다」 안내 | | 포맷 | PostToolUse `Edit\|Write\|MultiEdit` | `src/**/*.java`(build-logic과 `build/` 제외)를 google-java-format으로 맞춘다. 버전은 카탈로그 `googleJavaFormat`, jar는 Gradle 캐시, 옵션은 Spotless 단계와 같게 `--skip-reflowing-long-strings --replace` | 파일이 바뀌면 「다시 읽는다」 한 줄. 문법 오류면 첫 줄들 | | N1 | 같은 때, `src/**/src/main/java/**/*.java` | registry로 그 파일의 leaf를 찾고 import를 본다: 순수성 목록(`DomainPurityArchitectureTest`, `verifyApplicationCoreDependencyPurity`와 같은 패키지), inbound의 persistence 접근, `dev.caskeleton.*`의 주인 leaf가 registry `allowed_dependencies`(전이 포함)에 있는지 | 「HARD-STOP N 의심」 줄 | | N2 | 같은 때, `*.md` | `scripts/check-work-docs.py`와 `scripts/check-docs.py`를 돌린다 | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 | | N5 | Stop | 이 세션에서 Java를 고친 뒤 `ssh … gradlew …` 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 Java 편집 전까지 한 번 | - N5가 기억하는 것은 `.claude/hook-state/.json`이다(git이 무시한다). - 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 막는다. `.env.example` 같은 예시는 막지 않는다. ## 3. 시험 ```bash python3 -m unittest discover -s scripts/tests ``` - 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다. - 실제 포매터 시험은 Gradle 캐시에 카탈로그 버전 jar가 있는 기계에서만 돈다. 그 밖에서는 가짜 `java`로 옵션·파일 전달·바뀜 감지를 본다. - 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다. ## 4. 끄기 훅이 시끄럽거나 틀리면 `.claude/settings.json`에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 `.claude/settings.local.json`(git이 무시한다)에 `"disableAllHooks": true`를 둔다.