Files
messaging-library/docs/problem-statement.md
T
DongHyeonka dd194784c3
main / main-check (push) Successful in 8m35s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.

- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
  타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
  고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
  (Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
  Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
  grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
  Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
  docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
  인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
  docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
  이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
  시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
  않았다.

검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.

Refs: design-docs repo-structure/05-library-repos.md 14.2절
2026-11-08 16:16:38 +09:00

3.7 KiB

문제 정의 — messaging-library

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

고객의 말 그대로

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

지금은 어떻게 버티나

  • 2026-11-08까지 이 코드는 템플릿 주 빌드 안의 family(src/platforms/messaging)였다. 템플릿의 build-logic·카탈로그·registry를 그대로 썼고, 인증 lane은 템플릿의 별도 workflow(messaging-certification.yml)가 주 1회 돌렸다.
  • 템플릿 adapter 넷이 project(':messaging:…')로 이 코드를 직접 받았다. 템플릿 JPA leaf의 migration 시험은 이 코드의 migration 폴더를 경로(../../../platforms/messaging/…)로 읽었다.
  • 템플릿을 받은 파생 서비스는 쓰지 않아도 메시징 코드 450여 파일을 함께 받았다. 템플릿 재사용 체크리스트(「dev.caskeleton을 새 패키지로 바꾼다」)가 이 패키지까지 바꾸게 만들었다.

하지 않는 것

  • 새 브로커 adapter. RabbitMQ·Pulsar·NATS 등은 2026-09-25에 지웠다. 다시 들이려면 docs/messaging/experimental-policy.md를 따른다.
  • Maven Central 배포. 템플릿 밖 공개 소비자가 생기면 본다.
  • BOM. 소비자가 템플릿 하나라 카탈로그 버전 한 칸으로 충분하다. 템플릿 밖 소비자가 모듈 3개 이상을 쓰면 다시 본다.
  • SNAPSHOT 배포. 같이 고칠 때는 composite build를 쓴다.

성공 기준

기준 구체적으로 어떻게 재나 목표 값 기한
혼자 빌드된다 템플릿 없이 PR·main 단계가 초록. main은 실제 Kafka로 인증 증거를 다시 만든다 Gitea Actions pr·main 실행 결과 초록 2026-11-08
배포된다 태그 하나로 서명된 모든 모듈이 Gitea Packages에 올라가고 익명으로 읽힌다 release.yml, maven-metadata.xml v1.0.0 게시 2026-11-08
템플릿이 버전으로 받는다 템플릿에 메시징 폴더가 없고, 쓰는 leaf가 dev.cakit.messaging:*:1.0.0으로 같은 lane을 통과한다 템플릿 git ls-files src/platforms, 템플릿 integrationCheck 0, 초록 2026-11-08 PR

세 관점 점검

관점 묻는 것 답
비즈니스 돈이 되나, 누가 대가를 치르나 템플릿 유지비를 줄인다. 대가는 CI·build-logic 사본·release secret이 한 벌 더 생기는 것
기술 만들 수 있나, 가장 위험한 가정은 템플릿이 좌표로 바꿔도 lockfile의 외부 의존성 집합이 같다는 가정(설계 16절 H6). 배포한 POM·module 파일의 버전 선언이 해석을 바꾸면 깨진다
고객 쓸모 있나, 지금 방법보다 나은가 쓰는 서비스는 버전으로 받고, 쓰지 않는 서비스는 아무것도 받지 않는다

되돌릴 수 없는 결정

  • 배포한 버전은 지우지 않는다(docs/work/release.md 2절). 같은 버전은 다시 올릴 수 없다.
  • Maven group·Java 패키지 dev.cakit.messaging, 설정 접두사 app.messaging, migration 위치 db/migration/messaging. 바꾸면 모든 소비자의 MAJOR다. 근거는 design-docs repo-structure/05-library-repos.md 6.3절.