템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼(src/platforms/grpc·grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행·workflow job 넷과 단계 하나·build-logic 플러그인 둘·카탈로그와 SpotBugs 항목·살아 있는 문서를 템플릿이 함께 지고 있었다.
DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험
grpc-library의 lane 단계 검사(verifyStrictLaneStages)
남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), 기록 문서(ADR-GRPC 7개·gRPC 설계서·리뷰·history는 본문 그대로, 기록 9개의 머리 블록 「현재 정본」만 grpc-library를 가리킨다).
고른 방법과 버린 대안
이력: git filter-repo로 옛 경로(src/grpc*, src/optional-platforms)와 지금 경로(src/platforms/…)를 함께 넘겼다(Q12). 옮긴 코드 폴더의 트리 해시가 기준 커밋 22df3525과 같다. subtree split은 2026-11-07 이동 전 이력을 잃어 버렸다.
템플릿 쪽은 지우기만 한다. gRPC 소비자가 없어 「버전으로 받기」 단계가 비어 있다(Q13, 설계 4.6절).
옮긴 기록 문서는 처음에 같이 지웠다가 되살렸다. 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md가 설계서를 상대 링크로 부르는데, 기록 본문은 고치지 않는 규칙이라 링크를 고칠 수 없었다(desktop check-work-docs --links·lychee가 잡았다). 기록은 그때 템플릿 안 코드를 두고 한 결정이라 템플릿에 남는 것이 맞다(Q15와 같은 이유).
build-logic의 MainBuild(두 번째 빌드에서 주 빌드를 찾던 위로 걷기)는 두 번째 빌드가 없어져 지웠다. 세 곳이 Gradle 루트(src/)의 config/를 바로 읽는다. registry의 build 칸 지원(ModuleRegistry)은 일반 기능이라 남겼다.
registry build 칸: 두 번째 빌드가 없어진 뒤 main이 아닌 값을 적은 leaf는 조용히 빌드에서 빠진다(구조 리뷰가 찾음). ModuleRegistry가 그 칸을 거절한다. 칸과 modulesForBuild를 통째로 지우는 안은 settings 설치기·ArchitecturePlugin 시그니처까지 바꾸고 막는 효과는 같아 버렸다.
하네스: .claude/settings.json에 extraKnownMarketplaces·enabledPlugins 두 키만 더했다. 기존 deny·repo 훅은 그대로다. 사용자 전역에 H12가 있으면 플러그인 H12는 스스로 건너뛴다(소유자 기계가 그렇다).
라이브러리 쪽 결정(설계로 답이 안 나온 것, 근거는 grpc-library README와 build-logic/UPSTREAM.md):
leaf 폴더는 grpc/<leaf>·grpc-advanced/<leaf> 그대로, Gradle 경로도 :grpc:… 그대로. registry·문서가 그대로 맞고 ADR-GRPC-001의 접두사 분리가 폴더로 남는다.
Maven group·Java 패키지는 dev.cakit.grpc, proto는 cakit.grpc.common.v1(grpc-library PR #2, 소유자 지시로 개인 도메인 com.hyeonworks에서 바꿈). 템플릿 재사용 체크리스트의 dev.caskeleton 일괄 바꾸기와 겹치지 않는 이름이다. 생성 proto Java 패키지는 cakit.grpc.common.v1.generated로, 손으로 쓴 루트와 겹치지 않는다는 기존 규칙(시험이 고정)을 지킨다.
Buf는 Gradle 태스크(bufLint·bufBreaking)로 ci에 넣었다. job은 Gradle 한 줄이어야 하고(7.1절), 바이너리는 scripts/tool.sh가 SHA-256으로 고정해 받는다. 기준은 PR이면 대상 브랜치의 merge base, main이면 직전 커밋.
SBOM은 CycloneDX Gradle 플러그인 대신 이미 고정해 쓰는 Trivy로 만든다(도구를 늘리지 않는다). artifact dev.cakit.grpc:grpc-library:<버전>:cyclonedx@json.
api-surface 플러그인은 복사했지만 아직 모듈에 켜지 않았다(기준선 파일과 정책은 새 결정).
위험과 영향
파생 서비스: 이 경로를 고쳤으면 「수정 대 삭제」 충돌, :grpc:*·ca.grpc-platform-module·지운 카탈로그 alias를 쓰면 빌드 실패. 안내는 docs/upgrade/2026-11-maturity-review.md 3.8절 B-55·B-56. tech-log-backend는 플랫폼을 받은 적이 없다(설계 12절).
분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 달려면 22df3525에 단다.
템플릿 .github/actions/setup-gradle-java의 JDK 고정값 21.0.11+10은 Gitea runner의 setup-java가 「Could not find satisfied version」으로 거부했다(grpc-library main run 1). Temurin 이름은 21.0.11+10.0.LTS다. 템플릿 Actions는 아직 꺼져 있어 드러나지 않았다. CI 재편 세션 몫이라 고치지 않았다.
하네스 플러그인: 이 세션은 ~/.claude를 바꾸지 않아 설치는 하지 않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다.
검증
desktop, 새 detached worktree ~/x2-template-wt(기준 22df3525 = main, 그래서 이 브랜치 트리가 곧 합친 트리), Gradle 명령마다 --no-build-cache, 공유 잠금 아래 하나씩. 로그 ~/x2-grpc-library-logs/template/(1회차 round1/, 최종 final-*). 1회차 시작 부하 6.97.
configuration-cache job 세 줄, :integrationCheck, :performanceCheck, http3 실험 lane
1회차
0
integration 958, performance 26, http3 360
main
compose runtime smoke(전 lane), 빠른 시작(scripts/bootstrap-local.sh, healthcheck 200)
1회차
0
태그
:releaseCheck -PgitRevision
57988c2e
0
「태그 단계 — 라운드 끝 아님」. 1회차도 0
최종 트리 a2dbf33b(PR head)에서 다시 돌린 것(새 worktree, --no-build-cache, 로그 final2-*): :integrationCheck rc=0(958 tests, 265 tasks 모두 실행), :performanceCheck rc=0(26), compose runtime smoke rc=0(blocking 18 lane 모두 통과), 빠른 시작 scripts/bootstrap-local.sh rc=0(healthcheck HTTP 200, status=UP), :releaseCheck rc=0.
a2dbf33b(grpc-library 이름을 dev.cakit.grpc로 맞춤: 문서 넷과 카탈로그 주석 한 줄): 새 worktree에서 :verifyDependencyLocks :architectureCheck rc=0(317 tasks 모두 실행, 캐시 없음), verifyStrictLaneStages --dry-run rc=0, check-docs·check-work-docs(--links 포함) rc=0. 그 밖의 게이트는 Gradle 동작이 바뀌지 않아 다시 돌리지 않았다.
e1dd8e74는 위 최종 트리 57988c2e에 장부(docs/ledger/estimates.jsonl) 두 줄을 더한 것이다. 장부는 어떤 게이트의 입력도 아니다(check-work-docs.py rc=0으로 형식만 확인).
1회차 뒤 바뀐 것은 기록 문서 복원(머리 블록만), testkit 주석 줄바꿈, build-logic ModuleRegistry의 build 칸 거절과 문장 넷이다. 그래서 ci·build-logic·문서 게이트와 mainCheck·releaseCheck를 최종 트리에서 다시 돌렸고, 컨테이너 lane·smoke·빠른 시작은 1회차 결과다.
RED→GREEN: ModuleRegistryTest.aBuildFieldIsRejected…가 고치기 전 실패(9 tests, 1 failed), 고친 뒤 통과.
구조 리뷰(arch-reviewer): 차단 0, 권고 5 → 모두 57988c2e에서 고침.
grpc-library 쪽(desktop과 Gitea runner):
Gitea Actions(desktop-runner): main run 2 8d705bca 성공(mainCheck, Testcontainers PostgreSQL 포함), PR run 3 ce83f4d5 성공(ci·verifyStrictLaneStages --dry-run), PR #1·#2·#3 모두 runner pr 성공 후 총괄이 병합. v1.0.0 태그(2e880c75)의 release run 22 성공: 모듈 9개와 SBOM이 Gitea Packages에 게시됐고 익명으로 받힌다. 게시 jar의 .asc는 릴리스 키로 Good signature. main run 1은 JDK 이름 때문에 실패했고 고쳤다.
desktop: ci --rerun-tasks rc=0(130 tasks, build-logic 시험 포함), verifyStrictLaneStages --dry-run rc=0, mainCheck rc=0, releaseRehearsal rc=0(9개 모듈 + SBOM, 체크섬 넷, POM·module의 모든 의존성에 버전), 버리는 시험 키로 서명한 리허설 rc=0과 gpg --verify Good signature(키는 임시 폴더째 지움). bufBreaking은 이름 바꾸기 전 커밋과 비교하면 깨짐을 잡는다(1.0.0 전 한 번의 변경).
트리 대조: 옮긴 grpc·grpc-advanced 트리 해시와 optional 빌드 파일 다섯, 문서 열둘이 22df3525과 같다.
리뷰어가 볼 곳
src/build-logic/src/main/java/dev/caskeleton/buildlogic/{architecture/ArchitecturePlugin,java/JavaConventionsPlugin,quality/QualityConventionsPlugin}.java: MainBuild 대신 Gradle 루트 경로.
src/config/spotbugs/exclude.xml: 섞인 <Or>에서 gRPC 줄만 뺐다.
## 무엇을, 왜
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼(`src/platforms/grpc`·`grpc-advanced`)과 그것만을 위한 두 번째 Gradle 빌드(`src/platforms/optional-build`)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행·workflow job 넷과 단계 하나·build-logic 플러그인 둘·카탈로그와 SpotBugs 항목·살아 있는 문서를 템플릿이 함께 지고 있었다.
소유자 결정(2026-11-07, design-docs `repo-structure/README.md` 3.5절, `05-library-repos.md` Q1~Q17 모두 「권함」 승인)대로 gRPC를 별도 repo [grpc-library](https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library)로 옮기고 템플릿에서 지운다. 같은 PR에서 하네스 플러그인 `harness@claude-harness`를 켠다.
| 지운 것 | 새 자리 |
| --- | --- |
| `src/platforms/grpc`, `grpc-advanced`, `optional-build`(343파일) | grpc-library `grpc/`, `grpc-advanced/`, 루트 빌드(이력째, filter-repo) |
| registry `"build": "optional-grpc"` 9행 | grpc-library `config/architecture/modules.json` |
| `ci-quality-gates.yml` job `optional-platforms`·`grpc-proto-buf`와 `release-gate`의 두 needs | grpc-library `pr.yml`(`./gradlew ci`, Buf 포함) |
| `integration-main.yml` optional 성능 단계, job `grpc-optional-platform-integration` | grpc-library `main.yml`(`./gradlew mainCheck`) |
| `release.yml` job `grpc-stable-release-gate`와 이미지 job의 needs 한 줄 | grpc-library `release.yml`(`./gradlew releaseCheck release`) |
| build-logic `ca.grpc-platform-module`, `ca.optional-architecture-registry`, `MainBuild` | grpc-library `build-logic/`(사본, `UPSTREAM.md`) |
| 카탈로그 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf` | grpc-library 카탈로그. 템플릿에는 좌표도 넣지 않는다(Q14) |
| SpotBugs 제외의 gRPC 클래스 줄 | grpc-library `config/spotbugs/` |
| 살아 있는 문서 `docs/compatibility/`(폴더째), gRPC runbook 둘 | grpc-library `docs/` |
| `DeveloperExperienceContractTest`의 optional 빌드 lane 계약 시험 | grpc-library의 lane 단계 검사(`verifyStrictLaneStages`) |
남긴 것: `adapter:inbound:grpc`(`io.grpc`를 직접 쓰고 플랫폼을 쓰지 않는다), `src/platforms/messaging`(다음 분리 작업), 기록 문서(ADR-GRPC 7개·gRPC 설계서·리뷰·history는 본문 그대로, 기록 9개의 머리 블록 「현재 정본」만 grpc-library를 가리킨다).
## 고른 방법과 버린 대안
- 이력: `git filter-repo`로 옛 경로(`src/grpc*`, `src/optional-platforms`)와 지금 경로(`src/platforms/…`)를 함께 넘겼다(Q12). 옮긴 코드 폴더의 트리 해시가 기준 커밋 `22df3525`과 같다. `subtree split`은 2026-11-07 이동 전 이력을 잃어 버렸다.
- 템플릿 쪽은 지우기만 한다. gRPC 소비자가 없어 「버전으로 받기」 단계가 비어 있다(Q13, 설계 4.6절).
- 옮긴 기록 문서는 처음에 같이 지웠다가 되살렸다. 기록 `docs/history/plans/2026-08-30-grpc-platform-implementation.md`가 설계서를 상대 링크로 부르는데, 기록 본문은 고치지 않는 규칙이라 링크를 고칠 수 없었다(desktop `check-work-docs --links`·lychee가 잡았다). 기록은 그때 템플릿 안 코드를 두고 한 결정이라 템플릿에 남는 것이 맞다(Q15와 같은 이유).
- build-logic의 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 위로 걷기)는 두 번째 빌드가 없어져 지웠다. 세 곳이 Gradle 루트(`src/`)의 `config/`를 바로 읽는다. registry의 `build` 칸 지원(`ModuleRegistry`)은 일반 기능이라 남겼다.
- registry `build` 칸: 두 번째 빌드가 없어진 뒤 main이 아닌 값을 적은 leaf는 조용히 빌드에서 빠진다(구조 리뷰가 찾음). `ModuleRegistry`가 그 칸을 거절한다. 칸과 `modulesForBuild`를 통째로 지우는 안은 settings 설치기·ArchitecturePlugin 시그니처까지 바꾸고 막는 효과는 같아 버렸다.
- 하네스: `.claude/settings.json`에 `extraKnownMarketplaces`·`enabledPlugins` 두 키만 더했다. 기존 deny·repo 훅은 그대로다. 사용자 전역에 H12가 있으면 플러그인 H12는 스스로 건너뛴다(소유자 기계가 그렇다).
- 라이브러리 쪽 결정(설계로 답이 안 나온 것, 근거는 grpc-library README와 `build-logic/UPSTREAM.md`):
- leaf 폴더는 `grpc/<leaf>`·`grpc-advanced/<leaf>` 그대로, Gradle 경로도 `:grpc:…` 그대로. registry·문서가 그대로 맞고 ADR-GRPC-001의 접두사 분리가 폴더로 남는다.
- Maven group·Java 패키지는 `dev.cakit.grpc`, proto는 `cakit.grpc.common.v1`(grpc-library PR #2, 소유자 지시로 개인 도메인 `com.hyeonworks`에서 바꿈). 템플릿 재사용 체크리스트의 `dev.caskeleton` 일괄 바꾸기와 겹치지 않는 이름이다. 생성 proto Java 패키지는 `cakit.grpc.common.v1.generated`로, 손으로 쓴 루트와 겹치지 않는다는 기존 규칙(시험이 고정)을 지킨다.
- Buf는 Gradle 태스크(`bufLint`·`bufBreaking`)로 `ci`에 넣었다. job은 Gradle 한 줄이어야 하고(7.1절), 바이너리는 `scripts/tool.sh`가 SHA-256으로 고정해 받는다. 기준은 PR이면 대상 브랜치의 merge base, main이면 직전 커밋.
- SBOM은 CycloneDX Gradle 플러그인 대신 이미 고정해 쓰는 Trivy로 만든다(도구를 늘리지 않는다). artifact `dev.cakit.grpc:grpc-library:<버전>:cyclonedx@json`.
- `api-surface` 플러그인은 복사했지만 아직 모듈에 켜지 않았다(기준선 파일과 정책은 새 결정).
## 위험과 영향
- 파생 서비스: 이 경로를 고쳤으면 「수정 대 삭제」 충돌, `:grpc:*`·`ca.grpc-platform-module`·지운 카탈로그 alias를 쓰면 빌드 실패. 안내는 `docs/upgrade/2026-11-maturity-review.md` 3.8절 B-55·B-56. `tech-log-backend`는 플랫폼을 받은 적이 없다(설계 12절).
- 분리 직전 커밋 태그 `pre-library-split`(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 달려면 `22df3525`에 단다.
- 템플릿 `.github/actions/setup-gradle-java`의 JDK 고정값 `21.0.11+10`은 Gitea runner의 setup-java가 「Could not find satisfied version」으로 거부했다(grpc-library main run 1). Temurin 이름은 `21.0.11+10.0.LTS`다. 템플릿 Actions는 아직 꺼져 있어 드러나지 않았다. CI 재편 세션 몫이라 고치지 않았다.
- 하네스 플러그인: 이 세션은 `~/.claude`를 바꾸지 않아 설치는 하지 않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다.
## 검증
desktop, 새 detached worktree `~/x2-template-wt`(기준 `22df3525` = main, 그래서 이 브랜치 트리가 곧 합친 트리), Gradle 명령마다 `--no-build-cache`, 공유 잠금 아래 하나씩. 로그 `~/x2-grpc-library-logs/template/`(1회차 `round1/`, 최종 `final-*`). 1회차 시작 부하 6.97.
| 단계 | 게이트 | 트리 | rc | 수 |
| --- | --- | --- | --- | --- |
| PR | `:ci :verifyDependencyLocks --warning-mode=fail` | 1회차 `2921f596` | 1 | 7389 tests 실패 0. persistence-jpa testkit 주석 Spotless 1건 → `91804ec1`에서 고침 |
| PR | 같은 줄 | `57988c2e`(+ 장부 한 줄) | 0 | 7389 tests, 실패 0, skip 28, FROM-CACHE 0 |
| PR | `-p build-logic check javadoc` | `57988c2e` | 0 | 172 tests(1회차 `-p build-logic test` 171) |
| PR | `verifyStrictLaneStages --dry-run`, compose 계약, `check-repo-layout`, 문서 자기 시험, `check-docs`, `check-work-docs`(이력·`--links`·리뷰 색인) | `57988c2e` | 0 | 1회차의 `--links` broken 1(기록이 지운 설계서를 링크) → 기록 복원으로 0 |
| PR(경로) | fileserver 다섯, minio contract, jpa-pg16·pg18 contract, jpa migration, notification `pr` 일곱 | 1회차 | 0 | jpa 각 432, migration 45, notification 432+45 |
| PR(도구) | lychee 0.22.0(이미지), trivy 0.71.2 HIGH·CRITICAL | 1회차·`91804ec1` | 0 | lychee 1회차 Error 1(위와 같은 링크) → 0 |
| main | `:mainCheck --continue --warning-mode=fail` | `57988c2e` | 0 | 417 tests, 실패 0. 바깥 빌드 FROM-CACHE 0, 중첩 빌드(`verifyFeatureScaffold`) FROM-CACHE 10 |
| main | configuration-cache job 세 줄, `:integrationCheck`, `:performanceCheck`, http3 실험 lane | 1회차 | 0 | integration 958, performance 26, http3 360 |
| main | compose runtime smoke(전 lane), 빠른 시작(`scripts/bootstrap-local.sh`, healthcheck 200) | 1회차 | 0 | |
| 태그 | `:releaseCheck -PgitRevision` | `57988c2e` | 0 | 「태그 단계 — 라운드 끝 아님」. 1회차도 0 |
- **최종 트리 `a2dbf33b`(PR head)에서 다시 돌린 것(새 worktree, `--no-build-cache`, 로그 `final2-*`)**: `:integrationCheck` rc=0(958 tests, 265 tasks 모두 실행), `:performanceCheck` rc=0(26), compose runtime smoke rc=0(blocking 18 lane 모두 통과), 빠른 시작 `scripts/bootstrap-local.sh` rc=0(healthcheck HTTP 200, status=UP), `:releaseCheck` rc=0.
- `a2dbf33b`(grpc-library 이름을 `dev.cakit.grpc`로 맞춤: 문서 넷과 카탈로그 주석 한 줄): 새 worktree에서 `:verifyDependencyLocks :architectureCheck` rc=0(317 tasks 모두 실행, 캐시 없음), `verifyStrictLaneStages --dry-run` rc=0, `check-docs`·`check-work-docs`(`--links` 포함) rc=0. 그 밖의 게이트는 Gradle 동작이 바뀌지 않아 다시 돌리지 않았다.
- `e1dd8e74`는 위 최종 트리 `57988c2e`에 장부(`docs/ledger/estimates.jsonl`) 두 줄을 더한 것이다. 장부는 어떤 게이트의 입력도 아니다(`check-work-docs.py` rc=0으로 형식만 확인).
- 1회차 뒤 바뀐 것은 기록 문서 복원(머리 블록만), testkit 주석 줄바꿈, build-logic `ModuleRegistry`의 `build` 칸 거절과 문장 넷이다. 그래서 ci·build-logic·문서 게이트와 `mainCheck`·`releaseCheck`를 최종 트리에서 다시 돌렸고, 컨테이너 lane·smoke·빠른 시작은 1회차 결과다.
- RED→GREEN: `ModuleRegistryTest.aBuildFieldIsRejected…`가 고치기 전 실패(9 tests, 1 failed), 고친 뒤 통과.
- `mainCheck`의 FROM-CACHE는 중첩 빌드(`verifyFeatureScaffold`)의 것이다(gates.md 3절).
- 구조 리뷰(arch-reviewer): 차단 0, 권고 5 → 모두 `57988c2e`에서 고침.
grpc-library 쪽(desktop과 Gitea runner):
- Gitea Actions(`desktop-runner`): main run 2 `8d705bca` 성공(`mainCheck`, Testcontainers PostgreSQL 포함), PR run 3 `ce83f4d5` 성공(`ci`·`verifyStrictLaneStages --dry-run`), PR #1·#2·#3 모두 runner pr 성공 후 총괄이 병합. `v1.0.0` 태그(`2e880c75`)의 release run 22 성공: 모듈 9개와 SBOM이 Gitea Packages에 게시됐고 익명으로 받힌다. 게시 jar의 `.asc`는 릴리스 키로 Good signature. main run 1은 JDK 이름 때문에 실패했고 고쳤다.
- desktop: `ci --rerun-tasks` rc=0(130 tasks, build-logic 시험 포함), `verifyStrictLaneStages --dry-run` rc=0, `mainCheck` rc=0, `releaseRehearsal` rc=0(9개 모듈 + SBOM, 체크섬 넷, POM·module의 모든 의존성에 버전), 버리는 시험 키로 서명한 리허설 rc=0과 `gpg --verify` Good signature(키는 임시 폴더째 지움). `bufBreaking`은 이름 바꾸기 전 커밋과 비교하면 깨짐을 잡는다(1.0.0 전 한 번의 변경).
- 트리 대조: 옮긴 `grpc`·`grpc-advanced` 트리 해시와 optional 빌드 파일 다섯, 문서 열둘이 `22df3525`과 같다.
## 리뷰어가 볼 곳
- `src/build-logic/src/main/java/dev/caskeleton/buildlogic/{architecture/ArchitecturePlugin,java/JavaConventionsPlugin,quality/QualityConventionsPlugin}.java`: `MainBuild` 대신 Gradle 루트 경로.
- `src/config/spotbugs/exclude.xml`: 섞인 `<Or>`에서 gRPC 줄만 뺐다.
- `.github/workflows/*.yml`: 지운 job과 needs.
- `docs/work/reference/related-repos.md`(새 문서), `decisions.md` 「라이브러리 repo」 행.
- 기계적으로 만든 부분: 플랫폼 폴더 삭제(`git rm -r`), registry 행 삭제(`"build": "optional-grpc"`인 행만 지운 스크립트, diff는 삭제 84줄뿐).
## 관련
- 설계: design-docs `repo-structure/05-library-repos.md`(승인 2026-11-07), `repo-structure/README.md` 3.5절
- 라이브러리: https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library (PR https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library/pulls/1)
- 다음: 메시징 분리, CI 재편
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼
(src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드
(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데,
registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘,
카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절,
05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다.
gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13).
코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리
해시가 이 기준 커밋 22df3525와 같다).
지운 것:
- src/platforms/grpc, grpc-advanced, optional-build(343파일)
- registry의 "build": "optional-grpc" 9행
- ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs,
integration-main.yml optional 성능 단계와 job
grpc-optional-platform-integration, release.yml job
grpc-stable-release-gate와 이미지 job의 needs 한 줄
- build-logic ca.grpc-platform-module·ca.optional-architecture-registry,
MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의
optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다
- 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14:
채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄
- 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘,
gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리
블록 「현재 정본」만 새 자리를 말하게 했다
- DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험,
adopter API 표면 검사의 optional-build 제외 경로
남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),
src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원
(ModuleRegistry, 일반 기능).
살아 있는 문서: README, docs 지도, capability-status, work/delegate·
gates·decisions(새 행 「라이브러리 repo」)·defect-patterns·
review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로),
manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석.
새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이
고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56.
위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다
(tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전
커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지
않았다.
검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck,
compose smoke, 빠른 시작). 문서 검사 셋 rc=0.
BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:*
프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin
protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로
받는다(docs/upgrade/2026-11-maturity-review.md 3.8절).
Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
공통 훅·스킬(되돌릴 수 없는 명령 차단 H12, 비밀 값 알림, 예측·실측
장부 기록, estimate·retro·techdebt)은 claude-harness repo의 플러그인이
준다. 이 repo는 그 플러그인을 켜지 않아 새 세션이 그것들을 받지 못했다.
.claude/settings.json에 extraKnownMarketplaces(claude-harness, git URL)와
enabledPlugins를 더했다. 기존 deny와 repo 훅은 그대로다. 사용자 전역에
같은 H12가 등록돼 있으면 플러그인 H12는 스스로 아무것도 하지 않는다
(소유자 기계가 그렇다). 비대화형(claude -p)은 플러그인을 자동 설치하지
않으므로 CLAUDE.md와 docs/upgrade/2026-11-harness.md 9번에 수동 설치 두
명령을 적었다.
위험: 이 세션은 ~/.claude를 바꾸지 않으므로 플러그인 설치 자체는 하지
않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다(claude-
harness README도 같은 미확인).
검증: settings.json JSON 파싱, check-work-docs.py rc=0(CLAUDE.md 10/10줄).
앞 커밋이 ADR-GRPC 7개와 gRPC 설계서를 살아 있는 문서와 함께 지웠다.
그러자 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md의
상대 링크가 깨졌다(desktop: check-work-docs --links broken 1, lychee
Error 1). 기록 본문은 고치지 않는다는 규칙이라 링크를 고칠 수 없다.
기록은 그때 템플릿 안 코드를 두고 한 결정·설계이므로 템플릿에도 남는
것이 맞다(설계 Q15 「리뷰 기록은 템플릿에 남김」과 같은 이유).
- ADR-GRPC 7개와 설계서를 22df3525에서 되살리고, 머리 블록 「현재 정본」을
「없음 — grpc-library로 옮겼다」로 바꿨다. 사본은 grpc-library에도 있다.
- 업그레이드 안내 B-55의 지운 목록에서 그 기록들을 뺐다.
- persistence-jpa testkit 주석 둘을 Spotless 줄바꿈대로 다시 쌌다
(desktop ci의 spotlessJavaCheck 실패).
검증(로컬, 문서만): check-docs.py rc=0, check-work-docs.py --links
broken 0. Gradle 게이트는 desktop에서 다시 돈다.
구조 리뷰(arch-reviewer, 이 브랜치)가 찾은 권고 다섯을 고친다.
1. ModuleRegistry가 행의 `build` 칸을 아직 읽었다. 두 번째 빌드가 없어진
뒤로 main이 아닌 값(오타 포함)을 적은 leaf는 settings가 include하지
않고, 방향 검사도, 등록 안 된 build 스크립트 검사도 보지 않는데 ci는
초록으로 남는다(08-05가 막으려던 모양). 칸이 있으면(빈 값 포함) read에서
그 id와 'build'를 이름 대고 실패한다.
2. gates.md·defect-patterns.md의 「두 빌드의 verifyStrictLaneStages」.
3. shared-contract AGENTS.md의 「optional gRPC 빌드는 자기 사본을 둔다」를
별도 repo 라이브러리로.
4. QualityConventionsPlugin 주석의 현재형 「optional-platforms 빌드가 같은
제외 파일을 읽는다」를 이력으로.
5. StrictLaneStagesExtension 주석의 optional-build 경로에 그 빌드가 옮겨
갔다는 말을 붙였다.
버린 대안: `build` 칸과 modulesForBuild를 통째로 지우기. settings 설치기와
ArchitecturePlugin의 시그니처까지 바뀌고, 막는 효과는 같다.
검증(desktop ~/x2-template-wt, --no-build-cache):
- RED: 새 시험 aBuildFieldIsRejected… 고치기 전 실패(9 tests, 1 failed)
- GREEN: ModuleRegistryTest 통과. 옛 blankBuildOwnershipIsRefused는 새
문구로 바꿨다(빈 값도 같은 이유로 거절)
- -p build-logic check javadoc rc=0(172 tests), :ci :verifyDependencyLocks
rc=0(7389 tests, 실패 0), verifyStrictLaneStages --dry-run, check-docs,
check-work-docs(--links 포함), check-repo-layout 모두 rc=0
grpc-library가 이름을 com.hyeonworks.grpc에서 dev.cakit.grpc로 바꾼다
(grpc-library PR #2, 소유자 2026-11-08: 개인 도메인 이름을 공용
라이브러리에 쓰지 않는다). 이 브랜치 문서는 옛 이름을 적고 있었다.
- README 재사용 체크리스트 6번: 라이브러리 패키지 dev.cakit.*은 바꾸지
않는다. 2번이 바꾸는 dev.caskeleton과 겹치지 않게 정한 이름이라고 적었다
- related-repos.md(group 두 칸과 받는 법), capability-status, 업그레이드
안내 B-55, 카탈로그 주석
남긴 것: Gitea 서버 주소, 기록(ADR-GRPC-002, 리뷰·history 본문)의 옛
proto 조직 이름 hyeonworks.
검증: check-docs.py OK, check-work-docs.py OK, --links broken 0.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼(
src/platforms/grpc·grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행·workflow job 넷과 단계 하나·build-logic 플러그인 둘·카탈로그와 SpotBugs 항목·살아 있는 문서를 템플릿이 함께 지고 있었다.소유자 결정(2026-11-07, design-docs
repo-structure/README.md3.5절,05-library-repos.mdQ1~Q17 모두 「권함」 승인)대로 gRPC를 별도 repo grpc-library로 옮기고 템플릿에서 지운다. 같은 PR에서 하네스 플러그인harness@claude-harness를 켠다.src/platforms/grpc,grpc-advanced,optional-build(343파일)grpc/,grpc-advanced/, 루트 빌드(이력째, filter-repo)"build": "optional-grpc"9행config/architecture/modules.jsonci-quality-gates.ymljoboptional-platforms·grpc-proto-buf와release-gate의 두 needspr.yml(./gradlew ci, Buf 포함)integration-main.ymloptional 성능 단계, jobgrpc-optional-platform-integrationmain.yml(./gradlew mainCheck)release.ymljobgrpc-stable-release-gate와 이미지 job의 needs 한 줄release.yml(./gradlew releaseCheck release)ca.grpc-platform-module,ca.optional-architecture-registry,MainBuildbuild-logic/(사본,UPSTREAM.md)protobufPlugin·protobuf-java-grpc·protoc·pluginprotobufconfig/spotbugs/docs/compatibility/(폴더째), gRPC runbook 둘docs/DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험verifyStrictLaneStages)남긴 것:
adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),src/platforms/messaging(다음 분리 작업), 기록 문서(ADR-GRPC 7개·gRPC 설계서·리뷰·history는 본문 그대로, 기록 9개의 머리 블록 「현재 정본」만 grpc-library를 가리킨다).고른 방법과 버린 대안
git filter-repo로 옛 경로(src/grpc*,src/optional-platforms)와 지금 경로(src/platforms/…)를 함께 넘겼다(Q12). 옮긴 코드 폴더의 트리 해시가 기준 커밋22df3525과 같다.subtree split은 2026-11-07 이동 전 이력을 잃어 버렸다.docs/history/plans/2026-08-30-grpc-platform-implementation.md가 설계서를 상대 링크로 부르는데, 기록 본문은 고치지 않는 규칙이라 링크를 고칠 수 없었다(desktopcheck-work-docs --links·lychee가 잡았다). 기록은 그때 템플릿 안 코드를 두고 한 결정이라 템플릿에 남는 것이 맞다(Q15와 같은 이유).MainBuild(두 번째 빌드에서 주 빌드를 찾던 위로 걷기)는 두 번째 빌드가 없어져 지웠다. 세 곳이 Gradle 루트(src/)의config/를 바로 읽는다. registry의build칸 지원(ModuleRegistry)은 일반 기능이라 남겼다.build칸: 두 번째 빌드가 없어진 뒤 main이 아닌 값을 적은 leaf는 조용히 빌드에서 빠진다(구조 리뷰가 찾음).ModuleRegistry가 그 칸을 거절한다. 칸과modulesForBuild를 통째로 지우는 안은 settings 설치기·ArchitecturePlugin 시그니처까지 바꾸고 막는 효과는 같아 버렸다..claude/settings.json에extraKnownMarketplaces·enabledPlugins두 키만 더했다. 기존 deny·repo 훅은 그대로다. 사용자 전역에 H12가 있으면 플러그인 H12는 스스로 건너뛴다(소유자 기계가 그렇다).build-logic/UPSTREAM.md):grpc/<leaf>·grpc-advanced/<leaf>그대로, Gradle 경로도:grpc:…그대로. registry·문서가 그대로 맞고 ADR-GRPC-001의 접두사 분리가 폴더로 남는다.dev.cakit.grpc, proto는cakit.grpc.common.v1(grpc-library PR #2, 소유자 지시로 개인 도메인com.hyeonworks에서 바꿈). 템플릿 재사용 체크리스트의dev.caskeleton일괄 바꾸기와 겹치지 않는 이름이다. 생성 proto Java 패키지는cakit.grpc.common.v1.generated로, 손으로 쓴 루트와 겹치지 않는다는 기존 규칙(시험이 고정)을 지킨다.bufLint·bufBreaking)로ci에 넣었다. job은 Gradle 한 줄이어야 하고(7.1절), 바이너리는scripts/tool.sh가 SHA-256으로 고정해 받는다. 기준은 PR이면 대상 브랜치의 merge base, main이면 직전 커밋.dev.cakit.grpc:grpc-library:<버전>:cyclonedx@json.api-surface플러그인은 복사했지만 아직 모듈에 켜지 않았다(기준선 파일과 정책은 새 결정).위험과 영향
:grpc:*·ca.grpc-platform-module·지운 카탈로그 alias를 쓰면 빌드 실패. 안내는docs/upgrade/2026-11-maturity-review.md3.8절 B-55·B-56.tech-log-backend는 플랫폼을 받은 적이 없다(설계 12절).pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 달려면22df3525에 단다..github/actions/setup-gradle-java의 JDK 고정값21.0.11+10은 Gitea runner의 setup-java가 「Could not find satisfied version」으로 거부했다(grpc-library main run 1). Temurin 이름은21.0.11+10.0.LTS다. 템플릿 Actions는 아직 꺼져 있어 드러나지 않았다. CI 재편 세션 몫이라 고치지 않았다.~/.claude를 바꾸지 않아 설치는 하지 않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다.검증
desktop, 새 detached worktree
~/x2-template-wt(기준22df3525= main, 그래서 이 브랜치 트리가 곧 합친 트리), Gradle 명령마다--no-build-cache, 공유 잠금 아래 하나씩. 로그~/x2-grpc-library-logs/template/(1회차round1/, 최종final-*). 1회차 시작 부하 6.97.:ci :verifyDependencyLocks --warning-mode=fail2921f59691804ec1에서 고침57988c2e(+ 장부 한 줄)-p build-logic check javadoc57988c2e-p build-logic test171)verifyStrictLaneStages --dry-run, compose 계약,check-repo-layout, 문서 자기 시험,check-docs,check-work-docs(이력·--links·리뷰 색인)57988c2e--linksbroken 1(기록이 지운 설계서를 링크) → 기록 복원으로 0pr일곱91804ec1:mainCheck --continue --warning-mode=fail57988c2everifyFeatureScaffold) FROM-CACHE 10:integrationCheck,:performanceCheck, http3 실험 lanescripts/bootstrap-local.sh, healthcheck 200):releaseCheck -PgitRevision57988c2ea2dbf33b(PR head)에서 다시 돌린 것(새 worktree,--no-build-cache, 로그final2-*)::integrationCheckrc=0(958 tests, 265 tasks 모두 실행),:performanceCheckrc=0(26), compose runtime smoke rc=0(blocking 18 lane 모두 통과), 빠른 시작scripts/bootstrap-local.shrc=0(healthcheck HTTP 200, status=UP),:releaseCheckrc=0.a2dbf33b(grpc-library 이름을dev.cakit.grpc로 맞춤: 문서 넷과 카탈로그 주석 한 줄): 새 worktree에서:verifyDependencyLocks :architectureCheckrc=0(317 tasks 모두 실행, 캐시 없음),verifyStrictLaneStages --dry-runrc=0,check-docs·check-work-docs(--links포함) rc=0. 그 밖의 게이트는 Gradle 동작이 바뀌지 않아 다시 돌리지 않았다.e1dd8e74는 위 최종 트리57988c2e에 장부(docs/ledger/estimates.jsonl) 두 줄을 더한 것이다. 장부는 어떤 게이트의 입력도 아니다(check-work-docs.pyrc=0으로 형식만 확인).ModuleRegistry의build칸 거절과 문장 넷이다. 그래서 ci·build-logic·문서 게이트와mainCheck·releaseCheck를 최종 트리에서 다시 돌렸고, 컨테이너 lane·smoke·빠른 시작은 1회차 결과다.ModuleRegistryTest.aBuildFieldIsRejected…가 고치기 전 실패(9 tests, 1 failed), 고친 뒤 통과.mainCheck의 FROM-CACHE는 중첩 빌드(verifyFeatureScaffold)의 것이다(gates.md 3절).57988c2e에서 고침.grpc-library 쪽(desktop과 Gitea runner):
desktop-runner): main run 28d705bca성공(mainCheck, Testcontainers PostgreSQL 포함), PR run 3ce83f4d5성공(ci·verifyStrictLaneStages --dry-run), PR #1·#2·#3 모두 runner pr 성공 후 총괄이 병합.v1.0.0태그(2e880c75)의 release run 22 성공: 모듈 9개와 SBOM이 Gitea Packages에 게시됐고 익명으로 받힌다. 게시 jar의.asc는 릴리스 키로 Good signature. main run 1은 JDK 이름 때문에 실패했고 고쳤다.ci --rerun-tasksrc=0(130 tasks, build-logic 시험 포함),verifyStrictLaneStages --dry-runrc=0,mainCheckrc=0,releaseRehearsalrc=0(9개 모듈 + SBOM, 체크섬 넷, POM·module의 모든 의존성에 버전), 버리는 시험 키로 서명한 리허설 rc=0과gpg --verifyGood signature(키는 임시 폴더째 지움).bufBreaking은 이름 바꾸기 전 커밋과 비교하면 깨짐을 잡는다(1.0.0 전 한 번의 변경).grpc·grpc-advanced트리 해시와 optional 빌드 파일 다섯, 문서 열둘이22df3525과 같다.리뷰어가 볼 곳
src/build-logic/src/main/java/dev/caskeleton/buildlogic/{architecture/ArchitecturePlugin,java/JavaConventionsPlugin,quality/QualityConventionsPlugin}.java:MainBuild대신 Gradle 루트 경로.src/config/spotbugs/exclude.xml: 섞인<Or>에서 gRPC 줄만 뺐다..github/workflows/*.yml: 지운 job과 needs.docs/work/reference/related-repos.md(새 문서),decisions.md「라이브러리 repo」 행.git rm -r), registry 행 삭제("build": "optional-grpc"인 행만 지운 스크립트, diff는 삭제 84줄뿐).관련
repo-structure/05-library-repos.md(승인 2026-11-07),repo-structure/README.md3.5절