Files
clean-architecture-backend-…/scripts/hooks
DongHyeonka 38891071d6 feat(hooks)!: 편집 직후 포맷·레이어·문서 알림과 migration 차단 훅을 건다
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).

scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
  종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
  버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
  쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
  --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
  파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
  build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
  (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
  같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
  턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).

버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).

위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.

검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.

BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
2026-11-07 22:06:50 +09:00
..

repo 훅

Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 .claude/settings.json, 본체는 hooks.py 하나, 시험은 scripts/tests/test_hooks.py다. 모델이 잊어도 돈다.

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 <desktop 호스트> … gradlew … 실행이 없으면 턴을 한 번 막고 이유를 준다 decision: block, 다음 Java 편집 전까지 한 번
  • N5가 기억하는 것은 .claude/hook-state/<session_id>.json이다(git이 무시한다).
  • 권한 쪽 차단: .claude/settings.json의 permissions.deny가 실제 .env·.env.local·.env.lane 읽기·쓰기를 막는다. .env.example 같은 예시는 막지 않는다.

3. 시험

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를 둔다.