문제: 기록 문서(설계서·계획서·증거·학습 문서·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.
1.6 KiB
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.md4.1절). 세션 규칙은docs/work/delegate.md4.3절, 보고 형식은 소유자 전역 설정이다.