Files
clean-architecture-backend-…/CLAUDE.md
DongHyeonka 9c0a7cb3d8 feat(hooks): 기록 본문과 docs/vision.md 편집을 알리는 N6를 더한다
문제: 기록 문서(설계서·계획서·증거·학습 문서·ADR) 본문은 쓴 때의
원문이고 머리 블록만 고친다는 규칙(docs/README.md 「문서 수명과
언어」, .claude/rules/docs.md)과 docs/vision.md는 소유자만 쓴다는
규칙이 문서에만 있다. 훅도 게이트도 보지 않아, 세션이 기록 본문을
고쳐도 아무도 알리지 않는다(6a792b814가 기록 30개의 본문 경로를
고친 일이 있다).

고른 방법: post-edit에서 .md 편집마다 본다. docs/vision.md면
「소유자만 쓴다, 되돌리고 제안만 한다」 한 줄.
scripts/check-docs.py의 RECORD_KINDS 폴더 문서면 `git show
HEAD:./<경로>`의 옛 글과 머리 블록 끝 뒤 본문을 비교한다. 설계서·
history 기록은 같아야 하고, DECISION_PREFIXES(ADR)는 옛 본문이 새
본문의 앞부분이면 된다(끝에 보완 절). 끝의 빈 줄은 세지 않는다. 어기면
「기록 본문 알림(N6) <경로>: … n곳 다르다 …」와 바뀐 줄을 최대 5줄로
알린다(exit 0). HEAD에 없는 새 기록은 조용하다. N6에는 뒤에 게이트가
없으니 첫 줄은 늘 맨 앞에 두고, N2 실패 줄이 함께 있으면 N6는 첫 줄만
내 N2 줄이 잘리지 않게 한다. 상수(RECORD_KINDS·DECISION_PREFIXES·
HEAD_START·HEAD_END·HEAD_SEARCH_LINES)는 check-docs.py 소스에서
ast.literal_eval로 읽어 복사본을 두지 않는다. 하나라도 없거나 값이
리터럴이 아니면 N6는 조용하다(편집을 실패시키지 않는다). 시험이 진짜
check-docs.py의 record_kind·strip_head_block과 훅 판정이 같은지 본다.
README 표에 N6 줄과 한계, 루트 CLAUDE.md 훅 목록에 「기록 본문 알림」.
버린 대안: (1) check-docs.py를 import해 함수를 그대로 쓴다 — 편집마다
그 스크립트의 최상위 코드를 실행한다. N2 시험의 가짜 스크립트처럼
최상위에서 sys.exit하면 훅이 죽는다. (2) 상수를 hooks.py에 복사한다 —
두 벌이 갈라진다. (3) docs/reviews/도 본다 — 리뷰 기록 규칙이 문서끼리
맞지 않아 따로 정할 일이라 넣지 않았다(check-docs.py도 머리 블록을 아직
요구하지 않는다). (4) N2를 앞에 둔다 — N2 줄이 다섯이면 게이트가 없는
N6가 통째로 잘린다.

위험·한계: 편집 도구(Edit·Write·MultiEdit)만 본다. Bash 일괄 치환
(sed -i 등)이나 이미 커밋한 본문 변경은 잡지 못한다. 비교 기준이
HEAD라서, 이 브랜치에서 새로 쓰고 커밋한 기록을 다시 다듬을 때도
알린다. check-docs.py가 상수 이름을 바꾸면 N6는 조용해진다 — 그때 시험
test_the_record_rules_are_the_document_checkers가 실패한다.
check-docs.py와 settings.json은 고치지 않았다.

검증: python3 -m unittest discover -s scripts/tests -p test_hooks.py
rc=0(52개, 1 skip). 변이 18개(비교 끄기·ADR을 설계서처럼·설계서를
ADR처럼·머리 블록 안 떼기·시작 줄 확인 끄기·탐색 범위 끄기·vision
끄기·새 기록도 비교·reviews 넣기·post-edit 연결 끊기·N2 옆 첫 줄만
끄기·ADR 끝 덧붙임을 알림에 넣기·5줄 상한 끄기·없는 check-docs.py에서
죽기·리터럴 아닌 값에서 죽기·상수 일부만 받기·끝 빈 줄 세기·빈 줄
대신 첫 글자 줄 보이기 끄기)가 모두 시험 하나 이상을 실패시킨다. N5
변이 31개도 그대로 잡힌다. 실제 저장소에서 post-edit: docs/vision.md는
알림 한 줄, 고치지 않은 설계서·ADR은 출력 없음(rc=0).
python3 scripts/check-work-docs.py rc=0, python3 scripts/check-docs.py
rc=0.
2026-11-22 01:37:46 +09:00

1.6 KiB

@AGENTS.md

Claude Code에서만

  • 권한과 훅은 .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. 발동 조건이 설명에 있어 모델이 부른다.
  • 서브에이전트는 .claude/agents/다: reviewer(렌즈로 받은 be-* 스킬로 새 창에서 diff 판정), arch-reviewer(구조 리뷰), verify-api(desktop에서 앱 띄워 확인), code-simplifier(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다.
  • 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(docs/work/operate.md 4.1절). 세션 규칙은 docs/work/delegate.md 4.3절, 보고 형식은 소유자 전역 설정이다.