diff --git a/CLAUDE.md b/CLAUDE.md index f72554b1..6f176eaf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ ## Claude Code에서만 -- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. +- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사·기록 본문 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. - 공통 훅·스킬(되돌릴 수 없는 명령 차단, 비밀 값 알림, 장부, `estimate`·`retro`·`techdebt`)은 하네스 플러그인 `harness@claude-harness`다(같은 settings가 켠다). 비대화형(`claude -p`)은 설치하지 않으니 claude-harness README의 `--scope project` 두 명령을 한 번 돌린다. - 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다. - 스킬은 `.claude/skills/`다: `new-feature`(새 기능), `desktop-gates`(Gradle·Docker를 desktop에서), 분야 지식 `be-*`(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다). 여러 분야면 플러그인 `lead`. 발동 조건이 설명에 있어 모델이 부른다. diff --git a/scripts/hooks/README.md b/scripts/hooks/README.md index fff6bca2..68649244 100644 --- a/scripts/hooks/README.md +++ b/scripts/hooks/README.md @@ -4,9 +4,9 @@ Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.cl ```text Edit·Write 직전 ──> pre-edit ──> H13 적용된 migration이면 막는다(종료 코드 2) -Edit·Write 직후 ──> post-edit ──> Java면 포맷 → N1 레이어 의존 알림, 문서면 N2 문서 검사 알림 -Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 N5 기록을 비운다 -턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 한 번 알린다 +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 를 한 번 알린다 ``` ## 1. 원칙 @@ -25,9 +25,14 @@ Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 | 포맷 | 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`를 돌린다 | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 | -| N5 | Stop | 이 세션에서 Java를 고친 뒤 `ssh … gradlew …` 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 Java 편집 전까지 한 번 | +| 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 `를 가리킨다. desktop 실행으로 보는 것은 둘이다: `scripts/verify.sh`의 Gradle 단계(`leaf`·`pr`·`main`·`nightly`·`release`·`app`·`round`)를 desktop에서 돌린 것(`--on`이 없으면 기본 호스트 `${VERIFY_HOST:-desktop}`, `--on here`는 `ssh ` 안에서만), 그리고 `ssh ` 안에서 돈 `gradlew`. `docs` 단계, 노트북의 `--on here`와 `gradlew`는 아니다 | `decision: block`, 다음 Java 편집 전까지 한 번 | - N5가 기억하는 것은 `.claude/hook-state/.json`이다(git이 무시한다). +- N5는 셸 문법을 다 풀지 않는다. 주석·줄 잇기·here-document 본문을 떼고 `;`·`&&`·`||`·`|`·`&`·괄호·줄바꿈으로 명령을 나눈다. 명령마다 실제로 실행되는 낱말 하나만 본다: 대입(`VERIFY_HOST=…`)과 감싸개(`timeout`·`flock`·`env`·`nohup` 등) 뒤의 낱말, 셸에 준 스크립트 파일. 그래서 `echo scripts/verify.sh pr`·`bash -n …`은 세지 않는다. +- `ssh `의 원격 명령은 ssh가 보내는 대로 낱말을 이어 desktop에서 읽는다. 노트북 셸이 ssh에 거는 리다이렉션(`> log`, `2>&1`)은 원격 명령이 아니다. here-document 본문·`<<<` 문자열·`<셸> -c '…'`은 `ssh `나 셸(`bash`·`sh`·`zsh`)이 스크립트로 받을 때만 명령으로 읽고, 그 밖의 본문(`cat > 파일 < post-bash ──> desktop에서 Gradle을 돌렸으면 python3 -m unittest discover -s scripts/tests ``` -- 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다. +- 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크, 기록 본문 고침)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다. - 실제 포매터 시험은 Gradle 캐시에 카탈로그 버전 jar가 있는 기계에서만 돈다. 그 밖에서는 가짜 `java`로 옵션·파일 전달·바뀜 감지를 본다. - 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다. diff --git a/scripts/hooks/hooks.py b/scripts/hooks/hooks.py index 86205f92..a2180bbb 100644 --- a/scripts/hooks/hooks.py +++ b/scripts/hooks/hooks.py @@ -4,7 +4,7 @@ Called by `.claude/settings.json`, one event per invocation, with the hook input JSON on stdin: python3 scripts/hooks/hooks.py pre-edit # PreToolUse Edit|Write|MultiEdit H13 - python3 scripts/hooks/hooks.py post-edit # PostToolUse Edit|Write|MultiEdit format, N1, N2 + python3 scripts/hooks/hooks.py post-edit # PostToolUse Edit|Write|MultiEdit format, N1, N2, N6 python3 scripts/hooks/hooks.py post-bash # PostToolUse Bash records desktop Gradle runs python3 scripts/hooks/hooks.py stop # Stop N5 @@ -17,6 +17,8 @@ scripts/tests/test_hooks.py. from __future__ import annotations +import ast +import difflib import hashlib import json import os @@ -68,8 +70,51 @@ MAIN_JAVA = re.compile(r"^(?Psrc/.+?)/src/main/java/(?P.+\.java)$") DOC_CHECKS = (("scripts/check-work-docs.py",), ("scripts/check-docs.py",)) DOC_TIMEOUT = 20 +# --- N6: a record keeps the body it was written with; the vision is the owner's ------------------------ +# Which folders hold records, which of them are decisions and where a head block ends are read from the +# document checker's source (literals only, the script is not run), not copied here. +DOC_CHECKER = "scripts/check-docs.py" +DOC_CHECKER_NAMES = ("RECORD_KINDS", "DECISION_PREFIXES", "HEAD_START", "HEAD_END", "HEAD_SEARCH_LINES") +VISION = "docs/vision.md" +GIT_TIMEOUT = 10 +RECORD_CHANGES_SHOWN = 3 +# The body is compared with where this branch left the base, as scripts/verify.sh finds it +# (`git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"`); without that ref, with HEAD. +BASE_REF_VARIABLE = "VERIFY_BASE_REF" +BASE_REF_DEFAULT = "origin/main" + # --- N5: a Bash command that ran Gradle on the desktop clears the pending Java edits -------------------- DESKTOP_HOST = re.compile(r"desktop") +# The scripts/verify.sh stages that run Gradle or Docker (run_here). Their --on default is +# ${VERIFY_HOST:-desktop}; docs runs here and never on the desktop (scripts/verify.sh main). +VERIFY_SCRIPT = "verify.sh" +VERIFY_HEAVY_STAGES = ("leaf", "pr", "main", "nightly", "release", "app", "round") +# scripts/verify.sh main: any other word after the stage (and the leaf target) stops it at usage, before Gradle. +VERIFY_VALUE_OPTIONS = ("--on", "--log") +VERIFY_FLAGS = ("--no-cache", "--include-untracked") +VERIFY_HOST_ASSIGNMENT = "VERIFY_HOST=" +# scripts/verify.sh run_remote says this and exits 5 before it sends anything to the desktop. +VERIFY_REFUSED = "verify: 미추적 파일이 있어 보내지 않는다" +GRADLE_WRAPPER = "gradlew" +# How deep a script inside a script (ssh remote command, `-c`, here-document) is still read. +MAX_NESTING = 8 +# ssh options that take a value, so the host is the first word after them (ssh(1) SYNOPSIS). +SSH_VALUE_OPTIONS = ("-B", "-b", "-c", "-D", "-E", "-e", "-F", "-I", "-i", "-J", "-L", "-l", "-m", "-O", "-o", + "-P", "-p", "-Q", "-R", "-S", "-W", "-w") +# A here-document fed to one of these, or ` -c '