Commit Graph
14 Commits
Author SHA1 Message Date
DongHyeonka 7140f27948 docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).

- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
  규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
  지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
  지킬 규칙 몇 줄을 남겼다.
  - application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
    멱등성(KEYED) → 337줄에서 190줄.
  - persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
    TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
    194줄.
  - graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
  TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
  찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
  AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
  가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
  자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
  코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
  맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
  `lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
  PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.

위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.

검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.

BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
2026-11-07 22:33:08 +09:00
DongHyeonka d905980676 test(scripts): 하위 CLAUDE.md가 AGENTS.md만 가져오는지 보고 검사기 시험을 둔다
폴더 지역 규칙은 이제 src/**/AGENTS.md이고 옆의 CLAUDE.md는 `@AGENTS.md`
한 줄이다. 누가 CLAUDE.md에 규칙을 다시 쓰거나, AGENTS.md만 만들고
CLAUDE.md를 빠뜨리면 Claude Code가 그 폴더 규칙을 못 읽거나 규칙이 두 벌이
된다. 그리고 check-work-docs.py에는 자기 시험이 하나도 없었다.

- check-work-docs.py: src/**/AGENTS.md마다 옆 CLAUDE.md가 있고, 모든
  src/**/CLAUDE.md가 정확히 `@AGENTS.md`이며 옆에 AGENTS.md가 있는지 본다
  (build 출력 제외).
- scripts/tests/test_check_work_docs.py(13건): 최소 매뉴얼 통과, 지도 41줄·
  CLAUDE.md 11줄 실패, CLAUDE.md 첫 줄이 가져오기가 아니면 실패, 진입 경로가
  네 파일(AGENTS.md + CLAUDE.md + README + playbook) 합인지, 짝 셋, 하위
  규칙과 .claude/rules·skills·agents의 이력 ID, 로컬 .claude 상태는 안 봄,
  하위 규칙의 깨진 링크.
- gates.md 「링크 검사」: lychee 범위 밖 지침 문서는 check-docs.py `link`가
  보고, 손으로 돌리는 범위를 src/**/AGENTS.md로 바꿨다. docs/README.md의
  검사 설명에서 링크 문법 예를 뺐다(링크 검사기가 링크로 읽었다).

위험: 진입 경로 상한 350은 파일별 상한의 합(40+10+80+150=280)보다 커서
지금 구조에서는 닿지 않는다. 옛 상한(120+80+150=350)도 같았다. 상한은 그대로
두고 시험은 상한을 낮춰 계산식을 본다.

검증: unittest(전체), check-work-docs, check-docs, 같은 범위 --links 모두
rc=0(깨진 링크 0). 조건 다섯(짝 검사, 지도 상한, 진입 경로의 CLAUDE.md,
첫 줄 가져오기, .claude 문서 이력)을 하나씩 끈 사본마다 시험이 1~3건 실패했다.
2026-11-07 22:23:01 +09:00
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00
DongHyeonka 37c88fedd4 docs(ledger): 작업마다 예측과 실측을 쌓는 repo 장부를 둔다
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).

- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
  뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
  실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
  merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
  더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
  근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.

버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.

위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.

검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
2026-11-07 22:11:27 +09:00
DongHyeonka 67ecae2cc2 feat(skills)!: 새 기능과 desktop 게이트 절차를 모델이 부르는 스킬로 둔다
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).

- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
  실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
  → 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
  순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
  테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
  327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
  가리키기, skills-lock.json 없음)을 더했다.

버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).

위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.

검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.

BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
2026-11-07 22:10:08 +09:00
DongHyeonka c67c713177 feat(agents)!: Agent 금지를 풀고 결과만 돌려주는 서브에이전트 셋을 둔다
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).

- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
  판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
  띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
  않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
  4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
  직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
  조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
  따르는지 본다.

버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).

위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.

검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.

BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
2026-11-07 22:08:42 +09:00
DongHyeonka 38891071d6 feat(hooks)!: 편집 직후 포맷·레이어·문서 알림과 migration 차단 훅을 건다
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).

scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
  종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
  버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
  쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
  --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
  파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
  build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
  (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
  같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
  턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).

버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).

위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.

검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.

BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
2026-11-07 22:06:50 +09:00
DongHyeonka 08f932123a docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).

- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
  CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
  src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
  AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
  지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
  CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
  기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
  때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
  AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
  check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
  workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.

위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.

검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.

BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
2026-11-07 21:58:12 +09:00
DongHyeonka 2d43356136 ci(docs): 참조 검사가 디스크에만 남은 폴더를 있는 경로로 세지 않는다
참조 검사(reference)와 머리 블록의 「현재 정본」·「대체됨」 검사는 경로가
있는지를 파일 시스템(Path.exists)으로 본다. git mv는 옮긴 뒤 빈 옛 폴더를
디스크에 남긴다. 그래서 지운 폴더를 가리키는 살아 있는 문서가 노트북에서는
통과하고, 빈 폴더가 없는 새 checkout(PR workflow)에서만 실패한다. 알림 ADR을
옮길 때(39d4f248) 실제로 그랬다: docs/README.md에 쓴 옛 폴더 경로가 빈
docs/notification/adr/ 때문에 통과했고, 폴더를 지운 뒤에야 걸렸다.

「있다」를 git이 아는 파일(추적 + 무시되지 않은 새 파일, 문서 목록과 같은
git ls-files)과 그 위 폴더로 바꿨다(known_paths). leaf 기준 상대 경로를
위 폴더로 올라가며 찾는 규칙은 그대로다. 무시되는 경로(src/.env 등)는
전처럼 git check-ignore가 건너뛴다.

버린 대안: 빈 폴더만 따로 빼기. 아무도 추가하지 않은 파일(디스크에만 있는
build 밖 산출물)도 같은 거짓 통과를 만든다. git이 보는 것과 같게 하면
노트북과 PR workflow가 같은 답을 낸다.

자기 시험 셋을 더했다(79 OK): 빈 폴더를 가리키는 참조가 실패, 파일이 든
폴더는 통과, 빈 폴더를 가리키는 「현재 정본」이 실패. 변이 시험: 디스크의
모든 경로를 다시 세게 하면 rc=1, 빈 폴더 시험 둘이 실패한다.

검증(노트북): check-docs.py OK(여섯 검사 걸림 0, 0.8초), 자기 시험 79 OK.
빈 docs/notification/adr/를 다시 만들어도 known_paths는 그 폴더를 모른다.
2026-11-07 18:31:33 +09:00
DongHyeonka 9c4ca9f391 ci(docs): 숫자 검사가 굵은 글씨·표 칸의 Spring Boot 버전 복사도 잡는다
숫자 검사(number)는 「Spring Boot 4.0.8」처럼 이름 바로 뒤에 붙은 버전만
본다. 이름과 떨어진 복사는 지나간다. 기준 커밋 03a313ed의 살아 있는
문서에 그런 복사가 넷 있었다.
- docs/web/repository-adaptation.md:65 「baseline is **4.0.8**」
  (의존성 세션이 손으로 찾아 고친 줄. 그 브랜치는 **4.0.9**로 바꾼다)
- docs/compatibility/grpc-support-matrix.md:29 「| Spring Boot | 4.0.8 …」
- docs/mongodb/support-matrix.md:12 「| Spring Boot | 4.0.0 |」
- docs/jpa/repository-adaptation.md:100 「Boot 4.0.0 resolves …」
번역 묶음이 넷 모두 정본을 가리키게 고쳤지만, 검사가 막지 않으면
다시 생긴다.

규칙 셋을 더했다(Spring Boot 버전에만).
1. 이름 규칙이 「Spring」 없는 「Boot x.y.z」도 잡는다.
2. 표 행에 칸 전체가 「Spring Boot」(굵은 글씨·코드·링크를 벗긴 뒤,
   뒤에 BOM·버전이 붙어도 됨)인 칸이 있으면 그 행의 세 자리 버전.
3. 정본(src/gradle/libs.versions.toml의 springBoot)과 같은 버전 문자열은
   어디에 쓰든(굵은 글씨, 표 칸, 인라인 코드). 앞이 낱말·점·§이거나
   뒤가 낱말·「.숫자」이면 다른 수의 일부로 보고 넘긴다(RFC §4.0.8,
   14.0.8, 4.0.80, 4.0.8.1).
이름 옆 복사는 한 번만 센다(2·3이 그 안의 버전을 다시 세지 않는다).
결정 기록·제거 표·upgrade/를 빼는 범위는 그대로다(checked_for_drift).

버린 대안: 굵은 글씨 안의 모든 세 자리 버전을 잡기. 살아 있는 문서를
훑으면 Spring Boot 아닌 것이 둘 걸린다. docs/jpa/support-matrix.md의
Hibernate **7.1.8.Final**은 JpaDocumentationContractTest가 release
registry의 값과 같은지 단언하는 렌더링이라 지울 수 없다. 그것을 잡으면
굵은 글씨만 빼서 검사를 피하게 된다. 규칙 3은 정본 값을 직접 보므로,
지금 버전의 복사는 모양과 상관없이 생길 수 없고, 버전을 올리는 변경
때 옛 값의 복사가 남아 있을 수 없다.

한계: 정본 값과 다르고 이름과도 떨어진 버전(「4.0.0 / 5.0.0」 같은
문장)은 잡지 않는다. Spring Boot 밖의 버전 복사는 이 검사의 범위가
아니다(docs/README.md 「문서 검사」 number 행).

시험: 03a313ed 트리와 의존성 브랜치(cb67b879) 트리에 옛·새 검사를
돌렸다. 새 검사가 위 네 줄(의존성 브랜치는 **4.0.9**)을 더 잡고,
옛 검사가 잡던 28건은 모두 그대로 잡는다. 합친 트리는 걸림 0이라
예외를 더하거나 고칠 문서가 없다.

자기 시험 8개를 더했다(76 OK). 조건을 하나씩 끈 변이 시험 7개가 모두
rc=1이다: 옛 이름 정규식, 표 칸 규칙 끔, 정본 값 규칙 끔, 중복 세기
제거 끔, 정본 값 앞 § 허용, 정본 값 뒤 경계 끔, 칸 이름 앞부분만 맞춤.

검증(노트북): check-docs.py OK, 자기 시험 76 OK, check-work-docs.py OK.
2026-11-07 18:19:42 +09:00
DongHyeonka 80e7ef12a2 ci(docs): FROZEN에 목록에 없는 지문이 남으면 문서 검사가 실패한다
예외 목록은 줄기만 해야 하는데 빈틈이 있다. check-docs.py는 목록의
줄이 FROZEN에 있는지만 보고, FROZEN의 지문이 목록에 있는지는 보지
않는다. 그래서 번역해서 지운 줄의 지문이 FROZEN에 남고, 같은 줄을 다시
더해도 검사가 통과한다. 기준 커밋 03a313ed에서 이미 FROZEN 217개 중
9개가 목록에 줄이 없었다(앞 단계의 이름 바꾸기에서 남은 것).

- run()이 FROZEN - (목록 줄의 지문)을 실패로 낸다. --only와 상관없이
  돈다(목록의 줄이 FROZEN에 있는지 보는 검사와 같다).
- 합친 트리의 목록이 비었으므로 FROZEN에서 217개를 모두 뺐다. 이제
  목록에 어떤 줄을 더해도 실패한다.
- 설명(스크립트 머리, 예외 목록 머리 주석, docs/README.md 「문서
  검사」)에 「줄을 지우면 FROZEN에서 그 지문도 뺀다」를 더했다.
  스크립트 머리의 「넷 모두」를 지금의 여섯 검사로 고쳤다.

버린 대안: FROZEN을 그대로 두고 자기 시험만 더하기. 실제 검사(PR
workflow)는 자기 시험과 따로 돌므로, 목록과 FROZEN이 어긋난 트리가
check-docs.py만으로는 통과한다. 검사 자신이 막아야 한다.

자기 시험(scripts/tests/test_check_docs.py)에 셋을 더했다.
- test_a_frozen_fingerprint_whose_line_was_removed_fails: 고장 낸 입력
  (빈 목록 + 지문 하나)이 language·head 어느 검사로 돌려도 실패한다.
- test_a_removed_line_added_back_fails_once_its_fingerprint_is_gone:
  지문을 뺀 뒤 줄을 다시 더하면 「기준선에 없는 예외다」로 실패하고,
  남은 줄에는 고아 지문 오류가 나지 않는다.
- test_every_frozen_fingerprint_has_its_line_in_the_real_exception_list:
  실제 FROZEN과 실제 목록이 맞는다.

조건을 끈 변이 시험(사본에 문자열 치환, 자기 시험 실행):
- 고아 지문 검사를 지움 → rc=1, 첫째 시험 실패
- FROZEN을 03a313ed의 217개로 되돌림 → rc=1, 셋째 시험 실패.
  실제 트리의 check-docs.py도 고아 지문 217건으로 실패한다.
- 둘 다(바꾸기 전 코드) → rc=1, 첫째·셋째 시험 실패

검증(노트북): check-docs.py OK(여섯 검사 걸림 0), 자기 시험 68 OK,
check-work-docs.py OK.
2026-11-07 18:15:29 +09:00
DongHyeonka f56a100528 ci(docs): 문서 지도와 루트 README 절을 문서 검사가 본다
문제: 「모든 문서 폴더가 `docs/README.md` 지도에 있다」와 「루트 README가 정해진 절을
가진다」(design-docs `conventions/docs-system.md` 7절 K5·K6)를 아무것도 지키지 않는다.
테스트 자원 `broken-readme.md`(일부러 깨뜨린 입력)를 살아 있는 문서로 보고 언어 검사
예외에 둔다.

고른 방법: `scripts/check-docs.py`에 검사 둘을 더한다. docs-check workflow가 인자 없이
돌리므로 PR에서 바로 실패로 돈다.
- `map`: `docs/` 바로 아래 폴더가 모두 지도 표의 첫 칸에 있어야 한다. 파일 없이 폴더만
  가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. `.md`가 없는 폴더(스냅숏,
  yaml)도 본다. 지도에 있지만 없는 폴더도 실패다.
- `readme`: 첫 줄 `# 제목`, 그 아래 한 문단, `README_SECTIONS`의 `##` 절이 그 순서로
  있어야 한다. 사이에 다른 절은 있어도 된다.
