From 829ad58cfdb085ecc8577832f5c13718d20aa8b1 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건) --- grpc-advanced/CLAUDE.md | 6 +++--- grpc/CLAUDE.md | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/grpc-advanced/CLAUDE.md b/grpc-advanced/CLAUDE.md index 12b53b2..158830a 100644 --- a/grpc-advanced/CLAUDE.md +++ b/grpc-advanced/CLAUDE.md @@ -18,11 +18,11 @@ grpc:* → grpc-advanced:* (금지 — registry가 거부한다) `grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. `verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. -### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11) +### 공용 다이제스트 헬퍼를 복사해 두는 이유 `grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 `grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의 -같은 절과 이유가 같다(vendored 플랫폼, MSG-023 §6.2와 같은 배치). +같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). ## Capability grade와 feature flag @@ -61,7 +61,7 @@ property key는 `app.grpc.advanced..enabled`이고 전부 기본 off 승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 -호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 +호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 리뷰 규칙이다. 승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 diff --git a/grpc/CLAUDE.md b/grpc/CLAUDE.md index 5705281..dbaaccd 100644 --- a/grpc/CLAUDE.md +++ b/grpc/CLAUDE.md @@ -41,13 +41,13 @@ server profile·named channel profile·method size profile·method policy 기본 `caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. -### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11) +### 공용 다이제스트 헬퍼를 복사해 두는 이유 `grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). `shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging -family가 같은 이유로 고른 배치(MSG-023 §6.2)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 +family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 같은 규칙인지 함께 본다. ## 증거 등급 — testkit이 하나의 leaf인 이유 @@ -95,7 +95,7 @@ soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위 ## application이 이 family에 도달하는 경로 -`messaging:*`의 MSG-015(bridge 부재)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 +`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 ```text application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI @@ -164,9 +164,9 @@ These keys are not in `docs/registries/env-keys.yaml`: no `app.grpc.platform.*` optional build is not part of the shipped runtime. They join the registry when a composition root adopts the platform. -**Why the starter assembles the interceptor (03-11 (b)), and not (a).** The review proposed (a): -delete the flag and judge by whether a ledger bean exists. (b) was chosen and is recorded in -ADR-GRPC-004 (re-review 2026-11-03, RR-02-07): the flag stays and means what it says — when true, the +**Why the starter assembles the interceptor (option (b)), and not (a).** The 2026-11-01 maturity review proposed (a): +delete the flag and judge by whether a ledger bean exists. (b) was chosen on 2026-11-03 and is recorded in +ADR-GRPC-004: the flag stays and means what it says — when true, the decision function is assembled and its TTL comes from configuration. (a) would have removed the false promise but left every adopter to rebuild the same assembly and TTL validation by hand; (b) keeps that in one place. The interceptor bean has no `@ConditionalOnMissingBean` on purpose: a replacement would silently ignore `operation-ledger-claim-ttl`. @@ -182,7 +182,7 @@ its typed service adapter: `decide(...)` before the mutation, `recordCommit(...) transaction, `recordFailure(...)` on a terminal failure. Both record calls take the `GrpcClaimToken` the `PROCEED` decision carried: a commit by an attempt whose claim was taken over is refused (its transaction rolls back) and its failure is ignored, so a slow owner cannot write over the attempt that -took its claim (re-review RR-02-04, ADR-GRPC-004). +took its claim (ADR-GRPC-004). **Purge scheduling is the adopter's.** `GrpcOperationLedgerRetention.purgeExpired(now)` deletes expired finished rows in bounded batches (500 per statement) until a batch comes back short. The