옮겨 온 문서는 템플릿 안의 optional build를 전제로 했다(`-p
platforms/optional-build`, 템플릿 registry·workflow 경로, "벤더드 플랫폼").
하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다.
- 루트 AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것(core-api 순수성, Stable이
advanced를 안 씀, 템플릿에 기대지 않음, 배포한 버전 불변, 버전 규칙),
지도, 맡은 일, 검증 진입점. 비대화형 세션의 플러그인 설치 두 줄.
- README: 무엇인가, 받는 법(exclusiveContent), 지원 표, 구조, 문서 지도,
서명, 이력(filter-repo, 커밋 SHA·리뷰 ID는 템플릿 기준).
- docs/work/README.md·gates.md·release.md: 고치는 법, 단계와 바꾼 것별
게이트, 템플릿과 같이 고치기(composite), 릴리스와 소유자가 할 일
(PACKAGES_TOKEN, SIGNING_KEY·SIGNING_PASSWORD, 첫 태그 v1.0.0).
- CHANGELOG.md(1.0.0 미발행, 옮기는 법), docs/README.md(지도, 머리 블록).
- scripts/verify.sh: unit·pr·main·release 단계. 라이브러리라 app은 없다.
- 살아 있는 문서(grpc·grpc-advanced AGENTS.md, 지원 매트릭스, runbook):
경로·패키지·optional build 문장을 이 repo 기준으로. ADR·설계서 본문은
기록이라 고치지 않았다.
- docs/vision.md는 소유자가 쓰는 문서라 비워 두었다.
검증: scripts/verify.sh docs rc=0(AGENTS.md 38줄, 장부 JSON).
releaseRehearsal과 release가 태스크 설정 블록 안에서 `path`·`group`·
`version`을 읽었다. 그 자리에서 셋은 프로젝트가 아니라 태스크의 속성이라
루트 publish 태스크 경로를 `:releaseRehearsal:publish…`로 만들고, 좌표를
`release:<모듈>:0.0.0`으로 찾았다. 좌표를 루트에서 한 번 잡아 쓴다.
같이 고친 것:
- grpc-core-api의 test fixtures 변형을 publication에서 뺀다. 이 repo
시험끼리 쓰는 지원 코드이고(배포하는 testkit은 grpc-testkit), Maven이
표현하지 못하는 capability라 POM 경고를 냈다.
- Trivy 호출에 --skip-version-check. 새 버전 알림이 매번 네트워크를
부르고 로그를 덮었다.
검증(desktop): releaseRehearsal rc=0. 9개 모듈 + SBOM(733 components)이
staging에 올라가고 파일·체크섬 넷·POM/module 의존성 버전 확인 통과.
의존성 검사는 HIGH·CRITICAL 0, KEV 일치 0. 버리는 시험 키로 서명한
리허설도 rc=0, gpg --verify Good signature(키는 임시 폴더째 지웠다).
옮겨 온 gRPC 모듈은 템플릿의 두 번째 빌드(optional build)였다. 그 빌드는
템플릿 build-logic·카탈로그·registry·config를 상대 경로로 읽었고,
grpc-operation-ledger-jpa는 템플릿 persistence-jpa의 testFixtures 파일
셋을 빌드 때 복사해 왔다. 별도 repo에는 그 경로가 없다.
repo 루트를 Gradle 루트로 둔다.
- build-logic: 템플릿 22df3525의 src/build-logic을 복사하고 쓰지 않는
플러그인(bootrun-dotenv, redis topology, config contract,
spring-library, optional registry, purity 태스크)을 뺐다. 출처와 고친
곳은 build-logic/UPSTREAM.md에 적었다(설계 10.3절 L1).
- registry config/architecture/modules.json: 템플릿의 optional-grpc 9행,
source_path는 Gradle 루트 기준.
- 카탈로그·config: 이 repo가 쓰는 항목만. SpotBugs 제외는 이 repo
클래스와 일반 규칙만 남겼다.
- group은 gradle.properties의 libraryGroup(com.hyeonworks.grpc)에서
읽는다. 버전은 -PreleaseVersion 말고 RELEASE_TAG(vX.Y.Z)에서도 읽고,
다른 모양의 태그는 빌드 전에 거부한다.
- 배포: 새 ca.library-publishing이 모듈마다 Maven publication(sources·
javadoc jar, versionMapping으로 해석된 버전)과 저장소 gitea·staging,
SIGNING_KEY가 있으면 PGP 서명을 단다. 루트는 SBOM artifact
grpc-library와 단계 태스크 ci·mainCheck·releaseCheck·release·
releaseRehearsal을 가진다. Trivy·Buf는 scripts/tool.sh가 SHA-256으로
고정해 받는다.
- testFixtures 결합(설계 4.6절 2번)은 integrationTest 안 사본으로 끊었다.
- Buf lint·breaking은 Gradle 태스크(scripts/buf.sh)로 ci에 넣었다.
버린 대안: build-logic을 템플릿이 배포(L2, 순환), 공통 repo(L3, repo가
하나 더), 표준 플러그인만으로 새로 쓰기(L4, strict lane과 방향 검사를
잃음). SBOM은 CycloneDX Gradle 플러그인 대신 이미 고정해 쓰는 Trivy로
만든다(도구를 늘리지 않는다).
위험: strictlane 단계 검사는 included build 태스크를 따라가다 실패해서
그 태스크를 건너뛰게 고쳤다(UPSTREAM.md). Gitea에 실제로 올리는 경로는
비밀 값이 없어 이 커밋에서는 시험하지 못했다.
검증(desktop, 이 트리): ./gradlew ci rc=0, 테스트 739개(build-logic
포함) 중 첫 실행 실패 1개(템플릿 경로를 찾던 GrpcPackageOwnershipTest)를
고친 뒤 통과. ./gradlew verifyStrictLaneStages --dry-run rc=0.
Refs: design-docs repo-structure/05-library-repos.md 4.6·7·10절
템플릿에서 옮긴 gRPC 이력 위에 새 repo의 작업 환경을 먼저 깐다.
claude-harness main 72078ca의 scripts/new-project.sh가 만든 파일을
그대로 복사했다: AGENTS.md·CLAUDE.md 양식, .claude/settings.json
(.env deny, 하네스 플러그인 harness@claude-harness 켜기),
scripts/verify.sh 뼈대, docs/vision.md·problem-statement.md·
adr/0000-template.md 양식, docs/ledger/ 빈 장부, .gitattributes,
.gitignore.
채울 자리(「(채울 것」)는 뒤 커밋에서 이 repo의 내용으로 채운다.
이 커밋 자체는 아직 빌드되지 않는다(Gradle 루트가 없다).
검증: new-project.sh 종료 코드 0, 남은 {{…}} 없음.
Refs: design-docs repo-structure/05-library-repos.md 14.2절