leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code 밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가 2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다 (design-docs harness/01-harness-design.md 13절 Q1·Q2). - 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리 CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서 src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져 AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는 지금처럼 그 폴더를 만질 때 규칙을 읽는다. - 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다), CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다). - 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다. 기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴 때의 경로를 그대로 둔다. - link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이 AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는 check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다. workflow는 CI 재편 몫이라 고치지 않았다. - check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다. 위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은 이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은 `git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는 가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다. 검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py, python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사 시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다. BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로 바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
7.5 KiB
adapter:outbound:messaging — 설계 결정 참조
메시징(broker publish + outbox relay 발행) 아웃바운드 어댑터 모듈. 패키지 루트:
dev.caskeleton.adapter.outbound.messaging. outbox relay 실패는 이 모듈이 별도의 typed report
adapter로 구조화한다.
허용/금지 의존 정책은 src/config/architecture/modules.json과 이 모듈의
AGENTS.md가 소유한다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔
참조용 기록이다.
모듈 개요
application-core의 OutboxMessagePublishPort와 canonical IntegrationEventPublishPort 뒤에 두는
선택형 연동 어댑터다. 서비스는 이 모듈을 직접 고르지 않고
runtimeOnly project(':adapter:outbound:messaging-kafka') 한 줄로 받는다(추가할 한 줄·env 키는
messaging-kafka README). 모듈이 있으면 켜지고
app.messaging.enabled=false로만 끈다.
발행 경로는 하나다.
OutboxMessagePublishPort → OutboxMessagePublishAdapter → IntegrationEventPublishPort → PlatformIntegrationEventPublishAdapter → EncodedMessagePublisher
bridge는 broker SDK나 transport SPI를 직접 보지 않는다. legacy KafkaSender/MessageBroker R0
seam과 그 위의 MessagePublisher·OutboxEnvelopeJson은 outbox를 canonical 하나로 통일하면서
삭제했다(2026-09-28, 소유자 결정 7).
정해진 플랫폼 bridge
IntegrationEventPublishPort는 app.messaging.producer-id가 명시되고 platform publisher bean이
있을 때만 생성된다. exact ValidatedIntegrationEvent.envelopeBytes()를 보존하고 platform의 중앙
publish pipeline을 탄다. producer id는 host/pod/process 이름에서 추측하지 않는다.
OutboxMessagePublishAdapter는 claim된 row의 validated event를 그대로 bridge에 넘기고 platform
결과를 application 결과(CONFIRMED·AMBIGUOUS·REJECTED_BEFORE_SEND·REJECTED_AFTER_BROKER·
REJECTED_RETRYABLE)로 번역해 relay에 돌려준다. 다시 직렬화하지 않는다.
platform REJECTED 중 FailureDescriptor.retryable()이 true인 것(종료 중 SHUTTING_DOWN, permit
대기 초과, PUBLISH_RUNTIME_UNAVAILABLE, KAFKA_TRANSPORT_CLOSED, Kafka 인증·인가 실패)은
REJECTED_RETRYABLE로 번역한다. relay는 이 값을 DEAD로 보내지 않고 재시도한다. 확정 거부 두 값으로
번역하면 "같은 payload는 또 거부된다"로 읽혀 커밋된 이벤트와 그 aggregate의 뒤 이벤트가 바로
멈춘다(2026-11-01 리뷰 06-01). AMBIGUOUS로 번역하지 않은 이유: 동작은 같지만 "전송됐을 수
있음"이라는 거짓 정보가 남아 중복 경고를 오염시킨다.
실패 원인 코드
결과(outcome)는 relay가 무엇을 할지만 정한다. 종료 중 거부, 닫힌 transport, 거부된 credential은 모두
REJECTED_RETRYABLE 하나다. 그런데 이 셋은 끝이 없는 재시도다(시도 예산을 쓰지 않는다). 그래서 bridge는
platform FailureDescriptor.code()를 버리지 않고 OutboxPublishAttempt.failureCode()로 함께 넘긴다
(재리뷰 2026-11-03 RR-05-03). relay는 그 코드를 행의 last_failure_code(V22)와 실패 로그의
error.reason에 남긴다. 운영자는 이 값으로 "credential이 진짜 틀렸다"와 "broker가 이 레코드만 받지
않는다"를 가른다(docs/runbooks/outbox-publish-failed.md §4.1).
- platform code는 이미 정제된 이름이다(
KAFKA_AUTHENTICATIONEXCEPTION,PUBLISH_DEADLINE_EXCEEDED등). driver 메시지가 아니므로 그대로 옮긴다. application 코드 문법([A-Za-z0-9][A-Za-z0-9._:-]*, 120자)에 맞지 않는 code는 그 실패의FailureCategory이름으로 옮긴다. - platform으로 옮길 수 없는 event(아래 id 규칙)는 bridge가
EVENT_NOT_REPRESENTABLE로 거부한다. - 버린 대안: relay가 platform 타입을 직접 보는 것(경계가 깨진다), outcome 값을 원인별로 늘리는 것(relay가 할 일은 같은데 분기만 는다).
event id → message id
application EventId는 문자열이고 platform MessageId는 UUIDv7만 받는다. bridge는 event id가
정규 소문자 UUIDv7 문자열일 때만 같은 값으로 옮기고, 그 밖(대문자·축약 표기·v4 등 다른 버전)은 다른
문자열의 message id로 바꿔 보내지 않고 REJECTED_BEFORE_SEND로 거부한다(relay는 DEAD). 소비자 중복
제거 키가 event id라서 값을 바꿔 보내면 중복 제거가 깨지기 때문이다(리뷰 2026-11-01 06-06).
같은 규칙이 append 쪽에 먼저 있다. IntegrationEventDraft가 정규 소문자 UUIDv7이 아닌 event id와
causation id를 거부하므로(IntegrationIdentity.isCanonicalUuidV7), 그런 id는 업무 트랜잭션 안에서 실패한다
(재리뷰 2026-11-03 RR-05-04). bridge의 거부는 이 규칙 전에 쓰인 행(저장 문법 EventId는 그대로 넓다)을 위한
마지막 방어선이다.
outbox 발행 포트에는 대역이 없다
OutboxMessagePublishPort의 대역(항상 던지는 publisher)은 두지 않는다. 대역도 bean이므로 relay
스케줄러의 조건을 채우고, relay는 모든 PENDING 행을 그 대역에 실패시켜 DEAD로 소진한다. 그래서
모듈이 있고 켜져 있는데 IntegrationEventPublishPort가 없으면(producer id가 비었거나 platform
transport가 없으면) startup을 거부한다.
중복 가능 구간
publisher 정상 반환 뒤 DB mark가 실패하면 row는 IN_FLIGHT에 남아 timeout reclaim 후 같은
event가 다시 publish될 수 있다. 같은 event id로 다시 나가므로 consumer는 event id로 중복을 걸러야
한다. 같은 aggregate의 row는 (aggregate_sequence, event_index) 순서로 하나씩 풀린다.
OutboxRelayFailureReport 구조화 ERROR
MessagingConfig는 정확히 하나의 Slf4jOutboxRelayFailureReportAdapter를 등록한다.
dependency_name은 platform이 쓰는 broker 선택값(app.messaging.broker, 기본 kafka)이고, 비어
있으면 messaging-platform이다. 이 adapter는 confirmed FAILED/DEAD report 하나를 SLF4J 2 fluent
ERROR 하나로 렌더링한다.
공통 field는 error.code, error.category, error.cause_type, error.reason, dependency_name,
dependency_type=messaging, outcome, event_id, event_type, aggregate_id,
correlation_id, attempt_count, runbook_link다. retry report만 next_attempt_at을 추가한다.
error.reason은 위 실패 원인 코드다.
payload/envelope/exception-derived field는 받거나 렌더링하지 않는다. logging 내부
RuntimeException은 adapter와 use case 양쪽에서 방어하므로 persisted FAILED/DEAD outcome을 바꾸지
않는다.
encoder는 이 모듈에 없다
템플릿의 IntegrationEventEncoderPort 구현(JsonIntegrationEventEncoder)은
adapter:outbound:support에 있다. use case가 append 전에 encode하므로 outbox를 쓰는 모든 조립에
있어야 하고, 이 모듈은 발행 쪽에만 있다. 옛 R1 encoder 체인(contract·destination·config·
envelope·realtime)은 2026-09-25에 삭제됐고 복구 경로는 docs/capability-status.md 제거 표에
있다.
integration event 계약 검증은 루트 verifyMessagingContracts(src/build.gradle)가 한다. application-core·
shared-contract의 qualification lane 둘을 묶은 task다. 이 leaf는 그 검증에 관여하지 않는다.
canonical path는 platform PublishResult의 confirmation/transmission evidence를 application
OutboxPublishOutcome으로 명시적으로 변환하고, 실패 code를 OutboxPublishAttempt에 함께 싣는다.