# 작업 방법 — 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를 끼운다. 파일은 바꾸지 않는다. ```bash ./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로 넣는다(첫 배포 전 첫 커밋들만 예외였다).