문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
5.4 KiB
결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-30
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
- 대체됨:
docs/capability-status.md
ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다
- 상태: 대체됨(2026-09-28) — 2026-09-25 리뷰 후속의 소유자 결정 18
- 날짜: 2026-08-30
- 범위:
:grpc:grpc-proto-contract,:grpc:grpc-codegen(둘 다 지움)
대체됨. 정규식
.proto검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제:grpc:grpc-contract(src/grpc/grpc-contract/src/main/proto)에 있고 Gradle protobuf 플러그인(com.google.protobuf, 버전은gradle/libs.versions.toml에 고정. protoc와 protobuf-java runtime은 둘 다protobufGrpc)이 컴파일한다. 생성된 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다.buf lint와buf breaking(src/grpc/grpc-contract/buf.yaml, STANDARD lint, FILE breaking)은 CI의.github/workflows/ci-quality-gates.ymljobgrpc-proto-buf에서 돈다. proto organization은caskeleton이다(예전에는hyeonworks). 아래 글은 원래 결정의 기록으로 남긴다.
배경
Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽 컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다.
그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 protoc는 Gradle
protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH
confidence의 SpotBugs, Error Prone, -Werror를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다.
codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다.
그런 예외에는 선례가 있다: jmh source set은 spotbugsJmh와 checkstyleJmh를 끄고 Error Prone도 끈다. 그러니 빼는
길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위
밖이다.
adapter:inbound:grpc에도 반대 방향으로 기록된 결정이 있다: 그 CLAUDE.md는 쓰는 기능 모듈이 자기 schema를 가져야
한다는 이유로 그 leaf에서 protobuf 플러그인과 .proto를 금지한다.
결정
.proto 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다.
GrpcProtoContractValidator는 .proto 글을 읽고 다음을 강제한다: proto3 문법, {organization}.{domain}.v{major}
패키지 규칙, java_multiple_files, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, _UNSPECIFIED enum 0값, 받은 삭제
이력과 대조한 reserved 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고
돌므로, 출하하는 .proto 파일은 장식이 아니라 살아 있다.
GrpcBufPolicy는 breaking gate를 Buf의 FILE category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계
넷을 이름으로 댄다. GrpcCodegenManifest는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다.
GrpcDescriptorArtifact, GrpcConsumerFixture, GrpcSchemaArtifactPublisher는 schema hash, descriptor digest, 쓰는
쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을
거절한다.
커밋한 buf.yaml도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다.
결과
불변식은 강제하고, 과정은 돌리지 않는다. Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤 쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc 호출과 Buf 바이너리다.
codegen을 켜는 것은 한계 있는 변경이다. GrpcCodegenManifest.caSkeleton()이 이미 실제 플러그인 설정이 만족해야
할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set
예외와 플러그인 블록이지 재설계가 아니다.
fixture는 텍스트 codec을 쓴다. GrpcTextCodec이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty
lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지
모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라
오늘 돈다.