Files
clean-architecture-frontend…/scripts/hooks
DongHyeonka 9961ecb106 feat(hooks): 편집 직후 경계·게이트 기준·문서 알림과 턴 끝 desktop 알림을 건다
경계 위반, 늘어난 skip·only, 작업 매뉴얼 규칙 위반은 desktop 게이트에서야
드러났고, desktop 검증 없이 턴을 끝내도 아무것도 알리지 않았다.

scripts/hooks/hooks.py(백엔드 hooks.py와 같은 모양, 표준 라이브러리와
git만)를 .claude/settings.json에 단다.
- N3: src TypeScript를 고치면 import를 .dependency-cruiser.json의 forbidden
  규칙(path·pathNot·$1)에 그대로 대 본다. 규칙 파일을 읽으므로 규칙이
  바뀌면 따라간다.
- N6: 테스트에 .skip·.only·.fixme·.todo가 마지막 커밋보다 늘거나, 예산·
  기준선·ungated 목록·스냅숏을 고치면 알린다.
- N2: .md를 고치면 scripts/check-work-docs.py의 실패 줄을 알린다.
- N5: desktop만 확인할 수 있는 파일을 고친 뒤 desktop 실행이 없으면 턴
  끝을 한 번 막고 이유를 준다.
모두 넛지다. repo 안 편집에 되돌릴 수 없는 것이 없어 차단 훅은 없다.

고른 방법: 노트북에서는 정적 검사만 하고 포맷·린트·타입은 desktop
scripts/verify.sh에 둔다(brief, 2026-11-08). 설계 13절 Q6은 편집 훅에서
한 파일 eslint를 골랐지만, 프론트 eslint는 pnpm·node_modules가 필요해
"pnpm은 desktop에서만" 규칙과 부딪친다.

위험·한계: N3는 정규식으로 import를 뽑아 주석 속 따옴표 같은 드문
모양을 놓칠 수 있다. 정본은 check:architecture다. 훅 시험은 아직 CI
workflow가 부르지 않는다. 훅은 세션 시작에 읽혀 이 세션에서는 돌지
않았다.

검증: python3 -m unittest scripts/tests/test_hooks.py 26건 통과. 실제
규칙과 src 377개 파일에서 N3 알림 0(거짓 양성 시험). 조건 하나씩 끈
변이 10개를 모두 시험이 잡았다.

Refs: design-docs harness/01-harness-design.md 5.2·5.3절
2026-11-08 17:27:39 +09:00
..

repo 훅

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

Edit·Write 직후 ──> post-edit ──> src TypeScript면 N3 경계 알림, 테스트·기준 파일이면 N6 게이트 기준 알림, 문서면 N2 문서 검사 알림
Bash 직후      ──> post-bash ──> desktop에서 pnpm·게이트를 돌렸으면 N5 기록을 비운다
턴 끝          ──> stop      ──> N5 desktop이 확인해야 할 파일을 고쳤는데 desktop 실행이 없으면 한 번 알린다

1. 원칙

  • 막지 않는다. 모두 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다. 이 repo 안에서 편집 하나가 되돌릴 수 없는 일을 하지 않아서, 편집 전 차단 훅은 없다. 되돌릴 수 없는 명령 차단(force push, 범위 밖 rm -rf, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 harness@claude-harness 몫이다.
  • 훅은 게이트의 일부만 본다. 정본은 게이트(desktop check:architecture, lint, check:types, verify:documentation)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다.
  • 노트북에서 pnpm·node·eslint·브라우저를 돌리지 않는다. 포맷·린트·타입 검사는 desktop의 scripts/verify.sh에서 돈다(소유자 결정 2026-11-08, docs/work/reference/decisions.md). 그래서 편집 직후 훅은 Python 표준 라이브러리와 git만 쓰는 정적 검사이고, 1초 안에 끝난다.
  • 받거나 설치하지 않는다. 의존성이 없다.

2. 훅마다

ID 때 하는 일 결과
N3 PostToolUse Edit|Write|MultiEdit, src/**/*.{ts,tsx}(.d.ts 제외) 편집한 파일의 import(정적·type-only·re-export·리터럴 dynamic import·require)를 경로로 풀고, .dependency-cruiser.json의 forbidden 규칙(from·to의 path·pathNot, $1 치환)에 대 본다. 사이클 규칙은 그래프 전체가 필요해 보지 않는다 「꼭 지킬 것 N 의심」 줄(규칙 이름과 import), 정본 게이트 안내
N6 같은 때, 테스트 파일(tests/**, *.test.*·*.spec.*·*.stories.*) 마지막 커밋(git show HEAD:<path>)보다 .skip·.only·.fixme·.todo가 늘었는지 센다 늘어난 수와 「꼭 지킬 것 4」
N6 같은 때, 게이트 기준 파일(config/performance/budgets.json, config/scale/, config/testing/, config/ci/ungated-*.json, config/**/*baseline*.json, vitest.config.ts, 스냅숏) 편집 자체를 알린다 「게이트의 기준 파일」 한 줄과 「꼭 지킬 것 4」
N2 같은 때, *.md scripts/check-work-docs.py를 돌린다(작업 매뉴얼의 분량·이력 ID·뼈대·상대 링크) 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만
N5 Stop 이 세션에서 desktop만 확인할 수 있는 파일(아래 밖의 모든 파일)을 고친 뒤 desktop 실행이 없으면 턴을 한 번 막고 이유를 준다 decision: block, 다음 편집 전까지 한 번
  • N5가 "desktop 실행"으로 치는 것: ssh <desktop 호스트> …로 pnpm·ci:gate·verify.sh·vitest·playwright·node scripts/…를 돌린 명령, 또는 scripts/verify.sh를 docs·hooks 밖 단계로(--on here 없이) 돌린 명령.
  • N5가 세지 않는 파일(노트북에서 확인되는 것): .claude/, scripts/hooks/, scripts/tests/, scripts/check-work-docs.py, docs/ledger/, CLAUDE.md. 이것들은 scripts/verify.sh docs·hooks가 노트북에서 본다.
  • N5가 기억하는 것은 .claude/hook-state/<session_id>.json이다(git이 무시한다).
  • 권한 쪽 차단: .claude/settings.json의 permissions.deny가 실제 .env·.env.local·.env.*.local·.env.<mode> 읽기·쓰기를 막는다. .env.example은 막지 않는다.

3. 시험

scripts/verify.sh hooks
  • python3 -m unittest discover -s scripts/tests와 같다. 노트북에서 돈다.
  • 고장 낸 입력(배럴 밖 import, kernel 밖 adapter 간 import, 늘어난 .only, 깨진 링크)에서 알림이 나오고, 맞는 입력에서 조용한지 본다. N3는 실제 .dependency-cruiser.json과 src/ 전체에서 알림이 0인지도 본다(거짓 양성 시험).
  • 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다.
  • 이 시험은 아직 CI workflow가 부르지 않는다. 훅·검사기를 고친 PR은 보고에 scripts/verify.sh hooks 결과를 적는다.

4. 끄기

훅이 시끄럽거나 틀리면 .claude/settings.json에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 .claude/settings.local.json(git이 무시한다)에 "disableAllHooks": true를 둔다.