Files
messaging-library/docs/work/README.md
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.5 KiB

작업 방법 — messaging-library를 고칠 때

이 repo에서 일을 맡은 사람과 에이전트가 먼저 읽는다. 루트 AGENTS.md의 「꼭 지킬 것」이 이 문서보다 먼저다.

1. 일의 종류와 읽을 곳

일 먼저 읽을 곳 끝났다는 증거
모듈 코드 고치기·기능 더하기 messaging/AGENTS.md(family 규칙, 공개 표면 정책), 관련 제품 문서(docs/messaging/) 바꾼 모듈 check + ci(2절)
Kafka adapter·전달 보장 바꾸기 messaging/AGENTS.md 「Stable 승격에 필요한 증거」, docs/messaging/support-matrix.md 위 + mainCheck(인증 lane과 증거 게이트)
outbox·inbox·admin journal, migration docs/messaging/outbox-inbox.md 위 + integrationCheck. 적용된 migration은 고치지 않고 새 버전 파일을 더한다
공개 타입·설정 키(app.messaging.*) 바꾸기 release.md 2절 CHANGELOG.md에 옮기는 법, 템플릿 쪽 영향 확인(3절)
빌드 규칙(build-logic) 고치기 build-logic/AGENTS.md, build-logic/UPSTREAM.md buildLogicTest(ci 안)
릴리스 release.md release.yml 초록, 익명 메타데이터에 새 버전
리뷰 아래 2절의 게이트 목록과 루트 AGENTS.md 「꼭 지킬 것」 발견마다 위치·재현·고칠 곳

2. 검증

  • 진입점은 scripts/verify.sh <단계>다. 소유자 환경에서는 Gradle·Docker를 desktop에서만 돌린다: --on desktop을 붙이면 지금 작업 트리를 패치로 옮겨 잠금(/tmp/claude-gates/heavy.lock) 아래에서 돌린다.
  • 무엇을 돌릴지는 gates.md다. 완료를 말하기 전에 바꾼 것에 맞는 게이트를 돌리고, 못 돌렸으면 이유를 적는다.

3. 백엔드 템플릿과 같이 고치기

백엔드 템플릿은 이 라이브러리를 버전으로 받는다(카탈로그 칸 messagingLibrary, 쓰는 곳은 adapter:outbound:messaging, adapter:outbound:messaging-kafka, adapter:inbound:messaging, adapter:outbound:persistence-jpa의 migration 시험, composition:outbox-relay의 시험). 템플릿 쪽 절차는 템플릿 docs/work/reference/related-repos.md다.

  1. 이 repo와 템플릿에 브랜치를 하나씩 만든다. 두 repo를 같은 부모 폴더에 둔다.

  2. 템플릿 src/에서 명령 줄로만 이 repo를 끼운다. 파일은 바꾸지 않는다.

    ./gradlew --include-build ../../messaging-library <태스크>
    
  3. 그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다.

  4. 병합 순서는 하나다: 이 repo PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합. 끼운 상태로만 통과하는 템플릿 PR은 병합하지 않는다.

  5. 공개 API·설정 키·migration을 바꾸는 PR은 본문에 템플릿 쪽 영향(끼운 상태로 돌린 태스크와 결과)을 적는다.

4. 이 repo에서 정한 것

  • 결정 기록은 docs/adr/에 쌓는다. 템플릿에서 옮겨 온 결정 기록은 없다(메시징 결정은 설계서와 템플릿 리뷰에 있다). 새 결정은 docs/adr/0000-template.md 양식으로 ADR-MSG-001부터 쓴다.
  • 문서는 한국어로 쓴다. 지난 결정을 고칠 때는 본문이 아니라 머리 블록의 「상태」·「현재 정본」만 고친다(docs/README.md 2절).
  • 커밋·PR 규칙은 design-docs conventions/commit-and-pr.md다. main에는 PR로 넣는다(첫 배포 전 첫 커밋들만 예외였다).