- 소스 세트 resources 폴더 아래 `.md`(`/src/<세트>/resources/`)는 문서로 보지 않는다.
  그래서 `broken-readme.md` 예외 줄을 지운다.

버린 대안: 지도 폴더를 모든 깊이까지 요구하기. 리뷰 라운드 폴더, 납품 패키지 폴더마다
행이 생겨 지도가 목록이 된다. 절을 정확히 일곱 개만 허용하기. 서비스가 절을 더할 수
없게 된다.

위험·한계: `FROZEN` 지문은 건드리지 않았다. leaf·family README 절 검사(K6 뒷부분)와 파일
이름 규칙·실행 산출물 검사(K5 뒷부분)는 넣지 않았다.

검증:
- `python3 -m unittest discover -s scripts/tests` 65건 rc=0(새 시험 22건).
- 판정 조건 18개를 하나씩 끈 사본마다 자기 시험이 실패했다(rc=1).
- `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:18:19 +09:00
DongHyeonka fc3cad7dcc ci(docs): 참조 검사가 루트 compose 폴더 경로도 본다
문제: 구조 정리로 저장소 루트에 `compose/`(개발 compose의 보조 파일)가
생겼다. 참조 검사는 `src/`, `docs/`, `scripts/`, `infra/`, `.github/`로
시작하는 인라인 코드만 본다. 그래서 살아 있는 문서가 가리키는
`compose/redis/acl/README.md` 같은 경로는 파일이 옮겨지거나 지워져도
걸리지 않는다. 지금 살아 있는 문서 여덟 개가 `compose/` 경로를 쓴다.

고친 방법: PATH_ROOTS에 `compose/`를 더한다. 정본 design-docs
`conventions/docs-system.md` K3는 「repo 경로」 전체를 말하고 접두사 목록을
정하지 않으므로 규칙 변경이 아니라 새 루트 폴더를 적용한 것이다. 지운
`infra/`는 남겨 둔다(다시 쓰이면 낡은 참조로 걸린다). 루트 파일
(`compose.yaml` 등)은 지금처럼 보지 않는다.

위험·한계: 새로 걸린 참조는 없다(지금 트리의 `compose/` 참조는 모두 있다).

검증: 새 시험 `test_a_missing_path_under_the_root_compose_folder_fails`가
고치기 전 실패(RED: 오류 목록이 비어 있음), 고친 뒤 43개 모두 통과.
check-docs.py rc=0(참조 걸림 7·예외 7).
2026-11-07 15:04:17 +09:00
DongHyeonka 1c00f89765 ci(docs): 문서 언어·머리 블록·참조·숫자를 PR에서 검사한다
문제: 살아 있는 문서의 언어, 기록의 상태 표시, 인라인 코드 경로, 복사한
버전·개수를 아무 검사도 보지 않는다. lychee는 마크다운 링크만 보는데
경로 대부분은 인라인 코드로 쓰여 있고, leaf CLAUDE.md는 Spring Boot
버전을 4.0.0으로 적어 둔 채 낡았다.

고른 방법: Gradle 밖 scripts/check-docs.py 하나에 검사 넷을 둔다.
- language: 살아 있는 문서와 ADR 본문이 한국어인가. 판정은 보고 언어 훅
  H11과 같다(코드·명령·경로·인용을 빼고 영어 낱말 3개 이상, 한글 비율
  0.3 미만이면 영어).
- head: 기록·ADR 맨 위 머리 블록의 칸, 종류별 상태 어휘, 날짜, 한국어
  요약, 현재 정본·대체됨 경로.
- reference: 인라인 코드 안 src/·docs/·scripts/·infra/·.github/ 경로와
  Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, 「> 이력」 인용,
  제거 표, upgrade/는 건너뛴다. leaf 기준 경로는 어느 파일의 끝부분과
  맞으면 있다고 본다.
- number: Spring Boot x.y.z와 leaf 개수 문장.
예외 목록(scripts/check-docs-exceptions.txt)은 2026-11-07 기준선 217줄이고
줄기만 한다. 줄마다 sha256 지문이 스크립트의 FROZEN에 있어야 해서 목록에
새 줄을 더하면 실패하고, 더는 걸리지 않는 줄을 남겨 두면 실패한다.
workflow docs-check.yml이 PR마다 경로 필터 없이 자기 시험과 검사를 돌린다.
코드에서 파일을 지우는 변경이 문서를 낡게 만들기 때문이다. 같은 커밋에서
지도 CLAUDE.md의 Spring Boot 버전 복사를 정본 가리키기로 고쳤다.

버린 대안: 예외 목록 하나에 「늘리지 않는다」는 약속만 두는 방식(테스트의
KNOWN_DEVIATIONS와 같은 꼴)은 brief가 요구한 「더하면 실패」를 기계로 막지
못한다. 기준선을 git 이력(merge-base)과 비교하는 방식은 얕은 checkout에서
깨진다. 검사를 link-check.yml에 더하는 방식은 그 workflow가 docs 경로에만
걸리고 repository-contract 테스트가 trigger를 고정한다. CI 재편 때 단계
workflow로 접는다.

위험·한계: 타입 이름 검사(지운 클래스 이름)는 넣지 않았다. 외부 타입과
구분하려면 git 전체 이력이 필요하다. 경로 검사는 루트 폴더로 시작하는
경로만 보므로 src/ 기준 상대 경로(adapter/outbound/...)는 보지 않는다.
leaf 개수 규칙은 설계 문서의 개수 같은 정당한 숫자도 잡을 수 있다(지금
generator 출력 예 하나가 예외 목록에 있다). 구조 정리가 src/messaging 등을
옮기면 예외 줄의 경로가 바뀌므로 그 병합에서 FROZEN을 함께 고쳐야 한다.
레지스트리 yaml 설명 칸의 언어는 보지 않는다.

검증: python3 -m unittest discover -s scripts/tests 42개 통과. 변이 시험:
기준선 확인·낡은 예외 확인·언어 판정·이력 인용 건너뛰기·소스 세트 이름·
끝부분 대조·상태 어휘를 하나씩 끄면 해당 시험이 실패했다.
python3 scripts/check-docs.py rc=0(language 181·reference 7·number 29가
모두 예외, head 0), check-work-docs.py rc=0.
2026-11-07 12:26:37 +09:00