Files
messaging-library/messaging/AGENTS.md
T
DongHyeonka d11921e518 docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
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` 한 줄이다.
2026-11-07 21:58:12 +09:00

12 KiB

messaging — 메시징 플랫폼 family의 지역 정본

이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 src/config/architecture/modules.json이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 필요한 증거, runtime membership이 비어 있다는 사실의 의미.

루트 AGENTS.md와 충돌하면 루트가 이긴다.

Family와 framework 규칙

leaf의 정확한 id는 registry에서 읽는다. family는 디렉터리 이름의 접두사가 아니라 아래 표의 역할로 정해진다.

Family 역할 허용 framework
*-api (core-api — api·schema 패키지, policy, reliability-api, transport-spi) 값 타입, 포트, 정책 계약 Java stdlib만. Spring/broker SDK/logging framework 금지
schema-* (json/avro/protobuf), cloudevents 인코딩 구현 해당 codec 라이브러리만. Spring 금지
runtime-core, security, observability, admin(계약 admin + 실행 admin.runtime), reliability framework-free 실행 로직 Micrometer는 observability에서만. 나머지는 stdlib
kafka broker adapter 해당 broker client. Spring은 client가 곧 Spring인 경우만
reliability-jdbc-postgresql 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) Spring JDBC / Spring TX. JPA 아님 — 이름이 곧 계약이다
spring-boot-starter, spring-boot-starter-kafka 조립 경계 Spring Boot autoconfigure. 여기서만
testkit 테스트 지원 Testcontainers, JUnit. production leaf가 의존하지 않는다

신뢰성 기능은 세 leaf다. messaging-reliability-api가 vendor 중립 port(OutboxRepository, InboxRepository)를, messaging-reliability가 그 port만 보는 relay·consumer 로직(stdlib)을, messaging-reliability-jdbc-postgresql이 port의 관계형 구현과 migration(V1001..V1005, V1101)을 갖는다. 예전에는 outbox-jdbc-postgresql 하나가 relay 로직과 PG repository와 admin journal을 함께 가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 jdbc-postgresql로 명명된 이유: 구현은 Spring JDBC이고 SQL은 jsonb · FOR UPDATE SKIP LOCKED · ON CONFLICT · TIMESTAMPTZ로 PostgreSQL 전용이다. jpa라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.

공용 다이제스트 헬퍼를 복사해 두는 이유

messaging-admin(HmacApprovalVerifier, PlanDigest)과 messaging-claim-check (ClaimCheckIntegrityGuard)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의 shared-contract digest/Sha256·HmacSha256을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의 계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), messaging:* leaf는 domain-core·application-core·shared-contract 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에 registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 shared-contract의 정본과 같은 규칙인지 함께 본다.

인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization)

이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.

  • category 기본값: FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false. 소비 쪽 재시도 엔진(DefaultRetryDecisionEngine)은 policy가 category를 따로 정하지 않으면 이 기본값과 descriptor의 retryable을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다.
  • publish 거부의 retryable: KafkaPublishFailureClassifier는 인증·인가 거부에 retryable = true를 붙인다. broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든 publish를 거부한 뒤 멈추기 때문이다. retryable을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지 않게 하려는 것이다.

다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두 publish 경로, 소비 경로 동작은 그대로):

  • KafkaPublishFailureClassifier: 인증·인가 거부를 retryable = true로.
  • DefaultMessagePublisher: runtime이 없을 때의 거부(PUBLISH_RUNTIME_UNAVAILABLE)를 retryable = true로.
  • KafkaMessagingTransport: 닫힌 transport의 거부(KAFKA_TRANSPORT_CLOSED)를 retryable = true로.
  • MessagingShutdownLifecycle.PHASE: platform 밖 relay의 순서 테스트가 참조하도록 public.

버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로 번역하는 것. 버린 이유: retryable은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는 자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의 PublishResult를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application relay, composition:outbox-relay)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).

Public surface 정책

  • vendor 타입을 public signature에 노출하면 그 의존성은 api로 선언한다. 숨긴다고 타입이 숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다. (kafka-clients, cloudevents-api, micrometer-core, avro, protobuf-java가 이 규칙으로 api다.)
  • 반대로 노출하지 않는 것은 implementation으로 낮춘다. starter가 노출하지 않는 하위 모듈을 implementation으로 내린 것이, JSON codec이 ObjectMapper를 private으로만 쓰고 Jackson을 implementation으로 둔 것이 그 예다.
  • 이 규칙은 문서가 아니라 MessagingPublicSurfaceContractTest가 붙들고 있다. leaf의 production source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의 build.gradle이 api로 선언했는지 대조하고, starter의 api closure에 broker client 두 개가 들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만 등장하고 adopter가 이름 부를 일이 없다.
  • 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.

Application runtime에 포함되는 기준

기본 조립에는 Messaging family가 없다. 서비스가 app-bootstrap/build.gradle에 runtimeOnly project(':adapter:outbound:messaging-kafka') 한 줄을 넣으면 그 모듈이 bridge와 messaging-spring-boot-starter(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이 사실의 SSOT는 Gradle runtimeClasspath이며 registry에 동일한 membership 목록을 복제하지 않는다. 모듈이 있으면 켜지고(app.messaging.enabled 기본 true), APP_MESSAGING_ENABLED=false로만 끈다.

일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다. RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은 2026-09-25에 삭제했다(docs/capability-status.md 제거 표). 새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy, qualification/support 상태를 함께 변경한다.

application이 이 family에 도달하는 경로 (cutover 완료)

리뷰(docs/reviews/2026-08-14-messaging-module-code-review.md §6.1·§6.3)가 정한 application-owned port → platform anti-corruption bridge → platform 경로는 이제 존재한다.

  • application-owned port: IntegrationEventPublishPort
  • bridge: adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter
  • platform boundary: EncodedMessagePublisher
  • central implementation: DefaultMessagePublisher

bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge package는 messaging-core-api만 보며 concrete runtime/transport/Kafka 타입을 직접 보지 않는다.

application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정). application의 outbox append는 canonical OutboxAppendPort 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy OutboxEvent·LegacyOutboxAppendPort와 MessageBroker → KafkaSender R0 경로(TLS/SASL을 적용하지 않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security profile(KafkaSecurityConfigurer)을 적용한다.

canonical bridge의 producer identity는 app.messaging.producer-id로 명시한다. 값이 없으면 bridge bean을 만들지 않으며 spring.application.name/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면 relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.

IntegrationEventEncoderPort는 템플릿이 제공한다: adapter:outbound:support의 JsonIntegrationEventEncoder가 envelope v1(shared-contract의 contracts/messaging/envelope/v1.schema.json) 안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한 IntegrationEventContractContribution뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과 다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.

Stable 승격에 필요한 증거

adapter를 Experimental → Stable로 올릴 때 필요한 것 (docs/messaging/support-matrix.md가 현재 상태를 기록한다):

  1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이 BrokerCertificationEvidence를 산출한다.
  2. NetworkFaultScenario 전 항목에 대해 evidence가 있거나, 없는 항목이 knownGaps로 명시된다.
  3. capability 선언이 코드에서 파생된다 — MessagingCapabilities에 손으로 true를 쓰는 것은 증거가 아니다.
  4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은 Experimental에서도 금지다.
  5. unknown failure의 기본값이 AMBIGUOUS다. REJECTED는 전송이 시작되지 않았다는 typed 증거가 있을 때만.

Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.

증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:

./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain

레인(messagingCertificationTest)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며, 통과한 시나리오마다 BrokerCertificationEvidence 한 줄을 messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl에 쓴다. 게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — manifest를 손으로 고치면 실패하고, 레인을 돌리면 manifest가 다시 쓰인다. 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다). skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 test에서는 messaging-certification 태그로 제외된다.

Focused test

leaf의 gradle_path를 registry에서 읽어 파생한다.

cd src
./gradlew <gradle-path>:test --console=plain

Family 전체 검증:

./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew architectureCheck --console=plain
./gradlew verifyDependencyLocks --console=plain