Files
grpc-library/docs/problem-statement.md
T
DongHyeonka ce83f4d550
pr / ci (pull_request) Successful in 1m9s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 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).
2026-11-08 11:22:12 +09:00

3.2 KiB

문제 정의 — grpc-library

아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다. 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다.

고객의 말 그대로

  • 소유자(2026-11-07): 「템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리 폴더가 있으면 안 된다. 커스텀 라이브러리는 별도 repo로 관리하고, 매뉴얼에 관리 대상으로 둔다.」
  • 고객은 이 라이브러리를 받아 쓰는 백엔드 서비스(백엔드 템플릿과 그 파생 서비스)와 그 서비스를 만드는 사람·에이전트다.

지금은 어떻게 버티나

  • 2026-11-08까지 이 코드는 템플릿 안의 두 번째 Gradle 빌드(src/platforms/optional-build)였다. 템플릿 빌드 규칙·카탈로그·testFixtures를 경로로 읽었고, 템플릿 CI가 job 넷과 단계 하나로 따로 돌렸다.
  • 템플릿을 받은 파생 서비스는 쓰지도 않는 플랫폼 코드 수백 파일을 함께 받았다. 템플릿 재사용 체크리스트(「dev.caskeleton을 새 패키지로 바꾼다」)가 플랫폼 패키지까지 바꾸게 만들었다.

하지 않는 것

  • 템플릿 adapter:inbound:grpc를 이 라이브러리에 배선하는 일. 별도 결정이다(grpc/AGENTS.md 「application이 이 family에 도달하는 경로」).
  • Maven Central 배포. 템플릿 밖 공개 소비자가 생기면 본다.
  • BOM. 소비자가 템플릿 하나라 카탈로그 버전 한 칸으로 충분하다. 템플릿 밖 소비자가 한 라이브러리에서 모듈 3개 이상을 쓰면 다시 본다.
  • SNAPSHOT 배포. 같이 고칠 때는 composite build를 쓴다.

성공 기준

기준 구체적으로 어떻게 재나 목표 값 기한
혼자 빌드된다 템플릿 없이 PR·main 단계가 초록 Gitea Actions pr·main 실행 결과 초록 2026-11-08
배포된다 태그 하나로 서명된 모든 모듈이 Gitea Packages에 올라가고 익명으로 읽힌다 release.yml, maven-metadata.xml v1.0.0 게시 소유자가 비밀 값을 넣은 뒤
템플릿이 가벼워진다 템플릿에 gRPC 플랫폼 폴더·optional build·그 CI job이 없다 git ls-files src/platforms/grpc* 0 2026-11-08 PR

세 관점 점검

관점 묻는 것 답
비즈니스 돈이 되나, 누가 대가를 치르나 템플릿 유지비를 줄인다. 대가는 CI·build-logic 사본·release secret이 한 벌 더 생기는 것
기술 만들 수 있나, 가장 위험한 가정은 Gitea Packages가 Gradle이 올리는 체크섬 넷과 .asc·.module을 모두 받는다는 가정(설계 16절 H8). 첫 태그에서 드러난다
고객 쓸모 있나, 지금 방법보다 나은가 쓰는 서비스는 버전으로 받고, 쓰지 않는 서비스는 아무것도 받지 않는다

되돌릴 수 없는 결정

  • 배포한 버전은 지우지 않는다(docs/work/release.md 2절). 같은 버전은 다시 올릴 수 없다.
  • Maven group com.hyeonworks.grpc와 proto 패키지 hyeonworks.grpc.*. 바꾸면 모든 소비자의 MAJOR다. 근거는 design-docs repo-structure/05-library-repos.md 6.3절.