frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / merge / static checks (pull_request) Successful in 3m16s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m49s
frontend-quality-gates / merge / browser tests (pull_request) Failing after 8m20s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
앞 두 커밋 뒤 확인 리뷰가 퇴행 하나와 빠진 곳 하나를 찾았다. - 실행 판정을 다시 쓰면서 ssh 뒤 `-`로 시작하는 낱말만 뺐다. 값을 받는 옵션 (`ssh -o BatchMode=yes desktop …`, `ssh -p 22 desktop …`)은 그 값을 호스트로 읽어 desktop 실행으로 세지 않는다. `bash scripts/verify.sh merge`도 첫 낱말이 verify.sh가 아니라 세지 않는다. origin/main 판은 셋 다 셌다. - 노트북 파일에서 문서를 뺀 것이 `.claude/`뿐이다. `scripts/hooks/README.md`와 `docs/ledger/README.md`도 desktop `verify:documentation`이 읽는다. 고른 방법: ssh 뒤 옵션은 값을 받는 것(-o -p -i -l -J -F 등)이면 다음 낱말까지 건너뛰고 남은 첫 낱말을 호스트로 본다. bash·sh를 감싸는 낱말에 더한다. scripts/hooks/·scripts/tests/·docs/ledger/ 패턴에서도 `.md`를 뺀다. README 문장을 같이 고친다. 검증: python3 -m unittest discover -s scripts/tests 74개 통과(노트북). 새 경우 다섯(bash, ssh -o, ssh -p, 두 README)이 고치기 전 코드에서 실패했다. Refs: 1112/08-04, 1112/08-09
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/…를 돌린 명령(로그를 읽기만 하는cat·grep·tail등은 빼고), 또는scripts/verify.sh를 명령으로docs·hooks밖 단계로(--on here·--dry-run없이) 돌린 명령. 앞의VAR=값과timeout·nohup·bash같은 감싸는 낱말, ssh 옵션과 그 값(-o BatchMode=yes,-p 22)은 건너뛴다.verify.sh를 읽는 명령(sed,grep,git log -- scripts/verify.sh)은 세지 않는다. - N5가 세지 않는 파일(노트북에서 확인되는 것):
.claude/의 설정·훅 상태,scripts/hooks/·scripts/tests/의 코드,scripts/check-work-docs.py,docs/ledger/의 장부. 이것들은scripts/verify.sh docs·hooks가 노트북에서 본다. 그 폴더의 문서(.md)와CLAUDE.md,src/**/AGENTS.md·CLAUDE.md는 desktopverify:documentation도 보므로 센다. - 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를 둔다.