계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는 보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다. src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일, 그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그 폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든 폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에 @AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은 책을 읽는다(백엔드와 같은 짝). - .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다. - scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를 본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다. - docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters 아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다. - 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의 양식을 가리킨다. 버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md 없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만 읽어 백엔드와 갈린다). 위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면 이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture). 검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200), python3 -m unittest discover -s scripts/tests 62건 통과.
47 lines
5.0 KiB
Markdown
47 lines
5.0 KiB
Markdown
# repo 훅
|
|
|
|
Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.claude/settings.json`, 본체는 `hooks.py` 하나, 시험은 `scripts/tests/test_hooks.py`다. 모델이 잊어도 돈다.
|
|
|
|
```text
|
|
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`, `src/**/AGENTS.md`·`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. 시험
|
|
|
|
```bash
|
|
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`를 둔다.
|