문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시 없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는 거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다. 고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의 .md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일· 요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄 두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함). - 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거). - 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는 설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」. capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」, 2026-07-20 하네스 설계·계획과 production capability platform 설계는 「대체됨」이다. - 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신 docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다. docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와 코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록 충돌 가능성을 적었다. 버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이 파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는 안은 폴더와 같은 정보를 두 번 쓰게 한다. 위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지 아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을 끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다 (납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는 아직 머리 블록을 달지 않았다. 검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
4.9 KiB
결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-30
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
- 현재 정본:
docs/compatibility/grpc-support-matrix.md - 대체됨:
docs/capability-status.md
ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
- Status: superseded (2026-09-28) by owner decision 18 of the 2026-09-25 review follow-up
- Date: 2026-08-30
- Scope:
:grpc:grpc-proto-contract,:grpc:grpc-codegen(both removed)
Superseded. The regex
.protovalidator and the Java re-implementation of Buf's rules were deleted. The schema now lives in:grpc:grpc-contract(src/grpc/grpc-contract/src/main/proto), compiled by the Gradle protobuf plugin (com.google.protobuf, version pinned insrc/gradle/libs.versions.toml; protoc and the protobuf-java runtime are bothprotobufGrpc). Generated sources are excluded from Spotless, Checkstyle and Error Prone in that leaf only.buf lintandbuf breaking(src/grpc/grpc-contract/buf.yaml, STANDARD lint, FILE breaking) run in CI, jobgrpc-proto-bufin.github/workflows/ci-quality-gates.yml. The proto organization iscaskeleton(washyeonworks). The text below is kept as the record of the original decision.
Context
Stable Tasks 8 through 11 require proto style rules, Buf format/lint/breaking governance, a single Java codegen owner, and a descriptor artifact whose consumer-compile result gates a release.
Two of the tools those tasks name are absent from this toolchain. The Buf CLI is not installed. And
protoc is available through the Gradle protobuf plugin, but every leaf in this repository passes
spotless with google-java-format, checkstyle, SpotBugs at HIGH confidence, Error Prone and -Werror
— and generated protobuf sources pass none of them. Turning codegen on means excluding a source set
from five quality gates.
There is precedent for such an exclusion: the jmh source set has spotbugsJmh and checkstyleJmh
disabled and Error Prone off. So the carve-out is available. It is also a decision about the quality
baseline of a leaf, taken for one task, and outside what this work was asked to change.
adapter:inbound:grpc also carries a recorded decision in the opposite direction: its CLAUDE.md
forbids the protobuf plugin and .proto in that leaf, on the grounds that a consuming feature module
should own its schema.
Decision
Commit the .proto sources and implement every rule the tasks require as executable Java, with no
protoc run and no Buf CLI invocation.
GrpcProtoContractValidator reads .proto text and enforces proto3 syntax, the
{organization}.{domain}.v{major} package rule, java_multiple_files, a generated Java package
disjoint from the hand-written one, _UNSPECIFIED enum zero values, reserved declarations checked
against a supplied removal history, a well-known-type allowlist and a map-field allowlist. It runs
against the committed schema in its own test, so the shipped .proto files are live rather than
decorative.
GrpcBufPolicy fixes the breaking gate at Buf's FILE category and names the four lifecycle stages
a compliant pipeline registers. GrpcCodegenManifest fixes one codegen owner and refuses a literal
generator version. GrpcDescriptorArtifact, GrpcConsumerFixture and GrpcSchemaArtifactPublisher
carry the schema hash, the descriptor digest and the per-consumer source-break report, and refuse a
publish that breaks a consumer or republishes a released version with different bytes.
The committed buf.yaml states the same rules, so running the CLI in an environment that has it
reaches the same verdict.
Consequences
The invariants are enforced; the process is not run. Everything Tasks 8 to 11 are about — which schema changes are refused, which consumer breaks block a release, who owns generation — is a build-checkable rule here. What is missing is the protoc invocation and the Buf binary.
Turning codegen on is a bounded change. GrpcCodegenManifest.caSkeleton() already names the
owner, the managed version source, the build-directory output paths and the disjoint package policy
that a real plugin configuration has to satisfy. The work is a source-set carve-out and a plugin
block, not a redesign.
The fixtures use a text codec. GrpcTextCodec gives the testkit a UTF-8 marshaller so the
in-process and Netty lanes can exercise interceptors, status mapping, metadata limits and stream
sequencing without generated stubs. Those contracts are properties of the platform and the transport,
not of any message shape, so the substitution costs nothing — and the lanes run today rather than
after codegen lands.