Files
grpc-library/grpc-advanced/CLAUDE.md
T
DongHyeonka 829ad58cfd docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 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건)
2026-11-07 07:02:09 +09:00

5.0 KiB

grpc-advanced — local authority for the advanced gRPC capabilities

이 문서는 grpc-advanced:* family의 local authority다. leaf 목록·gradle path·허용 의존성은 src/config/architecture/modules.json이 SSOT다. Root 정책(CLAUDE.md / AGENTS.md)과 충돌하면 root가 이긴다.

이 family는 Stable gRPC 플랫폼(grpc:*)이 의도적으로 제외한 능력들을 담는다. 별도 디렉터리와 별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 불변 조건을 registry의 allowed_dependencies만으로 기계 검증할 수 있게 하기 위해서다.

의존 방향

grpc-advanced:* → grpc:*        (허용)
grpc:*          → grpc-advanced:*  (금지 — registry가 거부한다)

grpc-spring-boot-starter의 registry 엔트리에는 어떤 advanced id도 없다. verifyCleanArchitectureDependencies가 build time에 이 규칙을 강제한다. runtime 검사는 없다.

공용 다이제스트 헬퍼를 복사해 두는 이유

grpc-advanced(GrpcDiagnosticsRedactor)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 grpc-advanced:* → grpc:*로 닫혀 있고 shared-contract edge가 없는 것은 의도다. grpc/CLAUDE.md의 같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).

Capability grade와 feature flag

capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.

grade 시작 가능 production 추가 승인
ADVANCED_STABLE O 불필요
EXPERIMENTAL O 필요
WATCH X (추적만) —
DISABLED X —

property key는 app.grpc.advanced.<capability>.enabled이고 전부 기본 off다. GrpcAdvancedModuleGuard가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.

Leaf별 담당 capability

leaf 패키지(dev.caskeleton.grpc.advanced.*) capability
grpc-advanced bootstrap capability grade, feature flag, module guard, capability별 promotion gate
grpc-advanced edition Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane
grpc-advanced streaming client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control
grpc-advanced resilience·discovery·xds read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS
grpc-advanced diagnostics Channelz/CSDS 진단
grpc-advanced-compat web·integration·reactor·kotlin gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge

grpc-advanced-compat만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 않는 테스트 fixture(grpc-advanced-compat/src/test/resources/envoy/envoy.yaml)다.

Promotion은 capability별로 독립이다

승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 GrpcAdvancedPromotionGate는 자기 테스트 말고 호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 docs/runbooks/grpc-advanced-capabilities.md의 리뷰 규칙이다.

승격 문턱은 두 개다: ADVANCED_STABLE은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.

이 저장소에서 검증할 수 없는 것

capability별로 필요한 실제 인프라가 이 저장소에 없다.

  • grpc-web → gRPC-Web 프록시
  • servlet-compat → Servlet 컨테이너
  • xds → 중지 가능한 xDS control plane
  • kotlin → Kotlin 툴체인

인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. 이 사실을 상수로 반환하던 gate 클래스(GrpcKotlinCompatibilityGate, GrpcAdvancedInfrastructureTestkit 등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.

금지

  • Stable leaf(grpc:*)가 이 family를 참조하는 것.
  • capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
  • WATCH capability를 스키마 소스로 사용하는 것.
  • 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.