템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).
- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
composition:outbox-relay와 app-bootstrap architectureTest. import와
auto-configuration 이름 문자열 dev.caskeleton.messaging →
dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
(../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
의존성 집합은 그대로, 설계 16절 H6).
버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).
위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).
검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.
BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).
Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
repo 훅
Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 .claude/settings.json, 본체는 hooks.py 하나, 시험은 scripts/tests/test_hooks.py다. 모델이 잊어도 돈다.
Edit·Write 직전 ──> pre-edit ──> H13 적용된 migration이면 막는다(종료 코드 2)
Edit·Write 직후 ──> post-edit ──> Java면 포맷 → N1 레이어 의존 알림, 문서면 N2 문서 검사 알림
Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 N5 기록을 비운다
턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 한 번 알린다
1. 원칙
- 되돌릴 수 없는 것만 막는다. 나머지는 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다.
- 훅은 게이트의 일부만 본다. 정본은 게이트(desktop
architectureCheck,spotlessCheck, 문서 검사)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다. - 노트북에서 Gradle·Docker를 돌리지 않는다. 포매터는 Gradle 없이 JVM 하나로 파일 하나만 맞춘다(소유자 결정 2026-11-07).
- 받거나 설치하지 않는다. 포매터 jar는 Gradle이 이미 캐시에 받아 둔 것만 쓴다. 없으면 건너뛰고 세션에 한 번 알린다.
- 표준 라이브러리만 쓴다. 되돌릴 수 없는 명령 차단(force push, 범위 밖
rm -rf, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 몫이다.
2. 훅마다
| ID | 때 | 하는 일 | 결과 |
|---|---|---|---|
| H13 | PreToolUse Edit|Write|MultiEdit |
src/**/src/main/resources/db/migration/<키>의 <키>가 src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256에 있으면 막는다 |
종료 코드 2와 「새 버전 파일을 더한다」 안내 |
| 포맷 | PostToolUse Edit|Write|MultiEdit |
src/**/*.java(build-logic과 build/ 제외)를 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 <desktop 호스트> … gradlew … 실행이 없으면 턴을 한 번 막고 이유를 준다 |
decision: block, 다음 Java 편집 전까지 한 번 |
- N5가 기억하는 것은
.claude/hook-state/<session_id>.json이다(git이 무시한다). - 권한 쪽 차단:
.claude/settings.json의permissions.deny가 실제.env·.env.local·.env.lane읽기·쓰기를 막는다..env.example같은 예시는 막지 않는다.
3. 시험
python3 -m unittest discover -s scripts/tests
- 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다.
- 실제 포매터 시험은 Gradle 캐시에 카탈로그 버전 jar가 있는 기계에서만 돈다. 그 밖에서는 가짜
java로 옵션·파일 전달·바뀜 감지를 본다. - 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다.
4. 끄기
훅이 시끄럽거나 틀리면 .claude/settings.json에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 .claude/settings.local.json(git이 무시한다)에 "disableAllHooks": true를 둔다.