pr / done (pull_request) Successful in 3m35s
N5는 명령 안 어디에 있든 `verify.sh <단계>`를 실행으로 셌다. 그래서
`echo scripts/verify.sh pr`, `bash -n scripts/verify.sh pr`도 desktop
실행이 됐다. here-document는 명령 안 아무 낱말이나 bash·sh·zsh면
스크립트로 읽었고(`grep -c bash <<EOF`), `<<\EOF`·`<<'END NOTE'`
구분자는 못 알아 본문을 명령으로 읽었다. `ssh … gradlew`는 옛 검사
그대로 명령 글 전체에서 낱말을 찾아, 커밋 메시지 본문이나 주석의
`ssh desktop ./gradlew`도 셌다. registry에 없는 leaf 대상, 미추적
파일로 보내기를 거절한 실행(rc 5)처럼 Gradle 전에 멈춘 verify.sh도
셌다.
N6는 HEAD와 비교해서, 이 브랜치에서 새로 쓰고 커밋한 기록을 다듬을
때도 「본문을 되돌린다」를 알렸다. 아직 main에 들어가지 않은 글이라
그 알림은 정당한 수정을 되돌리게 만든다.
고친 방법:
- N5: 단순 명령마다 실제로 실행되는 낱말 하나만 본다. 대입과 감싸개
(timeout·flock·env·nohup 등, 값 받는 옵션과 앞 인자 수를 표로 둠)
뒤의 낱말, 셸에 준 스크립트 파일이다. 셸은 옵션을 읽어 -c 스크립트,
stdin 스크립트(-s 또는 인자 없음), 스크립트 파일, -n(실행 안 함)을
가른다. ssh 원격 명령은 ssh가 보내는 대로 리다이렉션을 뺀 낱말을
이어 desktop에서 다시 읽는다. gradlew도 같은 길로 desktop 안에서
돌 때만 센다. leaf 대상은 registry gradle_path와 대조하고, 출력에
verify.sh의 거절 문구가 있으면 그 명령의 verify.sh는 세지 않는다.
스크립트 안의 스크립트는 MAX_NESTING단까지만 읽는다(깊은 ssh 중첩이
RecursionError로 훅을 죽이지 않게).
- here-document 구분자 정규식이 `\WORD`와 따옴표 안 공백을 받는다.
- N6: 기준 커밋을 verify.sh와 같은
`git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"`로 하고, 그
ref가 없으면 HEAD로 돌아간다. 알림 문구는 기준 커밋 이름을 적는다.
버린 대안:
- README의 N5 문구를 verify.sh 경로로 좁히고 옛 gradlew 검사를 둔다
— 같은 오판이 gradlew 쪽에 남는다.
- 실패한 Bash는 PostToolUse가 안 돈다고 보고 rc 5를 두지 않는다 —
`| tail`·`; echo rc=$?`로 끝나면 rc가 0이라 돈다.
위험·한계: 여전히 넛지다. 원격 준비 실패(rc 4)는 출력으로 가리지
못해 센다. flock의 `-c` 꼴, 감싸개 표에 없는 감싸개는 실행으로 보지
않아 알림이 한 번 더 나올 수 있다. 「실행 중」 계획서 체크 상자 수정은
기록 규칙상 본문 수정이라 N6가 계속 알린다(이 브랜치에서 새로 쓴
계획서는 이제 조용하다).
검증(노트북, Python·문서만):
- python3 -m unittest discover -s scripts/tests -p test_hooks.py:
61개 rc=0(1 skip = 실제 포매터 jar).
- RED: 9c0a7cb3d의 hooks.py에 새 상수 셋만 얹고 새 시험을 돌리면
rc=1, failures=20.
- 변이: 이 커밋이 더하거나 건드린 조건 41개를 하나씩 끈 사본에서
모두 rc=1(생존 0).
- python3 scripts/check-docs.py, scripts/check-work-docs.py rc=0.
7.3 KiB
7.3 KiB
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 레이어 의존 알림, 문서면 N6 기록 본문 알림 → N2 문서 검사 알림
Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면(scripts/verify.sh 무거운 단계) N5 기록을 비운다
턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 scripts/verify.sh leaf <gradle-path>를 한 번 알린다
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/ 제외. build-logic/은 src/ 밖이라 대상이 아니다)를 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를 돌린다 |
실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 |
| N6 | 같은 때, *.md |
docs/vision.md면 소유자 문서라고 알린다. scripts/check-docs.py의 기록 폴더(RECORD_KINDS) 문서면 기준 커밋의 옛 글과 머리 블록 끝(HEAD_END) 뒤 본문을 비교한다. 기준 커밋은 scripts/verify.sh와 같은 git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"이고, 그 ref가 없으면 HEAD다. 결정 기록(DECISION_PREFIXES)은 옛 본문이 새 본문의 앞부분이면 되고(끝에 보완 절), 나머지 기록은 같아야 한다. 끝의 빈 줄은 세지 않는다. 기준 커밋에 없는 기록(이 브랜치에서 처음 쓴 기록, 커밋했어도)과 docs/reviews/는 보지 않는다. 상수는 그 파일의 소스에서 읽고, 그 파일을 실행하지 않는다 |
「기록 본문 알림(N6)」과 바뀐 줄(최대 5줄), 또는 「소유자 문서 알림(N6)」 한 줄. N2 실패 줄이 함께 있으면 N6는 첫 줄만 내고 N2 줄이 뒤따른다 |
| N5 | Stop | 이 세션에서 Java를 고친 뒤 desktop 실행이 없으면 턴을 한 번 막고 scripts/verify.sh leaf <gradle-path>를 가리킨다. desktop 실행으로 보는 것은 둘이다: scripts/verify.sh의 Gradle 단계(leaf·pr·main·nightly·release·app·round)를 desktop에서 돌린 것(--on이 없으면 기본 호스트 ${VERIFY_HOST:-desktop}, --on here는 ssh <desktop 호스트> 안에서만), 그리고 ssh <desktop 호스트> 안에서 돈 gradlew. docs 단계, 노트북의 --on here와 gradlew는 아니다 |
decision: block, 다음 Java 편집 전까지 한 번 |
- N5가 기억하는 것은
.claude/hook-state/<session_id>.json이다(git이 무시한다). - N5는 셸 문법을 다 풀지 않는다. 주석·줄 잇기·here-document 본문을 떼고
;·&&·||·|·&·괄호·줄바꿈으로 명령을 나눈다. 명령마다 실제로 실행되는 낱말 하나만 본다: 대입(VERIFY_HOST=…)과 감싸개(timeout·flock·env·nohup등) 뒤의 낱말, 셸에 준 스크립트 파일. 그래서echo scripts/verify.sh pr·bash -n …은 세지 않는다. ssh <desktop 호스트>의 원격 명령은 ssh가 보내는 대로 낱말을 이어 desktop에서 읽는다. 노트북 셸이 ssh에 거는 리다이렉션(> log,2>&1)은 원격 명령이 아니다. here-document 본문·<<<문자열·<셸> -c '…'은ssh <desktop 호스트>나 셸(bash·sh·zsh)이 스크립트로 받을 때만 명령으로 읽고, 그 밖의 본문(cat > 파일 <<EOF,git commit -F - <<EOF,bash 파일 <<EOF)은 글로 본다. 스크립트 안의 스크립트는hooks.pyMAX_NESTING단까지만 읽는다.verify.sh가 Gradle 전에 멈추는 실행은 세지 않는다: 사용법 오류로 멈출 인자(모르는 인자, 대상 없는leaf), registrygradle_path가 아닌leaf대상, 출력에 「미추적 파일이 있어 보내지 않는다」(rc 5)가 있는 실행. 원격 준비 실패(rc 4)는 출력으로 가리지 못해 센다.- N6는 편집 도구(Edit·Write·MultiEdit)로 바꾼 파일만 본다. Bash의 일괄 치환(
sed -i등)으로 바꾼 기록은 잡지 못한다. 그렇게 바꿔 커밋한 본문은 그 파일을 다음에 편집할 때 알린다. 편집 없이 커밋만 한 변경은 리뷰가 본다. - 권한 쪽 차단:
.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를 둔다.