Files
clean-architecture-backend-…/docs/jpa/support-matrix.md
T
DongHyeonka 08f932123a 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

8.9 KiB

JPA 영속성 플랫폼 — 지원 매트릭스

이 문서는 렌더링이다. 기계가 읽는 정본은 src/adapter/outbound/persistence-jpa/release/release-registry.json이다.

registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는 registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다.

  • JpaReleaseRenderingTest가 DB 표, gate 표, release.yml의 JPA matrix와 승격 목록을 registry와 비교한다.
  • jpaReleaseQualification 집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크 그래프를 만들 때 실패한다.
  • jpa-nightly.yml의 matrix도 같은 비교를 받는다. Experimental major는 .github/workflows의 어떤 lane이 그것을 대상으로 기록해야 하고, Stable lane은 그것을 돌리면 안 된다.

이력: 전에는 JpaReleaseManifest가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든 PostgreSQL NN이 지원 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다. 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. jpa-nightly.yml은 자기 matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다.

데이터베이스

Database Support Evidence
PostgreSQL 16 Stable 전체 계약 suite, 릴리스 lane(자기 matrix job)
PostgreSQL 17 Stable 전체 계약 suite, 릴리스 lane(자기 matrix job)
PostgreSQL 18 Stable 전체 계약 suite, 릴리스 lane(자기 matrix job)
PostgreSQL 19 Experimental jpa-next.yml — NOT_EXECUTABLE: postgres:19-alpine이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다
H2 Local convenience PostgreSQL 동작의 증거가 절대 아니다

major마다 자기 릴리스 job이 있다. release.yml의 jpa-release-gate job이 major마다 job 하나로 펼치고, 승격 job은 세 major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래서 major 하나가 빠지면 그 증거가 아니라 릴리스가 빠진다. JpaPlatformContractSupport.start()는 여러 버전 선택을 아예 거부한다.

이력: 한동안 그렇지 않았다. 릴리스 lane이 -Pjpa.matrix.versions=16,17,18을 selectedVersions().get(0)을 쓰는 JpaPlatformContractSupport.start()에 넘겼으므로, 통합 suite 전체가 PostgreSQL 16에만 돌았다. 이 표는 단언 셋짜리 smoke test를 근거로 17과 18을 전부 덮었다고 적었다.

provider 기준선. gate는 Spring Boot BOM이 푸는 Hibernate 버전 7.1.8.Final에서 돈다. registry는 그것을 stable-tested-baseline으로 기록한다. 7.4는 compatibility-target으로 기록하고, 전체 lane이 실제로 그 버전에서 돈 뒤에 기준선이 된다.

이력: 이 문서는 전에 7.4를 Stable 기준선이라 불렀고 페이지네이션 gate 이름도 hibernate-7.4-fetch-pagination이었다. 그래서 그 gate를 돌릴 때마다 한 번도 돌려 보지 않은 provider 이름이 붙은 증거가 나왔다.

H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스 빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.

SKIP LOCKED는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 AGENTS.md는 측정을 기록한다. H2 2.4.240은 FOR UPDATE SKIP LOCKED를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이 문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. 측정한 버전에서 관찰한 동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다. 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이 없으므로 모든 동시성 계약은 여전히 실제 PostgreSQL에서 돈다.

명세와 provider

구성 요소 Stable Experimental
Jakarta Persistence 3.2 4.0 (lane)
Hibernate ORM 7.4 선언 기준선 8 (lane)
Spring Boot 저장소 BOM —

Hibernate 줄에는 설명이 필요하다. 설계서는 7.4를 Stable provider로 선언하고, 이 저장소의 Spring Boot BOM은 7.1.x를 푼다. HibernateProviderPolicy가 둘을 다 가진다. 선언 기준선은 상수로, 풀린 버전은 Hibernate 자신에게서 읽는다. driftsFromDeclaredBaseline()이 상수를 상수와 비교하는 대신 그 차이를 드러낸다. repository-adaptation.md §4를 본다.

capability 지원 수준

수준은 jpaplatform actuator 엔드포인트가 JpaPlatformReport.platformCapabilities()로 보고하는 값이다. 마지막 세 줄(기술 감사, multi-tenancy, read replica)은 그 보고에 없고 이 문서가 정한다. Advanced와 Experimental 줄은 서비스가 직접 부르는 라이브러리 코드다(src/adapter/outbound/persistence-jpa/README.md 「라이브러리 API」).

capability 수준
Keyset pagination Stable
Flyway schema gate Stable
Runtime role verification Stable
Commit completion evidence Advanced
JDBC batch Advanced
Observability (query metrics, redaction) Advanced
PostgreSQL JSONB Advanced
PostgreSQL array and range Advanced
Bulk DML Advanced
Hibernate StatelessSession Advanced
PostgreSQL COPY Advanced (admin 자격 증명 필요)
Hibernate second-level cache Advanced
Hibernate Envers Advanced
기술 감사 — audit/AuditableEntity Stable (canonical)
Multi-tenancy (column, RLS, schema, database) Experimental
일관성을 아는 read replica Experimental

릴리스 gate

줄마다, 플랫폼이 테스트를 통과하고도 운영에서 틀릴 수 있는 길 하나다.

Gate Kind 막는 것
postgresql-contract gate DB 증거가 H2에서만 나온 릴리스
completion-unknown-no-retry gate 이미 커밋됐을 수 있는 쓰기를 자동으로 다시 돌림
osiv-disabled gate view 계층에서의 lazy loading, 렌더링한 행마다 쿼리 하나
flyway-validate gate Hibernate가 배포된 스키마를 바꾸거나, 맞지 않는 스키마에서 돎
runtime-role-no-ddl gate 애플리케이션 자신의 자격 증명으로 스키마 객체를 바꾸거나 지울 수 있음
collection-fetch-pagination gate 페이지 단위 collection fetch가 몰래 테이블 전체를 읽고 메모리에서 페이지를 나눔

감사 방식

감사 방식은 audit/AuditableEntity 하나다. created_*/updated_*, 256자 actor이고, repository 어댑터가 명시적으로 찍는다. 서비스의 엔티티는 이것을 상속하고, 마이그레이션도 이 열에 맞춰 썼다. 두 번째 방식인 Spring Data listener 기반 (auditing/AuditMetadata)은 한 번도 조립되지 않아서 지웠다. JpaAuditMechanismRule.entitiesUseExactlyOneAuditMechanism이 그것이 엔티티에 돌아오지 못하게 막는다.

이 방식은 bulk·native update에 닿지 않는다. 어댑터의 보통 save에서 찍으므로, DB로 바로 가는 문장은 감사 열을 앞 save의 값으로 남긴다. 그래서 감사 대상 엔티티의 bulk update는 문장 안에서 감사 열을 설정해야 하고, JpaAuditMechanismRule.bulkUpdatesOfAuditedEntitiesStampAudit가 운영 그래프에서 그것을 확인한다.

지원하지 않는다고 밝힌 것

  • Reactive JPA. JPA는 blocking 명세다. 그 위의 reactive facade는 blocking 호출을 없애는 게 아니라 event loop로 옮긴다.
  • 운영 스키마를 쓰는 Hibernate. ddl-auto는 배포된 스키마를 절대 바꾸지 않는다.
  • 플랫폼이 가진 generic CRUD repository. 도메인이 자기 repository를 가진다(설계서 §10.1).
  • 완료를 모르는 트랜잭션의 자동 맞추기. 플랫폼은 기록하고, 도메인이 푼다.