From 927de097d95d2e1b28cf3f9c69be571e6a4fade1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 07:02:09 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20=EC=9D=B4=EB=A0=A5=20ID=200=20?= =?UTF-8?q?=EA=B7=9C=EC=B9=99=EC=9D=84=20AGENTS.md=EC=99=80=20src/**/CLAUD?= =?UTF-8?q?E.md=EB=A1=9C=20=EB=84=93=ED=9E=8C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다. 새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰 05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을 수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로 했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는 넓히지 않는다. 고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는 발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계 기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과 코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지 보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006), 리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호 (03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID. 날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다. 문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는 커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음 커밋 — 중간 커밋이 rc=1이 된다. 위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review· decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews 밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의 실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만 repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은 문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음). 검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그 ~/manual-gap-fix-2-logs/A-*): - python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0, lychee 범위 --links rc=0(578파일, 깨짐 0) - ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0) - ./gradlew :adapter:outbound:persistence-mongo:test --tests 'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun rc=0(3건) --- messaging/CLAUDE.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/messaging/CLAUDE.md b/messaging/CLAUDE.md index 931c282..eda4b57 100644 --- a/messaging/CLAUDE.md +++ b/messaging/CLAUDE.md @@ -26,21 +26,21 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이 `InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을, `messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을 갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께 -가졌고 inbox도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring +가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL 전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다. -### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11) +### 공용 다이제스트 헬퍼를 복사해 두는 이유 `messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check` (`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 -계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(MSG-023 §6.2), `messaging:*` leaf는 +계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는 `domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 `shared-contract`의 정본과 같은 규칙인지 함께 본다. -### Publish retryability of authentication and authorization (review 2026-11-01 06-01) +### Publish retryability of authentication and authorization 이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. @@ -63,7 +63,7 @@ registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길 번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 `PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application -relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(재리뷰 2026-11-03 RR-05-07). +relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03). ## Public surface 정책 @@ -95,7 +95,7 @@ RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium 새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, qualification/support 상태를 함께 변경한다. -## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료) +## application이 이 family에 도달하는 경로 (cutover 완료) 리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한 `application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다. @@ -110,7 +110,7 @@ lease/transport/outcome normalization/observation은 platform 중앙 publish pat package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을 직접 보지 않는다. -**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical +**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical `OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy `OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지 않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security @@ -137,7 +137,7 @@ adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/ 3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은 증거가 아니다. 4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 - Experimental에서도 금지다(MSG-022). + Experimental에서도 금지다. 5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가 있을 때만.