From 08f932123abe2a0145eceb85a957034e4a8f2e88 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 21:57:53 +0900 Subject: [PATCH 01/12] =?UTF-8?q?docs(agents)!:=20leaf=20=EC=A7=80?= =?UTF-8?q?=EC=97=AD=20=EA=B7=9C=EC=B9=99=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20?= =?UTF-8?q?=EA=B0=99=EC=9D=80=20=ED=8F=B4=EB=8D=94=20AGENTS.md=EB=A1=9C=20?= =?UTF-8?q?=EC=98=AE=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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` 한 줄이다. --- README.md | 8 +- docs/README.md | 2 +- docs/jpa/support-matrix.md | 2 +- docs/manual/01-generator.md | 2 +- docs/manual/02-new-feature.md | 4 +- docs/manual/03-placement.md | 2 +- docs/manual/05-idempotency.md | 2 +- docs/manual/09-outbox-events.md | 2 +- docs/manual/11-checklist.md | 4 +- docs/manual/README.md | 4 +- docs/messaging/support-matrix.md | 2 +- docs/mongodb/consumer-leaf-guide.md | 2 +- docs/upgrade/2026-11-harness.md | 14 + docs/work/README.md | 2 +- docs/work/docs-writing.md | 4 +- docs/work/improve.md | 2 +- docs/work/new-feature.md | 2 +- docs/work/reference/defect-patterns.md | 4 +- docs/work/reference/review-criteria.md | 10 +- docs/work/research-design.md | 2 +- scripts/check-docs.py | 51 ++- scripts/check-work-docs.py | 7 +- scripts/tests/test_check_docs.py | 32 ++ src/README.md | 2 +- src/adapter/inbound/graphql/AGENTS.md | 218 +++++++++++ src/adapter/inbound/graphql/CLAUDE.md | 219 +---------- src/adapter/inbound/graphql/README.md | 2 +- src/adapter/inbound/grpc/AGENTS.md | 115 ++++++ src/adapter/inbound/grpc/CLAUDE.md | 116 +----- src/adapter/inbound/grpc/README.md | 2 +- src/adapter/inbound/messaging/AGENTS.md | 23 ++ src/adapter/inbound/messaging/CLAUDE.md | 24 +- src/adapter/inbound/web-advanced/AGENTS.md | 45 +++ src/adapter/inbound/web-advanced/CLAUDE.md | 46 +-- src/adapter/inbound/web/AGENTS.md | 172 +++++++++ src/adapter/inbound/web/CLAUDE.md | 173 +-------- src/adapter/inbound/web/README.md | 4 +- src/adapter/inbound/websocket/AGENTS.md | 120 ++++++ src/adapter/inbound/websocket/CLAUDE.md | 121 +----- src/adapter/inbound/websocket/README.md | 2 +- src/adapter/outbound/cache-redis/AGENTS.md | 180 +++++++++ src/adapter/outbound/cache-redis/CLAUDE.md | 181 +-------- src/adapter/outbound/fileserver/AGENTS.md | 41 ++ src/adapter/outbound/fileserver/CLAUDE.md | 42 +- src/adapter/outbound/fileserver/README.md | 2 +- src/adapter/outbound/httpclient/AGENTS.md | 86 +++++ src/adapter/outbound/httpclient/CLAUDE.md | 87 +---- src/adapter/outbound/identifier/AGENTS.md | 53 +++ src/adapter/outbound/identifier/CLAUDE.md | 54 +-- src/adapter/outbound/identifier/README.md | 4 +- .../outbound/messaging-kafka/AGENTS.md | 13 + .../outbound/messaging-kafka/CLAUDE.md | 14 +- src/adapter/outbound/messaging/AGENTS.md | 46 +++ src/adapter/outbound/messaging/CLAUDE.md | 47 +-- src/adapter/outbound/messaging/README.md | 2 +- src/adapter/outbound/notification/AGENTS.md | 49 +++ src/adapter/outbound/notification/CLAUDE.md | 50 +-- src/adapter/outbound/objectstorage/AGENTS.md | 48 +++ src/adapter/outbound/objectstorage/CLAUDE.md | 49 +-- src/adapter/outbound/objectstorage/README.md | 2 +- .../outbound/persistence-fileserver/AGENTS.md | 59 +++ .../outbound/persistence-fileserver/CLAUDE.md | 60 +-- .../outbound/persistence-jpa/AGENTS.md | 357 +++++++++++++++++ .../outbound/persistence-jpa/CLAUDE.md | 358 +----------------- .../outbound/persistence-jpa/README.md | 10 +- .../outbound/persistence-mongo/AGENTS.md | 157 ++++++++ .../outbound/persistence-mongo/CLAUDE.md | 158 +------- .../mongo/MongoNamespaceContractTest.java | 2 +- .../persistence-notification/AGENTS.md | 52 +++ .../persistence-notification/CLAUDE.md | 53 +-- src/adapter/outbound/redis-sdk/README.md | 2 +- src/adapter/outbound/support/AGENTS.md | 42 ++ src/adapter/outbound/support/CLAUDE.md | 43 +-- src/adapter/outbound/support/README.md | 2 +- src/app-bootstrap/AGENTS.md | 121 ++++++ src/app-bootstrap/CLAUDE.md | 122 +----- src/app-bootstrap/README.md | 4 +- ...ileserverUseCaseContractDeviationTest.java | 2 +- .../ForbiddenApiArchitectureTest.java | 2 +- .../architecture/NamingConventionTest.java | 4 +- .../TemplatePackageOwnershipRuleTest.java | 2 +- .../TemplatePackageOwnership.java | 4 +- .../TemplatePackageOwnershipDocumentTest.java | 4 +- .../MessagingPublicSurfaceContractTest.java | 2 +- .../feature/FeatureAggregateRepository.java | 2 +- src/application-core/AGENTS.md | 336 ++++++++++++++++ src/application-core/CLAUDE.md | 337 +---------------- src/application-core/README.md | 2 +- src/composition/outbox-relay/AGENTS.md | 19 + src/composition/outbox-relay/CLAUDE.md | 20 +- src/domain-core/AGENTS.md | 38 ++ src/domain-core/CLAUDE.md | 39 +- src/domain-core/README.md | 2 +- src/platforms/grpc-advanced/AGENTS.md | 88 +++++ src/platforms/grpc-advanced/CLAUDE.md | 89 +---- src/platforms/grpc/AGENTS.md | 192 ++++++++++ src/platforms/grpc/CLAUDE.md | 193 +--------- src/platforms/messaging/AGENTS.md | 176 +++++++++ src/platforms/messaging/CLAUDE.md | 177 +-------- src/shared-contract/AGENTS.md | 69 ++++ src/shared-contract/CLAUDE.md | 70 +--- src/shared-contract/README.md | 2 +- 102 files changed, 3107 insertions(+), 2986 deletions(-) create mode 100644 docs/upgrade/2026-11-harness.md create mode 100644 src/adapter/inbound/graphql/AGENTS.md create mode 100644 src/adapter/inbound/grpc/AGENTS.md create mode 100644 src/adapter/inbound/messaging/AGENTS.md create mode 100644 src/adapter/inbound/web-advanced/AGENTS.md create mode 100644 src/adapter/inbound/web/AGENTS.md create mode 100644 src/adapter/inbound/websocket/AGENTS.md create mode 100644 src/adapter/outbound/cache-redis/AGENTS.md create mode 100644 src/adapter/outbound/fileserver/AGENTS.md create mode 100644 src/adapter/outbound/httpclient/AGENTS.md create mode 100644 src/adapter/outbound/identifier/AGENTS.md create mode 100644 src/adapter/outbound/messaging-kafka/AGENTS.md create mode 100644 src/adapter/outbound/messaging/AGENTS.md create mode 100644 src/adapter/outbound/notification/AGENTS.md create mode 100644 src/adapter/outbound/objectstorage/AGENTS.md create mode 100644 src/adapter/outbound/persistence-fileserver/AGENTS.md create mode 100644 src/adapter/outbound/persistence-jpa/AGENTS.md create mode 100644 src/adapter/outbound/persistence-mongo/AGENTS.md create mode 100644 src/adapter/outbound/persistence-notification/AGENTS.md create mode 100644 src/adapter/outbound/support/AGENTS.md create mode 100644 src/app-bootstrap/AGENTS.md create mode 100644 src/application-core/AGENTS.md create mode 100644 src/composition/outbox-relay/AGENTS.md create mode 100644 src/domain-core/AGENTS.md create mode 100644 src/platforms/grpc-advanced/AGENTS.md create mode 100644 src/platforms/grpc/AGENTS.md create mode 100644 src/platforms/messaging/AGENTS.md create mode 100644 src/shared-contract/AGENTS.md diff --git a/README.md b/README.md index c961aca4..e92ab1c1 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src | 하려는 일 | 시작할 곳 | | --- | --- | -| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) | +| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [AGENTS.md](AGENTS.md) | | 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` | | 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` | | 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` | @@ -92,7 +92,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src | 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 | | 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` | -각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)). +각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)). ## 검증 @@ -130,6 +130,6 @@ cd src ## 규칙과 기여 - 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다. -- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. -- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다. +- 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. +- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다. - 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다. diff --git a/docs/README.md b/docs/README.md index effd1865..d6937d9a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -200,4 +200,4 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 - 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다. - 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다. -- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다. +- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다. diff --git a/docs/jpa/support-matrix.md b/docs/jpa/support-matrix.md index 50a1965d..b0b5cf92 100644 --- a/docs/jpa/support-matrix.md +++ b/docs/jpa/support-matrix.md @@ -48,7 +48,7 @@ major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래 H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스 빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다. -`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다. +`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.md`는 측정을 기록한다. H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이 문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한 동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이 diff --git a/docs/manual/01-generator.md b/docs/manual/01-generator.md index 51adb4c1..d69e2cca 100644 --- a/docs/manual/01-generator.md +++ b/docs/manual/01-generator.md @@ -30,7 +30,7 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에 | 입력 | 규칙 | 어디서 막나 | | --- | --- | --- | | 이름 | PascalCase, 영숫자 | 스크립트 | -| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` | +| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` | | HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` | | 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 | diff --git a/docs/manual/02-new-feature.md b/docs/manual/02-new-feature.md index 0f36708c..aa781dc0 100644 --- a/docs/manual/02-new-feature.md +++ b/docs/manual/02-new-feature.md @@ -50,7 +50,7 @@ - **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`. - **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record). `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술 - 저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/CLAUDE.md`. + 저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`. ## 2단계 — application-core: 유스케이스와 포트 @@ -70,7 +70,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai - **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가. - **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`. - **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만 - `inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md` + `inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md` 「Allowed transactional shapes」. ### 판단: 무엇을 반환하나 diff --git a/docs/manual/03-placement.md b/docs/manual/03-placement.md index 395780c9..f74d59d0 100644 --- a/docs/manual/03-placement.md +++ b/docs/manual/03-placement.md @@ -55,7 +55,7 @@ - ``는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과 겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를 이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다. -- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md` +- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md` 「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다. - 이름 규칙은 같은 파일 「Naming convention」이 정본이다. diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md index 25280c6c..707251aa 100644 --- a/docs/manual/05-idempotency.md +++ b/docs/manual/05-idempotency.md @@ -16,7 +16,7 @@ DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false) ``` -정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」 +정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」 (executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명). ## 판단: 이 쓰기를 KEYED로 만드나 diff --git a/docs/manual/09-outbox-events.md b/docs/manual/09-outbox-events.md index 68affbe9..48a560ce 100644 --- a/docs/manual/09-outbox-events.md +++ b/docs/manual/09-outbox-events.md @@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을 없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다. -정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, +정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, `docs/messaging/delivery-guarantees.md`. ## 순서 diff --git a/docs/manual/11-checklist.md b/docs/manual/11-checklist.md index 70c210d2..2282613d 100644 --- a/docs/manual/11-checklist.md +++ b/docs/manual/11-checklist.md @@ -5,8 +5,8 @@ ## 배치·이름 - [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `` 패키지). -- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. -- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다. +- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. +- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다. ## domain diff --git a/docs/manual/README.md b/docs/manual/README.md index 47d7cc38..f3225d92 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -42,8 +42,8 @@ | --- | --- | | 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) | | leaf 목록·허용 의존 | `src/config/architecture/modules.json` | -| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` | -| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 | +| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` | +| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 | | HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` | | 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` | | 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` | diff --git a/docs/messaging/support-matrix.md b/docs/messaging/support-matrix.md index 1a2e72c9..d0325b2e 100644 --- a/docs/messaging/support-matrix.md +++ b/docs/messaging/support-matrix.md @@ -27,7 +27,7 @@ > `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만 > `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter / > auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와 -> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다. +> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다. ## 브로커 등급 diff --git a/docs/mongodb/consumer-leaf-guide.md b/docs/mongodb/consumer-leaf-guide.md index 9b7dd563..9ca05e57 100644 --- a/docs/mongodb/consumer-leaf-guide.md +++ b/docs/mongodb/consumer-leaf-guide.md @@ -3,7 +3,7 @@ 파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나 만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository· mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다 -(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden"). +(`src/adapter/outbound/persistence-mongo/AGENTS.md` "Forbidden"). 전체 흐름: diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md new file mode 100644 index 00000000..8d817540 --- /dev/null +++ b/docs/upgrade/2026-11-harness.md @@ -0,0 +1,14 @@ +# 업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스) + +- 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 `AGENTS.md`·`CLAUDE.md`), `.claude/`의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부 +- 근거: 소유자 결정(2026-11-07), design-docs `harness/01-harness-design.md` 13절, `docs/work/reference/decisions.md` 「지침 배치」 + +## 1. 누가 읽나 + +이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다. + +## 2. 바뀐 것과 할 일 + +| # | 바뀐 것 | 서비스가 할 일 | +| --- | --- | --- | +| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src//CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) | diff --git a/docs/work/README.md b/docs/work/README.md index 85ec8261..b16c5eec 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -31,7 +31,7 @@ 1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. 2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. -3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다. +3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다. 4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다. 5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. 6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md index 7d0147bd..fd4d8ae7 100644 --- a/docs/work/docs-writing.md +++ b/docs/work/docs-writing.md @@ -4,7 +4,7 @@ ## 1. 언제 쓰나 -- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때. +- `docs/work/`, `docs/manual/`, 루트·leaf `AGENTS.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때. - 이것은 아니다. - 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절) - 설계서·ADR → [research-design.md](research-design.md) @@ -28,7 +28,7 @@ ## 4. 절차 1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다". -2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. +2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. 3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. 4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다. diff --git a/docs/work/improve.md b/docs/work/improve.md index 5918448e..21a75b94 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -69,7 +69,7 @@ ### 4.3 리팩터링, 성능, 구조, 테스트 구조 - 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다. -- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다. +- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `AGENTS.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다. - 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다. - 구조 변경: 설계서(`docs/design/`)와 계획서(`docs/history/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다. - 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다. diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index de926738..1bb3aa2f 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -29,7 +29,7 @@ ## 4. 절차 1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다. -2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다. +2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. 3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. 4. 뼈대를 만든다: `scripts/new-feature.sh `(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」). 5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index d53b87d7..2052e1bb 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -2,7 +2,7 @@ 이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다. -계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. +계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. ## 패턴 @@ -121,7 +121,7 @@ | 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc | | 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) | | 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) | -| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) | +| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) | | 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` | ## 패턴을 더하는 법 diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index 4db104b6..ca26ce51 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -101,7 +101,7 @@ | # | 관점 | 볼 곳 | 이런 증거면 결함 | | --- | --- | --- | --- | | 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 | -| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | +| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | | 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | | 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 | | 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | @@ -123,9 +123,9 @@ | 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 | | 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 | | 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 | -| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | +| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | | 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 | -| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | +| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | | 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 | | 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 | @@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신 - 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다. - 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다. - 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). -- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. +- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. - vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. - source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). @@ -212,7 +212,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 - [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` -- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키) +- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키) - [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표 - [ ] ArchUnit 규칙과 그 위반·허용 fixture - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) diff --git a/docs/work/research-design.md b/docs/work/research-design.md index 406489b5..45d9e832 100644 --- a/docs/work/research-design.md +++ b/docs/work/research-design.md @@ -26,7 +26,7 @@ - `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」 - `docs/adr/`(되돌리기 비싼 선택), `docs/design/`(설계서), `docs/history/plans/`(계획서) - `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안" - - 가장 가까운 `src/**/CLAUDE.md`와 모듈 README + - 가장 가까운 `src/**/AGENTS.md`와 모듈 README - 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다. - 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다. diff --git a/scripts/check-docs.py b/scripts/check-docs.py index cb5628f3..f646ff36 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -61,7 +61,7 @@ from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt" REGISTRY_FILE = "src/config/architecture/modules.json" -CHECKS = ("language", "head", "reference", "number", "map", "readme") +CHECKS = ("language", "head", "reference", "number", "map", "readme", "link") # 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다. RECORD_KINDS = [ @@ -148,6 +148,10 @@ VERSION = re.compile(r"(? list[tuple[int, str]]: return spans +def link_targets(lines: list[str]) -> list[tuple[int, str]]: + """(줄 번호, 상대 링크 대상) — 코드 블록·인라인 코드·「이력」 인용 블록 밖에서만.""" + targets, fence, history = [], None, False + for number, line in enumerate(lines, start=1): + match = FENCE.match(line) + if fence: + if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence): + fence = None + continue + if match: + fence = match.group(1) + continue + quoted = line.lstrip().startswith(">") + if quoted and HISTORY_QUOTE.match(line): + history = True + elif not quoted: + history = False + if history: + continue + for found in LINK_TARGET.finditer(INLINE.sub("", line)): + target = found.group(1).split("#", 1)[0] + if target and not URL_SCHEME.match(target): + targets.append((number, target)) + return targets + + +def check_link(root: Path, files: list[str]) -> list[Problem]: + known = known_paths(root) + problems = [] + for path in files: + if not is_living(path): + continue + text = (root / path).read_text(encoding="utf-8") + lines = body_lines(text) + offset = len(text.split("\n")) - len(lines) + for number, target in link_targets(lines): + resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target)) + if resolved.startswith("..") or not is_known(known, resolved): + problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}", + number + offset)) + return problems + + def registry_projects(root: Path) -> set[str]: registry = root / REGISTRY_FILE if not registry.is_file(): @@ -634,7 +681,7 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]: RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number, - "map": check_map, "readme": check_readme} + "map": check_map, "readme": check_readme, "link": check_link} def read_exceptions(text: str) -> list[str]: diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index da225c80..c2729a99 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -9,7 +9,7 @@ to finish the job from those alone. Two things break that, and both are mechanic who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and - every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and + every `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and `docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository. 2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a total limit, so a session reads the whole path instead of skimming it. @@ -196,11 +196,12 @@ def check_skeleton(errors: list[str]) -> None: def module_guides() -> list[Path]: - """Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output.""" + """Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output. + The src/**/CLAUDE.md beside it is one line, `@AGENTS.md`, so Claude Code reads the same book.""" skipped = {"build", ".gradle", "node_modules"} return sorted( path - for path in (REPO_ROOT / "src").rglob("CLAUDE.md") + for path in (REPO_ROOT / "src").rglob("AGENTS.md") if not skipped.intersection(path.relative_to(REPO_ROOT).parts) ) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index 2924849e..17dd28d0 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -439,6 +439,38 @@ class ReadmeTest(RepositoryTestCase): self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다") +class LinkTest(RepositoryTestCase): + def errors_for(self, text: str, path: str = "src/app/AGENTS.md") -> list[str]: + self.repo.write(path, KOREAN + text) + return self.repo.run(("link",)) + + def test_a_relative_link_to_a_missing_file_fails(self) -> None: + self.assertFailsWith(self.errors_for("[설계](README.md)를 본다.\n"), "없는 곳을 가리키는 상대 링크다: README.md") + + def test_a_relative_link_to_a_tracked_file_passes(self) -> None: + self.repo.write("src/app/README.md", KOREAN) + self.assertEqual(self.errors_for("[설계](README.md#결정)를 본다.\n"), []) + + def test_a_link_up_the_tree_resolves_from_the_document_folder(self) -> None: + self.assertEqual(self.errors_for("[살아 있는 문서](../../docs/live.md)를 본다.\n"), []) + + def test_a_link_out_of_the_repository_fails(self) -> None: + self.assertFailsWith(self.errors_for("[밖](../../../outside.md)를 본다.\n"), "../../../outside.md") + + def test_a_folder_left_empty_on_disk_fails(self) -> None: + (self.repo.root / "src/app/moved").mkdir(parents=True) + self.assertFailsWith(self.errors_for("[옮김](moved/)을 본다.\n"), "moved/") + + def test_urls_anchors_code_and_history_quotes_are_skipped(self) -> None: + text = ("[웹](https://example.com/x) [절](#절) `[코드](gone.md)`\n" + "```text\n[블록](gone.md)\n```\n> 이력: [옛 문서](gone.md)는 지웠다.\n") + self.assertEqual(self.errors_for(text), []) + + def test_a_record_is_not_checked(self) -> None: + self.repo.write("docs/design/2026-08-11-x-design.md", head() + "[옛](gone.md)\n") + self.assertEqual(self.repo.run(("link",)), []) + + class CommandLineTest(unittest.TestCase): def test_an_unknown_check_is_a_usage_error(self) -> None: self.assertEqual(check_docs.main(["--only", "spelling"]), 2) diff --git a/src/README.md b/src/README.md index 7db03a60..a29728d9 100644 --- a/src/README.md +++ b/src/README.md @@ -1,7 +1,7 @@ # src — 빌드 스크립트 / 환경 변수 참조 `src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md) -와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다. +와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다. 이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과 결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조" diff --git a/src/adapter/inbound/graphql/AGENTS.md b/src/adapter/inbound/graphql/AGENTS.md new file mode 100644 index 00000000..bec9db91 --- /dev/null +++ b/src/adapter/inbound/graphql/AGENTS.md @@ -0,0 +1,218 @@ +# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치) + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-graphql` +- Gradle 경로: `:adapter:inbound:graphql` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +Package root: `dev.caskeleton.adapter.inbound.graphql`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 +규칙 SSOT). + +## 플랫폼 모듈 = sub-package (Gradle 모듈 아님) + +GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이 +leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은 +방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 +SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다. + +**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매 +플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는 +`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간 +낡는다. 즉 이 레포에는 두 패턴이 공존한다: + +| | 방식 | 경계 강제 | +| --- | --- | --- | +| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 | +| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) | + +어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다. + +sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/` +모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다 +(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 — +`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상): + +- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과 + 그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명 + 매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이 + 오면 실패한다. +- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다. + +두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의 +required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다. + +## 책임 + +- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`, + 프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를 + 자동 합성/바인딩하도록 얹는 얇은 계층이다. +- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송 + 프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을 + 소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다. +- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/ + `@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.** +- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')` + 한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며, + 그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다. + 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 + 명시해야 한다. + +## 오류 코드 소유 + +`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현 +코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를 +`GraphQlErrorCode`에 둔다. + +- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 + 실패한다. +- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다. + GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 — + DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25). +- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire + 계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다. +- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에 + 더하지 않는다. + +`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를 +고정한다. + +## 허용 + +- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제 + 의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이 + 거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일 + 의존해야 했고, 그건 의존 방향이 뒤집힌다. +- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음). +- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용), + `spring-boot-starter-security`(HTTP 인증/CORS qualification 용), + `io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**). +- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가 + 소유하고 production jar 에 들어가지 않는다. +- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`). + +**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`· +`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만 +`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를 +고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부 +`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행 +프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다. +- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가 + `@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티 + 게이트가 이 선언을 요구한다. + +## 금지 + +- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 + 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit + `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이 + 모듈을 자동 커버 — per-module 규칙 추가 불필요). +- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의 + `HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. +- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다. + +## 오류 대응 (`Category → ErrorType`) + +모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 +pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 +(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된 +application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의 +`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한 +실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안 +걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 +shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category → +wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다. +DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정). + +## 향후 adopter 의 feature 기여 방법 + +- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면 + `classpath:graphql/**` 병합으로 합칠 수 있다. +- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동 + 바인딩된다. +- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나 + `ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다. + +템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는 +health 스키마만 소유한다. + +## 구현된 플랫폼 범위 — 등급으로 말한다 + +"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 +쓰고, **현재 등급보다 높게 표현하지 않는다.** + +| 등급 | 의미 | +| --- | --- | +| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. | +| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. | +| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. | +| `production-verified` | 실부하·장애 시나리오 증거가 있다. | + +| Capability | 등급 | 증거 | +| --- | --- | --- | +| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) | +| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 | +| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 | +| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 | +| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` | +| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) | +| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 | +| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` | +| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) | +| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 | +| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 | +| 실부하·장애 | 미달성 | 증거 없음 | + +여전히 미구현인 것: + +- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음). +- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`, + `advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에 + 삭제했다. +- 실제 datastore 통합 증거 — 없다. +- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription + replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 + (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 + 형태로 새로 만든다. + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:graphql:test --console=plain +./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain +``` + +테스트 레인: + +```bash +./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지 +./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버) +``` + +`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면 +실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다. + +## 아티팩트 게이트 + +```bash +./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain +./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain +``` + +- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/ + `TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는 + `src/testFixtures/java` 가 소유한다. +- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public + 타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로, + 표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후: + `./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`. + +- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context· + fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본 + `GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면 + application `IdempotencyExecutor` 를 use case 안에서 쓴다. diff --git a/src/adapter/inbound/graphql/CLAUDE.md b/src/adapter/inbound/graphql/CLAUDE.md index bec9db91..43c994c2 100644 --- a/src/adapter/inbound/graphql/CLAUDE.md +++ b/src/adapter/inbound/graphql/CLAUDE.md @@ -1,218 +1 @@ -# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치) - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-graphql` -- Gradle 경로: `:adapter:inbound:graphql` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -Package root: `dev.caskeleton.adapter.inbound.graphql`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 -규칙 SSOT). - -## 플랫폼 모듈 = sub-package (Gradle 모듈 아님) - -GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이 -leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은 -방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 -SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다. - -**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매 -플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는 -`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간 -낡는다. 즉 이 레포에는 두 패턴이 공존한다: - -| | 방식 | 경계 강제 | -| --- | --- | --- | -| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 | -| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) | - -어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다. - -sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/` -모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다 -(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 — -`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상): - -- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과 - 그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명 - 매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이 - 오면 실패한다. -- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다. - -두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의 -required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다. - -## 책임 - -- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`, - 프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를 - 자동 합성/바인딩하도록 얹는 얇은 계층이다. -- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송 - 프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을 - 소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다. -- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/ - `@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.** -- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')` - 한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며, - 그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다. - 실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께 - 명시해야 한다. - -## 오류 코드 소유 - -`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현 -코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를 -`GraphQlErrorCode`에 둔다. - -- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로 - 실패한다. -- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다. - GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 — - DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25). -- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire - 계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다. -- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에 - 더하지 않는다. - -`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를 -고정한다. - -## 허용 - -- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제 - 의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이 - 거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일 - 의존해야 했고, 그건 의존 방향이 뒤집힌다. -- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음). -- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용), - `spring-boot-starter-security`(HTTP 인증/CORS qualification 용), - `io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**). -- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가 - 소유하고 production jar 에 들어가지 않는다. -- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`). - -**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`· -`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만 -`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를 -고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부 -`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행 -프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다. -- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가 - `@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티 - 게이트가 이 선언을 요구한다. - -## 금지 - -- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 - 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit - `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이 - 모듈을 자동 커버 — per-module 규칙 추가 불필요). -- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의 - `HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다. -- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다. - -## 오류 대응 (`Category → ErrorType`) - -모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 -pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 -(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된 -application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의 -`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한 -실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안 -걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 -shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category → -wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다. -DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정). - -## 향후 adopter 의 feature 기여 방법 - -- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면 - `classpath:graphql/**` 병합으로 합칠 수 있다. -- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동 - 바인딩된다. -- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나 - `ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다. - -템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는 -health 스키마만 소유한다. - -## 구현된 플랫폼 범위 — 등급으로 말한다 - -"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 -쓰고, **현재 등급보다 높게 표현하지 않는다.** - -| 등급 | 의미 | -| --- | --- | -| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. | -| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. | -| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. | -| `production-verified` | 실부하·장애 시나리오 증거가 있다. | - -| Capability | 등급 | 증거 | -| --- | --- | --- | -| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) | -| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 | -| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 | -| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 | -| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` | -| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) | -| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 | -| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` | -| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) | -| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 | -| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 | -| 실부하·장애 | 미달성 | 증거 없음 | - -여전히 미구현인 것: - -- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음). -- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`, - `advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에 - 삭제했다. -- 실제 datastore 통합 증거 — 없다. -- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription - replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 - (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 - 형태로 새로 만든다. - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:graphql:test --console=plain -./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain -``` - -테스트 레인: - -```bash -./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지 -./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버) -``` - -`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면 -실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다. - -## 아티팩트 게이트 - -```bash -./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain -./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain -``` - -- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/ - `TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는 - `src/testFixtures/java` 가 소유한다. -- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public - 타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로, - 표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후: - `./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`. - -- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context· - fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본 - `GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면 - application `IdempotencyExecutor` 를 use case 안에서 쓴다. +@AGENTS.md diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index 98e59e89..34399b67 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -4,7 +4,7 @@ `dev.caskeleton.adapter.inbound.graphql`. 허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다. --- diff --git a/src/adapter/inbound/grpc/AGENTS.md b/src/adapter/inbound/grpc/AGENTS.md new file mode 100644 index 00000000..9b4ef61f --- /dev/null +++ b/src/adapter/inbound/grpc/AGENTS.md @@ -0,0 +1,115 @@ +# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치) + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-grpc` +- Gradle 경로: `:adapter:inbound:grpc` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +Package root: `dev.caskeleton.adapter.inbound.grpc`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 +규칙 SSOT). + +## 책임 + +- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`), + feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` + + `GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard + health, 명시적으로 켠 경우에만 reflection). +- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을 + 이름으로 알지 않는다. + +## 허용 + +- `:application-core`, `:domain-core`, `:shared-contract`. +- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services), + `spring-boot-starter`, `spring-boot-starter-validation`. + +## 금지 + +- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 + 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit + `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`). +- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와 + 서비스는 consuming feature 모듈이 소유한다. +- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의 + `HealthcheckController` 와 동일 원칙). + +## 설정 손잡이 (`app.grpc.server.*`) + +타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 +(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이 +`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*` +키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). + +| key | default | 의미 | +|---|---|---| +| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 | +| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) | +| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 | +| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override | +| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 | +| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 | +| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 | +| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) | +| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) | +| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 | +| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) | +| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` | +| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` | +| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) | +| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 | +| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 | + +한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다. +`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로 +`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면 +configuration binding/startup 단계에서 실패한다. + +## 이 capability 채택하기 + +gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다. + +1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존 + edge를 더한다. +2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에 + `dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다. +3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다. +4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다. +5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다. + +**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은 +Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을 +받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS +credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다. + +## Feature 기여 방법 + +현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할 +때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한 +개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면 +listener 시작이 실패한다. 정책은 `Optional authenticate(Metadata)`이고, 돌려준 +호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이 +빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지 +않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드 +이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다). + +## P1 증거와 한계 + +- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건. +- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패, + reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction. + 서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다. + +이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS, +external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다. + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:grpc:test +``` diff --git a/src/adapter/inbound/grpc/CLAUDE.md b/src/adapter/inbound/grpc/CLAUDE.md index 9b4ef61f..43c994c2 100644 --- a/src/adapter/inbound/grpc/CLAUDE.md +++ b/src/adapter/inbound/grpc/CLAUDE.md @@ -1,115 +1 @@ -# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치) - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-grpc` -- Gradle 경로: `:adapter:inbound:grpc` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -Package root: `dev.caskeleton.adapter.inbound.grpc`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 -규칙 SSOT). - -## 책임 - -- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`), - feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` + - `GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard - health, 명시적으로 켠 경우에만 reflection). -- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을 - 이름으로 알지 않는다. - -## 허용 - -- `:application-core`, `:domain-core`, `:shared-contract`. -- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services), - `spring-boot-starter`, `spring-boot-starter-validation`. - -## 금지 - -- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드 - 포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit - `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`). -- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와 - 서비스는 consuming feature 모듈이 소유한다. -- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의 - `HealthcheckController` 와 동일 원칙). - -## 설정 손잡이 (`app.grpc.server.*`) - -타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 -(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이 -`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*` -키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). - -| key | default | 의미 | -|---|---|---| -| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 | -| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) | -| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 | -| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override | -| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 | -| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 | -| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 | -| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) | -| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) | -| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 | -| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) | -| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` | -| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` | -| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) | -| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 | -| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 | - -한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다. -`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로 -`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면 -configuration binding/startup 단계에서 실패한다. - -## 이 capability 채택하기 - -gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다. - -1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존 - edge를 더한다. -2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에 - `dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다. -3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다. -4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다. -5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다. - -**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은 -Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을 -받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS -credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다. - -## Feature 기여 방법 - -현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할 -때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한 -개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면 -listener 시작이 실패한다. 정책은 `Optional authenticate(Metadata)`이고, 돌려준 -호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이 -빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지 -않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드 -이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다). - -## P1 증거와 한계 - -- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건. -- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패, - reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction. - 서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다. - -이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS, -external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다. - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:grpc:test -``` +@AGENTS.md diff --git a/src/adapter/inbound/grpc/README.md b/src/adapter/inbound/grpc/README.md index 47bd49d8..23e16504 100644 --- a/src/adapter/inbound/grpc/README.md +++ b/src/adapter/inbound/grpc/README.md @@ -4,7 +4,7 @@ `dev.caskeleton.adapter.inbound.grpc`. 허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다. --- diff --git a/src/adapter/inbound/messaging/AGENTS.md b/src/adapter/inbound/messaging/AGENTS.md new file mode 100644 index 00000000..e1637a6e --- /dev/null +++ b/src/adapter/inbound/messaging/AGENTS.md @@ -0,0 +1,23 @@ +# adapter:inbound:messaging + +- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본: + `src/config/architecture/modules.json`. +- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는 + inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의 + `TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의 + `MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에 + 아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다. +- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이 + 없다. 허용 edge는 registry 항목에서만 온다. +- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접 + 만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다 + (`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계, + `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」, + `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, + `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler`)만 구현하고, + `Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). +- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`. + 실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`). +- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본 + group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다. +- 설계와 버린 대안: `README.md`. diff --git a/src/adapter/inbound/messaging/CLAUDE.md b/src/adapter/inbound/messaging/CLAUDE.md index e1637a6e..43c994c2 100644 --- a/src/adapter/inbound/messaging/CLAUDE.md +++ b/src/adapter/inbound/messaging/CLAUDE.md @@ -1,23 +1 @@ -# adapter:inbound:messaging - -- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본: - `src/config/architecture/modules.json`. -- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는 - inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의 - `TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의 - `MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에 - 아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다. -- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이 - 없다. 허용 edge는 registry 항목에서만 온다. -- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접 - 만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다 - (`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계, - `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」, - `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, - `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler`)만 구현하고, - `Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`). -- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`. - 실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`). -- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본 - group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다. -- 설계와 버린 대안: `README.md`. +@AGENTS.md diff --git a/src/adapter/inbound/web-advanced/AGENTS.md b/src/adapter/inbound/web-advanced/AGENTS.md new file mode 100644 index 00000000..1f11e209 --- /dev/null +++ b/src/adapter/inbound/web-advanced/AGENTS.md @@ -0,0 +1,45 @@ +# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-web-advanced` +- Gradle 경로: `:adapter:inbound:web-advanced` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain` +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄, +설정은 [README.md](README.md)에 있다. + +## 책임 + +- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch / + Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning, + operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록. +- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의 + `AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다. + +## 규칙 + +- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다. + `app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다. +- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다. +- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다 + (서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나 + `@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports + 한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`). +- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와 + OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`). +- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다: + forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache + header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`). + 그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`). +- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음, + `application-core`·`domain-core`로 새는 DTO 없음. + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:web-advanced:check --console=plain +./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain +``` diff --git a/src/adapter/inbound/web-advanced/CLAUDE.md b/src/adapter/inbound/web-advanced/CLAUDE.md index 1f11e209..43c994c2 100644 --- a/src/adapter/inbound/web-advanced/CLAUDE.md +++ b/src/adapter/inbound/web-advanced/CLAUDE.md @@ -1,45 +1 @@ -# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리 - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-web-advanced` -- Gradle 경로: `:adapter:inbound:web-advanced` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain` -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄, -설정은 [README.md](README.md)에 있다. - -## 책임 - -- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch / - Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning, - operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록. -- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의 - `AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다. - -## 규칙 - -- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다. - `app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다. -- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다. -- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다 - (서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나 - `@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports - 한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`). -- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와 - OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`). -- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다: - forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache - header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`). - 그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`). -- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음, - `application-core`·`domain-core`로 새는 DTO 없음. - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:web-advanced:check --console=plain -./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain -``` +@AGENTS.md diff --git a/src/adapter/inbound/web/AGENTS.md b/src/adapter/inbound/web/AGENTS.md new file mode 100644 index 00000000..50d56f78 --- /dev/null +++ b/src/adapter/inbound/web/AGENTS.md @@ -0,0 +1,172 @@ +# adapter:inbound:web — inbound HTTP 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-web` +- Gradle 경로: `:adapter:inbound:web` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.inbound.web`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). + +## 책임 + +- HTTP controller. +- 요청·응답 DTO. +- 요청 DTO를 application command로 바꾸기. +- 인증, 검증, 오류 대응, filter, web·보안 설정. +- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥. +- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는, + 전송 계층이 가진 OpenAPI 손질. + +모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports` +루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다. +`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만 +뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다. +이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이 +이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual +thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context +bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다. +운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다 +(Gradle registry + ArchUnit `WEB-ARCH-ADV`). + +## 허용 + +- `:application-core` +- `:domain-core` +- `:shared-contract` +- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는 + 모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그 + leaf에서 이 클래스만 허용한다. +- Spring Web·Security·Validation 의존성. + +## 금지 + +- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기. +- controller에서 repository나 JPA 엔티티에 직접 접근하기. +- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙. +- DTO가 application이나 domain으로 새는 것. + +## 경계 검증과 mapper 계약 + +`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위 +가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임 +패턴도 정한다. + +- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`, + `fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을 + `false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지 + **않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는 + wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 + 한다. +- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 + *없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에 + `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 `Optional` wrapper를 쓴다. +- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL + 정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로 + 보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한 + `IllegalArgumentException`은 계속 `BAD_PARAMETER`다. +- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은 + `application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다. + `@Valid` cascade 깊이는 3 이하로 둔다. +- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나 + `LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다 + (`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command` + 타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다. +- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지 + 않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나 + `RequestContextHolder`로 `requestId` / `traceId`를 전파한다. +- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에 + 닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답 + 원본 타입은 `domain-core`로 새면 안 된다. +- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가 + 실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로 + 답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다. + +이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는 +다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의 +catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다. + +기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약 +(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`, +`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는 +애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`). + +## schema·직렬화 계약 + +`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1 +*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch` + `JsonNullable`, +B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의 +`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제 +설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`). + +- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은 + `JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` → + `"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z` + offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대 + 없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다. +- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과 + schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가 + 큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융 + endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를 + 잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할 + 때 정한다. +- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다 + (`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로 + 만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다. +- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1 + `read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지 + 않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch`(B2)로 + 나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다. +- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운 + 필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용 + Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은 + 다른 브랜치다. + +## 업무 규칙 검증 계약 + +`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서, +「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과 +계약 시험이 강제한다(새 런타임 장치가 아니다). + +| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 | +|---|---|---|---|---| +| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` | +| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | +| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | +| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | + +- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 + `adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로 + 나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙 + `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다. +- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성 + 경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴 + 인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만 + 지키기」). +- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는 + **클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index + 이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본 + `GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로 + 바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은 + `feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다. +- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수 + 있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나 + 관련 `AGENTS.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날 + 위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지 + `needs-confirmation`이다. + +이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와 +`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper +표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드 +(`feature-operational-error-observability-foundation`). + +## 테스트 + +```bash +cd src +./gradlew :adapter:inbound:web:test --console=plain +``` diff --git a/src/adapter/inbound/web/CLAUDE.md b/src/adapter/inbound/web/CLAUDE.md index b31212eb..43c994c2 100644 --- a/src/adapter/inbound/web/CLAUDE.md +++ b/src/adapter/inbound/web/CLAUDE.md @@ -1,172 +1 @@ -# adapter:inbound:web — inbound HTTP 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-web` -- Gradle 경로: `:adapter:inbound:web` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.inbound.web`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). - -## 책임 - -- HTTP controller. -- 요청·응답 DTO. -- 요청 DTO를 application command로 바꾸기. -- 인증, 검증, 오류 대응, filter, web·보안 설정. -- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥. -- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는, - 전송 계층이 가진 OpenAPI 손질. - -모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports` -루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다. -`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만 -뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다. -이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이 -이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual -thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context -bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다. -운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다 -(Gradle registry + ArchUnit `WEB-ARCH-ADV`). - -## 허용 - -- `:application-core` -- `:domain-core` -- `:shared-contract` -- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는 - 모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그 - leaf에서 이 클래스만 허용한다. -- Spring Web·Security·Validation 의존성. - -## 금지 - -- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기. -- controller에서 repository나 JPA 엔티티에 직접 접근하기. -- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙. -- DTO가 application이나 domain으로 새는 것. - -## 경계 검증과 mapper 계약 - -`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위 -가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임 -패턴도 정한다. - -- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`, - `fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을 - `false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지 - **않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는 - wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 - 한다. -- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 - *없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에 - `org.openapitools:jackson-databind-nullable`(`JsonNullable`)이나 `Optional` wrapper를 쓴다. -- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL - 정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로 - 보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한 - `IllegalArgumentException`은 계속 `BAD_PARAMETER`다. -- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은 - `application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다. - `@Valid` cascade 깊이는 3 이하로 둔다. -- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나 - `LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다 - (`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command` - 타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다. -- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지 - 않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나 - `RequestContextHolder`로 `requestId` / `traceId`를 전파한다. -- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에 - 닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답 - 원본 타입은 `domain-core`로 새면 안 된다. -- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가 - 실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로 - 답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다. - -이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는 -다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의 -catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다. - -기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약 -(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`, -`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는 -애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`). - -## schema·직렬화 계약 - -`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1 -*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch` + `JsonNullable`, -B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의 -`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제 -설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`). - -- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은 - `JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` → - `"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z` - offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대 - 없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다. -- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과 - schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가 - 큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융 - endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를 - 잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할 - 때 정한다. -- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다 - (`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로 - 만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다. -- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1 - `read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지 - 않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch`(B2)로 - 나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다. -- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운 - 필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용 - Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은 - 다른 브랜치다. - -## 업무 규칙 검증 계약 - -`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서, -「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과 -계약 시험이 강제한다(새 런타임 장치가 아니다). - -| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 | -|---|---|---|---|---| -| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` | -| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | -| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | -| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | - -- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 - `adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로 - 나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙 - `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다. -- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성 - 경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴 - 인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만 - 지키기」). -- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는 - **클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index - 이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본 - `GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로 - 바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은 - `feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다. -- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수 - 있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나 - 관련 `CLAUDE.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날 - 위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지 - `needs-confirmation`이다. - -이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와 -`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper -표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드 -(`feature-operational-error-observability-foundation`). - -## 테스트 - -```bash -cd src -./gradlew :adapter:inbound:web:test --console=plain -``` +@AGENTS.md diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 840517b1..9173bad1 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -9,7 +9,7 @@ route inventory)는 opt-in leaf `adapter:inbound:web-advanced` 에 있다 ([README](../web-advanced/README.md)). 허용/금지 의존, 경계 계약(B1~B8), 스키마/직렬화 계약(S1~S5), 비즈니스 규칙 검증 계약(C1~C8), -테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 +테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다. @@ -197,7 +197,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML - **D5: RFC 7807 `ProblemDetail` 표현은 거부**하고 자체 `Envelope` 형식을 쓴다. - **운영/전송/보안 예외만** 처리한다. 도메인 예외는 소비 모듈의 별도 `@RestControllerAdvice` 가 처리하고 - Spring 이 두 advice 를 합성(compose)한다(CLAUDE.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조). + Spring 이 두 advice 를 합성(compose)한다(AGENTS.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조). - **클라이언트 메시지는 allowlist다.** 예외 메시지, validation interpolated message, rejected request value, raw request URL은 `error.message`/`details`에 넣지 않는다. `error.message`는 항상 shared-contract diff --git a/src/adapter/inbound/websocket/AGENTS.md b/src/adapter/inbound/websocket/AGENTS.md new file mode 100644 index 00000000..cc19b9f8 --- /dev/null +++ b/src/adapter/inbound/websocket/AGENTS.md @@ -0,0 +1,120 @@ +# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계 + +## 등록 정보 + +- 모듈 ID: `adapter-inbound-websocket` +- Gradle 경로: `:adapter:inbound:websocket` +- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain` +- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json` + +패키지 루트: `dev.caskeleton.adapter.inbound.websocket`. + +## 책임 + +이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다. + +1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정, + handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는 + 만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다. +2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘 + `core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의 + 어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을 + 적는다. + +이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command +원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는 +command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도 +살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다. + +이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다. + +## 허용 + +- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존. +- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter. +- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane). + +## 금지 + +- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기. +- repository, Spring Data, 영속 엔티티, 업무 정책 접근. +- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화. +- 켜져 있을 때 wildcard·빈 handshake origin. +- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기. +- 이 골격 leaf 안의 운영 기능 `@MessageMapping`. +- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다. +- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는 + `WebSocketConnectionBudget`의 필드가 아니다. +- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다. + +## 타입 있는 설정 (`app.websocket.*`) + +속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만 +설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다. + +| 속성 | env | 기본값·역할 | +| --- | --- | --- | +| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 | +| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` | +| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 | +| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | +| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 | +| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) | +| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) | +| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) | +| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) | +| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 | + +`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다. + +## 이 capability 채택하기 + +WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다. + +1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용 + edge를 더한다. +2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에 + `dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다. +3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에 + 있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로 + 한다. +4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그 + `SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다. +5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다: + `./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`. + +## inbound 정책 (STOMP) + +- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다. +- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다. +- 인증된 `SEND`는 `/app/**` 아래에만 허용한다. +- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다. +- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진 + ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은 + `ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그 + 밖에는 `WEBSOCKET_REQUEST_REJECTED`다. + +## 이벤트 projection 계약 + +나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector` bean을 기여할 수 있다. +broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이 +실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는 +`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로, +simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면 +이벤트를 버린다(best-effort, R1). + +템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다. + +## 증거와 한계 + +| lane | 증명하는 것 | +| --- | --- | +| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 | +| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 | +| `websocketJettyTest` | Jetty에서 handler 런타임 계약 | +| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) | +| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 | + +simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달, +롤백에 안전한 발행, replay·resume은 주지 않는다. diff --git a/src/adapter/inbound/websocket/CLAUDE.md b/src/adapter/inbound/websocket/CLAUDE.md index cc19b9f8..43c994c2 100644 --- a/src/adapter/inbound/websocket/CLAUDE.md +++ b/src/adapter/inbound/websocket/CLAUDE.md @@ -1,120 +1 @@ -# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계 - -## 등록 정보 - -- 모듈 ID: `adapter-inbound-websocket` -- Gradle 경로: `:adapter:inbound:websocket` -- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain` -- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json` - -패키지 루트: `dev.caskeleton.adapter.inbound.websocket`. - -## 책임 - -이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다. - -1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정, - handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는 - 만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다. -2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘 - `core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의 - 어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을 - 적는다. - -이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command -원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는 -command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도 -살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다. - -이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다. - -## 허용 - -- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존. -- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter. -- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane). - -## 금지 - -- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기. -- repository, Spring Data, 영속 엔티티, 업무 정책 접근. -- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화. -- 켜져 있을 때 wildcard·빈 handshake origin. -- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기. -- 이 골격 leaf 안의 운영 기능 `@MessageMapping`. -- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다. -- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는 - `WebSocketConnectionBudget`의 필드가 아니다. -- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다. - -## 타입 있는 설정 (`app.websocket.*`) - -속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만 -설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다. - -| 속성 | env | 기본값·역할 | -| --- | --- | --- | -| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 | -| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` | -| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 | -| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | -| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 | -| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) | -| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) | -| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) | -| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) | -| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 | - -`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다. - -## 이 capability 채택하기 - -WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다. - -1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용 - edge를 더한다. -2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에 - `dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다. -3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에 - 있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로 - 한다. -4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그 - `SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다. -5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다: - `./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`. - -## inbound 정책 (STOMP) - -- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다. -- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다. -- 인증된 `SEND`는 `/app/**` 아래에만 허용한다. -- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다. -- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진 - ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은 - `ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그 - 밖에는 `WEBSOCKET_REQUEST_REJECTED`다. - -## 이벤트 projection 계약 - -나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector` bean을 기여할 수 있다. -broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이 -실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는 -`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로, -simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면 -이벤트를 버린다(best-effort, R1). - -템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다. - -## 증거와 한계 - -| lane | 증명하는 것 | -| --- | --- | -| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 | -| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 | -| `websocketJettyTest` | Jetty에서 handler 런타임 계약 | -| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) | -| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 | - -simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달, -롤백에 안전한 발행, replay·resume은 주지 않는다. +@AGENTS.md diff --git a/src/adapter/inbound/websocket/README.md b/src/adapter/inbound/websocket/README.md index 8bb1bf11..31c91557 100644 --- a/src/adapter/inbound/websocket/README.md +++ b/src/adapter/inbound/websocket/README.md @@ -1,6 +1,6 @@ # adapter-inbound-websocket -모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [CLAUDE.md](CLAUDE.md)가 SSOT다. 이 문서는 무엇을 +모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [AGENTS.md](AGENTS.md)가 SSOT다. 이 문서는 무엇을 제공하는지, 어떻게 붙이는지, 왜 이런 모양인지를 적는다. 이 leaf는 두 가지를 제공한다. 서로 참조하지 않는다. diff --git a/src/adapter/outbound/cache-redis/AGENTS.md b/src/adapter/outbound/cache-redis/AGENTS.md new file mode 100644 index 00000000..b00bee92 --- /dev/null +++ b/src/adapter/outbound/cache-redis/AGENTS.md @@ -0,0 +1,180 @@ +# adapter:outbound:cache-redis — cache와 Redis 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-cache-redis` +- Gradle 경로: `:adapter:outbound:cache-redis` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.cache`. + +## 책임 + +- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다. +- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결, + capability별 실패 뜻을 가진다. +- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL + jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의 + `CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에 + 맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다. +- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로 + 구현한다. +- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다. +- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. +- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis + runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다. +- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이 + leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다. + +## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`) + +등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의 +`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다). + +- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology + client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`, + `SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에 + 의존한다. +- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를 + 상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고 + 자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을 + `RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`). + `cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**. +- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌 + semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고, + `redis-command-policy.yml`이 그것을 다루지 않는다. +- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고, + `META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다. + +`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의 +일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은 +`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다. + +- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는 + `sdk.api.reactive` 안에만 둔다. +- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다. +- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령 + 정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책 + 파일이 아니다. +- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인 + `RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서 + driver를 직접 부르지 않는다. +- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지 + 않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot + 요청을 거절할 수 있다. +- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지 + 않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는 + 애플리케이션이 아니라 admin plane이다. +- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한 + 키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다. + 줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기 + 때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이 + 아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의 + 명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니, + 트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다. +- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에 + `ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다. + 명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다. +- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자 + 읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지 + 않게 응답을 걸러 낸다. +- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은 + `ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두 + `ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가 + 아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다. +- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기, + 아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다. +- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인 + R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음. + metric이나 trace tag에 실제 키 없음. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다. +- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다. +- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다. +- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다. +- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다. +- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은 + 조율 role이고 실패하면 닫히는 것뿐이다. +- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애 + 증거는 R2를 위해 따로 필요하다. + +## 테스트 + +이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의 +`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를 +거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다. + +실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의 +`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 — +`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을 +읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`, +`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약), +`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다 +(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의 +낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이 +ACL 파일을 이름으로 댈 때만 서버를 띄운다. + +`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과 +`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과 +`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`, +`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은 +`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나 +돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가 +실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라 +lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다. + +예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은 +`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로 +관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가 +줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다. + +## 조립 + +`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이 +생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인 +동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기 +`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다. + +골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그 +`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED` +스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야 +한다. + +모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 — +`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이 +각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다. + +lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는 +*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다. +`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은 +script를 실행할 수 없다. + +cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다 +(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다). +`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면 +안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`, +tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는 +`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`). + +Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한 +`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을 +빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다. + +설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함): +`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서 +`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이 +leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP +경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은 +그중 하나에 넣고, 네 번째 트리를 만들지 않는다. + +`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이 +그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는 +properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은 +`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit +provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이 +모듈은 bean을 하나도 기여하지 않는다. diff --git a/src/adapter/outbound/cache-redis/CLAUDE.md b/src/adapter/outbound/cache-redis/CLAUDE.md index b00bee92..43c994c2 100644 --- a/src/adapter/outbound/cache-redis/CLAUDE.md +++ b/src/adapter/outbound/cache-redis/CLAUDE.md @@ -1,180 +1 @@ -# adapter:outbound:cache-redis — cache와 Redis 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-cache-redis` -- Gradle 경로: `:adapter:outbound:cache-redis` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.cache`. - -## 책임 - -- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다. -- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결, - capability별 실패 뜻을 가진다. -- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL - jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의 - `CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에 - 맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다. -- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로 - 구현한다. -- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다. -- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. -- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis - runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다. -- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이 - leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다. - -## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`) - -등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의 -`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다). - -- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology - client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`, - `SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에 - 의존한다. -- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를 - 상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고 - 자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을 - `RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`). - `cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**. -- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌 - semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고, - `redis-command-policy.yml`이 그것을 다루지 않는다. -- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고, - `META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다. - -`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의 -일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은 -`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다. - -- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는 - `sdk.api.reactive` 안에만 둔다. -- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다. -- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령 - 정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책 - 파일이 아니다. -- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인 - `RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서 - driver를 직접 부르지 않는다. -- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지 - 않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot - 요청을 거절할 수 있다. -- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지 - 않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는 - 애플리케이션이 아니라 admin plane이다. -- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한 - 키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다. - 줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기 - 때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이 - 아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의 - 명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니, - 트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다. -- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에 - `ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다. - 명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다. -- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자 - 읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지 - 않게 응답을 걸러 낸다. -- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은 - `ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두 - `ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가 - 아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다. -- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기, - 아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다. -- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인 - R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음. - metric이나 trace tag에 실제 키 없음. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다. -- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다. -- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다. -- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다. -- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다. -- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은 - 조율 role이고 실패하면 닫히는 것뿐이다. -- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애 - 증거는 R2를 위해 따로 필요하다. - -## 테스트 - -이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의 -`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를 -거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다. - -실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의 -`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 — -`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을 -읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`, -`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약), -`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다 -(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의 -낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이 -ACL 파일을 이름으로 댈 때만 서버를 띄운다. - -`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과 -`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과 -`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`, -`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은 -`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나 -돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가 -실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라 -lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다. - -예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은 -`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로 -관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가 -줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다. - -## 조립 - -`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이 -생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인 -동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기 -`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다. - -골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그 -`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED` -스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야 -한다. - -모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 — -`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이 -각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다. - -lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는 -*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다. -`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은 -script를 실행할 수 없다. - -cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다 -(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다). -`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면 -안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`, -tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는 -`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`). - -Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한 -`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을 -빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다. - -설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함): -`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서 -`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이 -leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP -경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은 -그중 하나에 넣고, 네 번째 트리를 만들지 않는다. - -`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이 -그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는 -properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은 -`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit -provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이 -모듈은 bean을 하나도 기여하지 않는다. +@AGENTS.md diff --git a/src/adapter/outbound/fileserver/AGENTS.md b/src/adapter/outbound/fileserver/AGENTS.md new file mode 100644 index 00000000..fbece082 --- /dev/null +++ b/src/adapter/outbound/fileserver/AGENTS.md @@ -0,0 +1,41 @@ +# adapter:outbound:fileserver — 모듈 규칙 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-fileserver` +- Gradle 경로: `:adapter:outbound:fileserver` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven +(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다. +설계 근거는 [README.md](README.md)에 있다. + +## 책임 + +- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric. +- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한 + `platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다. +- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은 + `docs/fileserver/support-matrix.md`가 적는다. + +## 허용 + +- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고 + `src/build.gradle`이 강제한다. `:domain-core`는 없다. +- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`. + +## 금지 + +- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). +- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기. +- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기. +- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. + +## 테스트 + +```bash +cd src +./gradlew :adapter:outbound:fileserver:check +``` diff --git a/src/adapter/outbound/fileserver/CLAUDE.md b/src/adapter/outbound/fileserver/CLAUDE.md index fbece082..43c994c2 100644 --- a/src/adapter/outbound/fileserver/CLAUDE.md +++ b/src/adapter/outbound/fileserver/CLAUDE.md @@ -1,41 +1 @@ -# adapter:outbound:fileserver — 모듈 규칙 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-fileserver` -- Gradle 경로: `:adapter:outbound:fileserver` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven -(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다. -설계 근거는 [README.md](README.md)에 있다. - -## 책임 - -- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric. -- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한 - `platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다. -- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은 - `docs/fileserver/support-matrix.md`가 적는다. - -## 허용 - -- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고 - `src/build.gradle`이 강제한다. `:domain-core`는 없다. -- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`. - -## 금지 - -- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). -- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기. -- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기. -- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. - -## 테스트 - -```bash -cd src -./gradlew :adapter:outbound:fileserver:check -``` +@AGENTS.md diff --git a/src/adapter/outbound/fileserver/README.md b/src/adapter/outbound/fileserver/README.md index 39e29bfc..f1bfaf72 100644 --- a/src/adapter/outbound/fileserver/README.md +++ b/src/adapter/outbound/fileserver/README.md @@ -5,7 +5,7 @@ HTTP 파일 서버 플랫폼의 outbound(driven) 어댑터다. 패키지 루트: 시스템 내용 저장, 업로드 검증, 식별자, 감사, metric. 허용·금지 운영 의존 정책은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이 -가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md)에 있다. +가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [AGENTS.md](AGENTS.md)에 있다. 전송·보안·설정·운영 계약은 `docs/fileserver/`에 있다. 이 파일 서버 플랫폼과 Object Storage 중 무엇을 고를지에 대한 저장소 단위 선택은 diff --git a/src/adapter/outbound/httpclient/AGENTS.md b/src/adapter/outbound/httpclient/AGENTS.md new file mode 100644 index 00000000..f1e67aab --- /dev/null +++ b/src/adapter/outbound/httpclient/AGENTS.md @@ -0,0 +1,86 @@ +# adapter:outbound:httpclient — HTTP client 플랫폼 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-httpclient` +- Gradle 경로: `:adapter:outbound:httpclient` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`. + +## 설계 정본 + +구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는 +것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다. +그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른 +패키지로 옮기기 전에 그것을 읽는다. + +## 책임 + +- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native + engine 접근은 `apache`, `jdk`, `http3` 안에 머문다. +- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`, + Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다. +- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS, + SSRF 방어, streaming lifecycle, 관측을 가진다. +- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다. +- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. + +## 패키지 경계 + +`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다: + +- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다. +- `profile`은 공개적으로 `api`에만 의존한다. +- transport 패키지는 gateway로 거슬러 닿지 않는다. +- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다. +- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures` + (`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은 + test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의 + 유일한 정의는 `PlatformClasses`다. +- Stable 코드는 `http3`를 참조하지 않는다. +- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다. +- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에 + 남는다. +- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client, + 재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle + 의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다. +- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다. +- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩, + 기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성 + metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다. + 스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다. +- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는 + 이 런타임 켜기 스위치와 따로 정한다. + +## 테스트 + +기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다: + +| lane | 용도 | +|---|---| +| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 | +| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality | +| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** | +| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 | +| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 | +| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite | +| `jmh` | 호출당 부담 benchmark | + +고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이 +비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가 +`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이 +실패시킨다. + +transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나 +`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고 +(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본 +fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의 +변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6). diff --git a/src/adapter/outbound/httpclient/CLAUDE.md b/src/adapter/outbound/httpclient/CLAUDE.md index f1e67aab..43c994c2 100644 --- a/src/adapter/outbound/httpclient/CLAUDE.md +++ b/src/adapter/outbound/httpclient/CLAUDE.md @@ -1,86 +1 @@ -# adapter:outbound:httpclient — HTTP client 플랫폼 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-httpclient` -- Gradle 경로: `:adapter:outbound:httpclient` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`. - -## 설계 정본 - -구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는 -것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다. -그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른 -패키지로 옮기기 전에 그것을 읽는다. - -## 책임 - -- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native - engine 접근은 `apache`, `jdk`, `http3` 안에 머문다. -- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`, - Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다. -- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS, - SSRF 방어, streaming lifecycle, 관측을 가진다. -- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다. -- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. - -## 패키지 경계 - -`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다: - -- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다. -- `profile`은 공개적으로 `api`에만 의존한다. -- transport 패키지는 gateway로 거슬러 닿지 않는다. -- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다. -- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures` - (`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은 - test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의 - 유일한 정의는 `PlatformClasses`다. -- Stable 코드는 `http3`를 참조하지 않는다. -- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다. -- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에 - 남는다. -- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client, - 재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle - 의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다. -- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다. -- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩, - 기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성 - metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다. - 스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다. -- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는 - 이 런타임 켜기 스위치와 따로 정한다. - -## 테스트 - -기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다: - -| lane | 용도 | -|---|---| -| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 | -| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality | -| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** | -| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 | -| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 | -| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite | -| `jmh` | 호출당 부담 benchmark | - -고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이 -비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가 -`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이 -실패시킨다. - -transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나 -`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고 -(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본 -fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의 -변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6). +@AGENTS.md diff --git a/src/adapter/outbound/identifier/AGENTS.md b/src/adapter/outbound/identifier/AGENTS.md new file mode 100644 index 00000000..0d021b3a --- /dev/null +++ b/src/adapter/outbound/identifier/AGENTS.md @@ -0,0 +1,53 @@ +# adapter:outbound:identifier — IO 없는 기반 capability 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-identifier` +- Gradle 경로: `:adapter:outbound:identifier` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.identifier`. + +예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다. + +## 책임 + +- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256, + 소문자 hex). +- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7). + operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다. + `composition:durable-operation`이 배선한다. +- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니 + 이름을 그대로 둔다(README). +- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다. + +## 허용 + +[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다. + +- `:application-core` — 두 클래스가 구현하는 포트. +- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다. + `HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴 + 로그를 이 값으로 잇기 때문이다. +- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry + edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`). +- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7. + +## 금지 + +- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit + `IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다. +- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`. +- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다. + +## 테스트 + +Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함), +`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`. + +```bash +cd src +./gradlew :adapter:outbound:identifier:test --console=plain +``` diff --git a/src/adapter/outbound/identifier/CLAUDE.md b/src/adapter/outbound/identifier/CLAUDE.md index 0d021b3a..43c994c2 100644 --- a/src/adapter/outbound/identifier/CLAUDE.md +++ b/src/adapter/outbound/identifier/CLAUDE.md @@ -1,53 +1 @@ -# adapter:outbound:identifier — IO 없는 기반 capability 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-identifier` -- Gradle 경로: `:adapter:outbound:identifier` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.identifier`. - -예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다. - -## 책임 - -- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256, - 소문자 hex). -- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7). - operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다. - `composition:durable-operation`이 배선한다. -- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니 - 이름을 그대로 둔다(README). -- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다. - -## 허용 - -[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다. - -- `:application-core` — 두 클래스가 구현하는 포트. -- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다. - `HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴 - 로그를 이 값으로 잇기 때문이다. -- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry - edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`). -- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7. - -## 금지 - -- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit - `IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다. -- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`. -- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다. - -## 테스트 - -Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함), -`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`. - -```bash -cd src -./gradlew :adapter:outbound:identifier:test --console=plain -``` +@AGENTS.md diff --git a/src/adapter/outbound/identifier/README.md b/src/adapter/outbound/identifier/README.md index 95acbb3d..d338f02c 100644 --- a/src/adapter/outbound/identifier/README.md +++ b/src/adapter/outbound/identifier/README.md @@ -3,7 +3,7 @@ 이 leaf의 main 코드는 `HmacUserPrincipalPseudonymizer`와 `UuidV7DurableOperationIdFactory` 두 클래스다. 패키지 루트: `dev.caskeleton.adapter.outbound.identifier`. -허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md)가 기준이다. 이 문서는 +허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md)가 기준이다. 이 문서는 설계 결정의 근거를 모은다. ## 이름과 내용이 다른 이유 (review 05-21) @@ -49,7 +49,7 @@ Spring 어노테이션이 없다. bean은 의존은 넷이다: `:application-core`(두 클래스가 구현하는 port), `:shared-contract`(`HmacSha256`), `:domain-core`(기능의 `*IdFactory` 구현 자리), `uuid-creator`(UUIDv7). 목록과 이유는 -[CLAUDE.md](CLAUDE.md) Allowed 절이 기준이다. +[AGENTS.md](AGENTS.md) Allowed 절이 기준이다. `:application-core`를 `implementation`으로 받는다. 이 leaf의 public 타입 시그니처에 application-core 타입이 드러나지만, 조립하는 쪽이 application-core를 이미 classpath에 갖고 있다. diff --git a/src/adapter/outbound/messaging-kafka/AGENTS.md b/src/adapter/outbound/messaging-kafka/AGENTS.md new file mode 100644 index 00000000..8434332e --- /dev/null +++ b/src/adapter/outbound/messaging-kafka/AGENTS.md @@ -0,0 +1,13 @@ +# adapter:outbound:messaging-kafka + +- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`. + registry 정본: `src/config/architecture/modules.json`. +- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다: + `adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온 + 플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다. +- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온 + 제품(`src/platforms/messaging/AGENTS.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는 + registry 항목에서만 온다. +- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane + `messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`). +- 설계: `README.md`. diff --git a/src/adapter/outbound/messaging-kafka/CLAUDE.md b/src/adapter/outbound/messaging-kafka/CLAUDE.md index 7f2fa07a..43c994c2 100644 --- a/src/adapter/outbound/messaging-kafka/CLAUDE.md +++ b/src/adapter/outbound/messaging-kafka/CLAUDE.md @@ -1,13 +1 @@ -# adapter:outbound:messaging-kafka - -- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`. - registry 정본: `src/config/architecture/modules.json`. -- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다: - `adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온 - 플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다. -- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온 - 제품(`src/platforms/messaging/CLAUDE.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는 - registry 항목에서만 온다. -- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane - `messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`). -- 설계: `README.md`. +@AGENTS.md diff --git a/src/adapter/outbound/messaging/AGENTS.md b/src/adapter/outbound/messaging/AGENTS.md new file mode 100644 index 00000000..bfd3277d --- /dev/null +++ b/src/adapter/outbound/messaging/AGENTS.md @@ -0,0 +1,46 @@ +# adapter:outbound:messaging — 메시징 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-messaging` +- Gradle 경로: `:adapter:outbound:messaging` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.messaging`. + +## 책임 + +- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다. +- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다. +- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해 + 남긴다. +- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다. +- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다. + `platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다. +- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛 + `KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와 + 함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다. +- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod, + 프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할 + 길이 없다. +- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라 + `adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도 + 있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다 + (`docs/capability-status.md`). +- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사 + (`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25). +- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다. +- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진 + ERROR 하나를 가진다. + +## 테스트 + +가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다. +설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다. diff --git a/src/adapter/outbound/messaging/CLAUDE.md b/src/adapter/outbound/messaging/CLAUDE.md index bfd3277d..43c994c2 100644 --- a/src/adapter/outbound/messaging/CLAUDE.md +++ b/src/adapter/outbound/messaging/CLAUDE.md @@ -1,46 +1 @@ -# adapter:outbound:messaging — 메시징 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-messaging` -- Gradle 경로: `:adapter:outbound:messaging` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.messaging`. - -## 책임 - -- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다. -- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다. -- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해 - 남긴다. -- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다. -- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다. - `platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다. -- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛 - `KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와 - 함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다. -- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod, - 프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할 - 길이 없다. -- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라 - `adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도 - 있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다 - (`docs/capability-status.md`). -- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사 - (`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25). -- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다. -- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진 - ERROR 하나를 가진다. - -## 테스트 - -가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다. -설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다. +@AGENTS.md diff --git a/src/adapter/outbound/messaging/README.md b/src/adapter/outbound/messaging/README.md index 95aa5803..3cce4894 100644 --- a/src/adapter/outbound/messaging/README.md +++ b/src/adapter/outbound/messaging/README.md @@ -5,7 +5,7 @@ adapter로 구조화한다. 허용/금지 의존 정책은 `src/config/architecture/modules.json`과 이 모듈의 -[CLAUDE.md](CLAUDE.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 +[AGENTS.md](AGENTS.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다. ## 모듈 개요 diff --git a/src/adapter/outbound/notification/AGENTS.md b/src/adapter/outbound/notification/AGENTS.md new file mode 100644 index 00000000..16bd153e --- /dev/null +++ b/src/adapter/outbound/notification/AGENTS.md @@ -0,0 +1,49 @@ +# adapter:outbound:notification — 알림 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-notification` +- Gradle 경로: `:adapter:outbound:notification` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.notification`. + +## 책임 + +- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환 + 기준선으로만 지킨다. +- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을 + 새게 하지 않는다. +- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은 + 애플리케이션 정책이 가진다. +- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. + +## 지금의 R0 동결 + +- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다. +- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다. +- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나 + 검증된 provider card가 아니다. +- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가 + 대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다. +- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다. +- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을 + 더하지 않는다. + +## 경계 + +- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. +- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다. +- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다. +- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는 + 아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동 + 구성에 그런 것이 스물두 개 쌓여 있었다. + `dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는 + import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다. + +## 테스트 + +provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면 +바인딩·검증 시험을 더한다. diff --git a/src/adapter/outbound/notification/CLAUDE.md b/src/adapter/outbound/notification/CLAUDE.md index 16bd153e..43c994c2 100644 --- a/src/adapter/outbound/notification/CLAUDE.md +++ b/src/adapter/outbound/notification/CLAUDE.md @@ -1,49 +1 @@ -# adapter:outbound:notification — 알림 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-notification` -- Gradle 경로: `:adapter:outbound:notification` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.notification`. - -## 책임 - -- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환 - 기준선으로만 지킨다. -- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을 - 새게 하지 않는다. -- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은 - 애플리케이션 정책이 가진다. -- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다. - -## 지금의 R0 동결 - -- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다. -- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다. -- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나 - 검증된 provider card가 아니다. -- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가 - 대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다. -- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다. -- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을 - 더하지 않는다. - -## 경계 - -- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다. -- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다. -- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다. -- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는 - 아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동 - 구성에 그런 것이 스물두 개 쌓여 있었다. - `dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는 - import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다. - -## 테스트 - -provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면 -바인딩·검증 시험을 더한다. +@AGENTS.md diff --git a/src/adapter/outbound/objectstorage/AGENTS.md b/src/adapter/outbound/objectstorage/AGENTS.md new file mode 100644 index 00000000..49182c7c --- /dev/null +++ b/src/adapter/outbound/objectstorage/AGENTS.md @@ -0,0 +1,48 @@ +# adapter:outbound:objectstorage — 모듈 규칙 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-objectstorage` +- Gradle 경로: `:adapter:outbound:objectstorage` +- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는 +[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다. + +## 책임 + +- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과 + 엄격한 durable 제어 레코드 뒤에서 구현한다. +- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는 + provider·destination·route·policy 바인딩으로 컴파일한다. +- R1 전용 개발 provider로 `filesystem-local-dev`를 준다. +- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant· + multipart 포트는 없다. + +## 허용 + +- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다. + 지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge + (`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/ + `SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게 + 바인딩한다. capability 규칙 4)다. +- provider SDK·설정 타입은 이 leaf 안에 머문다. +- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다. + +## 금지 + +- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존. +- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것. +- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경. +- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기. +- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장. +- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기. + +## 테스트 + +```bash +cd src +./gradlew :adapter:outbound:objectstorage:check --console=plain +``` diff --git a/src/adapter/outbound/objectstorage/CLAUDE.md b/src/adapter/outbound/objectstorage/CLAUDE.md index 49182c7c..43c994c2 100644 --- a/src/adapter/outbound/objectstorage/CLAUDE.md +++ b/src/adapter/outbound/objectstorage/CLAUDE.md @@ -1,48 +1 @@ -# adapter:outbound:objectstorage — 모듈 규칙 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-objectstorage` -- Gradle 경로: `:adapter:outbound:objectstorage` -- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는 -[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다. - -## 책임 - -- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과 - 엄격한 durable 제어 레코드 뒤에서 구현한다. -- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는 - provider·destination·route·policy 바인딩으로 컴파일한다. -- R1 전용 개발 provider로 `filesystem-local-dev`를 준다. -- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant· - multipart 포트는 없다. - -## 허용 - -- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다. - 지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge - (`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/ - `SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게 - 바인딩한다. capability 규칙 4)다. -- provider SDK·설정 타입은 이 leaf 안에 머문다. -- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다. - -## 금지 - -- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존. -- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것. -- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경. -- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기. -- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장. -- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기. - -## 테스트 - -```bash -cd src -./gradlew :adapter:outbound:objectstorage:check --console=plain -``` +@AGENTS.md diff --git a/src/adapter/outbound/objectstorage/README.md b/src/adapter/outbound/objectstorage/README.md index 696b97c3..89d51fed 100644 --- a/src/adapter/outbound/objectstorage/README.md +++ b/src/adapter/outbound/objectstorage/README.md @@ -4,7 +4,7 @@ `dev.caskeleton.application.objectstorage`의 semantic 계약을 구현하고, provider 키·경로·SDK 타입·제어 레코드를 애플리케이션 경계 뒤에 둔다. -허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md), 전체 +허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [AGENTS.md](AGENTS.md), 전체 설계는 `docs/design/2026-07-28-objectstorage-production-capability-design.md`, 정확한 증거 주장은 `docs/registries/object-storage-readiness.yaml`에 있다. diff --git a/src/adapter/outbound/persistence-fileserver/AGENTS.md b/src/adapter/outbound/persistence-fileserver/AGENTS.md new file mode 100644 index 00000000..94273307 --- /dev/null +++ b/src/adapter/outbound/persistence-fileserver/AGENTS.md @@ -0,0 +1,59 @@ +# persistence-fileserver + +파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는 +store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/AGENTS.md`도 그대로 적용된다. 이 파일은 이 +leaf에만 있는 것을 더한다. + +## 패키지 + +- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다. +- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`). +- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration` + 클래스. + +`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을 +따르므로 두 capability leaf를 같은 방식으로 읽는다. + +## 규칙 + +- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require(" ")`로 + 시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다. +- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity` + (`Persistable`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로 + 하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도 + 된다. 새것인지는 version이 아니라 `Persistable`이 정한다. +- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트 + 인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다. +- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리 + 처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다. + +## migration + +- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream + (`flyway_jpa_fileserver_history`)으로 적용한다. +- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의 + `AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다. + +## 테스트 + +- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기: + `./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`. + - `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에 + 닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다). + - `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고, + JPA 루트 자동 구성보다 먼저 돈다. + - `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는 + `PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다. + - `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다. + 새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다. +- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota + 포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는 + 포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL + 쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서 + `FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다. +- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이 + container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`, + `JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와 + selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`, + `postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest` + (`./gradlew :adapter:outbound:persistence-jpa: --console=plain`). diff --git a/src/adapter/outbound/persistence-fileserver/CLAUDE.md b/src/adapter/outbound/persistence-fileserver/CLAUDE.md index bb4c0a83..43c994c2 100644 --- a/src/adapter/outbound/persistence-fileserver/CLAUDE.md +++ b/src/adapter/outbound/persistence-fileserver/CLAUDE.md @@ -1,59 +1 @@ -# persistence-fileserver - -파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는 -store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/CLAUDE.md`도 그대로 적용된다. 이 파일은 이 -leaf에만 있는 것을 더한다. - -## 패키지 - -- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다. -- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`). -- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration` - 클래스. - -`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을 -따르므로 두 capability leaf를 같은 방식으로 읽는다. - -## 규칙 - -- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require(" ")`로 - 시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다. -- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity` - (`Persistable`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로 - 하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도 - 된다. 새것인지는 version이 아니라 `Persistable`이 정한다. -- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트 - 인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다. -- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리 - 처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다. - -## migration - -- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream - (`flyway_jpa_fileserver_history`)으로 적용한다. -- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의 - `AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다. - -## 테스트 - -- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기: - `./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`. - - `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에 - 닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다). - - `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고, - JPA 루트 자동 구성보다 먼저 돈다. - - `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는 - `PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다. - - `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다. - 새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다. -- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota - 포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는 - 포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL - 쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서 - `FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다. -- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이 - container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`, - `JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와 - selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`, - `postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest` - (`./gradlew :adapter:outbound:persistence-jpa: --console=plain`). +@AGENTS.md diff --git a/src/adapter/outbound/persistence-jpa/AGENTS.md b/src/adapter/outbound/persistence-jpa/AGENTS.md new file mode 100644 index 00000000..b6131bef --- /dev/null +++ b/src/adapter/outbound/persistence-jpa/AGENTS.md @@ -0,0 +1,357 @@ +# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-persistence-jpa` +- Gradle 경로: `:adapter:outbound:persistence-jpa` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.persistence`. + +예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산 +lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다. + +이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다. +앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다. + +## JPA 관계형 영속 플랫폼 + +`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리 +모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의 +**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다. + +| 플랫폼 패키지 | 가지는 것 | +|---|---| +| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 | +| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor | +| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) | +| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard | +| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session | +| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY | +| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) | +| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 | +| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 | +| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 | +| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector | + +`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`, +`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`, +`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는 +자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다. + +### Spring 조립 소유 + +`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다: +`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다** +`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. +둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은 +`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은 +2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 +않는다. + +`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가 +Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource, +pool, EntityManagerFactory, Flyway가 하나도 없다. + +소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL +store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다), +`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 +고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability +registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌 +data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다. + +이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본 +조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: +migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 +(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정 +(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 +안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다. +기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 +실수로 `verifyJpaApiSurface`가 늘지 않게 한다. + +### 양보할 수 없는 것 + +- `GenericRepository`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다. +- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는 + completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다. +- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다. +- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다. +- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 + (`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그 + 규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미 + `main`에 있는 파일에서 그것을 찾았을 때만 늘어난다. +- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY` + migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서 + 만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가 + `Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위 + 클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema"). +- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다. +- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다. + +### 플랫폼 lane + +```bash +cd src +./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour +# Release blocking composition is CI-owned; locally run the exact database qualification set: +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \ + :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \ + :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \ + :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \ + :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \ + :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest +``` + +Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 +아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. + +## 책임 + +- JPA 엔티티. +- Spring Data repository. +- 영속 mapper. +- repository 어댑터 구현. +- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope + 바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수 + 없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다. +- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고 + `lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에 + 대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는 + 2026-09-25에 지웠다(`docs/capability-status.md`). +- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의 + 다리. +- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) — + 아래 「영속 감사 계약」을 본다. +- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점: + - `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그 + 옆 `outbox/postgresql`과 `outbox/h2`에 있다. + - `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다. + +## vendor 고르기 + +vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 +등록한다: + +| vendor | 패키지 | 고르는 것 | schema 소유 | +| --- | --- | --- | --- | +| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` | +| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 | + +outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와 +`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 +driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도 +`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다. + +`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 +`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 +`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를 +`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 +성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가 +고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤 +속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다: +`postgresql` provider는 기동 때 H2 data source를 거절한다. + +H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — +capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 +`postgresqlIntegrationTest`에 남는다. + +outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 +정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다. + +### capability로 막은 store + +선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver` +패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는 +`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다. + +그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 +필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 +capability의 store는 있으면 안 된다. + +## 허용 + +- `:application-core` +- `:domain-core` +- `:shared-contract` +- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기) +- Spring Data JPA와 Spring transaction. + +## 금지 (Forbidden) + +- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터. +- 표현 계층 DTO. +- 업무 정책 판단. +- 영속 어댑터 안에 숨긴 유스케이스 조율. +- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션 + 유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을 + 정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert). + [application-core/AGENTS.md](../../../application-core/AGENTS.md)를 본다. +- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의 + 맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다. + `CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가 + 강제한다. +- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다. +- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터. + +## TransactionPort 구현 계약 + +`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: + +| 모드 | 전파 | 격리 | 읽기 전용 | timeout | +|---|---|---|---|---| +| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) | +| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 | +| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) | +| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 | + +격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이 +`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용), +`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 +`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다. + +모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 +취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 +`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다. +후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에 +던진 업무 예외는 바꾸지 않고 넘긴다. + +미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기 +template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥 +트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시 +`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다. + +`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 +올리고 호출자에게 성공 값을 돌려주지 않는다. + +### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract) + +`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다: + +``` +hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 +``` + +레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나, +반복문을 트랜잭션 밖으로 뺀다. + +## 영속 실패 번역 계약 (feature-persistence-failure-baseline) + +날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. +`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 +분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. + +**표준 행(core):** + +| SQLState | code | category | http | retryable | +|---|---|---|---|---| +| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true | +| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true | +| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false | +| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | +| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false | +| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | + +**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):** + +| SQLState | code | vendor | +|---|---|---| +| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) | +| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL | +| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL | +| `57014` | `DB_QUERY_CANCELED` | PostgreSQL | +| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL | +| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 | +| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 | + +PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. +`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와 +`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는 +것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에 +따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든 +다르면 `SqlStateClassificationParityTest`가 실패한다. + +**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA +`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`) +→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring +data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`. + +**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기 +트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`: +PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라 +`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 +수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다. + +- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다 + (`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 + `INTERNAL` envelope으로 답하게 한다(새는 것 없음). +- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT). + +## 영속 감사 계약 (feature-persistence-auditing-contract) + +감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. +`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 +명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. +ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 +`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. + +- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 + 감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로 + 넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다. +- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 + (scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은 + feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다. +- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를 + 상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / + feature-transaction-concurrency-contract가 가진다. +- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity` + 계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data + listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. + +## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules) + +영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계 +위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다: + +```java +import javax.annotation.processing.Generated; + +classes() + .that().resideInAPackage("..adapter.persistence.mapper..") + .and().areNotAnnotatedWith(Generated.class) + .should() /* ... boundary rule ... */; +``` + +> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는 +> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는 +> 바로 그 애너테이션으로 범위를 잡는다. + +지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위 +predicate를 따르고, fixture mapper로 red/green 시험을 더한다. + +## NoSQL 확장 규칙 + +`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB, +Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다: + +```text +adapter-persistence-mongodb +adapter-persistence-redis +adapter-persistence-dynamodb +``` + +그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다. + +## 테스트 + +```bash +cd src +./gradlew :adapter:outbound:persistence-jpa:test --console=plain +``` diff --git a/src/adapter/outbound/persistence-jpa/CLAUDE.md b/src/adapter/outbound/persistence-jpa/CLAUDE.md index 2fd3e384..43c994c2 100644 --- a/src/adapter/outbound/persistence-jpa/CLAUDE.md +++ b/src/adapter/outbound/persistence-jpa/CLAUDE.md @@ -1,357 +1 @@ -# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-persistence-jpa` -- Gradle 경로: `:adapter:outbound:persistence-jpa` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.persistence`. - -예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산 -lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다. - -이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다. -앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다. - -## JPA 관계형 영속 플랫폼 - -`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리 -모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의 -**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다. - -| 플랫폼 패키지 | 가지는 것 | -|---|---| -| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 | -| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor | -| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) | -| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard | -| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session | -| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY | -| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) | -| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 | -| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 | -| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 | -| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector | - -`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`, -`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`, -`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는 -자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다. - -### Spring 조립 소유 - -`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다: -`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다** -`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. -둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은 -`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은 -2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 -않는다. - -`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가 -Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource, -pool, EntityManagerFactory, Flyway가 하나도 없다. - -소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL -store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다), -`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 -고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability -registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌 -data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다. - -이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본 -조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: -migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 -(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정 -(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 -안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다. -기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 -실수로 `verifyJpaApiSurface`가 늘지 않게 한다. - -### 양보할 수 없는 것 - -- `GenericRepository`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다. -- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는 - completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다. -- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다. -- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다. -- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 - (`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그 - 규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미 - `main`에 있는 파일에서 그것을 찾았을 때만 늘어난다. -- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY` - migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서 - 만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가 - `Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위 - 클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema"). -- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다. -- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다. - -### 플랫폼 lane - -```bash -cd src -./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour -# Release blocking composition is CI-owned; locally run the exact database qualification set: -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \ - :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \ - :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \ - :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \ - :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \ - :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest -``` - -Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 -아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. - -## 책임 - -- JPA 엔티티. -- Spring Data repository. -- 영속 mapper. -- repository 어댑터 구현. -- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope - 바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수 - 없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다. -- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고 - `lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에 - 대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는 - 2026-09-25에 지웠다(`docs/capability-status.md`). -- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의 - 다리. -- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) — - 아래 「영속 감사 계약」을 본다. -- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점: - - `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그 - 옆 `outbox/postgresql`과 `outbox/h2`에 있다. - - `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다. - -## vendor 고르기 - -vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 -등록한다: - -| vendor | 패키지 | 고르는 것 | schema 소유 | -| --- | --- | --- | --- | -| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` | -| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 | - -outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와 -`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 -driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도 -`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다. - -`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 -`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 -`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를 -`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 -성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가 -고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤 -속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다: -`postgresql` provider는 기동 때 H2 data source를 거절한다. - -H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — -capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 -`postgresqlIntegrationTest`에 남는다. - -outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 -정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다. - -### capability로 막은 store - -선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver` -패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는 -`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다. - -그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 -필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 -capability의 store는 있으면 안 된다. - -## 허용 - -- `:application-core` -- `:domain-core` -- `:shared-contract` -- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기) -- Spring Data JPA와 Spring transaction. - -## 금지 (Forbidden) - -- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터. -- 표현 계층 DTO. -- 업무 정책 판단. -- 영속 어댑터 안에 숨긴 유스케이스 조율. -- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션 - 유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을 - 정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert). - [application-core/CLAUDE.md](../../../application-core/CLAUDE.md)를 본다. -- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의 - 맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다. - `CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가 - 강제한다. -- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다. -- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터. - -## TransactionPort 구현 계약 - -`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: - -| 모드 | 전파 | 격리 | 읽기 전용 | timeout | -|---|---|---|---|---| -| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) | -| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 | -| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) | -| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 | - -격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이 -`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용), -`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 -`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다. - -모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 -취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 -`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다. -후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에 -던진 업무 예외는 바꾸지 않고 넘긴다. - -미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기 -template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥 -트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시 -`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다. - -`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 -올리고 호출자에게 성공 값을 돌려주지 않는다. - -### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract) - -`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다: - -``` -hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 -``` - -레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나, -반복문을 트랜잭션 밖으로 뺀다. - -## 영속 실패 번역 계약 (feature-persistence-failure-baseline) - -날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. -`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 -분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. - -**표준 행(core):** - -| SQLState | code | category | http | retryable | -|---|---|---|---|---| -| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true | -| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true | -| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false | -| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | -| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false | -| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | - -**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):** - -| SQLState | code | vendor | -|---|---|---| -| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) | -| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL | -| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL | -| `57014` | `DB_QUERY_CANCELED` | PostgreSQL | -| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL | -| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 | -| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 | - -PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. -`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와 -`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는 -것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에 -따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든 -다르면 `SqlStateClassificationParityTest`가 실패한다. - -**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA -`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`) -→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring -data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`. - -**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기 -트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`: -PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라 -`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 -수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다. - -- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다 - (`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 - `INTERNAL` envelope으로 답하게 한다(새는 것 없음). -- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT). - -## 영속 감사 계약 (feature-persistence-auditing-contract) - -감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. -`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 -명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. -ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 -`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. - -- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 - 감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로 - 넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다. -- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 - (scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은 - feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다. -- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를 - 상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / - feature-transaction-concurrency-contract가 가진다. -- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity` - 계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data - listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. - -## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules) - -영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계 -위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다: - -```java -import javax.annotation.processing.Generated; - -classes() - .that().resideInAPackage("..adapter.persistence.mapper..") - .and().areNotAnnotatedWith(Generated.class) - .should() /* ... boundary rule ... */; -``` - -> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는 -> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는 -> 바로 그 애너테이션으로 범위를 잡는다. - -지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위 -predicate를 따르고, fixture mapper로 red/green 시험을 더한다. - -## NoSQL 확장 규칙 - -`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB, -Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다: - -```text -adapter-persistence-mongodb -adapter-persistence-redis -adapter-persistence-dynamodb -``` - -그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다. - -## 테스트 - -```bash -cd src -./gradlew :adapter:outbound:persistence-jpa:test --console=plain -``` +@AGENTS.md diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 35815116..4688c323 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -3,9 +3,9 @@ RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.persistence`. 허용/금지 의존, 테스트 명령, 그리고 **계약 테이블**(TransactionPort 모드표, SQLState → Error -Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [CLAUDE.md](CLAUDE.md) 다. +Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [AGENTS.md](AGENTS.md) 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 -"왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만 +"왜 이렇게 했나"가 궁금할 때 본다. 표가 AGENTS.md 에 있으면 여기서는 중복하지 않고 그 근거만 적는다. ## capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env @@ -107,7 +107,7 @@ promotion gate, 생성하는 곳 없는 `JpaTransactionObservation` 등)은 `doc readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로 (`WRITE` / `READ_ONLY` / `REQUIRES_NEW`) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가 사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 `READ_COMMITTED` -로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract). +로 고정한다(모드표는 AGENTS.md §TransactionPort implementation contract). ### 왜 `inRootWrite`가 별도 템플릿이나 `NEVER` propagation을 만들지 않나 `inRootWrite`의 실행 속성은 `inWrite`와 같은 `WRITE + REQUIRED + READ_COMMITTED`라 기존 @@ -179,7 +179,7 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto ## failure — 퍼시스턴스 실패 변환 SPI -매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence +매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 AGENTS.md §Persistence failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다. ### SPI-pluggable 설계 (vendor 추출) @@ -502,7 +502,7 @@ stream migration이 중단되면 history/registry/object 상태를 먼저 확인 ## lock — 분산 락 -provider 선택표(flag → bean → registry)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다. +provider 선택표(flag → bean → registry)의 SSOT 는 AGENTS.md(또는 app-bootstrap 와이어링)다. 여기서는 어댑터/설정 결정 근거만 적는다. ### `LockRegistryDistributedLock` 계약 diff --git a/src/adapter/outbound/persistence-mongo/AGENTS.md b/src/adapter/outbound/persistence-mongo/AGENTS.md new file mode 100644 index 00000000..c3110014 --- /dev/null +++ b/src/adapter/outbound/persistence-mongo/AGENTS.md @@ -0,0 +1,157 @@ +# adapter:outbound:persistence-mongo — 모듈 규칙 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-persistence-mongo` +- Gradle 경로: `:adapter:outbound:persistence-mongo` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속 +플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은 +`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다. + +## 책임 + +- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기 + 문서, repository, mapper, application·domain 포트 구현을 더한다. +- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다). +- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는 + 모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고 + 기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*` + 설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다. + 연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이 + `uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다: + `MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제 + `MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반 + 기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기 + **전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다. + 자기 설정 키는 없다. +- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는 + `docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지 + `…mongo.example`이고, `mongoStableContractTest`가 돌린다. +- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은 + 우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을 + `spring.autoconfigure.exclude`에 붙인다. +- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두 + **라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 + 받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다. +- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고, + 그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator + SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다. + +## 허용 + +- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest, + credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한 + `application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가 + 실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을 + 배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의 + 부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두 + 집합이 다르면 실패한다. +- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄 + `runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는 + imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream → + 메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도 + reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`). +- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api, + configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서 + Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다. +- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`). + +## 금지 (Forbidden) + +- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). +- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기. +- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기. +- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. + +### 패키지 경계 규칙 (`MongoModuleBoundaryTest`) + +설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다: + +- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다. + `api/package-info.java`가 이유를 적는다. +- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다. +- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다. +- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`. + +### 일관성에 묶인 template + +`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에 +setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사, +lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해 +넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은 +묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다. + +### 공개 surface + +jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다. +`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다. +늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다. + +아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을 +싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은 +둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와 +`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째 +짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도 +없었다. 옮기지 않고 없앴다. + +아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을 +낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로 +줄었다는 증거가 된다. + +### credential과 운영 profile + +운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을 +선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는 +것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean +속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다. + +`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane +`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`, +`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그 +요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다. + +기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고 +다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것: +실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새 +generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다. + +### 문체가 아닌 플랫폼 불변식 + +- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만 + 재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003). +- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다. +- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002). +- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004). +- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는 + `MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다. + 「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다. +- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로 + `MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안 + 된다. +- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는 + 문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다. +- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고 + 2026-09-25에 지웠다. +- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다. + +## 테스트 + +`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client· +template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기 +바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다. + +밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container +lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다. +`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다. + +```bash +cd src +./gradlew :adapter:outbound:persistence-mongo:check --console=plain +``` + +릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와 +`scripts/verify-mongodb-advanced.sh`(Advanced). diff --git a/src/adapter/outbound/persistence-mongo/CLAUDE.md b/src/adapter/outbound/persistence-mongo/CLAUDE.md index c3110014..43c994c2 100644 --- a/src/adapter/outbound/persistence-mongo/CLAUDE.md +++ b/src/adapter/outbound/persistence-mongo/CLAUDE.md @@ -1,157 +1 @@ -# adapter:outbound:persistence-mongo — 모듈 규칙 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-persistence-mongo` -- Gradle 경로: `:adapter:outbound:persistence-mongo` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속 -플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은 -`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다. - -## 책임 - -- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기 - 문서, repository, mapper, application·domain 포트 구현을 더한다. -- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다). -- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는 - 모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고 - 기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*` - 설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다. - 연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이 - `uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다: - `MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제 - `MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반 - 기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기 - **전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다. - 자기 설정 키는 없다. -- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는 - `docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지 - `…mongo.example`이고, `mongoStableContractTest`가 돌린다. -- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은 - 우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을 - `spring.autoconfigure.exclude`에 붙인다. -- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두 - **라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 - 받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다. -- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고, - 그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator - SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다. - -## 허용 - -- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest, - credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한 - `application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가 - 실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을 - 배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의 - 부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두 - 집합이 다르면 실패한다. -- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄 - `runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는 - imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream → - 메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도 - reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`). -- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api, - configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서 - Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다. -- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`). - -## 금지 (Forbidden) - -- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음). -- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기. -- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기. -- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상. - -### 패키지 경계 규칙 (`MongoModuleBoundaryTest`) - -설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다: - -- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다. - `api/package-info.java`가 이유를 적는다. -- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다. -- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다. -- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`. - -### 일관성에 묶인 template - -`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에 -setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사, -lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해 -넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은 -묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다. - -### 공개 surface - -jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다. -`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다. -늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다. - -아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을 -싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은 -둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와 -`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째 -짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도 -없었다. 옮기지 않고 없앴다. - -아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을 -낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로 -줄었다는 증거가 된다. - -### credential과 운영 profile - -운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을 -선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는 -것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean -속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다. - -`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane -`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`, -`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그 -요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다. - -기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고 -다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것: -실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새 -generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다. - -### 문체가 아닌 플랫폼 불변식 - -- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만 - 재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003). -- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다. -- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002). -- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004). -- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는 - `MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다. - 「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다. -- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로 - `MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안 - 된다. -- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는 - 문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다. -- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고 - 2026-09-25에 지웠다. -- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다. - -## 테스트 - -`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client· -template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기 -바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다. - -밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container -lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다. -`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다. - -```bash -cd src -./gradlew :adapter:outbound:persistence-mongo:check --console=plain -``` - -릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와 -`scripts/verify-mongodb-advanced.sh`(Advanced). +@AGENTS.md diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java index 621b0e2e..cea76ec8 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java @@ -55,7 +55,7 @@ class MongoNamespaceContractTest { @DisplayName("operator-facing Mongo documentation names only the Boot 4 canonical namespace") void operatorDocumentationDoesNotRecommendTheDeprecatedNamespace() { Path module = repositoryRoot().resolve("src/adapter/outbound/persistence-mongo"); - List documents = List.of(module.resolve("README.md"), module.resolve("CLAUDE.md")); + List documents = List.of(module.resolve("README.md"), module.resolve("AGENTS.md")); assertThat(documents) .allSatisfy(path -> assertThat(Files.isRegularFile(path)).as(path.toString()).isTrue()); diff --git a/src/adapter/outbound/persistence-notification/AGENTS.md b/src/adapter/outbound/persistence-notification/AGENTS.md new file mode 100644 index 00000000..9a34f725 --- /dev/null +++ b/src/adapter/outbound/persistence-notification/AGENTS.md @@ -0,0 +1,52 @@ +# adapter:outbound:persistence-notification — 알림 관계형 영속 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는 + `src/config/architecture/modules.json`에 있다. +- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`. +- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은 + `persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다: + - `platform.entity` — JPA 행만. + - `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`). + - `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미), + `NotificationRecordMapper`, payload codec. + - `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다. + 엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는 + record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다: + `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap + `architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다. + +## 시험은 어디 있나 + +| 무엇 | 어디 | 돌리기 | +|---|---|---| +| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` | +| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests ''` | +| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 | +| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` | + +`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라 +그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위 +클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는 +`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다. + +## 규칙 + +- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("")`로 + 시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25). +- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream + (`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지 + 않는다: 다음 `V__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고, + `NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에 + 적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 + (`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는 + migration을 거절한다). +- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT () DO + NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다 + (`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌 + 대상에는 migration에 unique 제약이 있어야 한다. +- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시 + 읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은 + `JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다. +- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다. diff --git a/src/adapter/outbound/persistence-notification/CLAUDE.md b/src/adapter/outbound/persistence-notification/CLAUDE.md index 9a34f725..43c994c2 100644 --- a/src/adapter/outbound/persistence-notification/CLAUDE.md +++ b/src/adapter/outbound/persistence-notification/CLAUDE.md @@ -1,52 +1 @@ -# adapter:outbound:persistence-notification — 알림 관계형 영속 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는 - `src/config/architecture/modules.json`에 있다. -- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`. -- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은 - `persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다: - - `platform.entity` — JPA 행만. - - `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`). - - `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미), - `NotificationRecordMapper`, payload codec. - - `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다. - 엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는 - record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다: - `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap - `architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다. - -## 시험은 어디 있나 - -| 무엇 | 어디 | 돌리기 | -|---|---|---| -| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` | -| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests ''` | -| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 | -| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` | - -`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라 -그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위 -클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는 -`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다. - -## 규칙 - -- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("")`로 - 시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25). -- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream - (`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지 - 않는다: 다음 `V__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고, - `NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에 - 적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다 - (`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는 - migration을 거절한다). -- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT () DO - NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다 - (`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌 - 대상에는 migration에 unique 제약이 있어야 한다. -- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시 - 읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은 - `JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다. -- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다. +@AGENTS.md diff --git a/src/adapter/outbound/redis-sdk/README.md b/src/adapter/outbound/redis-sdk/README.md index 84ff69be..f5142640 100644 --- a/src/adapter/outbound/redis-sdk/README.md +++ b/src/adapter/outbound/redis-sdk/README.md @@ -73,7 +73,7 @@ executor, operations). 등록된 script(`RedisScriptRegistry`). 서비스가 SDK를 조립하는 곳에서 넘긴다. 패키지 규칙(driver 가두기, 문자열 명령 surface 없음, 트랜잭션과 raw gateway의 불변식)은 -`src/adapter/outbound/cache-redis/CLAUDE.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다. +`src/adapter/outbound/cache-redis/AGENTS.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다. `RedisSdkModuleBoundaryTest`가 강제한다. ## env 키 diff --git a/src/adapter/outbound/support/AGENTS.md b/src/adapter/outbound/support/AGENTS.md new file mode 100644 index 00000000..a68269c7 --- /dev/null +++ b/src/adapter/outbound/support/AGENTS.md @@ -0,0 +1,42 @@ +# adapter:outbound:support — outbound 공용 지원 + +## 등록 정보 + +- 모듈 ID: `adapter-outbound-support` +- Gradle 경로: `:adapter:outbound:support` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`. + +## 책임 + +- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다. +- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다. +- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다. + `IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의 + 인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을 + 싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1 + 형식이다. +- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`, + `filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며 + `NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는 + `IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의 + `LocalStorageFailures`). 여기는 오류 코드를 모른다. +- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support + 클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을 + 댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은 + 설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함). +- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다. + +## 경계 + +- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약. +- inbound 전송, 영속, bootstrap, 샘플 의존이 없다. +- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다. + +## 테스트 + +지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application +context를 띄우지 않는다. diff --git a/src/adapter/outbound/support/CLAUDE.md b/src/adapter/outbound/support/CLAUDE.md index a68269c7..43c994c2 100644 --- a/src/adapter/outbound/support/CLAUDE.md +++ b/src/adapter/outbound/support/CLAUDE.md @@ -1,42 +1 @@ -# adapter:outbound:support — outbound 공용 지원 - -## 등록 정보 - -- 모듈 ID: `adapter-outbound-support` -- Gradle 경로: `:adapter:outbound:support` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`. - -## 책임 - -- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다. -- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다. -- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다. - `IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의 - 인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을 - 싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1 - 형식이다. -- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`, - `filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며 - `NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는 - `IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의 - `LocalStorageFailures`). 여기는 오류 코드를 모른다. -- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support - 클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을 - 댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은 - 설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함). -- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다. - -## 경계 - -- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약. -- inbound 전송, 영속, bootstrap, 샘플 의존이 없다. -- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다. - -## 테스트 - -지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application -context를 띄우지 않는다. +@AGENTS.md diff --git a/src/adapter/outbound/support/README.md b/src/adapter/outbound/support/README.md index bf801a7c..c4b782e2 100644 --- a/src/adapter/outbound/support/README.md +++ b/src/adapter/outbound/support/README.md @@ -6,7 +6,7 @@ 허용/금지 의존 정책은 `src/build.gradle` 의 `allowedProjectDependencies['adapter:outbound:support']` 항목이 SSOT 다(이 모듈은 아직 별도 -CLAUDE.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 +AGENTS.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. ## 왜 별도 모듈인가 diff --git a/src/app-bootstrap/AGENTS.md b/src/app-bootstrap/AGENTS.md new file mode 100644 index 00000000..21ed43ce --- /dev/null +++ b/src/app-bootstrap/AGENTS.md @@ -0,0 +1,121 @@ +# app-bootstrap — 애플리케이션 진입점과 조립 루트 + +## 등록 정보 + +- 모듈 ID: `app-bootstrap` +- Gradle 경로: `:app-bootstrap` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.bootstrap`. + +## 책임 + +- Spring Boot 진입점(`CaSkeletonApplication`). +- 런타임 설정과 로깅 시작. +- 모듈을 가로지르는 마지막 배선. +- 모든 모듈을 들여다보는 아키텍처 시험. + +## 허용 + +- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle + runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다. +- Spring Boot 시작·런타임 의존성. +- 시험에서 ArchUnit. + +## 금지 + +- 구체적인 업무 정책. +- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper. +- 업무 로직을 구현하는 설정 클래스. +- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 + 설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 — + `CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다. +- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures` + (`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` / + `requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 + 필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다. +- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 + `dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다. +- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에 + 둔다. `docs/testing/TESTING_STRATEGY.md`를 본다. + +## 패키지 배치 + +아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 +(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/` +아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능 +패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 +설정 아홉 개로, Redis는 376줄 클래스 하나로. + +- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가 + 등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략, + lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는 + `adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은 + `composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한 + `runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability + 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. + component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`, + `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support + (`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure//`에 + 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay, + 멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은 + `composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각 + `runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 + role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults` + 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context + 전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다. +- **`Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는 + 어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다. + 이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 + 없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸 + 수 없는 값을 거절한다. +- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출, + 여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에 + 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 + capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다. +- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외, + `StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`). + 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는 + `StartupFailureExceptionReporter`만 남는다. +- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한 + `StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적 + `RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든 + profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩 + 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 + `@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백, + `@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 + 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 + 비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고, + `SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다. + +## 분해 기준 + +취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다. + +- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로 + 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다. +- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다. +- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건, + `@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다: + 조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다. + `cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional + 어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의 + `NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의 + `NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는 + `adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`, + `PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에 + 없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`). + Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health + bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. +- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — + `cache-redis`의 `capability/RedisKeys`가 참조 예다. + +## 테스트 + +```bash +cd src +./gradlew :app-bootstrap:test +./gradlew verifyCleanArchitectureDependencies +``` diff --git a/src/app-bootstrap/CLAUDE.md b/src/app-bootstrap/CLAUDE.md index 21ed43ce..43c994c2 100644 --- a/src/app-bootstrap/CLAUDE.md +++ b/src/app-bootstrap/CLAUDE.md @@ -1,121 +1 @@ -# app-bootstrap — 애플리케이션 진입점과 조립 루트 - -## 등록 정보 - -- 모듈 ID: `app-bootstrap` -- Gradle 경로: `:app-bootstrap` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.bootstrap`. - -## 책임 - -- Spring Boot 진입점(`CaSkeletonApplication`). -- 런타임 설정과 로깅 시작. -- 모듈을 가로지르는 마지막 배선. -- 모든 모듈을 들여다보는 아키텍처 시험. - -## 허용 - -- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle - runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다. -- Spring Boot 시작·런타임 의존성. -- 시험에서 ArchUnit. - -## 금지 - -- 구체적인 업무 정책. -- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper. -- 업무 로직을 구현하는 설정 클래스. -- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 - 설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 — - `CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다. -- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures` - (`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` / - `requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 - 필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다. -- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 - `dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다. -- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에 - 둔다. `docs/testing/TESTING_STRATEGY.md`를 본다. - -## 패키지 배치 - -아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 -(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/` -아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능 -패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 -설정 아홉 개로, Redis는 376줄 클래스 하나로. - -- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가 - 등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략, - lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는 - `adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은 - `composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한 - `runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability - 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. - component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`, - `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support - (`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure//`에 - 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay, - 멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은 - `composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각 - `runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 - role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults` - 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context - 전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다. -- **`Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는 - 어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다. - 이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 - 없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸 - 수 없는 값을 거절한다. -- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출, - 여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에 - 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 - capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다. -- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외, - `StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`). - 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는 - `StartupFailureExceptionReporter`만 남는다. -- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한 - `StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적 - `RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든 - profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩 - 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 - `@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백, - `@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 - 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 - 비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고, - `SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다. - -## 분해 기준 - -취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다. - -- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로 - 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다. -- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다. -- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건, - `@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다: - 조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다. - `cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional - 어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의 - `NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의 - `NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는 - `adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`, - `PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에 - 없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`). - Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health - bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. -- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — - `cache-redis`의 `capability/RedisKeys`가 참조 예다. - -## 테스트 - -```bash -cd src -./gradlew :app-bootstrap:test -./gradlew verifyCleanArchitectureDependencies -``` +@AGENTS.md diff --git a/src/app-bootstrap/README.md b/src/app-bootstrap/README.md index 3881e831..4e196289 100644 --- a/src/app-bootstrap/README.md +++ b/src/app-bootstrap/README.md @@ -5,7 +5,7 @@ 이 모듈은 비즈니스 로직을 담지 않는다. Spring Boot 기동, 런타임 설정 바인딩, 기본 runtime 모듈 간 최종 와이어링, 그리고 composition classpath를 대상으로 한 중앙 아키텍처 테스트만 둔다. 모든 leaf의 프로젝트 edge는 JSON registry를 읽는 Gradle 방향 게이트가 별도로 검사한다. 허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**의 -SSOT 는 [CLAUDE.md](CLAUDE.md) 다. +SSOT 는 [AGENTS.md](AGENTS.md) 다. 기본 composition의 SSOT는 `build.gradle`의 실제 project dependency graph다. registry는 runtime membership 목록을 두지 않는다. `allowed_dependencies` 밖의 project는 방향 게이트가 막는다. @@ -417,7 +417,7 @@ relay 조립(`OutboxRelayAutoConfiguration`, 스케줄러·metrics·leader token ## build.gradle — 의존성 구성 근거 app-bootstrap 은 합성 루트라 "왜 이 의존성이, 왜 이 scope 로" 결정이 많다. 빌드 파일에는 한 줄 -요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(CLAUDE.md): +요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(AGENTS.md): 모듈 간 의존은 기본 `implementation`이라 transitive 로 새지 않는다 — 그래서 테스트에서 그 타입이 필요하면 여기서 **명시적으로** 다시 선언한다. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java index a7ddeee5..9693d2ee 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/FileserverUseCaseContractDeviationTest.java @@ -14,7 +14,7 @@ import org.junit.jupiter.api.Test; /** * Freezes what is left of the Fileserver's exemption from the inbound use-case contract. * - *

{@code application-core/CLAUDE.md} requires every inbound port implementation to extend {@code + *

{@code application-core/AGENTS.md} requires every inbound port implementation to extend {@code * CommandUseCase} or {@code QueryUseCase} and to declare {@code @UseCaseCapability}. The ArchUnit * rules that enforce it only match types that implement {@link UseCase}; a service that never does * is invisible to them. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java index 8d69bc6c..f3074b82 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ForbiddenApiArchitectureTest.java @@ -121,7 +121,7 @@ class ForbiddenApiArchitectureTest { + root + " lives in one of the listed operational contract packages, and the root holds" + " only its package-info; a business or domain concept belongs to the module that" - + " owns it (shared-contract CLAUDE.md)") + + " owns it (shared-contract AGENTS.md)") .allowEmptyShould(true); } diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java index a0d58794..e271b74a 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java @@ -10,7 +10,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties; /** * Naming convention enforcement — the machine-checkable subset of the naming table in {@code - * src/application-core/CLAUDE.md} ("Naming convention"), which is the rule book. + * src/application-core/AGENTS.md} ("Naming convention"), which is the rule book. * *

This test enforces only the rules that ArchUnit can decide reliably (N6 configuration binding, * I5 throwables, and the two package-ownership rules beside that table). The rest of that table — @@ -55,7 +55,7 @@ class NamingConventionTest { // Package ownership — a business feature package does not take a template package's name. The // template's own packages are listed in TemplatePackageOwnership (machine copy of the "Package - // ownership" table in src/application-core/CLAUDE.md); everything else under the two roots is a + // ownership" table in src/application-core/AGENTS.md); everything else under the two roots is a // feature, so a derived service adds features without editing the list. A feature always has a // domain package (docs/manual/03-placement.md ①), which is where a feature named after an // application template package — `operation`, `lock`, `cache` — shows up. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java index 0aaec0d7..9a2d7991 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java @@ -110,7 +110,7 @@ class TemplatePackageOwnershipRuleTest { .as( "a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was" + " renamed or removed without the list (and the table in" - + " src/application-core/CLAUDE.md) following it") + + " src/application-core/AGENTS.md) following it") .containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet()); assertThat(domain) .as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists") diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java index 4e64b0ba..460dfacb 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java @@ -15,7 +15,7 @@ import java.util.TreeSet; * owns each, and which packages are a service's business features. * *

This is the machine copy of the "Package ownership" tables in {@code - * src/application-core/CLAUDE.md}, which are the rule book. A template change that adds, renames, + * src/application-core/AGENTS.md}, which are the rule book. A template change that adds, renames, * moves or removes one of these packages changes the table and this class together. Two tests hold * them to it: {@code TemplatePackageOwnershipDocumentTest} (document-contract lane, main stage) * fails when the table and this class differ in a name or an owning leaf, or when a listed package @@ -107,7 +107,7 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) { + name.get() + "', a name the template already uses. A feature beside a template package" + " of the same name merges into the same tree on every upstream update." - + " Rename the feature (template packages: src/application-core/CLAUDE.md" + + " Rename the feature (template packages: src/application-core/AGENTS.md" + " \"Package ownership\").")); } } diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java index 137c5a94..45d436d7 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java @@ -19,7 +19,7 @@ import org.junit.jupiter.api.Test; /** * The template package list exists twice — the "Package ownership" tables in {@code - * src/application-core/CLAUDE.md}, which people and agents read, and {@link + * src/application-core/AGENTS.md}, which people and agents read, and {@link * TemplatePackageOwnership}, which the architecture rules read — and nothing held the two together * (original review 2026-11-01 §16.3). Changing either one alone fails here: a name or an owning * leaf that differs, or a listed package that is not in the leaf the table says owns it. @@ -29,7 +29,7 @@ import org.junit.jupiter.api.Test; @Tag("document-contract") class TemplatePackageOwnershipDocumentTest { - private static final String RULE_BOOK = "src/application-core/CLAUDE.md"; + private static final String RULE_BOOK = "src/application-core/AGENTS.md"; private static final String REGISTRY = "src/config/architecture/modules.json"; private static final String APPLICATION_TABLE = "| 패키지 (`dev.caskeleton.application.*`) |"; private static final String DOMAIN_TABLE = "| 패키지 (`dev.caskeleton.domain.*`) |"; diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java index 22527fd2..c42097b8 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingPublicSurfaceContractTest.java @@ -34,7 +34,7 @@ import org.junit.jupiter.api.Test; * *

So the rule is one-directional and mechanical: a vendor library named in a public or protected * signature is declared {@code api}; one used only behind private members stays {@code - * implementation}. {@code src/platforms/messaging/CLAUDE.md} states it as policy — this holds it to + * implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to * the source so the two cannot drift. * *

The libraries checked are the ones an adopter would otherwise have to reverse-engineer into diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java b/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java index 24b168b7..ab409a98 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/domain/feature/FeatureAggregateRepository.java @@ -3,7 +3,7 @@ package dev.caskeleton.onboarding.domain.feature; /** * Aggregate-level persistence for {@link FeatureAggregate}. The domain owns it because it stores * and returns whole aggregates — the {@code *Repository} side of the naming rule in {@code - * application-core/CLAUDE.md}; a technical store the application owns is a {@code *StorePort}. + * application-core/AGENTS.md}; a technical store the application owns is a {@code *StorePort}. */ public interface FeatureAggregateRepository { diff --git a/src/application-core/AGENTS.md b/src/application-core/AGENTS.md new file mode 100644 index 00000000..0a8a6bf0 --- /dev/null +++ b/src/application-core/AGENTS.md @@ -0,0 +1,336 @@ +# application-core — 애플리케이션 유스케이스 + +## 등록 정보 + +- 모듈 ID: `application-core` +- Gradle 경로: `:application-core` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.application`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). + +## 책임 (Responsibility) + +- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약. +- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스). +- 애플리케이션 예외와 정책 타입. +- 포트를 거쳐 도메인 모델을 조율한다. +- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다. +- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 + 어댑터가 가진다. +- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 + payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다. + +## 허용 + +- `:domain-core` +- `:shared-contract` +- Java 표준 라이브러리 타입. + +## 금지 (Forbidden) + +- `adapter-*` 구현 클래스. +- `app-bootstrap`. +- controller의 요청·응답 DTO. +- JPA 엔티티와 Spring Data repository. +- HTTP 상태, 전송 타입(`org.springframework.web..`). +- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다). +- `org.springframework.context.ApplicationContext` — 직접 의존 금지 + (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로 + bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이 + 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다. +- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이 + 계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다. +- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다. +- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는 + 전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다. +- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload, + serializer·schema validator 구현, 보안 토폴로지, publication epoch. + +## 계약 타입 + +| 타입 | 용도 | +|---|---| +| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | +| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | +| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | +| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | +| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | +| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | +| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | +| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | +| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | +| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | +| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | +| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | +| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | +| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | +| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | +| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | +| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | +| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | +| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | + +## 알림 (NOTIF-ADR-005) + +알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과 +`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`, +`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이 +유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다. + +## 이름 규칙 (Naming convention) + +이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap +architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」 +열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다. + +| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) | +|---|---|---|---| +| 유스케이스(inbound 포트 구현) | `UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) | +| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — | +| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — | +| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) | +| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — | +| 그 밖의 outbound 포트 | `Port` | application 패키지 | — | +| 서버가 정하는 id 생성 | `IdFactory extends IdFactory<Id>` | domain 패키지. id record는 `implements ResourceId` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) | +| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | +| Throwable | `*Exception`, ArchUnit이 강제 | — | — | +| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | + +저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 +필요한 배관이면 application의 `StorePort`다.** + +## 패키지 소유 (Package ownership) + +이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. +`docs/manual/03-placement.md`가 이곳을 가리킨다. + +- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, + `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 + 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 + 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. +- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 + 않는다. +- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 + 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. + +| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | +|---|---|---| +| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | +| `capability` | application-core | `@UseCaseCapability`와 그 enum | +| `transaction` | application-core | `TransactionPort`와 그 모드 | +| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | +| `tenant` | application-core | `TenantId` | +| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | +| `secret` | application-core | `SecretSourcePort`, `SecretReference` | +| `messaging` | application-core | integration event semantic contract | +| `outbox` | application-core | 트랜잭션 outbox append와 relay | +| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | +| `operation` | application-core | durable(오래 걸리는) operation | +| `lease`, `lock` | application-core | 분산 lease·lock 포트 | +| `cache` | application-core | cache region 포트 | +| `realtime` | application-core | live event 재생 포트 | +| `notification` | application-notification | 알림 capability | +| `fileserver` | application-fileserver | 파일 서버 capability | +| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | + +| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | +|---|---|---| +| `identifier` | domain-core | `ResourceId`, `IdFactory` | +| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | + +강제하는 곳: + +- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 + 거절한다. 템플릿 패키지도 모두 여기 걸린다. +- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 + 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 + `dev.caskeleton.domain.operation`에서 걸린다. +- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 + 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. +- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap + `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). + `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 + 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. + `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 + 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. +- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 + (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 + 더하는 일이다. +- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 + 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 + 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). + +## 정해진 유스케이스 모양 (Canonical use case shape) + +```java +@RequiresPermission("user:register") +@UseCaseCapability( + transactionMode = TransactionMode.WRITE, + idempotency = Idempotency.KEYED, + repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) +public class RegisterUserUseCase implements CommandUseCase { + + private final UserRepository users; + private final TransactionPort tx; + + public RegisterUserUseCase(UserRepository users, TransactionPort tx) { + this.users = users; + this.tx = tx; + } + + @Override + public User handle(RegisterUserCommand cmd) { + return tx.inWrite(() -> { + // ... domain coordination + }); + } +} +``` + +이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI +프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 +`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final +클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. +`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 +소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 +사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 +모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 +작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 +위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: +`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 +의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. +`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 +클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 +전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). +`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 +타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 +경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 +곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 +(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). + +## 허용하는 트랜잭션 모양 (Allowed transactional shapes) + +| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 | +|---|---|---|---| +| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. | +| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. | +| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. | +| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. | + +`NESTED`와 `NEVER` 전파는 금지다. +`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을 +반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다. +`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두 +만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다. + +### 콜백 시그니처 계약 + +`TransactionPort` 콜백은 `Supplier` / `Runnable`이라 checked 예외를 던지지 못한다. Spring +`TransactionCallback`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로 +감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로 +감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다. + +### `inNew` 풀 크기 제약 + +`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다. + +``` +hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 +``` + +**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길 +수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다. + +## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract + +`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 +`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 +유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. + +- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation + code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 + store에도 닿지 않는다. +- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 + 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). + 운영에서 메모리 저장소는 금지다. +- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 + 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 + 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. +- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 + 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 + `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. + `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 + 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. +- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. + 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 + 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 + 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 + 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 + lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 + 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. +- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). + 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 + 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). +- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 + 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 + handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 + 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, + `IdempotencyStoreContract`). +- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 + 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — + retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). + +예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 +이 브랜치가 병합될 때 지웠다. + +## 읽기·query 경로 (feature-application-query-bypass-contract) + +읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다. + +| 모양 | 돌려주는 것 | 언제 | 어떻게 | +|---|---|---|---| +| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` | +| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate | + +- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시 + 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭 + 타입 인자를 거쳐서도**(`List`) 안 된다. ArchUnit + `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이 + 아니라 **선택**이다. +- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은 + 경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다. +- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는 + `spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음) + **그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다. +- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다. + 「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새 + enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다. +- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다. + +## ArchUnit 가드레일(강제됨) + +- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` +- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION` +- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT` +- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` +- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE` +- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY` +- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성) + +## 테스트 + +```bash +cd src +./gradlew :application-core:test +./gradlew :app-bootstrap:architectureTest +``` + +위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox +영속, 그 밖의 메시징 R2 capability를 주장하지 않는다. diff --git a/src/application-core/CLAUDE.md b/src/application-core/CLAUDE.md index 0a8a6bf0..43c994c2 100644 --- a/src/application-core/CLAUDE.md +++ b/src/application-core/CLAUDE.md @@ -1,336 +1 @@ -# application-core — 애플리케이션 유스케이스 - -## 등록 정보 - -- 모듈 ID: `application-core` -- Gradle 경로: `:application-core` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.application`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). - -## 책임 (Responsibility) - -- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약. -- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스). -- 애플리케이션 예외와 정책 타입. -- 포트를 거쳐 도메인 모델을 조율한다. -- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다. -- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 - 어댑터가 가진다. -- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 - payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다. - -## 허용 - -- `:domain-core` -- `:shared-contract` -- Java 표준 라이브러리 타입. - -## 금지 (Forbidden) - -- `adapter-*` 구현 클래스. -- `app-bootstrap`. -- controller의 요청·응답 DTO. -- JPA 엔티티와 Spring Data repository. -- HTTP 상태, 전송 타입(`org.springframework.web..`). -- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다). -- `org.springframework.context.ApplicationContext` — 직접 의존 금지 - (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로 - bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이 - 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다. -- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이 - 계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다. -- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다. -- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는 - 전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다. -- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload, - serializer·schema validator 구현, 보안 토폴로지, publication epoch. - -## 계약 타입 - -| 타입 | 용도 | -|---|---| -| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | -| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | -| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | -| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | -| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | -| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | -| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | -| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | -| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | -| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | -| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | -| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | -| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | -| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | -| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | -| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | -| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | -| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | -| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | -| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | -| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | - -## 알림 (NOTIF-ADR-005) - -알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과 -`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`, -`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이 -유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다. - -## 이름 규칙 (Naming convention) - -이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap -architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」 -열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다. - -| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) | -|---|---|---|---| -| 유스케이스(inbound 포트 구현) | `UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) | -| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — | -| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — | -| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) | -| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — | -| 그 밖의 outbound 포트 | `Port` | application 패키지 | — | -| 서버가 정하는 id 생성 | `IdFactory extends IdFactory<Id>` | domain 패키지. id record는 `implements ResourceId` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) | -| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | -| Throwable | `*Exception`, ArchUnit이 강제 | — | — | -| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | - -저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 -필요한 배관이면 application의 `StorePort`다.** - -## 패키지 소유 (Package ownership) - -이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. -`docs/manual/03-placement.md`가 이곳을 가리킨다. - -- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, - `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 - 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. -- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 - 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. -- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 - 않는다. -- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 - 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. - -| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | -|---|---|---| -| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | -| `capability` | application-core | `@UseCaseCapability`와 그 enum | -| `transaction` | application-core | `TransactionPort`와 그 모드 | -| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | -| `tenant` | application-core | `TenantId` | -| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | -| `secret` | application-core | `SecretSourcePort`, `SecretReference` | -| `messaging` | application-core | integration event semantic contract | -| `outbox` | application-core | 트랜잭션 outbox append와 relay | -| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | -| `operation` | application-core | durable(오래 걸리는) operation | -| `lease`, `lock` | application-core | 분산 lease·lock 포트 | -| `cache` | application-core | cache region 포트 | -| `realtime` | application-core | live event 재생 포트 | -| `notification` | application-notification | 알림 capability | -| `fileserver` | application-fileserver | 파일 서버 capability | -| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | - -| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | -|---|---|---| -| `identifier` | domain-core | `ResourceId`, `IdFactory` | -| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | - -강제하는 곳: - -- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 - 거절한다. 템플릿 패키지도 모두 여기 걸린다. -- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 - 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 - `dev.caskeleton.domain.operation`에서 걸린다. -- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 - 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. -- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap - `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). - `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 - 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. - `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 - 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. -- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 - (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 - 더하는 일이다. -- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 - 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 - 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). - -## 정해진 유스케이스 모양 (Canonical use case shape) - -```java -@RequiresPermission("user:register") -@UseCaseCapability( - transactionMode = TransactionMode.WRITE, - idempotency = Idempotency.KEYED, - repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) -public class RegisterUserUseCase implements CommandUseCase { - - private final UserRepository users; - private final TransactionPort tx; - - public RegisterUserUseCase(UserRepository users, TransactionPort tx) { - this.users = users; - this.tx = tx; - } - - @Override - public User handle(RegisterUserCommand cmd) { - return tx.inWrite(() -> { - // ... domain coordination - }); - } -} -``` - -이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI -프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 -`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final -클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. -`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 -소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 -사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 -모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 -작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 -위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: -`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 -의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. -`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 -클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 -전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). -`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 -타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 -경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 -곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 -(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). - -## 허용하는 트랜잭션 모양 (Allowed transactional shapes) - -| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 | -|---|---|---|---| -| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. | -| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. | -| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. | -| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. | - -`NESTED`와 `NEVER` 전파는 금지다. -`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을 -반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다. -`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두 -만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다. - -### 콜백 시그니처 계약 - -`TransactionPort` 콜백은 `Supplier` / `Runnable`이라 checked 예외를 던지지 못한다. Spring -`TransactionCallback`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로 -감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로 -감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다. - -### `inNew` 풀 크기 제약 - -`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다. - -``` -hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 -``` - -**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길 -수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다. - -## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract - -`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 -`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 -유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. - -- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation - code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 - store에도 닿지 않는다. -- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 - 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). - 운영에서 메모리 저장소는 금지다. -- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 - 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 - 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. -- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 - 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 - `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. - `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 - 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. -- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. - 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 - 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 - 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 - 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 - lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 - 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. -- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). - 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 - 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). -- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 - 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 - handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 - 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, - `IdempotencyStoreContract`). -- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 - 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — - retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). - -예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 -이 브랜치가 병합될 때 지웠다. - -## 읽기·query 경로 (feature-application-query-bypass-contract) - -읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다. - -| 모양 | 돌려주는 것 | 언제 | 어떻게 | -|---|---|---|---| -| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` | -| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate | - -- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시 - 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭 - 타입 인자를 거쳐서도**(`List`) 안 된다. ArchUnit - `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이 - 아니라 **선택**이다. -- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은 - 경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다. -- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는 - `spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음) - **그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다. -- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다. - 「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새 - enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다. -- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다. - -## ArchUnit 가드레일(강제됨) - -- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` -- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION` -- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT` -- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` -- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE` -- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY` -- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성) - -## 테스트 - -```bash -cd src -./gradlew :application-core:test -./gradlew :app-bootstrap:architectureTest -``` - -위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox -영속, 그 밖의 메시징 R2 capability를 주장하지 않는다. +@AGENTS.md diff --git a/src/application-core/README.md b/src/application-core/README.md index 026f6593..5aa32fe9 100644 --- a/src/application-core/README.md +++ b/src/application-core/README.md @@ -3,7 +3,7 @@ 애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`. 허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다. diff --git a/src/composition/outbox-relay/AGENTS.md b/src/composition/outbox-relay/AGENTS.md new file mode 100644 index 00000000..1f890d5f --- /dev/null +++ b/src/composition/outbox-relay/AGENTS.md @@ -0,0 +1,19 @@ +# composition:outbox-relay + +- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본: + `src/config/architecture/modules.json`. +- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한 + 바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연 + tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric + (`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다. +- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`, + `OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging + 줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다 + (`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다. +- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우 + (`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다. +- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰 + 고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는 + `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다. +- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`, + `docs/runbooks/outbox-dead-letter.md`. diff --git a/src/composition/outbox-relay/CLAUDE.md b/src/composition/outbox-relay/CLAUDE.md index 1f890d5f..43c994c2 100644 --- a/src/composition/outbox-relay/CLAUDE.md +++ b/src/composition/outbox-relay/CLAUDE.md @@ -1,19 +1 @@ -# composition:outbox-relay - -- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본: - `src/config/architecture/modules.json`. -- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한 - 바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연 - tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric - (`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다. -- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`, - `OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging - 줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다 - (`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다. -- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우 - (`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다. -- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰 - 고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는 - `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다. -- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`, - `docs/runbooks/outbox-dead-letter.md`. +@AGENTS.md diff --git a/src/domain-core/AGENTS.md b/src/domain-core/AGENTS.md new file mode 100644 index 00000000..70bf470b --- /dev/null +++ b/src/domain-core/AGENTS.md @@ -0,0 +1,38 @@ +# domain-core — 순수 도메인 계층 + +## 등록 정보 + +- 모듈 ID: `domain-core` +- Gradle 경로: `:domain-core` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.domain`. + +코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). + +## 책임 + +- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스. +- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트. +- 도메인 불변식과 핵심 규칙. + +## 허용 + +- Java 표준 라이브러리. +- 값만 담은 공용 운영 타입은 정말 필요할 때만. + +## 금지 + +- Spring 애너테이션. +- JPA 애너테이션. +- Servlet·HTTP 타입. +- 어댑터, application, bootstrap, 표현 계층 DTO 의존. + +## 테스트 + +```bash +cd src +./gradlew :domain-core:test +``` diff --git a/src/domain-core/CLAUDE.md b/src/domain-core/CLAUDE.md index 70bf470b..43c994c2 100644 --- a/src/domain-core/CLAUDE.md +++ b/src/domain-core/CLAUDE.md @@ -1,38 +1 @@ -# domain-core — 순수 도메인 계층 - -## 등록 정보 - -- 모듈 ID: `domain-core` -- Gradle 경로: `:domain-core` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.domain`. - -코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). - -## 책임 - -- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스. -- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트. -- 도메인 불변식과 핵심 규칙. - -## 허용 - -- Java 표준 라이브러리. -- 값만 담은 공용 운영 타입은 정말 필요할 때만. - -## 금지 - -- Spring 애너테이션. -- JPA 애너테이션. -- Servlet·HTTP 타입. -- 어댑터, application, bootstrap, 표현 계층 DTO 의존. - -## 테스트 - -```bash -cd src -./gradlew :domain-core:test -``` +@AGENTS.md diff --git a/src/domain-core/README.md b/src/domain-core/README.md index d89d7f84..9ab2a4ce 100644 --- a/src/domain-core/README.md +++ b/src/domain-core/README.md @@ -2,7 +2,7 @@ 순수 도메인 계층 모듈. 패키지 루트: `dev.caskeleton.domain`. -허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. +허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 플랜/스펙 추적용 ID는 더 이상 코드 주석에 두지 않고, 그 근거를 아래에 쉬운 말로 풀어 둔다. diff --git a/src/platforms/grpc-advanced/AGENTS.md b/src/platforms/grpc-advanced/AGENTS.md new file mode 100644 index 00000000..6121029a --- /dev/null +++ b/src/platforms/grpc-advanced/AGENTS.md @@ -0,0 +1,88 @@ +# grpc-advanced — 고급 gRPC capability의 지역 정본 + +이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 +`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면 +루트가 이긴다. + +이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와 +별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 +불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다. + +## 의존 방향 + +```text +grpc-advanced:* → grpc:* (허용) +grpc:* → grpc-advanced:* (금지 — registry가 거부한다) +``` + +`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. +`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 +`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/AGENTS.md`의 +같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). + +## Capability grade와 feature flag + +capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 +결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 +때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다. + +| grade | 시작 가능 | production 추가 승인 | +| --- | --- | --- | +| `ADVANCED_STABLE` | O | 불필요 | +| `EXPERIMENTAL` | O | **필요** | +| `WATCH` | X (추적만) | — | +| `DISABLED` | X | — | + +property key는 `app.grpc.advanced..enabled`이고 전부 기본 off다. +`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 +구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다. + +## Leaf별 담당 capability + +| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability | +| --- | --- | --- | +| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate | +| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane | +| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control | +| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS | +| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 | +| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge | + +`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 +다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 +독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 +않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다. + +## Promotion은 capability별로 독립이다 + +승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 +것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 +호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 +리뷰 규칙이다. + +승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 +더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. + +## 이 저장소에서 검증할 수 없는 것 + +capability별로 필요한 실제 인프라가 이 저장소에 없다. + +- `grpc-web` → gRPC-Web 프록시 +- `servlet-compat` → Servlet 컨테이너 +- `xds` → 중지 가능한 xDS control plane +- `kotlin` → Kotlin 툴체인 + +인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. +이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit` +등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다. + +## 금지 + +- Stable leaf(`grpc:*`)가 이 family를 참조하는 것. +- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것. +- `WATCH` capability를 스키마 소스로 사용하는 것. +- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것. diff --git a/src/platforms/grpc-advanced/CLAUDE.md b/src/platforms/grpc-advanced/CLAUDE.md index d78e9d8d..43c994c2 100644 --- a/src/platforms/grpc-advanced/CLAUDE.md +++ b/src/platforms/grpc-advanced/CLAUDE.md @@ -1,88 +1 @@ -# grpc-advanced — 고급 gRPC capability의 지역 정본 - -이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 -root가 이긴다. - -이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와 -별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는 -불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다. - -## 의존 방향 - -```text -grpc-advanced:* → grpc:* (허용) -grpc:* → grpc-advanced:* (금지 — registry가 거부한다) -``` - -`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다. -`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이 -`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의 -같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치). - -## Capability grade와 feature flag - -capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는 -결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기 -때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다. - -| grade | 시작 가능 | production 추가 승인 | -| --- | --- | --- | -| `ADVANCED_STABLE` | O | 불필요 | -| `EXPERIMENTAL` | O | **필요** | -| `WATCH` | X (추적만) | — | -| `DISABLED` | X | — | - -property key는 `app.grpc.advanced..enabled`이고 전부 기본 off다. -`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을 -구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다. - -## Leaf별 담당 capability - -| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability | -| --- | --- | --- | -| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate | -| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane | -| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control | -| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS | -| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 | -| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge | - -`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지 -다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별 -독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지 -않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다. - -## Promotion은 capability별로 독립이다 - -승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른 -것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고 -호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의 -리뷰 규칙이다. - -승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가 -더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다. - -## 이 저장소에서 검증할 수 없는 것 - -capability별로 필요한 실제 인프라가 이 저장소에 없다. - -- `grpc-web` → gRPC-Web 프록시 -- `servlet-compat` → Servlet 컨테이너 -- `xds` → 중지 가능한 xDS control plane -- `kotlin` → Kotlin 툴체인 - -인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다. -이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit` -등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다. - -## 금지 - -- Stable leaf(`grpc:*`)가 이 family를 참조하는 것. -- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것. -- `WATCH` capability를 스키마 소스로 사용하는 것. -- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것. +@AGENTS.md diff --git a/src/platforms/grpc/AGENTS.md b/src/platforms/grpc/AGENTS.md new file mode 100644 index 00000000..2dd48896 --- /dev/null +++ b/src/platforms/grpc/AGENTS.md @@ -0,0 +1,192 @@ +# grpc — gRPC 플랫폼 family의 지역 정본 + +이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 +`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, +Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. + +루트 `AGENTS.md`와 충돌하면 루트가 이긴다. + +이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은 +자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은 +`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다. + +설계 근거와 원본 계획 대비 deviation은 +[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다. + +## Family와 framework 규칙 + +leaf의 정확한 id는 registry에서 읽는다. + +| Family | 역할 | 허용 framework | +| --- | --- | --- | +| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 | +| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 | +| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 | +| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 | +| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** | +| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 | +| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 | + +`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와 +실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이 +전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은 +`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다. + +기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고, +server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두 +그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면 +기동을 거부한다. + +`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지 +`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 +때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. + +### 공용 다이제스트 헬퍼를 복사해 두는 이유 + +`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 +안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 +family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). +`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging +family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 +같은 규칙인지 함께 본다. + +## 증거 등급 — testkit이 하나의 leaf인 이유 + +원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를 +네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test +lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date +결과를 제공하지 않는다). + +`grpc-testkit`의 네 lane과 그 태그: + +| lane | 태그 | 증명하는 것 | +| --- | --- | --- | +| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay | +| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain | +| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream | +| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget | + +lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임 +체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다. + +**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은 +release path의 flaky gate가 되고, flaky gate는 꺼진다. + +## Stable 범위 + +Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming, +hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며 +capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가 +등록되면 startup을 거부한다. + +`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의 +`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다. + +## Optional build에 있다는 것의 의미 + +`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반 +`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는 +`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가 +명시적으로 dependency를 가져오는 별도 변경이 필요하다. + +런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 +soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 +별도로 정의한다. + +## application이 이 family에 도달하는 경로 + +`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 + +```text +application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI +``` + +이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에 +직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이 +검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의 +`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다. +starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 — +starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation +ledger adoption」). + +## 테스트 명령 + +focused test는 registry의 `gradle_path`에서 파생한다. + +```bash +cd src +./gradlew -p platforms/optional-build :grpc::test --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain +./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain +``` + +## 금지 + +- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용. +- Stable leaf에서 `:grpc-advanced:*` 참조. +- `grpc-testkit`을 production leaf가 의존하는 것. +- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다). +- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것 + (`GrpcMetricCardinalityPolicy`가 거부한다). + + +### 채택할 때의 관측 게이트 + +`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 +않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 +`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 +이름을 저장소가 인증한 metric처럼 내세우지 않는다. + + +### durable operation 원장 채택 + +`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable +operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, +`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway +위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. +원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. + +| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | +| --- | --- | --- | +| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | +| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | +| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | + +기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, +주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL +(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 +operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. + +이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 +`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. + +**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 +(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 +적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 +온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 +했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: +바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 +중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 +필요한 메서드가 그것을 필요로 할 때 키가 된다. + +**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 +않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 +별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 +아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor +(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 +typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 +`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 +`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 +무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). + +**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 +끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 +예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 +배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). +지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 +테이블이 끝없이 커진다. + +커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 +이유는 모두 ADR-GRPC-004에 있다. diff --git a/src/platforms/grpc/CLAUDE.md b/src/platforms/grpc/CLAUDE.md index 3e128277..43c994c2 100644 --- a/src/platforms/grpc/CLAUDE.md +++ b/src/platforms/grpc/CLAUDE.md @@ -1,192 +1 @@ -# grpc — gRPC 플랫폼 family의 지역 정본 - -이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 -`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, -Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. - -Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. - -이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은 -자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은 -`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다. - -설계 근거와 원본 계획 대비 deviation은 -[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다. - -## Family와 framework 규칙 - -leaf의 정확한 id는 registry에서 읽는다. - -| Family | 역할 | 허용 framework | -| --- | --- | --- | -| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 | -| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 | -| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 | -| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 | -| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** | -| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 | -| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 | - -`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와 -실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이 -전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은 -`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다. - -기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고, -server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두 -그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면 -기동을 거부한다. - -`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지 -`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할 -때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다. - -### 공용 다이제스트 헬퍼를 복사해 두는 이유 - -`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기 -안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 -family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표). -`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging -family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과 -같은 규칙인지 함께 본다. - -## 증거 등급 — testkit이 하나의 leaf인 이유 - -원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를 -네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test -lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date -결과를 제공하지 않는다). - -`grpc-testkit`의 네 lane과 그 태그: - -| lane | 태그 | 증명하는 것 | -| --- | --- | --- | -| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay | -| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain | -| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream | -| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget | - -lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임 -체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다. - -**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은 -release path의 flaky gate가 되고, flaky gate는 꺼진다. - -## Stable 범위 - -Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming, -hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며 -capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가 -등록되면 startup을 거부한다. - -`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의 -`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다. - -## Optional build에 있다는 것의 의미 - -`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반 -`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는 -`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가 -명시적으로 dependency를 가져오는 별도 변경이 필요하다. - -런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의 -soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가 -별도로 정의한다. - -## application이 이 family에 도달하는 경로 - -`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는 - -```text -application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI -``` - -이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에 -직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이 -검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의 -`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다. -starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 — -starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation -ledger adoption」). - -## 테스트 명령 - -focused test는 registry의 `gradle_path`에서 파생한다. - -```bash -cd src -./gradlew -p platforms/optional-build :grpc::test --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain -./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain -``` - -## 금지 - -- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용. -- Stable leaf에서 `:grpc-advanced:*` 참조. -- `grpc-testkit`을 production leaf가 의존하는 것. -- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다). -- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것 - (`GrpcMetricCardinalityPolicy`가 거부한다). - - -### 채택할 때의 관측 게이트 - -`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 -않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 -`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 -이름을 저장소가 인증한 metric처럼 내세우지 않는다. - - -### durable operation 원장 채택 - -`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable -operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, -`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway -위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. -원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. - -| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | -| --- | --- | --- | -| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | -| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | -| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | - -기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, -주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL -(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 -operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. - -이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 -`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. - -**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 -(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 -적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 -온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 -했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: -바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 -중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 -필요한 메서드가 그것을 필요로 할 때 키가 된다. - -**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 -않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 -별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 -아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor -(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 -typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 -`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 -`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 -무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). - -**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 -끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 -예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 -배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). -지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 -테이블이 끝없이 커진다. - -커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 -이유는 모두 ADR-GRPC-004에 있다. +@AGENTS.md diff --git a/src/platforms/messaging/AGENTS.md b/src/platforms/messaging/AGENTS.md new file mode 100644 index 00000000..9c68440a --- /dev/null +++ b/src/platforms/messaging/AGENTS.md @@ -0,0 +1,176 @@ +# 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는 그 실행의 출력이다: + +```bash +./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에서 읽어 파생한다. + +```bash +cd src +./gradlew :test --console=plain +``` + +Family 전체 검증: + +```bash +./gradlew verifyCleanArchitectureDependencies --console=plain +./gradlew architectureCheck --console=plain +./gradlew verifyDependencyLocks --console=plain +``` diff --git a/src/platforms/messaging/CLAUDE.md b/src/platforms/messaging/CLAUDE.md index 807a5890..43c994c2 100644 --- a/src/platforms/messaging/CLAUDE.md +++ b/src/platforms/messaging/CLAUDE.md @@ -1,176 +1 @@ -# messaging — 메시징 플랫폼 family의 지역 정본 - -이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 -`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 -것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 -필요한 증거, runtime membership이 비어 있다는 사실의 의미. - -Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. - -## 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는 그 실행의 출력이다: - -```bash -./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에서 읽어 파생한다. - -```bash -cd src -./gradlew :test --console=plain -``` - -Family 전체 검증: - -```bash -./gradlew verifyCleanArchitectureDependencies --console=plain -./gradlew architectureCheck --console=plain -./gradlew verifyDependencyLocks --console=plain -``` +@AGENTS.md diff --git a/src/shared-contract/AGENTS.md b/src/shared-contract/AGENTS.md new file mode 100644 index 00000000..51539ac8 --- /dev/null +++ b/src/shared-contract/AGENTS.md @@ -0,0 +1,69 @@ +# shared-contract — 골격 전체가 쓰는 운영 계약 + +## 등록 정보 + +- 모듈 ID: `shared-contract` +- Gradle 경로: `:shared-contract` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. + +패키지 루트: `dev.caskeleton.shared`. + +예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계, +tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로 +남는다. + +## 책임 (Responsibility) +- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). +- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, + `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. + 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). +- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). +- 요청 값 계약(`request/Patch`). +- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과 + span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는 + 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). +- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): + `digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`), + `digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는 + `U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에 + 의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징 + 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지 + 않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에 + edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다. +- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는 + snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`). +- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트 + (`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」). +- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」). +- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」). +- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile + 어휘. +- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키. +- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다: + `ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 + `dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는 + `package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께 + 넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면 + 실패한다. +- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다: + `metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`, + `tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다. +- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope + metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에 + 찾아지거나 등록되는 것은 아니다. + +## 허용 +- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다. + +## 금지 (Forbidden) +- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다). +- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다). +- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기. + +## 테스트 +```bash +cd src +./gradlew :shared-contract:test +``` diff --git a/src/shared-contract/CLAUDE.md b/src/shared-contract/CLAUDE.md index 6722710c..43c994c2 100644 --- a/src/shared-contract/CLAUDE.md +++ b/src/shared-contract/CLAUDE.md @@ -1,69 +1 @@ -# shared-contract — 골격 전체가 쓰는 운영 계약 - -## 등록 정보 - -- 모듈 ID: `shared-contract` -- Gradle 경로: `:shared-contract` -- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain` -- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. -- registry 정본: `src/config/architecture/modules.json`. - -패키지 루트: `dev.caskeleton.shared`. - -예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계, -tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로 -남는다. - -## 책임 (Responsibility) -- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). -- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, - `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. - 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). -- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). -- 요청 값 계약(`request/Patch`). -- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과 - span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는 - 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). -- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): - `digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`), - `digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는 - `U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에 - 의존하지 않고 자기 사본을 둔다. 각 제품의 CLAUDE.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징 - 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지 - 않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에 - edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다. -- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는 - snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`). -- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트 - (`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」). -- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」). -- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」). -- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile - 어휘. -- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키. -- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다: - `ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 - `dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는 - `package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께 - 넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면 - 실패한다. -- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다: - `metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`, - `tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다. -- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope - metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에 - 찾아지거나 등록되는 것은 아니다. - -## 허용 -- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다. - -## 금지 (Forbidden) -- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다). -- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다). -- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기. - -## 테스트 -```bash -cd src -./gradlew :shared-contract:test -``` +@AGENTS.md diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index b22731a4..998e49ac 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -3,7 +3,7 @@ 스켈레톤 전역 운영 계약(operational contract) 모듈. 패키지 루트: `dev.caskeleton.shared`. 모듈 책임·허용/금지 의존(Java 표준 라이브러리 only)·테스트 명령 같은 **모듈 규칙**은 -[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 +[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다. -- 2.54.0 From 3c73fc333cf7053a918a8b11bd28fd83d2ffdb17 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 21:59:34 +0900 Subject: [PATCH 02/12] =?UTF-8?q?docs(agents)!:=20=EB=A3=A8=ED=8A=B8=20AGE?= =?UTF-8?q?NTS.md=EB=A5=BC=2040=EC=A4=84=20=EC=A0=95=EB=B3=B8=EC=9C=BC?= =?UTF-8?q?=EB=A1=9C=20=EC=A4=84=EC=9D=B4=EA=B3=A0=20CLAUDE.md=EA=B0=80=20?= =?UTF-8?q?=EA=B0=80=EC=A0=B8=EC=98=A8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은 AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은 AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs harness/01-harness-design.md 13절 Q1·Q2·Q3). - AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증, 일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄. - 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새), 테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스), 계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새 src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 → src/composition/AGENTS.md(새), capability 규칙·완료 기준 → docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 → .claude/rules/settings-and-runtime.md, 문서 편집 규칙 → .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README 「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길· 작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다. - 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛 행에 취소선을 긋고 「지침 배치」 행을 더했다. - check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10), 진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지, .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다. - DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서 읽는다. 단언은 그대로다. 버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함), CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크. 위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로 읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다. 검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10), check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트 변경은 마지막 트리에서 desktop documentContractTest로 확인한다. BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로 옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행. --- .claude/rules/docs.md | 12 + .claude/rules/java-tests.md | 28 ++ .claude/rules/settings-and-runtime.md | 34 ++ .gitignore | 3 +- AGENTS.md | 359 ++---------------- CLAUDE.md | 77 +--- README.md | 12 +- docs/README.md | 2 +- docs/manual/01-generator.md | 4 +- docs/manual/03-placement.md | 2 +- docs/manual/08-testing.md | 4 +- docs/manual/10-capabilities.md | 16 +- docs/manual/README.md | 5 +- docs/testing/TESTING_STRATEGY.md | 2 +- docs/upgrade/2026-11-harness.md | 2 + docs/work/README.md | 10 +- docs/work/delegate.md | 2 +- docs/work/docs-writing.md | 4 +- docs/work/improve.md | 4 +- docs/work/new-feature.md | 2 +- docs/work/operate.md | 4 +- docs/work/reference/decisions.md | 20 +- docs/work/reference/defect-patterns.md | 4 +- docs/work/reference/gates.md | 8 +- docs/work/reference/review-criteria.md | 4 +- scripts/check-docs.py | 2 +- scripts/check-repo-layout.py | 12 +- scripts/check-work-docs.py | 65 +++- src/README.md | 4 +- src/adapter/inbound/AGENTS.md | 20 + src/adapter/inbound/CLAUDE.md | 1 + src/adapter/inbound/graphql/README.md | 2 +- src/adapter/inbound/web-advanced/README.md | 2 +- src/adapter/inbound/websocket/README.md | 2 +- src/adapter/outbound/AGENTS.md | 20 + src/adapter/outbound/CLAUDE.md | 1 + src/adapter/outbound/httpclient/AGENTS.md | 2 +- .../outbound/persistence-mongo/AGENTS.md | 2 +- .../outbound/persistence-mongo/README.md | 2 +- src/adapter/outbound/redis-sdk/README.md | 2 +- src/app-bootstrap/AGENTS.md | 3 + .../DeveloperExperienceContractTest.java | 2 +- src/application-core/AGENTS.md | 3 + src/build-logic/AGENTS.md | 38 ++ src/build-logic/CLAUDE.md | 1 + src/composition/AGENTS.md | 12 + src/composition/CLAUDE.md | 1 + src/domain-core/AGENTS.md | 3 + 48 files changed, 336 insertions(+), 490 deletions(-) create mode 100644 .claude/rules/docs.md create mode 100644 .claude/rules/java-tests.md create mode 100644 .claude/rules/settings-and-runtime.md create mode 100644 src/adapter/inbound/AGENTS.md create mode 100644 src/adapter/inbound/CLAUDE.md create mode 100644 src/adapter/outbound/AGENTS.md create mode 100644 src/adapter/outbound/CLAUDE.md create mode 100644 src/build-logic/AGENTS.md create mode 100644 src/build-logic/CLAUDE.md create mode 100644 src/composition/AGENTS.md create mode 100644 src/composition/CLAUDE.md diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md new file mode 100644 index 00000000..58fb8eb2 --- /dev/null +++ b/.claude/rules/docs.md @@ -0,0 +1,12 @@ +--- +paths: + - "**/*.md" +--- + +# 문서를 고칠 때 + +- 문서 위치·언어·머리 블록 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다. +- 기록 문서(`docs/design/`, `docs/history/`, `docs/reviews/`, `docs/adr/`)는 맨 위 머리 블록만 고친다. +- 진입 문서(`AGENTS.md`, 모든 `src/**/AGENTS.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. +- 문서를 읽는 테스트가 있다. 태그 `document-contract`(main 단계)·`repository-contract`(PR)다. 고친 문서의 경로로 `git grep -n '<경로>' -- 'src/*.java'`를 해서 그 테스트를 찾고 desktop에서 돌린다. +- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다. diff --git a/.claude/rules/java-tests.md b/.claude/rules/java-tests.md new file mode 100644 index 00000000..2f68c697 --- /dev/null +++ b/.claude/rules/java-tests.md @@ -0,0 +1,28 @@ +--- +paths: + - "src/**/src/test/**/*.java" + - "src/**/src/testFixtures/**/*.java" + - "src/**/src/*Test/**/*.java" + - "src/**/src/*Testkit/**/*.java" +--- + +# Java 테스트 작성 규칙 + +새로 쓰거나 고치는 테스트에 적용한다. 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`, 계층별로 무엇을 검증하는지는 그 계층의 `AGENTS.md` 「테스트」 절이다. + +## 작성 규칙 + +1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다. +2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로 쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트 메서드를 고칠 때 한국어로 바꾼다. 같은 클래스의 고치지 않은 메서드는 바꾸지 않아도 되고, 바꾸면 같은 커밋에 넣고 보고에 적는다. +3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할 것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다. 예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때 `// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다. +4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다. +5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는 `extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`·`isPresent`·`doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입과 reason·message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다. +6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는 포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크 경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다. + +GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고, 실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다. + +## 코드만 보고는 헷갈리는 것 + +- 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다. +- 성능 lane에는 단언을 끄는 스위치가 없다. `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 하나라도 있으면 테스트 전에 실패한다. +- 테스트는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절). diff --git a/.claude/rules/settings-and-runtime.md b/.claude/rules/settings-and-runtime.md new file mode 100644 index 00000000..dda442cd --- /dev/null +++ b/.claude/rules/settings-and-runtime.md @@ -0,0 +1,34 @@ +--- +paths: + - "src/**/*Settings.java" + - "src/**/settings/**" + - "src/**/autoconfigure/**" + - "src/**/application*.yml" + - "src/**/application*.yaml" + - "src/**/config/module-defaults/**" + - "src/.env.example" + - "src/.env.local.example" + - "src/Dockerfile" + - "compose.yaml" + - "compose/**" + - "src/**/compose/**" + - "src/app-bootstrap/compose-lanes/**" +--- + +# 설정과 런타임 규칙 + +## 설정 + +- 비밀 값(토큰, 비밀번호, 개인 키)을 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다. 예시 값이면 `example`·`dummy`·`changeme`처럼 예시임이 보이게 쓴다. +- 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다. +- 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다. +- capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함). +- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다. 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다. +- `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다. + +## Docker·Compose + +- `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다. +- container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다. +- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다. 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`). +- Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절). diff --git a/.gitignore b/.gitignore index f22be9da..47cfcf38 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,10 @@ .vscode/ src/**/bin/ # Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project -# settings file is committed: it denies the Agent tool for everyone (AGENTS.md 「Superpowers Workflow」). +# settings and the path rules are committed: everyone who opens the repository gets them (CLAUDE.md). .claude/* !.claude/settings.json +!.claude/rules/ # Operator input, not a build input. The examples beside it are the tracked contract; # verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one. diff --git a/AGENTS.md b/AGENTS.md index 3ae9a897..2449fa91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,344 +1,37 @@ -# AGENTS.md +# AGENTS.md — 백엔드 템플릿의 정본 -## 프로젝트 정체성 +Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. -이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다. +## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다 -기본 패키지는 `dev.caskeleton`이다. 업무 기능의 예시는 `scripts/new-feature.sh`의 출력과 `docs/manual/`이다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다. +1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다. +2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다. +3. inbound DTO가 `application-core`나 `domain-core`로 들어간다. +4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다. +5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다. +6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다. +7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다. -## Prime Directive +## 지도 -에이전트는 속도보다 아키텍처 보존을 우선한다. +- Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다. +- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다. +- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다. +- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). `src/platforms/*`는 계층이 아닌 들여온 제품, `src/composition/*`는 조립만 한다. +- capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`. -동작하는 코드라도 HARD-STOP 조건을 하나라도 위반하면 완료된 작업이 아니다. +## 맡은 일 -다음 HARD-STOP 7개 항목이 이 저장소의 정본(canonical) 로컬 정책 권위이자 SSOT다. +먼저 `docs/work/README.md`, 그다음 맡은 일의 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 서비스 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다. -1. `domain-core`가 framework, transport, database, cloud 의존성을 가진다. -2. controller가 repository, Spring Data interface, persistence entity를 직접 사용한다. -3. inbound DTO가 `application-core` 또는 `domain-core`로 유출된다. -4. 비즈니스 규칙이 mapper, filter, configuration, settings, controller로 이동한다. -5. 프로젝트 의존성이 `src/config/architecture/modules.json` 또는 Gradle 의존성 검증을 위반한다. -6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다. -7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다. +## 검증 -root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면 -이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 Gradle -정책 권위와 ArchUnit/Test가 담당한다. +- leaf 하나: registry의 `gradle_path`로 `./gradlew :check --console=plain`(`src/`에서). 기억이나 폴더 이름으로 짐작하지 않는다. +- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때). 게이트 고르기는 `docs/work/reference/gates.md`. +- 문서·지침을 고쳤으면 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`. -## Superpowers Workflow +## 일하는 방식 -이 프로젝트에서 에이전트는 관련 Superpowers 스킬을 먼저 확인하고, 작업 성격에 맞는 스킬을 사용한다. 사용자 지시와 이 `AGENTS.md`가 로컬 프로젝트의 최상위 규칙이며, Superpowers는 그 규칙을 실행하기 위한 작업 방식이다. - -사용 가능한 주요 스킬과 트리거: - -- `superpowers:using-superpowers`: 대화나 작업을 시작할 때 관련 스킬을 확인한다. -- `superpowers:brainstorming`: 기능 설계, 구조 변경, 동작 변경, 새 문서 정책 수립 전에 사용한다. -- `superpowers:writing-plans`: 승인된 설계가 있고 작업이 여러 단계로 나뉠 때 사용한다. -- `superpowers:executing-plans`: 작성된 계획을 현재 세션에서 순차 실행할 때 사용한다. -- `superpowers:subagent-driven-development`, `superpowers:dispatching-parallel-agents`: 이 저장소에서는 - 쓰지 않는다. 세션 안의 하위 에이전트(Agent 도구)는 `.claude/settings.json`이 막는다. 일을 나눠 - 맡길 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). 다른 스킬이 - 하위 에이전트를 띄우라고 하면 그 단계는 같은 세션이 직접 한다. -- `superpowers:test-driven-development`: 기능 추가와 버그 수정을 테스트 우선으로 진행할 때 사용한다. -- `superpowers:systematic-debugging`: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다. -- `superpowers:verification-before-completion`: 완료, 수정됨, 통과함을 주장하기 전에 사용한다. -- `superpowers:requesting-code-review`: 의미 있는 구현을 마친 뒤 병합 또는 PR 전에 사용한다. -- `superpowers:receiving-code-review`: 리뷰 피드백을 적용하기 전에 사용한다. -- `superpowers:finishing-a-development-branch`: 구현과 검증이 끝난 브랜치를 정리할 때 사용한다. -- `superpowers:using-git-worktrees`: 격리된 작업 공간이 필요할 때 사용한다. -- `superpowers:writing-skills`: 스킬을 만들거나 수정할 때 사용한다. - -## Gradle 정책 권위 - -- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, - Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다: 조립 루트가 - 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 — - 산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다: - `verifyDocumentedLeafCount`는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 - 사유는 아니고, 그 태스크는 모든 `CLAUDE.md`와 `build.gradle`을 정규식으로 훑는 파서였다. -- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 - project를 include/mapping 한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 - 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 - `verifyCleanArchitectureDependencies`가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가 - 하나도 없다. -- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나 - (`strictTestLanes`). leaf는 `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중 - 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. - `ca.architecture`가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging· - graphql·JPA readiness 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면 - 그 파일을 그 leaf의 test task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()` - 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. 문서가 아닌 저장소 파일(빌드 스크립트, - workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 - 별도 레인(app-bootstrap `repository-contract`)에 둔다. 저장소 루트(`ca.repository.root`)는 이 두 - 레인에만 주므로 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다. -- strict lane 캐시: `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다. - `INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼 - 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 - 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다. -- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다: convention이 테스트 JVM에 - `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 - 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). - 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. -- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 - `ca.config-contract`다. 옛 included build `build-tools`는 지웠다(`docs/capability-status.md` 「제거된 코드」). -- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, - `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages - --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 - 단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`· - `releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`· - `performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 - 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀 - lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`· - `-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 - 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다. - (1) 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는 - 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, - `exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`. (2) 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌 - `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나 - 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 - 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 - 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` - 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` - 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 - 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 - job. - (3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 - 명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤, - `bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를 - 적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 - 시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다. - -작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를 -함께 읽는다. focused test는 registry의 `gradle_path`에서 -`./gradlew :test --console=plain` 형태로 파생한다. 파일 수만으로 위험을 판단하지 않고, -변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다. - -commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다. -예외는 하나다: brief가 허용한 것만(commit과 push는 따로) 그 작업의 자기 브랜치에 한다. main 병합, -다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」). - -## 강제 수준 - -이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다. - -이 프로젝트의 규칙은 세 단계로 관리한다. - -1. `AGENTS.md`: 에이전트와 개발자가 따라야 할 아키텍처, 작업 순서, 검증 원칙을 정의한다. -2. ArchUnit/Gradle/Test: 모듈 의존성, 계층 침범, 설정 바인딩, 동작 회귀를 자동으로 탐지한다. -3. Code Review/CI: 문서와 자동 검증이 놓친 설계 품질, 운영 위험, 템플릿 일관성을 최종 확인한다. - -에이전트는 `AGENTS.md`를 따라 작업해야 하며, 현업 수준의 스켈레톤 완성도는 반드시 자동 검증과 리뷰로 보강해야 한다. - -## 모듈 책임 - -모든 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 production 의존성은 -`src/config/architecture/modules.json`이 SSOT다. focused test는 소유 leaf의 `gradle_path`에서 -파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운 -`src/**/CLAUDE.md`를 함께 읽는다. - -- `domain-core`: 순수 도메인 모델, 불변식, 이벤트, port. Spring/JPA/transport/IO 타입 금지. -- `application-core`: command, use case, application policy, transaction port, application 예외. - inbound DTO, persistence entity, adapter 타입 금지. -- `adapter:inbound:*`: HTTP/gRPC/GraphQL/WebSocket transport, DTO, validation, 인증·인가 매핑, - error mapping. repository 직접 호출과 비즈니스 정책 금지. -- `adapter:outbound:persistence-*`: JPA/PostgreSQL 또는 MongoDB persistence 구현과 mapping, - migration/vendor 동작. 유스케이스 정책 금지. -- 그 밖의 `adapter:outbound:*`: support, messaging, cache, notification, object storage, - file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는 - registry만 따른다. -- `shared-contract`: skeleton-wide 운영 계약. business/domain 개념 저장 금지. -- `app-bootstrap`: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지. - -## 의존성 방향 - -family 수준 기본 방향: - -```text -app-bootstrap -> adapter:inbound:* -> application-core -> domain-core -app-bootstrap -> adapter:outbound:* -> application-core -> domain-core -runtime modules -> shared-contract -``` - -개별 edge는 `src/config/architecture/modules.json`의 `allowed_dependencies`가 유일한 목록이다. -Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억에서 leaf edge를 추론하지 않는다. - -## 기능 개발 프로토콜 - -새 기능이나 동작 변경은 다음 순서로 진행한다. - -1. 요구사항을 읽고 소유 계층을 판단한다. -2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다. -3. 여러 단계의 작업이면 `docs/design/`에 설계 문서를 남긴다. 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다. -4. 실행 계획이 필요하면 구현 전 `docs/history/plans/`에 둔다. 계획서도 머리 블록을 단다. 머리 블록 형식은 `docs/README.md`다. -5. 동작 변경은 테스트를 먼저 작성한다. -6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다. -7. 유스케이스는 `application-core` command와 use case/service method로 표현한다. -8. 외부 연동은 registry가 가리키는 `adapter:outbound:*` leaf에서 port 구현으로 추가한다. -9. endpoint는 마지막에 해당 `adapter:inbound:*` leaf에서 얇게 연결한다. -10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다. - -단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는 -`scripts/new-feature.sh `이 계층 leaf에 만든다. 실제 기능은 계층 leaf별로 나눈다. - -## 테스트 전략 - -계층별 테스트 기준: - -- `domain-core`: Spring 없이 순수 unit test로 도메인 규칙을 검증한다. -- `application-core`: fake/in-memory port를 사용해 유스케이스 흐름을 검증한다. -- `adapter:inbound:*`: transport validation, auth mapping, status/response contract를 검증한다. -- `adapter:outbound:persistence-*`: persistence mapping, repository adapter, vendor/migration 동작을 검증한다. -- 그 밖의 `adapter:outbound:*`: external capability adapter contract를 검증한다. -- `app-bootstrap/settings`: configuration binding, validation, logging 설정을 검증한다. - -테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용): - -1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다. -2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로 - 쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다. -3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할 - 것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다. - 예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때 - `// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다. -4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다. -5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는 - `extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`/`isPresent`/ - `doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외). - 예외는 타입과 reason/message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다. -6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는 - 포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크 - 경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다. - -GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고, -실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다. - -검증 원칙: - -- 완료를 주장하기 전에 `superpowers:verification-before-completion`을 사용한다. -- 실행한 명령과 결과를 최종 응답에 적는다. -- 테스트를 실행하지 못했다면 이유와 남은 위험을 솔직히 적는다. - -권장 절차: - -```bash -cd src -./gradlew :check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne -./gradlew check # 모든 leaf의 check -./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit -./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다) -./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci) -./gradlew ci # PR 게이트 = leaf check + architecture + quality -./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck) -./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요) -./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly). 상한은 항상 단언, 끄면 실패 -./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p platforms/optional-build로 따로) -./gradlew verifyPublicPathSnapshot -./gradlew :app-bootstrap:verifyEnvKeys -``` - -leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다. - -소유 leaf의 정확한 Gradle path는 `src/config/architecture/modules.json`에서 읽고 focused test -명령을 파생한다. root 문서에 leaf별 명령 목록을 복제하지 않는다. - -## 부가 기능(capability) 모듈 규칙 - -Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다. -각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다. -설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`. - -템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics· -tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`· -`adapter:outbound:identifier`. 그 밖의 기능(JPA 포함)은 한 줄을 추가해서 켠다. - -capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"): - -1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다. -2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` - 설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 명시한다(`afterName`). -3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키 - 자체를 두지 않는다. -4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact - constructor에서 한다. - 예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`· - `app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중 - 하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`. -5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두 - 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다. -6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키. -7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지 - 않고, 한 줄을 지우면 기능이 완전히 사라진다. - -모듈 설정 기본값은 `config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의 -`ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf -(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다. - -서비스 코드가 모듈 타입을 직접 호출해야 하는 라이브러리형 기능은 `runtimeOnly`로 컴파일되지 -않는다. 그런 기능은 가능한 한 포트 뒤로 옮기고, 불가피하면 서비스의 어댑터 leaf에서 -`implementation`으로 받는다. - -## 설정과 런타임 - -설정 규칙: - -- secrets를 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다. -- 새 설정 그룹은 typed settings class로 만든다. -- 흩어진 `@Value`보다 configuration properties와 settings class를 선호한다. -- `.env.local`은 로컬 오버라이드로 취급한다. -- `application.yml`은 환경별로 안전한 기본값과 명확한 placeholder만 담는다. -- 새 settings class를 만들면 binding/validation 테스트를 추가한다. - -Docker/runtime 규칙: - -- Dockerfile 변경 시 build context와 runtime env 요구사항을 함께 확인한다. -- container 안에서 필요한 profile, port, env var를 문서나 예시 설정에 반영한다. -- local-only 경로와 운영 경로를 섞지 않는다. - -## 템플릿 재사용 체크리스트 - -이 저장소를 새 프로젝트 시작점으로 사용할 때: - -1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다. -2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다. - gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/`의 - 디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다. -3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다. -4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가한다. -5. 모듈 이름과 경계는 유지한다. -6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다. -7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다. -8. README와 운영 문서를 새 프로젝트 설명으로 갱신한다. -9. 전체 테스트를 실행한다. - -```bash -cd src -./gradlew test -``` - -## 금지된 지름길 - -에이전트는 다음을 하지 않는다. - -- `domain-core`에 Spring/JPA annotation 추가 -- controller에서 repository 직접 호출 -- application method가 web request DTO를 인자로 받게 만들기 -- application이나 domain에서 JPA entity 반환 -- mapper에 비즈니스 정책 넣기 -- filter/config/settings class에 유스케이스 넣기 -- 요청 범위 밖의 대규모 리팩터링 -- 사용자 변경사항 되돌리기 -- 명시적 요청 없는 destructive git command 실행 -- 테스트 미실행 상태에서 "완료"라고 말하기 - -## 작업 보고 규칙 - -최종 응답에는 다음을 포함한다. - -- 변경한 파일 -- 핵심 변경 내용 -- 실행한 검증 명령 -- 실패하거나 실행하지 못한 검증 -- 남은 위험 또는 후속 작업 - -짧은 작업이라도 검증 여부는 생략하지 않는다. +- 커밋 정책은 `human-only`다. brief가 허용한 것만 자기 브랜치에 한다(`docs/work/README.md` 4절). +- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다. +- 일을 나눌 때는 소유자가 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). Gradle·Docker는 누가 돌려도 desktop에서다. diff --git a/CLAUDE.md b/CLAUDE.md index 6458871f..c6029fd8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,75 +1,6 @@ -# CLAUDE.md — 이 repo의 지도 +@AGENTS.md -이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다. +## Claude Code에서만 -## 1. 이 repo - -- Java 21 + Spring Boot Gradle 멀티모듈(버전은 `src/gradle/libs.versions.toml`) Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다. -- Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다. -- 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다. - -## 2. HARD-STOP — 하나라도 어기면 완료가 아니다 - -정본은 `AGENTS.md` 「Prime Directive」다. 두 문서가 다르면 `AGENTS.md`가 맞다. - -1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다. -2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다. -3. inbound DTO가 `application-core`나 `domain-core`로 들어간다. -4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다. -5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다. -6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다. -7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다. - -## 3. 맡은 일 → 읽을 문서 - -먼저 [docs/work/README.md](docs/work/README.md)를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다. - -| 맡은 일 | playbook | -| --- | --- | -| 새 업무 기능, 새 capability 모듈 | [docs/work/new-feature.md](docs/work/new-feature.md) → `docs/manual/` | -| 리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 | [docs/work/improve.md](docs/work/improve.md) | -| 바꾸기 전에 대안 비교와 소유자 결정 | [docs/work/research-design.md](docs/work/research-design.md) | -| 매뉴얼·안내 문서 쓰기 | [docs/work/docs-writing.md](docs/work/docs-writing.md) | -| 게이트 실행, desktop 검증, 릴리스, 파생 서비스 | [docs/work/operate.md](docs/work/operate.md) | -| 큰 일을 나눠 다른 세션에 맡기기 | [docs/work/delegate.md](docs/work/delegate.md) | - -brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다. - -## 4. 검증 명령과 실행 위치 - -- **실행 위치**: 소유자 환경에서는 Gradle·Docker·테스트·게이트를 desktop에서만 돌린다. 절차는 [docs/work/operate.md](docs/work/operate.md) 4.1절이다. -- **leaf 하나**: registry에서 그 leaf의 `gradle_path`를 읽고 `./gradlew :test --console=plain` 또는 `:check`를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다. -- **저장소 전체 질문**: - -```bash -./gradlew architectureCheck --console=plain -./gradlew :app-bootstrap:architectureTest --console=plain -./gradlew verifyPublicPathSnapshot --console=plain -./gradlew :app-bootstrap:verifyEnvKeys --console=plain -``` - -- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다. -- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다. -- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크). -- 문서(`.md`)나 문서가 가리키는 경로·Gradle 프로젝트를 바꿨으면 `python3 scripts/check-docs.py`를 돌린다(언어, 기록의 머리 블록, 참조, 복사한 숫자). PR마다 `docs-check` workflow가 같은 검사를 돈다. 규칙은 [docs/README.md](docs/README.md)다. - -## 5. 코드만 보고는 헷갈리는 곳 - -- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다. -- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. -- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다. -- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다. -- **capability는 한 줄로 켜고 끈다.** 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켠다. 규칙은 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」이다. -- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p platforms/optional-build`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다. -- **새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.** 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)를 가리킨다. -- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」). -- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다. -- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다. -- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 고치지 않는 기록(계획서·납품 패키지·증거·학습)은 `docs/history/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. 기록은 맨 위 머리 블록만 고친다. - -## 6. 소유자 환경 - -- 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: [docs/work/operate.md](docs/work/operate.md) 4.1절(실행 위치)과 [docs/work/delegate.md](docs/work/delegate.md) 4.3절(세션). 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다. -- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다. -- 작업 사고 순서의 정본은 design-docs `conventions/work-thinking-order.md`, 커밋·PR 형식은 `conventions/commit-and-pr.md`다. -- 보고 말투와 형식은 소유자의 전역 `~/.claude/CLAUDE.md`를 따른다. +- 권한은 `.claude/settings.json`, 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 규칙은 그 경로의 파일을 열 때 읽힌다. +- 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/README.md b/README.md index e92ab1c1..4a2bd33c 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src - 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다. - 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표. - 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md). -- capability 모듈이 지켜야 하는 규칙: [AGENTS.md](AGENTS.md) 「부가 기능(capability) 모듈 규칙」. +- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md). 뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다. @@ -110,7 +110,7 @@ cd src ## 새 서비스로 시작하기 -이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 전체 체크리스트는 [AGENTS.md](AGENTS.md) 「템플릿 재사용 체크리스트」다. +이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다. 1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다. 2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. @@ -122,6 +122,10 @@ cd src 3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다. 4. 새 업무 기능은 `scripts/new-feature.sh `으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다. 5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다. +6. gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`도 바꾼다. `src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/` 디렉터리와 각 `.proto`의 `package`·`java_package`다. `buf lint`로 확인한다. +7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다. +8. `src/.env.example`, `src/.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다. +9. README와 운영 문서를 새 서비스 설명으로 고친다. 복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`). @@ -129,7 +133,7 @@ cd src ## 규칙과 기여 -- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다. -- 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. +- 규칙의 정본이자 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 「HARD-STOP」 조건을 어기면 동작하더라도 병합하지 않는다. Claude Code 세션은 [CLAUDE.md](CLAUDE.md)가 이 파일을 가져온다. +- 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다. - 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다. - 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다. diff --git a/docs/README.md b/docs/README.md index d6937d9a..95b1489b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,7 +19,7 @@ | 폴더 | 무엇 | | --- | --- | -| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 | +| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `AGENTS.md` 다음에 읽는다 | | `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` | | `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 | diff --git a/docs/manual/01-generator.md b/docs/manual/01-generator.md index d69e2cca..58772860 100644 --- a/docs/manual/01-generator.md +++ b/docs/manual/01-generator.md @@ -79,7 +79,7 @@ verify-feature-scaffold.sh | 형태 | 결정 | 이유 | | --- | --- | --- | | `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `src/build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 | -| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`CLAUDE.md` Gradle policy). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 | +| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`src/build-logic/AGENTS.md`). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 | | 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 | | 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 | | 생성 뒤 자동 `spotlessApply` | 채택(끄려면 `--no-format`) | google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 | @@ -90,7 +90,7 @@ verify-feature-scaffold.sh | 파일 | 설정 | 왜 | | --- | --- | --- | -| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(AGENTS.md 테스트 규칙 6) | +| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(`.claude/rules/java-tests.md` 규칙 6) | | `src/application-core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/app-bootstrap/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 | | `src/adapter/inbound/web/build.gradle` | `implementation project(':domain-core')` | 컨트롤러가 경로 문자열을 도메인 id로 바꾼다 | | `src/adapter/outbound/identifier/build.gradle` | `implementation project(':domain-core')` | id adapter가 도메인 `IdFactory` 포트를 구현한다 | diff --git a/docs/manual/03-placement.md b/docs/manual/03-placement.md index f74d59d0..06c626f9 100644 --- a/docs/manual/03-placement.md +++ b/docs/manual/03-placement.md @@ -32,7 +32,7 @@ - **기본값**: ①. 업무 기능은 그 서비스의 존재 이유라 끌 일이 없다. 파일 추가만으로 끝나고, leaf 경계 검사가 계층마다 걸린다. - **예외**: ② — 여러 서비스가 쓰는 플랫폼 기능, 배포마다 켜고 끄는 기능, 자기 설정 prefix와 자기 - 저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(`AGENTS.md`, 10장). + 저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(10장). - **다시 볼 조건**: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트 시간이 문제가 되면 ①을 ②로 옮긴다. diff --git a/docs/manual/08-testing.md b/docs/manual/08-testing.md index ae0560a5..240b7257 100644 --- a/docs/manual/08-testing.md +++ b/docs/manual/08-testing.md @@ -2,7 +2,7 @@ ## 핵심 -테스트 규칙의 정본은 `AGENTS.md` 「테스트 전략」이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤 +테스트 작성 규칙의 정본은 `.claude/rules/java-tests.md`이고, 계층별로 무엇을 검증하는지는 그 계층의 `AGENTS.md` 「테스트」 절이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤 파일 배치가 되는지**와 **어느 단계(PR/main/integration)에서 도는지**를 적는다. ```text @@ -30,7 +30,7 @@ fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스 | inbound | HTTP status·Envelope·오류 코드 | 실제 유스케이스 + fake, standalone MockMvc | `ControllerTest` | | bootstrap | 조립 조건(있을 때 켜짐, 없을 때 없음), imports 등록 | fake bean | `ConfigTest` | -## 작성 규칙 요약 (정본은 AGENTS.md) +## 작성 규칙 요약 (정본은 `.claude/rules/java-tests.md`) 1. 이름은 lowerCamelCase 행동 문장. 이름이 말한 성질을 단언한다. 예: 이름에 "트랜잭션 전에"를 넣었으면 트랜잭션이 없었다는 것도 단언하거나, 이름에서 뺀다. diff --git a/docs/manual/10-capabilities.md b/docs/manual/10-capabilities.md index 31140b5c..61152fc7 100644 --- a/docs/manual/10-capabilities.md +++ b/docs/manual/10-capabilities.md @@ -17,7 +17,7 @@ app-bootstrap/build.gradle 기능 XConfig의 @ConditionalOnBean(포트) → 유스케이스·엔드포인트가 켜진다 ``` -정본: `AGENTS.md` 「부가 기능(capability) 모듈 규칙」(완료 기준 7개), +이 장이 capability 규칙과 완료 기준 7개의 정본이다. 설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`, 현황은 `docs/capability-status.md`. ## 켜기 @@ -49,11 +49,23 @@ app-bootstrap/build.gradle | 1 | 서비스는 포트만 호출 | `runtimeOnly`로 컴파일되는가 | | 2 | 자기 `AutoConfiguration.imports`, 필요하면 `enabled` 스위치, 순서는 `afterName` | 모듈 자동 설정 테스트 | | 3 | 켜면 완전히 동작. 동작하지 않는 설정 키는 두지 않는다 | 설정 바인딩 테스트 | -| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(AGENTS.md 기준 4) | +| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(아래) | | 5 | 포트 계약 테스트를 fake와 실제 adapter가 모두 통과, 실 벤더(Testcontainers) 1개 이상 | strict lane(08장) | | 6 | README: 제공하는 것, 추가할 한 줄, env 키 | | | 7 | 이 모듈을 아는 곳은 모듈 자신뿐. bootstrap scan·스위치 목록에 등록하지 않는다 | 줄을 지우면 기능이 완전히 사라지는가 | +7개를 모두 충족해야 "포장 완료"다. 표의 뜻을 풀면 이렇다. + +1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다. +2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` 설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 밝힌다(`afterName`). +3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다. +4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor에서 한다. 예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중 하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/AGENTS.md`. +5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 adapter가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다. +6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키. +7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지 않고, 한 줄을 지우면 기능이 완전히 사라진다. + +모듈 설정 기본값은 그 모듈의 `src/main/resources/config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의 `ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다. + 등록할 공용 파일: `src/config/architecture/modules.json`(leaf와 허용 edge), `src/settings.gradle`이 읽는 디렉터리 매핑, app-bootstrap의 허용 edge, 새 leaf lockfile. registry가 허용하지 않은 edge는 `architectureCheck`(의존 방향)가 막는다. diff --git a/docs/manual/README.md b/docs/manual/README.md index f3225d92..33a4068d 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -40,14 +40,15 @@ | 무엇 | 정본 | | --- | --- | -| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) | +| 계층 경계·금지 규칙 | `AGENTS.md`와 가장 가까운 `src/**/AGENTS.md` | +| 테스트 작성 규칙 | `.claude/rules/java-tests.md` | | leaf 목록·허용 의존 | `src/config/architecture/modules.json` | | 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` | | 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 | | HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` | | 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` | | 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` | -| capability 완료 기준 7개 | `AGENTS.md` 「부가 기능(capability) 모듈 규칙」 | +| capability 완료 기준 7개 | [10-capabilities.md](10-capabilities.md) | 이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 **따른 결과**를 보여 줄 뿐이고, 규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(`scripts/feature-scaffold/templates/`)이 규칙과 diff --git a/docs/testing/TESTING_STRATEGY.md b/docs/testing/TESTING_STRATEGY.md index 6858520b..27e8bb04 100644 --- a/docs/testing/TESTING_STRATEGY.md +++ b/docs/testing/TESTING_STRATEGY.md @@ -196,7 +196,7 @@ PERFORMANCE lane은 상한을 매번 단언한다. 측정만 하고 통과하는 ## 9. application-core 포트의 공유 계약 현황 (review 2026-11-01 01-05·TEST-F-1) -규칙(`AGENTS.md` 테스트 규칙): 포트마다 fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 +규칙(`.claude/rules/java-tests.md` 규칙 6): 포트마다 fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 모든 adapter가 같은 추상 계약 테스트(`*Contract`)를 상속한다. 실제 adapter의 계약 테스트는 그 adapter leaf의 실 DB·Redis lane에서 돈다. fake가 실제와 다르게 동작하면 유스케이스 테스트가 거짓 녹색이 되기 때문이다. diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index 8d817540..5de4e5e5 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -12,3 +12,5 @@ | # | 바뀐 것 | 서비스가 할 일 | | --- | --- | --- | | 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src//CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) | +| 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 | +| 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 | diff --git a/docs/work/README.md b/docs/work/README.md index b16c5eec..c7cdd40c 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -1,7 +1,7 @@ # 작업 매뉴얼 이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. -읽는 순서는 하나다: 루트 `CLAUDE.md`(지도) → 이 README → 맡은 일의 playbook 하나. +읽는 순서는 하나다: 루트 `AGENTS.md`(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 `CLAUDE.md`가 `AGENTS.md`를 가져온다. 규칙의 정본은 `AGENTS.md`와 registry(`src/config/architecture/modules.json`)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다. ## 1. 어떤 playbook인가 @@ -32,7 +32,7 @@ 1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. 2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. 3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다. -4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다. +4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다([delegate.md](delegate.md) 4.3절). 5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. 6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. 7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). @@ -72,6 +72,6 @@ ## 8. 이 폴더를 고칠 때 -- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. `reference/`는 상한이 없다. -- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 `AGENTS.md`와 `src/**/CLAUDE.md`도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다. -- 이 폴더, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. +- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. +- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다. +- 이 폴더, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. diff --git a/docs/work/delegate.md b/docs/work/delegate.md index ded7c1bd..076dd9fa 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | -| `AGENTS.md`, 루트 `CLAUDE.md`, `docs/work/` | 모든 세션이 읽는다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/` | 모든 세션이 읽거나 모든 세션에 걸린다 | | `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | 나눌 때 지킬 것: diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md index fd4d8ae7..df4c0fe5 100644 --- a/docs/work/docs-writing.md +++ b/docs/work/docs-writing.md @@ -36,7 +36,7 @@ 7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. 8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. 9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다). -10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. +10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. 11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`. - 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다. @@ -52,7 +52,7 @@ - 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다. - 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다. - 정본을 복사한 문장이 없다. 가리키는 줄만 있다. -- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. +- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. - 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그). - 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다. diff --git a/docs/work/improve.md b/docs/work/improve.md index 21a75b94..ab77a9de 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -61,7 +61,7 @@ - RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다. 4. 가장 작은 수정으로 GREEN을 본다. 5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. 찾은 자리가 brief 영역 안이고 공개 동작이 바뀌지 않으면 함께 고치고 보고에 적는다. 공개 동작이 바뀌거나 brief 영역 밖이면 고치지 않고 「범위 밖에서 본 것」에 권하는 안과 함께 적는다. 묶음 상한(4.4절)도 지킨다. -6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`CLAUDE.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. +6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. 7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다). - 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다. 8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). @@ -102,7 +102,7 @@ - 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과). - 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다. - 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다. -- `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다. +- `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다. ## 6. 하지 말 것 diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 1bb3aa2f..a3808e56 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -30,7 +30,7 @@ 1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다. 2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. -3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. +3. capability 모듈이면 `docs/manual/10-capabilities.md`의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. 4. 뼈대를 만든다: `scripts/new-feature.sh `(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」). 5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. 6. 기능에 필요한 장만 더 읽는다: 저장(04), 재시도될 쓰기(05), 오류(06), 권한(07), 테스트 배치(08), 이벤트(09). diff --git a/docs/work/operate.md b/docs/work/operate.md index 0fa9b782..fe2313e9 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -105,8 +105,8 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 파생 서비스는 이 템플릿을 받아 도메인을 채운 repo다. 템플릿 변경을 두 방식으로 받는다: 기준 커밋을 적은 tracked snapshot에 3-way로 반영하거나(`template.lock.json`), `git merge upstream/main`을 한다. - 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다. - 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다. -- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md` 지도에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. -- `.claude/settings.json`(Agent 도구 금지)은 추적 파일이라 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. +- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. +- `.claude/`의 추적 파일(`settings.json`의 Agent 도구 금지, `rules/`)은 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. ## 5. 완료 기준 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index d7dc02c1..34e651ea 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -32,10 +32,10 @@ | 주제 | 결정 | 누가 | 날짜 | 출처 | | --- | --- | --- | --- | --- | -| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 | +| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「일하는 방식」 | | 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 | | 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 총괄이 쓰고, 리뷰어는 보고의 색인 표를 `check-review-index.py --extra-index`로 대조해 rc=0을 보인다 | 기본값 | 2026-11-06, 2026-11-07 | `docs/work/evidence.md` 9·11절 | -| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`. 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 | +| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`(2026-11-07부터 `src/**/AGENTS.md`, 루트 `CLAUDE.md`, `.claude/` 아래 문서). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 | | 커밋 단위 | 커밋 하나에 논리 변경 하나(`conventions/commit-and-pr.md` 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf `check`를 돌리고, 무거운 묶음은 마지막 트리에서 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 | | 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 | | desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 | @@ -47,15 +47,17 @@ | 무거운 실행 위치 | 노트북에서 Gradle·Docker를 돌리지 않는다. desktop에서 브랜치를 받아 돌린다 | 소유자 | 2026-11-05 | `1103` 17.1절 | | desktop 공유 잠금 | desktop의 Gradle·Docker 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 프론트와 부하·포트(4173·4174)가 겹치지 않게 | 총괄 지시 | 2026-11-05 | 2026-11-05 총괄 세션 brief, design-docs `conventions/delegation-loop.md` 11절 | | 세션 분업 | 총괄 세션은 지휘만, 실제 작업은 하위 세션 | 소유자 | 2026-11-05 | design-docs `conventions/delegation-loop.md` 2절 | -| 하위 에이전트 | Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`) | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 | -| 매뉴얼 체계 | 짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작 | 소유자 | 2026-11-06 | 같은 문서 D1, D4 | +| 하위 에이전트 | ~~Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`)~~ → 아래 「서브에이전트와 하위 세션」 행에서 바꿈 | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 | +| 서브에이전트와 하위 세션 | Agent 금지를 푼다. 결과만 받는 일(검색, 구조 리뷰, 직접 돌려 보는 검증, 코드 단순화 제안)은 서브에이전트(`.claude/agents/`)에 맡기고, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션에 맡긴다. Gradle·Docker는 서브에이전트도 desktop에서만 | 소유자 | 2026-11-07 | design-docs `harness/01-harness-design.md` 13절 Q5 | +| 매뉴얼 체계 | ~~짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작~~ → 아래 「지침 배치」 행에서 바꿈 | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D1, D4 | +| 지침 배치 | 정본은 루트 `AGENTS.md`(40줄 이하: 비전·지도·HARD-STOP), 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄. 폴더 규칙은 그 폴더 `AGENTS.md`(`CLAUDE.md`가 가져옴), 폴더를 가로지르는 파일 종류 규칙은 `.claude/rules/`, 특정 시점 절차는 모델이 부르는 스킬(`.claude/skills/`), 예외 없는 규칙은 훅(편집 직후 넛지, 되돌릴 수 없는 것만 차단)·게이트. 편집 훅은 그 파일 하나만 Gradle 없이 포맷한다 | 소유자 | 2026-11-07 | design-docs `harness/01-harness-design.md` 13절 Q1·Q2·Q3·Q6·Q9 | | 크기별 생략 | 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 | 소유자 | 2026-11-06 | 같은 문서 D2, design-docs `conventions/work-thinking-order.md` | | 매뉴얼 검사 장치 | 이력 ID·분량 검사와 리뷰 색인 검사는 Gradle 밖 `scripts/`(`check-work-docs.py`, `check-review-index.py`) | 소유자 | 2026-11-06 | 같은 문서 D6 | | 규칙 ID | 규칙마다 ID(`R-…`)는 아직 붙이지 않는다. 원장이 생길 때 붙인다 | 소유자 | 2026-11-06 | 같은 문서 D7 | | 옛 개선 매뉴얼 | 브랜치 `claude/improvement-manual-6ae516`은 병합하지 않고 재료로만 쓴다 | 소유자 | 2026-11-06 | 같은 문서 D12 | | 개선 매뉴얼을 먼저(지난 것) | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 brief | | 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 | `1103` 2절 | -| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 | +| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `.claude/rules/java-tests.md` 규칙 2 | | 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 | | 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` | | 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 | @@ -74,7 +76,7 @@ | --- | --- | --- | --- | | outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 | | 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 | -| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `CLAUDE.md`에 이유 | 위임 | `1101` 15절(01-11) | +| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `AGENTS.md`에 이유 | 위임 | `1101` 15절(01-11) | | caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 | | id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 | | 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 | @@ -170,7 +172,7 @@ | 개발 compose Redis | lane Redis에 ACL 계정, "기동 WARN 없음" 검사 유지 | 위임 | `1101` 15절(r3-J) | | 서블릿 오류 디스패치 | 보안 체인이 ERROR 디스패치만 허용 | 기본값 | `1103` 6절 r4-b, 8절 | | 설정 prefix | `app.*`로 통일, `APP_*` env 키 유지 | 소유자 | 결정 16 | -| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `AGENTS.md` capability 기준 4 | +| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `docs/manual/10-capabilities.md` 기준 4 | | 로그 설정 | logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated | 위임 | `1101` 15절(07) | | 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | `1101` 15절 | | `APP_FLYWAY_ENABLED` | dev·prod에도 적용 | 위임 | `1101` 15절(r3-F) | @@ -191,8 +193,8 @@ | 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 | | lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) | | workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② | -| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `AGENTS.md` 「Gradle 정책 권위」 | -| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 | +| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 | +| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」 | | MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) | | Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) | | httpclient reactive | 삭제 | 소유자 | 결정 9 | diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index 2052e1bb..921574d0 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -2,7 +2,7 @@ 이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다. -계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. +계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 의존 방향)와 family·leaf의 책임·금지 절을 담은 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. ## 패턴 @@ -45,7 +45,7 @@ - **모양**: 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다. - **막는 기준**: [review-criteria.md](review-criteria.md) 7절 점검표. 변이로 확인한다. skip은 0이거나 설계 이유를 적는다. -- **장치**: 포트당 fake와 공유 계약 상속(`AGENTS.md` 테스트 작성 규칙 6), `rejectSkipped`. +- **장치**: 포트당 fake와 공유 계약 상속(`.claude/rules/java-tests.md` 규칙 6), `rejectSkipped`. ### A7. 거짓 통과 게이트 diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 423f6484..211a17a4 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -48,9 +48,9 @@ | env 키 | `:app-bootstrap:verifyEnvKeys` | | 공개 경로·보안 체인 | `verifyPublicPathSnapshot` | | 의존성 | `verifyDependencyLocks` | -| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` | +| 문서(`docs/**`, `AGENTS.md`·`CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` | | 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) | -| `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md` | `python3 scripts/check-work-docs.py` | +| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` | | 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` | | build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` | | 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) | @@ -177,7 +177,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | ## 5. 성능 lane -- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `AGENTS.md` 「Gradle 정책 권위」와 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다. +- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」과 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다. - strict lane convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. leaf나 lane은 이 값을 선언하지 않는다. - 빌드(`-P`, `GRADLE_OPTS`)나 lane이 `true` 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. `-Pperformance.assertions.enabled=true`는 받지만 줄 필요가 없다. - 그래서 desktop에서 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. @@ -199,7 +199,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | | --- | --- | | 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) | | optional 빌드를 보지 않음 | optional 빌드도 같은 검사 | -| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `AGENTS.md` 「Gradle 정책 권위」의 세는 규칙 | +| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `src/build-logic/AGENTS.md` 「`verifyStrictLaneStages`가 세는 명령」 | | lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index ca26ce51..f331c4be 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -70,7 +70,7 @@ | 수준 | 이 repo의 증거 | 주장할 수 없는 것 | | --- | --- | --- | -| E0 설명·주장 | README, `CLAUDE.md`, Javadoc, 리뷰 문서의 이전 실행 기록, 묶음 보고의 "통과" | 현재 커밋의 동작 | +| E0 설명·주장 | README, `AGENTS.md`·`CLAUDE.md`, Javadoc, 리뷰 문서의 이전 실행 기록, 묶음 보고의 "통과" | 현재 커밋의 동작 | | E1 정적 확인 | 현재 커밋의 코드·설정·`build.gradle`·workflow를 `file:line`으로 읽음, `--dry-run` 그래프 | 실행 결과 | | E2 테스트 실행 | 이름을 댄 테스트, leaf `check`, `ci`가 현재 커밋에서 통과(명령, rc, 테스트 수) | 실 vendor, 부하, 장애 | | E3 통합·실험 | Testcontainers 실 PostgreSQL·Redis·Kafka·MinIO lane, `java -jar`·compose 실제 기동, 부하·장애 주입·동시 요청 실험 | 운영 환경, 운영 기간 | @@ -147,7 +147,7 @@ ## 7. 테스트가 증명해야 하는 것 -정본: 테스트 작성 규칙은 `AGENTS.md` 「테스트 전략」, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다. +정본: 테스트 작성 규칙은 `.claude/rules/java-tests.md`, 계층별 검증 기준은 그 계층의 `AGENTS.md` 「테스트」 절, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다. | 점검 | 결함 모양 | | --- | --- | diff --git a/scripts/check-docs.py b/scripts/check-docs.py index f646ff36..a7708bda 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -43,7 +43,7 @@ python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number, map, readme) python3 -m unittest discover -s scripts/tests # 이 검사의 시험 -Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(AGENTS.md 「Gradle 정책 권위」). +Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(src/build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」). """ from __future__ import annotations diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py index d05fb1b3..5e5a4c95 100755 --- a/scripts/check-repo-layout.py +++ b/scripts/check-repo-layout.py @@ -17,7 +17,7 @@ 추적 파일만 본다(git ls-files). build 출력과 IDE 폴더는 처음부터 대상이 아니다. -새 최상위 항목이 정말 필요하면 아래 목록과 루트 CLAUDE.md 5절 「최상위 폴더는 정해진 것만 둔다」를 같은 +새 최상위 항목이 정말 필요하면 아래 목록과 루트 AGENTS.md 「지도」의 최상위 줄을 같은 변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(docs/work/README.md 2절). Gradle 밖에 둔다: 빌드는 저장소 배치를 판단하지 않는다(scripts/check-work-docs.py와 같은 자리). @@ -38,7 +38,7 @@ REGISTRY = "src/config/architecture/modules.json" # 저장소 루트: 문서·스크립트·CI·개발 환경과 Gradle 루트(src)뿐이다. ROOT_ALLOWED = { # 폴더 - ".claude": "에이전트 세션 설정(추적되는 settings.json)", + ".claude": "Claude Code 세션 설정(추적: settings.json의 권한·훅, rules·skills·agents)", ".github": "workflow와 공용 action", "compose": "compose.yaml이 마운트하는 보조 파일", "docs": "문서", @@ -50,8 +50,8 @@ ROOT_ALLOWED = { ".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다", ".tool-versions": "JDK 버전 고정", ".trivyignore.yaml": "취약점 검사 예외", - "AGENTS.md": "규칙 정본", - "CLAUDE.md": "작업 지도", + "AGENTS.md": "규칙 정본이자 작업 지도", + "CLAUDE.md": "Claude Code 진입점(AGENTS.md를 가져온다)", "README.md": "저장소 소개", "compose.yaml": "개발 환경(하나뿐)", "renovate.json": "의존성 갱신 봇 설정", @@ -195,8 +195,8 @@ def main() -> int: print(f"FAIL: {failure}", file=sys.stderr) print( "check-repo-layout: a new top-level entry changes the repository's shape. If it is " - "wanted, add it to the allow list in scripts/check-repo-layout.py and to CLAUDE.md " - "section 5 in the same change.", + "wanted, add it to the allow list in scripts/check-repo-layout.py and to the map in " + "AGENTS.md in the same change.", file=sys.stderr, ) return 1 diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index c2729a99..96c55053 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -1,18 +1,22 @@ #!/usr/bin/env python3 """Fail when the work manual stops being readable without history or grows past its size limits. -The work manual is the root `CLAUDE.md` (the map) plus `docs/work/`. A session that has never seen -this repository's history reads the map, `docs/work/README.md` and one playbook, and must be able -to finish the job from those alone. Two things break that, and both are mechanical: +The work manual is the root `AGENTS.md` (the map and the rule book) plus `docs/work/`. A Claude Code +session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and adds a few +Claude-only lines. A session that has never seen this repository's history reads the map, +`docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two +things break that, and both are mechanical: 1. History IDs in the body. A sentence such as "fixed as in 1101/05-01" means nothing to a reader who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). - The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and - every `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and - `docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository. -2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a - total limit, so a session reads the whole path instead of skimming it. + The same rule covers the other files a new session reads first: the root `AGENTS.md` and + `CLAUDE.md`, and every folder rule book `src/**/AGENTS.md` (owner decision 2026-11-07). Module + READMEs, design documents and `docs/reviews/**` keep their IDs, because a reader can follow them + from inside the repository. +2. Length. Each entry file has a line limit, and the entry path (map + root `CLAUDE.md` + README + + one playbook) has a total limit, so a session reads the whole path instead of skimming it. The + map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only). It also checks that every playbook keeps the shared nine-section skeleton, that the "common mistakes" section stays short, and that relative links in the checked files resolve. @@ -34,8 +38,10 @@ import sys from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent -MAP = REPO_ROOT / "CLAUDE.md" -RULE_BOOK = REPO_ROOT / "AGENTS.md" +MAP = REPO_ROOT / "AGENTS.md" +CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md" +IMPORT_LINE = "@AGENTS.md" +CLAUDE_FOLDERS = ("rules", "skills", "agents") WORK = REPO_ROOT / "docs/work" README = WORK / "README.md" @@ -58,7 +64,8 @@ EVIDENCE = "evidence.md" # Files that may name history, relative to docs/work/. Everything else must not. HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"} -MAP_LIMIT = 120 +MAP_LIMIT = 40 +CLAUDE_ENTRY_LIMIT = 10 README_LIMIT = 80 PLAYBOOK_LIMIT = 150 ENTRY_PATH_LIMIT = 350 @@ -134,7 +141,7 @@ def line_count(path: Path) -> int: def check_exists(errors: list[str]) -> bool: - expected = [MAP, RULE_BOOK, README, WORK / EVIDENCE] + expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE] expected += [WORK / name for name in PLAYBOOKS + REFERENCES] missing = [rel(path) for path in expected if not path.is_file()] for name in missing: @@ -143,12 +150,12 @@ def check_exists(errors: list[str]) -> bool: def check_limits(errors: list[str], report: list[str]) -> None: - for path, limit in [(MAP, MAP_LIMIT), (README, README_LIMIT)]: + for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]: lines = line_count(path) report.append(f"{rel(path)}: {lines}/{limit}") if lines > limit: errors.append(f"{rel(path)}: {lines} lines, limit {limit}") - base = line_count(MAP) + line_count(README) + base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README) for name in PLAYBOOKS: path = WORK / name lines = line_count(path) @@ -158,7 +165,7 @@ def check_limits(errors: list[str], report: list[str]) -> None: errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}") if entry > ENTRY_PATH_LIMIT: errors.append( - f"{rel(path)}: entry path CLAUDE.md + docs/work/README.md + this file is {entry} lines," + f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines," f" limit {ENTRY_PATH_LIMIT}" ) @@ -195,19 +202,33 @@ def check_skeleton(errors: list[str]) -> None: ) +SKIPPED_PARTS = {"build", ".gradle", "node_modules"} + + def module_guides() -> list[Path]: - """Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output. - The src/**/CLAUDE.md beside it is one line, `@AGENTS.md`, so Claude Code reads the same book.""" - skipped = {"build", ".gradle", "node_modules"} + """Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output.""" return sorted( path for path in (REPO_ROOT / "src").rglob("AGENTS.md") - if not skipped.intersection(path.relative_to(REPO_ROOT).parts) + if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts) ) +def check_claude_entry(errors: list[str]) -> None: + """The root CLAUDE.md starts with the import, so a Claude Code session reads the map.""" + lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines() + if not lines or lines[0].strip() != IMPORT_LINE: + errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'") + + +def claude_documents() -> list[Path]: + """The tracked Claude Code documents a session reads: path rules, skills, subagent definitions. + Only these folders: the rest of .claude/ is local state (worktrees, settings.local.json).""" + return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md")) + + def history_checked_files() -> list[Path]: - files = [MAP, RULE_BOOK] + files = [MAP, CLAUDE_ENTRY] + claude_documents() for path in sorted(WORK.rglob("*.md")): if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED: files.append(path) @@ -266,7 +287,8 @@ def check_history(errors: list[str], report: list[str]) -> None: def check_links(errors: list[str], report: list[str]) -> None: - checked, broken = broken_links([MAP, RULE_BOOK] + sorted(WORK.rglob("*.md"))) + checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + module_guides() + + claude_documents()) for path, number, target in broken: errors.append(f"{rel(path)}:{number}: broken relative link '{target}'") report.append(f"relative links checked: {checked}") @@ -311,6 +333,7 @@ def main() -> int: report: list[str] = [] if check_exists(errors): check_limits(errors, report) + check_claude_entry(errors) check_skeleton(errors) check_history(errors, report) check_links(errors, report) diff --git a/src/README.md b/src/README.md index a29728d9..552f5ec5 100644 --- a/src/README.md +++ b/src/README.md @@ -1,7 +1,7 @@ # src — 빌드 스크립트 / 환경 변수 참조 -`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md) -와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다. +`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md), +모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다. 이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과 결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조" diff --git a/src/adapter/inbound/AGENTS.md b/src/adapter/inbound/AGENTS.md new file mode 100644 index 00000000..5da33398 --- /dev/null +++ b/src/adapter/inbound/AGENTS.md @@ -0,0 +1,20 @@ +# adapter:inbound:* — inbound adapter family 공통 규칙 + +모든 inbound leaf에 같은 규칙만 적는다. leaf마다 자기 폴더의 `AGENTS.md`가 그 leaf의 자세한 규칙(등록 정보, 허용·금지, 테스트 명령)을 둔다. 루트 `AGENTS.md` HARD-STOP이 이 문서와 leaf 문서보다 먼저다. + +## 책임 + +- HTTP·gRPC·GraphQL·WebSocket·메시지 수신 같은 transport, 요청·응답 DTO, 입력 검증, 인증·인가 매핑, 오류 매핑. +- 요청 DTO를 `application-core`의 command·query로 바꿔 유스케이스를 부른다. 엔드포인트는 얇게 둔다. + +## 금지 + +- repository·Spring Data interface·persistence entity를 직접 쓴다(HARD-STOP 2). +- inbound DTO를 `application-core`·`domain-core`로 넘긴다(HARD-STOP 3). +- 업무 정책을 controller·mapper·filter에 둔다(HARD-STOP 4). +- registry `allowed_dependencies`에 없는 leaf에 기댄다(HARD-STOP 5). + +## 테스트 + +- transport 검증, 인증·인가 매핑, 상태 코드와 응답 계약을 검증한다. +- 작성 규칙은 `.claude/rules/java-tests.md`다. diff --git a/src/adapter/inbound/CLAUDE.md b/src/adapter/inbound/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/adapter/inbound/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index 34399b67..edc1cf9a 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -344,7 +344,7 @@ resolver 마다 deadline 을 검사하게 하는 방법은 adopter 가 기억해 아래 타입은 auto-configuration 이 빈으로 만들지 않는다. 서비스가 자기 GraphQL 어댑터 leaf 에서 `implementation project(':adapter:inbound:graphql')` 로 받아 resolver 안에서 직접 생성·호출한다 -(AGENTS.md capability 규칙의 라이브러리형 예외). 켜는 설정 키는 없다. +(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). 켜는 설정 키는 없다. | 기능 | 진입점 | 테스트 | | --- | --- | --- | diff --git a/src/adapter/inbound/web-advanced/README.md b/src/adapter/inbound/web-advanced/README.md index e7d8efac..0caad374 100644 --- a/src/adapter/inbound/web-advanced/README.md +++ b/src/adapter/inbound/web-advanced/README.md @@ -16,7 +16,7 @@ implementation project(':adapter:inbound:web-advanced') registry(`src/config/architecture/modules.json`)의 그 leaf `allowed_dependencies` 에 `adapter-inbound-web-advanced` 를 더한다. 서비스 코드가 타입을 직접 부르므로 `runtimeOnly` 로는 안 된다 -(AGENTS.md capability 규칙의 라이브러리형 예외). +(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). ## 제공하는 것 diff --git a/src/adapter/inbound/websocket/README.md b/src/adapter/inbound/websocket/README.md index 31c91557..024a4a0a 100644 --- a/src/adapter/inbound/websocket/README.md +++ b/src/adapter/inbound/websocket/README.md @@ -107,7 +107,7 @@ simple broker는 한 프로세스 안의 best-effort 전달이다. 영속·트 ## 라이브러리 API — 서비스의 어댑터 leaf에서 직접 조립 설정 키도 자동 설정도 없다. 서비스의 어댑터 leaf가 `implementation project(':adapter:inbound:websocket')`로 -받아 아래 타입을 직접 만든다(AGENTS.md capability 규칙의 라이브러리형 예외). +받아 아래 타입을 직접 만든다(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). | 진입점 | 역할 | | --- | --- | diff --git a/src/adapter/outbound/AGENTS.md b/src/adapter/outbound/AGENTS.md new file mode 100644 index 00000000..5246830f --- /dev/null +++ b/src/adapter/outbound/AGENTS.md @@ -0,0 +1,20 @@ +# adapter:outbound:* — outbound adapter family 공통 규칙 + +모든 outbound leaf에 같은 규칙만 적는다. leaf마다 자기 폴더의 `AGENTS.md`가 그 leaf의 자세한 규칙(등록 정보, 허용·금지, 테스트 명령)을 둔다. 루트 `AGENTS.md` HARD-STOP이 이 문서와 leaf 문서보다 먼저다. + +## 책임 + +- `persistence-*`: JPA·PostgreSQL 또는 MongoDB 영속 구현과 mapping, migration·vendor 동작. +- 그 밖의 leaf: support, messaging, cache, notification, object storage, file server, HTTP client, identifier 능력을 application이 가진 port 뒤에서 구현한다. + +## 금지 + +- 유스케이스 정책을 adapter에 둔다(HARD-STOP 4). +- registry `allowed_dependencies`에 없는 adapter끼리의 edge(HARD-STOP 5). 허용 edge는 registry만 정한다. +- 이미 적용된 migration 파일을 고친다. 새 버전 파일을 더하고 `persistence-jpa`의 `src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다. + +## 테스트 + +- `persistence-*`: persistence mapping, repository adapter, vendor·migration 동작을 실제 DB로 검증한다. +- 그 밖의 leaf: port 계약(fake와 adapter가 같은 추상 계약 테스트를 상속)과 외부 능력 adapter 계약을 검증한다. +- 작성 규칙은 `.claude/rules/java-tests.md`다. diff --git a/src/adapter/outbound/CLAUDE.md b/src/adapter/outbound/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/adapter/outbound/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/adapter/outbound/httpclient/AGENTS.md b/src/adapter/outbound/httpclient/AGENTS.md index f1e67aab..4f3a12e4 100644 --- a/src/adapter/outbound/httpclient/AGENTS.md +++ b/src/adapter/outbound/httpclient/AGENTS.md @@ -83,4 +83,4 @@ transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계 `testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고 (`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본 fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의 -변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6). +변경은 사본이 아니라 같은 클래스를 상속한다(`.claude/rules/java-tests.md` 규칙 6). diff --git a/src/adapter/outbound/persistence-mongo/AGENTS.md b/src/adapter/outbound/persistence-mongo/AGENTS.md index c3110014..4e62b1b6 100644 --- a/src/adapter/outbound/persistence-mongo/AGENTS.md +++ b/src/adapter/outbound/persistence-mongo/AGENTS.md @@ -133,7 +133,7 @@ generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoCli `MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안 된다. - 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는 - 문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다. + 문서로 남기지 않고 지운다(`docs/manual/10-capabilities.md` 기준 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다. - 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고 2026-09-25에 지웠다. - observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다. diff --git a/src/adapter/outbound/persistence-mongo/README.md b/src/adapter/outbound/persistence-mongo/README.md index 105f6310..6842172b 100644 --- a/src/adapter/outbound/persistence-mongo/README.md +++ b/src/adapter/outbound/persistence-mongo/README.md @@ -147,7 +147,7 @@ Mongo auto-configuration 이름을 Boot 자신의 등록 파일에서 읽어 배 ## 라이브러리 API — 서비스의 어댑터 leaf에서 `implementation`으로 받아 직접 호출 bean으로 등록되지 않고 설정 키도 없다. 서비스의 Mongo 어댑터 leaf가 이 leaf를 `implementation`으로 -받아 생성자로 만든다(AGENTS.md capability 규칙의 라이브러리형 예외). 테스트 열은 그 진입점을 검증하는 이 leaf의 테스트다. +받아 생성자로 만든다(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). 테스트 열은 그 진입점을 검증하는 이 leaf의 테스트다. 소비 leaf를 만드는 절차(레지스트리 edge, Gradle 줄, collection profile 등록, 예외 변환, 정책을 우회하는 경로)는 [`docs/mongodb/consumer-leaf-guide.md`](../../../../docs/mongodb/consumer-leaf-guide.md)에 있다. diff --git a/src/adapter/outbound/redis-sdk/README.md b/src/adapter/outbound/redis-sdk/README.md index f5142640..f7f6a0e3 100644 --- a/src/adapter/outbound/redis-sdk/README.md +++ b/src/adapter/outbound/redis-sdk/README.md @@ -5,7 +5,7 @@ **capability가 아니라 라이브러리다.** 이 leaf가 classpath에 있다고 켜지는 것은 없다: `AutoConfiguration.imports`가 없고, bean을 만들지 않고, 자기 `enabled` 스위치가 없다. 서비스 코드가 그 타입을 직접 부르므로 `runtimeOnly`로 -받을 수 없다(AGENTS.md, capability 규칙의 라이브러리 타입 예외). +받을 수 없다(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). ## 더하기 diff --git a/src/app-bootstrap/AGENTS.md b/src/app-bootstrap/AGENTS.md index 21ed43ce..b03760b2 100644 --- a/src/app-bootstrap/AGENTS.md +++ b/src/app-bootstrap/AGENTS.md @@ -114,6 +114,9 @@ ## 테스트 +- `settings` 패키지: 설정 바인딩, 값 검증, 로깅 설정을 검증한다. 새 settings 클래스에는 바인딩·검증 테스트를 더한다. +- 설정·런타임·Docker 규칙은 `.claude/rules/settings-and-runtime.md`다. + ```bash cd src ./gradlew :app-bootstrap:test diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java index 1347650f..38e4b325 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java @@ -309,7 +309,7 @@ class DeveloperExperienceContractTest { @DisplayName("루트 안내 문서는 아키텍처 suite를 그 source set의 태스크 이름으로 안내한다") void guidanceNamesTheArchitectureSourceSetTask() throws IOException { // when - String guidance = read("CLAUDE.md"); + String guidance = read("AGENTS.md"); // then assertThat(guidance) diff --git a/src/application-core/AGENTS.md b/src/application-core/AGENTS.md index 0a8a6bf0..56e4d359 100644 --- a/src/application-core/AGENTS.md +++ b/src/application-core/AGENTS.md @@ -326,6 +326,9 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ## 테스트 +- fake·in-memory 포트로 유스케이스 흐름을 검증한다. Spring context를 띄우지 않는다. +- 포트마다 fake 하나와 추상 계약 테스트(`*Contract`)를 이 모듈 testFixtures에 둔다. 작성 규칙은 `.claude/rules/java-tests.md`다. + ```bash cd src ./gradlew :application-core:test diff --git a/src/build-logic/AGENTS.md b/src/build-logic/AGENTS.md new file mode 100644 index 00000000..51480a45 --- /dev/null +++ b/src/build-logic/AGENTS.md @@ -0,0 +1,38 @@ +# build-logic — Gradle 정책 권위 + +registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `src/build-logic/`, `src/settings.gradle`, `src/build.gradle`, `src/config/architecture/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다. + +## 정본 넷 + +- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다. +- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다. +- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다. +- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전. + +## 저장소 파일을 읽는 테스트 + +- 테스트가 저장소 파일을 읽으면 그 파일을 그 leaf의 test task `inputs`로 선언한다. +- 저장소 문서와 대조하는 테스트는 `mainStage()` 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. +- 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstrap `repository-contract`)에 둔다. +- 저장소 루트(`ca.repository.root`)는 이 두 레인에만 준다. 그래서 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다. +- 문서를 파싱해 대조하는 Gradle 검사는 두지 않는다. 문서 검사는 Gradle 밖 `scripts/check-docs.py`·`scripts/check-work-docs.py`다. + +## lane 캐시와 성능 lane + +- `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다. `INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다. +- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. +- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 `ca.config-contract`다. + +## `verifyStrictLaneStages`가 세는 명령 + +`verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다. + +1. 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`. +2. 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job. +3. 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤, `bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). + +실패 메시지는 명령마다 이유를 적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다. + +## 테스트 + +- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. diff --git a/src/build-logic/CLAUDE.md b/src/build-logic/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/build-logic/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/composition/AGENTS.md b/src/composition/AGENTS.md new file mode 100644 index 00000000..16c0f54e --- /dev/null +++ b/src/composition/AGENTS.md @@ -0,0 +1,12 @@ +# composition:* — 조립 leaf family 공통 규칙 + +`composition:*` leaf는 조립만 한다. outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼, 서비스 실행 환경처럼 `app-bootstrap`에서 떼어 낸 조립이다. 서비스는 `src/app-bootstrap/build.gradle`에서 필요한 것만 `runtimeOnly` 한 줄로 고른다. leaf마다 자기 폴더의 `AGENTS.md`나 README가 자세한 규칙을 둔다. + +## 금지 + +- 업무 규칙과 SQL. 조립에 필요한 타입만 쓴다. +- registry `allowed_dependencies`에 없는 edge. 어떤 adapter를 아는지는 그 leaf의 registry 행이 정한다. outbox relay·멱등성은 포트만 알고, 알림·파일 서버 플랫폼은 자기 adapter를 함께 조립한다. + +## 테스트 + +- 설정 바인딩, 기동 거절 조건, 종료 순서처럼 조립이 가진 것만 검증한다. 업무 동작은 core와 adapter의 테스트가 맡는다. diff --git a/src/composition/CLAUDE.md b/src/composition/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/src/composition/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/domain-core/AGENTS.md b/src/domain-core/AGENTS.md index 70bf470b..61c13ba9 100644 --- a/src/domain-core/AGENTS.md +++ b/src/domain-core/AGENTS.md @@ -32,6 +32,9 @@ ## 테스트 +- Spring 없이 순수 unit test로 도메인 규칙과 불변식을 검증한다. +- 도메인이 가진 포트의 fake와 추상 계약 테스트(`*Contract`)는 이 모듈 testFixtures에 둔다. 작성 규칙은 `.claude/rules/java-tests.md`다. + ```bash cd src ./gradlew :domain-core:test -- 2.54.0 From 38891071d6a7ebb4c14e144a6c03163e05485ebc Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:06:50 +0900 Subject: [PATCH 03/12] =?UTF-8?q?feat(hooks)!:=20=ED=8E=B8=EC=A7=91=20?= =?UTF-8?q?=EC=A7=81=ED=9B=84=20=ED=8F=AC=EB=A7=B7=C2=B7=EB=A0=88=EC=9D=B4?= =?UTF-8?q?=EC=96=B4=C2=B7=EB=AC=B8=EC=84=9C=20=EC=95=8C=EB=A6=BC=EA=B3=BC?= =?UTF-8?q?=20migration=20=EC=B0=A8=EB=8B=A8=20=ED=9B=85=EC=9D=84=20?= =?UTF-8?q?=EA=B1=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사 실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도 desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다. 소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고, 전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다 (design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7). scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만): - pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면 종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다. - post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다. 버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만 쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게 --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상 파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는 build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다. - post-edit N1: registry로 leaf를 찾고 import를 순수성 목록 (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와 같은 패키지)과 allowed_dependencies 전이 closure에 대 본다. - post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄. - post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면 턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다. - 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠). 버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로 정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일 (Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다). 위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이 시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어 확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다. 검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29, 그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이 시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제 운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초, 문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0. BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다. docs/upgrade/2026-11-harness.md 2절 4행. --- .claude/rules/docs.md | 2 +- .claude/rules/settings-and-runtime.md | 2 +- .claude/settings.json | 39 ++- CLAUDE.md | 3 +- docs/upgrade/2026-11-harness.md | 1 + docs/work/delegate.md | 2 +- docs/work/operate.md | 4 +- scripts/hooks/README.md | 45 +++ scripts/hooks/hooks.py | 461 ++++++++++++++++++++++++++ scripts/tests/test_hooks.py | 400 ++++++++++++++++++++++ src/adapter/outbound/AGENTS.md | 2 +- src/build-logic/AGENTS.md | 2 +- 12 files changed, 954 insertions(+), 9 deletions(-) create mode 100644 scripts/hooks/README.md create mode 100644 scripts/hooks/hooks.py create mode 100644 scripts/tests/test_hooks.py diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md index 58fb8eb2..136ce71c 100644 --- a/.claude/rules/docs.md +++ b/.claude/rules/docs.md @@ -9,4 +9,4 @@ paths: - 기록 문서(`docs/design/`, `docs/history/`, `docs/reviews/`, `docs/adr/`)는 맨 위 머리 블록만 고친다. - 진입 문서(`AGENTS.md`, 모든 `src/**/AGENTS.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. - 문서를 읽는 테스트가 있다. 태그 `document-contract`(main 단계)·`repository-contract`(PR)다. 고친 문서의 경로로 `git grep -n '<경로>' -- 'src/*.java'`를 해서 그 테스트를 찾고 desktop에서 돌린다. -- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다. +- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다. 편집 훅이 실패 줄을 먼저 알려 준다. diff --git a/.claude/rules/settings-and-runtime.md b/.claude/rules/settings-and-runtime.md index dda442cd..861e9cae 100644 --- a/.claude/rules/settings-and-runtime.md +++ b/.claude/rules/settings-and-runtime.md @@ -23,7 +23,7 @@ paths: - 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다. - 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다. - capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함). -- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다. 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다. +- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다. - `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다. ## Docker·Compose diff --git a/.claude/settings.json b/.claude/settings.json index 3a3d67f9..ba08091d 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,7 +1,44 @@ { "permissions": { "deny": [ - "Agent" + "Agent", + "Read(**/.env)", + "Read(**/.env.local)", + "Read(**/.env.lane)", + "Edit(**/.env)", + "Edit(**/.env.local)", + "Edit(**/.env.lane)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py pre-edit", "timeout": 10} + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-edit", "timeout": 60} + ] + }, + { + "matcher": "Bash", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-bash", "timeout": 10} + ] + } + ], + "Stop": [ + { + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py stop", "timeout": 10} + ] + } ] } } diff --git a/CLAUDE.md b/CLAUDE.md index c6029fd8..4df9a8b5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,5 +2,6 @@ ## Claude Code에서만 -- 권한은 `.claude/settings.json`, 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 규칙은 그 경로의 파일을 열 때 읽힌다. +- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. +- 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다. - 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index 5de4e5e5..127155a8 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -14,3 +14,4 @@ | 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src//CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) | | 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 | | 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 | +| 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 | diff --git a/docs/work/delegate.md b/docs/work/delegate.md index 076dd9fa..eb09419d 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | -| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/` | 모든 세션이 읽거나 모든 세션에 걸린다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | | `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | 나눌 때 지킬 것: diff --git a/docs/work/operate.md b/docs/work/operate.md index fe2313e9..04165e4d 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -28,7 +28,7 @@ > 이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다. 다른 환경(파생 서비스 등)은 이 절만 자기 환경으로 바꾼다. -- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** +- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** 예외는 편집 훅의 한 파일 포매터 하나다(Gradle 없이 JVM 한 번, 캐시에 있는 jar만. 소유자 결정 2026-11-07, `scripts/hooks/README.md`). - desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다. - desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다. - design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다. @@ -106,7 +106,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다. - 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다. - 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. -- `.claude/`의 추적 파일(`settings.json`의 Agent 도구 금지, `rules/`)은 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. +- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. ## 5. 완료 기준 diff --git a/scripts/hooks/README.md b/scripts/hooks/README.md new file mode 100644 index 00000000..c0d51d64 --- /dev/null +++ b/scripts/hooks/README.md @@ -0,0 +1,45 @@ +# repo 훅 + +Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.claude/settings.json`, 본체는 `hooks.py` 하나, 시험은 `scripts/tests/test_hooks.py`다. 모델이 잊어도 돈다. + +```text +Edit·Write 직전 ──> pre-edit ──> H13 적용된 migration이면 막는다(종료 코드 2) +Edit·Write 직후 ──> post-edit ──> Java면 포맷 → N1 레이어 의존 알림, 문서면 N2 문서 검사 알림 +Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 N5 기록을 비운다 +턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 한 번 알린다 +``` + +## 1. 원칙 + +- 되돌릴 수 없는 것만 막는다. 나머지는 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다. +- 훅은 게이트의 일부만 본다. 정본은 게이트(desktop `architectureCheck`, `spotlessCheck`, 문서 검사)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다. +- 노트북에서 Gradle·Docker를 돌리지 않는다. 포매터는 Gradle 없이 JVM 하나로 파일 하나만 맞춘다(소유자 결정 2026-11-07). +- 받거나 설치하지 않는다. 포매터 jar는 Gradle이 이미 캐시에 받아 둔 것만 쓴다. 없으면 건너뛰고 세션에 한 번 알린다. +- 표준 라이브러리만 쓴다. 되돌릴 수 없는 명령 차단(force push, 범위 밖 `rm -rf`, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 몫이다. + +## 2. 훅마다 + +| ID | 때 | 하는 일 | 결과 | +| --- | --- | --- | --- | +| H13 | PreToolUse `Edit\|Write\|MultiEdit` | `src/**/src/main/resources/db/migration/<키>`의 `<키>`가 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 있으면 막는다 | 종료 코드 2와 「새 버전 파일을 더한다」 안내 | +| 포맷 | PostToolUse `Edit\|Write\|MultiEdit` | `src/**/*.java`(build-logic과 `build/` 제외)를 google-java-format으로 맞춘다. 버전은 카탈로그 `googleJavaFormat`, jar는 Gradle 캐시, 옵션은 Spotless 단계와 같게 `--skip-reflowing-long-strings --replace` | 파일이 바뀌면 「다시 읽는다」 한 줄. 문법 오류면 첫 줄들 | +| N1 | 같은 때, `src/**/src/main/java/**/*.java` | registry로 그 파일의 leaf를 찾고 import를 본다: 순수성 목록(`DomainPurityArchitectureTest`, `verifyApplicationCoreDependencyPurity`와 같은 패키지), inbound의 persistence 접근, `dev.caskeleton.*`의 주인 leaf가 registry `allowed_dependencies`(전이 포함)에 있는지 | 「HARD-STOP N 의심」 줄 | +| N2 | 같은 때, `*.md` | `scripts/check-work-docs.py`와 `scripts/check-docs.py`를 돌린다 | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 | +| N5 | Stop | 이 세션에서 Java를 고친 뒤 `ssh … gradlew …` 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 Java 편집 전까지 한 번 | + +- N5가 기억하는 것은 `.claude/hook-state/.json`이다(git이 무시한다). +- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 막는다. `.env.example` 같은 예시는 막지 않는다. + +## 3. 시험 + +```bash +python3 -m unittest discover -s scripts/tests +``` + +- 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다. +- 실제 포매터 시험은 Gradle 캐시에 카탈로그 버전 jar가 있는 기계에서만 돈다. 그 밖에서는 가짜 `java`로 옵션·파일 전달·바뀜 감지를 본다. +- 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다. + +## 4. 끄기 + +훅이 시끄럽거나 틀리면 `.claude/settings.json`에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 `.claude/settings.local.json`(git이 무시한다)에 `"disableAllHooks": true`를 둔다. diff --git a/scripts/hooks/hooks.py b/scripts/hooks/hooks.py new file mode 100644 index 00000000..1d32adb3 --- /dev/null +++ b/scripts/hooks/hooks.py @@ -0,0 +1,461 @@ +#!/usr/bin/env python3 +"""Claude Code repo hooks: nudge right after an edit, block only what cannot be undone. + +Called by `.claude/settings.json`, one event per invocation, with the hook input JSON on stdin: + + python3 scripts/hooks/hooks.py pre-edit # PreToolUse Edit|Write|MultiEdit H13 + python3 scripts/hooks/hooks.py post-edit # PostToolUse Edit|Write|MultiEdit format, N1, N2 + python3 scripts/hooks/hooks.py post-bash # PostToolUse Bash records desktop Gradle runs + python3 scripts/hooks/hooks.py stop # Stop N5 + +What each ID does, and why it nudges instead of blocking, is in scripts/hooks/README.md. A nudge +exits 0 and adds at most a few lines to the model's context; only H13 exits 2. No hook runs Gradle +or Docker: the owner's laptop never does (docs/work/operate.md 4.1). The formatter is one JVM on +one file, from the jar Gradle already cached. Standard library only. The tests are +scripts/tests/test_hooks.py. +""" + +from __future__ import annotations + +import hashlib +import json +import os +import re +import shlex +import subprocess +import sys +from pathlib import Path + +REGISTRY = "src/config/architecture/modules.json" +CATALOG = "src/gradle/libs.versions.toml" +MIGRATION_MANIFEST = "src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256" +STATE_DIR = ".claude/hook-state" +EDIT_TOOLS = ("Edit", "Write", "MultiEdit") +MAX_LINES = 5 + +# --- formatter: the step Spotless runs (QualityConventionsPlugin), on one file ----------------------- +GJF_GROUP = "com.google.googlejavaformat/google-java-format" +# The Spotless step keeps long strings as written; the CLI reflows them unless told not to. +GJF_FLAGS = ("--skip-reflowing-long-strings", "--replace") +GJF_EXPORTS = tuple(f"--add-exports=jdk.compiler/com.sun.tools.javac.{part}=ALL-UNNAMED" + for part in ("api", "code", "file", "parser", "tree", "util")) +GJF_TIMEOUT = 25 +# Spotless is not applied to build-logic (it is its own build), so the hook leaves it alone too. +FORMAT_EXCLUDED = ("src/build-logic/",) +SKIPPED = "포맷을 건너뛰었다" + +# --- N1: the layer rules the gates hold, checked on the imports of one edited main source -------------- +# Mirrors DomainPurityArchitectureTest (DOMAIN_IS_PURE, DOMAIN_HAS_NO_LOGGER). +DOMAIN_FORBIDDEN = ("org.springframework.", "jakarta.persistence.", "javax.persistence.", "jakarta.servlet.", + "org.hibernate.", "lombok.", "org.slf4j.", "java.util.logging.", "ch.qos.logback.", + "org.apache.logging.log4j.") +# Mirrors VerifyApplicationCoreDependencyPurityTask and the application-core AGENTS.md forbidden list. +APPLICATION_FORBIDDEN = ("org.springframework.", "org.slf4j.", "ch.qos.logback.", "org.apache.logging.log4j.", + "io.micrometer.", "java.util.logging.", "jakarta.persistence.", "javax.persistence.", + "lombok.") +SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.") +# HARD-STOP 2: an inbound adapter reaching the store. +INBOUND_FORBIDDEN = ("org.springframework.data.repository.", "org.springframework.data.jpa.", + "org.springframework.data.mongodb.repository.", "jakarta.persistence.", "javax.persistence.") +IMPORT = re.compile(r"^\s*import\s+(static\s+)?([\w.]+)(\.\*)?\s*;", re.M) +PROJECT_PREFIX = "dev.caskeleton." +MAIN_JAVA = re.compile(r"^(?Psrc/.+?)/src/main/java/(?P.+\.java)$") + +# --- N2: the document checks a living document edit can break ------------------------------------------- +DOC_CHECKS = (("scripts/check-work-docs.py",), ("scripts/check-docs.py",)) +DOC_TIMEOUT = 20 + +# --- N5: a Bash command that ran Gradle on the desktop clears the pending Java edits -------------------- +DESKTOP_HOST = re.compile(r"desktop") + + +# ---------------------------------------------------------------------------------------------------- +# plumbing + + +def project_root(payload: dict) -> Path: + root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd() + return Path(root).resolve() + + +def relative(root: Path, file_path: str | None) -> str | None: + if not file_path: + return None + path = Path(file_path) + if not path.is_absolute(): + path = root / path + try: + return path.resolve().relative_to(root).as_posix() + except ValueError: + return None + + +def edited_path(payload: dict) -> str | None: + if payload.get("tool_name") not in EDIT_TOOLS: + return None + return relative(project_root(payload), (payload.get("tool_input") or {}).get("file_path")) + + +def context(event: str, lines: list[str]) -> str: + """The PostToolUse output that adds lines to the model's context without blocking.""" + text = "\n".join(lines[:MAX_LINES] + ([f"(… {len(lines) - MAX_LINES}줄 더)"] if len(lines) > MAX_LINES else [])) + return json.dumps({"hookSpecificOutput": {"hookEventName": event, "additionalContext": text}}, + ensure_ascii=False) + + +def state_file(root: Path, session_id: str) -> Path: + safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session_id or "unknown") + return root / STATE_DIR / f"{safe}.json" + + +def load_state(root: Path, session_id: str) -> dict: + try: + return json.loads(state_file(root, session_id).read_text(encoding="utf-8")) + except (OSError, ValueError): + return {"java_edits": [], "reminded": False} + + +def save_state(root: Path, session_id: str, state: dict) -> None: + path = state_file(root, session_id) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8") + + +# ---------------------------------------------------------------------------------------------------- +# H13 — an applied migration is never edited + + +def applied_migrations(root: Path) -> set[str]: + try: + text = (root / MIGRATION_MANIFEST).read_text(encoding="utf-8") + except OSError: + return set() + return {line.split()[1] for line in text.splitlines() if line.strip() and not line.startswith("#") + and len(line.split()) == 2} + + +def migration_key(path: str) -> str | None: + """`src//src/main/resources/db/migration/jpa/core/V1__x.sql` → `jpa/core/V1__x.sql`.""" + marker = "/src/main/resources/db/migration/" + if marker not in path or not path.endswith(".sql"): + return None + return path.split(marker, 1)[1] + + +def h13_message(root: Path, path: str | None) -> str | None: + key = migration_key(path) if path else None + if key is None or key not in applied_migrations(root): + return None + return (f"[H13 적용된 migration 편집 금지] {path}\n" + "이 파일은 이미 적용된 migration이다(" + MIGRATION_MANIFEST + "에 있다). Flyway가 기동마다 checksum을" + " 대조하므로 고치면 운영 DB가 뜨지 않는다.\n" + "대신 새 버전 파일(V<다음 번호>__<설명>.sql)을 더하고 sha256 목록에 한 줄을 더한다. 어떤 DB에도 적용된 적 없는" + " 파일이라 고쳐야 하면 소유자에게 묻는다.") + + +# ---------------------------------------------------------------------------------------------------- +# format — google-java-format on the one edited file + + +def catalog_version(root: Path, key: str) -> str | None: + try: + text = (root / CATALOG).read_text(encoding="utf-8") + except OSError: + return None + match = re.search(rf'^{re.escape(key)}\s*=\s*"([^"]+)"', text, re.M) + return match.group(1) if match else None + + +def gradle_cache() -> Path: + home = os.environ.get("GRADLE_USER_HOME") + return (Path(home) if home else Path.home() / ".gradle") / "caches/modules-2/files-2.1" + + +def version_key(version: str) -> tuple: + return tuple(int(part) if part.isdigit() else -1 for part in re.split(r"[.-]", version)) + + +def newest_jar(cache: Path, group_artifact: str, suffix: str = "") -> Path | None: + folder = cache / group_artifact + artifact = group_artifact.rsplit("/", 1)[1] + versions = sorted((v.name for v in folder.glob("*") if v.name.endswith(suffix)), key=version_key) \ + if folder.is_dir() else [] + for version in reversed(versions): + jars = sorted(folder.glob(f"{version}/*/{artifact}-{version}.jar")) + if jars: + return jars[0] + return None + + +def formatter_classpath(root: Path, cache: Path) -> tuple[list[Path] | None, str]: + version = catalog_version(root, "googleJavaFormat") + if version is None: + return None, f"{CATALOG}에 googleJavaFormat 버전이 없다" + jars = sorted(cache.glob(f"{GJF_GROUP}/{version}/*/google-java-format-{version}.jar")) + if not jars: + return None, f"google-java-format {version} jar가 Gradle 캐시({cache})에 없다" + guava = newest_jar(cache, "com.google.guava/guava", "-jre") + access = newest_jar(cache, "com.google.guava/failureaccess") + if guava is None or access is None: + return None, "guava jar가 Gradle 캐시에 없다" + return [jars[0], guava, access], version + + +def wants_format(path: str | None) -> bool: + return bool(path) and path.startswith("src/") and path.endswith(".java") \ + and not path.startswith(FORMAT_EXCLUDED) and "/build/" not in path + + +def format_java(root: Path, path: str, cache: Path | None = None) -> list[str]: + """Format lines for the model. A skip line starts with SKIPPED so the caller can say it once.""" + classpath, detail = formatter_classpath(root, cache or gradle_cache()) + if classpath is None: + return [f"{SKIPPED}: {detail}. 받거나 설치하지 않는다. desktop `./gradlew spotlessApply`가 맞춘다."] + target = root / path + before = hashlib.sha256(target.read_bytes()).hexdigest() + command = ["java", *GJF_EXPORTS, "-cp", os.pathsep.join(str(jar) for jar in classpath), + "com.google.googlejavaformat.java.Main", *GJF_FLAGS, str(target)] + try: + result = subprocess.run(command, capture_output=True, text=True, timeout=GJF_TIMEOUT) + except FileNotFoundError: + return [f"{SKIPPED}: `java`가 PATH에 없다. desktop `./gradlew spotlessApply`가 맞춘다."] + except subprocess.TimeoutExpired: + return [f"{SKIPPED}: google-java-format이 {GJF_TIMEOUT}초 안에 끝나지 않았다."] + if result.returncode != 0: + errors = [line for line in result.stderr.splitlines() if line.strip()][:3] + return [f"google-java-format {detail}가 {path}를 읽지 못했다(문법 오류일 수 있다):", *errors] + if hashlib.sha256(target.read_bytes()).hexdigest() != before: + return [f"google-java-format {detail}가 {path}를 Spotless와 같은 모양으로 다시 썼다. 다음 Edit 전에 다시 읽는다."] + return [] + + +# ---------------------------------------------------------------------------------------------------- +# N1 — imports of one edited main source against the registry and the layer purity rules + + +def load_registry(root: Path) -> list[dict]: + return json.loads((root / REGISTRY).read_text(encoding="utf-8")).get("modules", []) + + +def owning_leaf(modules: list[dict], path: str) -> dict | None: + owners = [m for m in modules if path.startswith(m["source_path"].rstrip("/") + "/")] + return max(owners, key=lambda m: len(m["source_path"])) if owners else None + + +def package_index(root: Path, modules: list[dict]) -> dict[str, set[str]]: + """Java package → the leaves whose main source set has a class in it.""" + index: dict[str, set[str]] = {} + for module in modules: + base = root / module["source_path"] / "src/main/java" + for directory, _, names in os.walk(base): + if any(name.endswith(".java") for name in names): + package = Path(directory).relative_to(base).as_posix().replace("/", ".") + index.setdefault(package, set()).add(module["id"]) + return index + + +def closure(modules: list[dict], start: str) -> set[str]: + edges = {m["id"]: m.get("allowed_dependencies", []) for m in modules} + seen, pending = {start}, [start] + while pending: + for target in edges.get(pending.pop(), []): + if target not in seen: + seen.add(target) + pending.append(target) + return seen + + +def owner_of(index: dict[str, set[str]], name: str) -> tuple[str, set[str]] | None: + """The longest package prefix of an imported name that some leaf owns (handles nested and static).""" + parts = name.split(".") + for end in range(len(parts), 1, -1): + package = ".".join(parts[:end]) + if package in index: + return package, index[package] + return None + + +def forbidden_prefixes(leaf: str) -> tuple[str, tuple[str, ...]] | None: + if leaf == "domain-core": + return "HARD-STOP 1", DOMAIN_FORBIDDEN + if leaf.startswith("application-"): + return "HARD-STOP 1·4", APPLICATION_FORBIDDEN + if leaf == "shared-contract": + return "shared-contract 금지", SHARED_FORBIDDEN + if leaf.startswith("adapter-inbound-"): + return "HARD-STOP 2", INBOUND_FORBIDDEN + return None + + +def stop_number(leaf: str, target: str) -> str: + if (leaf == "domain-core" or leaf.startswith("application-")) and target.startswith("adapter-inbound-"): + return "HARD-STOP 3" + if leaf.startswith("adapter-inbound-") and target.startswith("adapter-outbound-persistence"): + return "HARD-STOP 2" + return "HARD-STOP 5" + + +def boundary_findings(root: Path, path: str, source: str) -> list[str]: + if not MAIN_JAVA.match(path): + return [] + modules = load_registry(root) + leaf = owning_leaf(modules, path) + if leaf is None: + return [] + allowed = closure(modules, leaf["id"]) + index = package_index(root, modules) + rule = forbidden_prefixes(leaf["id"]) + findings = [] + for static, name, wildcard in IMPORT.findall(source): + imported = name + (".*" if wildcard else "") + if rule and any(imported.startswith(prefix) for prefix in rule[1]): + findings.append(f"- {rule[0]} 의심: `{leaf['id']}`가 `{imported}`를 import한다.") + continue + if not name.startswith(PROJECT_PREFIX): + continue + owner = owner_of(index, name) + if owner is None or owner[1] & allowed: + continue + target = sorted(owner[1])[0] + findings.append(f"- {stop_number(leaf['id'], target)} 의심: `{imported}`는 leaf `{target}`의 것인데" + f" `{leaf['id']}`의 registry allowed_dependencies(전이 포함)에 없다.") + if findings: + findings.insert(0, f"레이어 의존 알림(N1) {path}") + findings.append("정본은 게이트다: desktop `./gradlew architectureCheck`. 의도한 edge면 registry가 먼저다.") + return findings + + +# ---------------------------------------------------------------------------------------------------- +# N2 — the document checks, failures only + + +def wants_doc_check(path: str | None) -> bool: + return bool(path) and path.endswith(".md") and "/build/" not in path and not path.startswith(".claude/hook-state/") + + +def doc_findings(root: Path, path: str) -> list[str]: + failures: list[str] = [] + for script in DOC_CHECKS: + try: + result = subprocess.run([sys.executable, *script], cwd=root, capture_output=True, text=True, + timeout=DOC_TIMEOUT) + except subprocess.TimeoutExpired: + failures.append(f"- {script[0]}: {DOC_TIMEOUT}초 안에 끝나지 않았다") + continue + if result.returncode == 0: + continue + lines = [line.strip() for line in result.stderr.splitlines() + if line.startswith(" ") and line.strip()] + mine = [line for line in lines if path in line] + failures += [f"- {line}" for line in (mine or lines)] + if failures: + failures.insert(0, f"문서 검사 알림(N2) {path} 편집 뒤 실패 줄:") + return failures + + +# ---------------------------------------------------------------------------------------------------- +# N5 — Java changed and the desktop has not compiled it since + + +def ran_desktop_gradle(command: str) -> bool: + try: + words = shlex.split(command) + except ValueError: + words = command.split() + for position, word in enumerate(words): + if word.endswith("ssh"): + hosts = [w for w in words[position + 1:position + 5] if not w.startswith("-")][:2] + if any(DESKTOP_HOST.search(host) for host in hosts) and "gradlew" in command: + return True + return False + + +def turn_end_reason(state: dict) -> str | None: + edits = state.get("java_edits") or [] + if not edits or state.get("reminded"): + return None + shown = ", ".join(f"`{edit}`" for edit in edits[:3]) + (f" 외 {len(edits) - 3}개" if len(edits) > 3 else "") + return (f"[N5 턴 끝 알림] 이 세션에서 Java 파일 {len(edits)}개를 고쳤고({shown}) 그 뒤 desktop Gradle 실행이 없다. " + "컴파일과 테스트는 노트북이 아니라 desktop에서 소유 leaf의 `:check`로 한다" + "(docs/work/operate.md 4.1절). 이번 턴에 돌릴 수 없으면 완료를 말하지 말고, 보고의 확인 줄에 돌리지 못한 것과" + " 이유를 적는다(HARD-STOP 6). 이 알림은 다음 Java 편집 전까지 한 번만 나온다.") + + +# ---------------------------------------------------------------------------------------------------- +# events + + +def pre_edit(payload: dict) -> int: + message = h13_message(project_root(payload), edited_path(payload)) + if message: + print(message, file=sys.stderr) + return 2 + return 0 + + +def post_edit(payload: dict) -> int: + root = project_root(payload) + path = edited_path(payload) + if path is None or not (root / path).is_file(): + return 0 + lines: list[str] = [] + if wants_format(path): + state = load_state(root, payload.get("session_id", "")) + formatted = format_java(root, path) + if formatted and formatted[0].startswith(SKIPPED): + # The reason does not change within a session; saying it on every edit is noise. + formatted = [] if state.get("format_skip_reported") else formatted + state["format_skip_reported"] = True + lines += formatted + if path not in state["java_edits"]: + state["java_edits"].append(path) + state["reminded"] = False + save_state(root, payload.get("session_id", ""), state) + lines += boundary_findings(root, path, (root / path).read_text(encoding="utf-8")) + if wants_doc_check(path): + lines += doc_findings(root, path) + if lines: + print(context("PostToolUse", lines)) + return 0 + + +def post_bash(payload: dict) -> int: + command = (payload.get("tool_input") or {}).get("command", "") + if ran_desktop_gradle(command): + root = project_root(payload) + state = load_state(root, payload.get("session_id", "")) + state["java_edits"] = [] + state["reminded"] = False + save_state(root, payload.get("session_id", ""), state) + return 0 + + +def stop(payload: dict) -> int: + if payload.get("stop_hook_active"): + return 0 + root = project_root(payload) + state = load_state(root, payload.get("session_id", "")) + reason = turn_end_reason(state) + if reason: + state["reminded"] = True + save_state(root, payload.get("session_id", ""), state) + print(json.dumps({"decision": "block", "reason": reason}, ensure_ascii=False)) + return 0 + + +EVENTS = {"pre-edit": pre_edit, "post-edit": post_edit, "post-bash": post_bash, "stop": stop} + + +def main(argv: list[str]) -> int: + if len(argv) != 1 or argv[0] not in EVENTS: + print(f"usage: hooks.py {{{'|'.join(EVENTS)}}} < hook-input.json", file=sys.stderr) + return 1 + try: + payload = json.load(sys.stdin) + except ValueError: + return 0 + return EVENTS[argv[0]](payload if isinstance(payload, dict) else {}) + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/scripts/tests/test_hooks.py b/scripts/tests/test_hooks.py new file mode 100644 index 00000000..b5c1fa08 --- /dev/null +++ b/scripts/tests/test_hooks.py @@ -0,0 +1,400 @@ +"""scripts/hooks/hooks.py의 시험. 고장 낸 입력에서 알림·차단이 나오고, 맞는 입력에서 조용한지 본다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import importlib.util +import io +import json +import os +import stat +import subprocess +import sys +import tempfile +import textwrap +import unittest +from contextlib import redirect_stderr, redirect_stdout +from pathlib import Path +from unittest import mock + +SCRIPTS = Path(__file__).resolve().parent.parent +REPO = SCRIPTS.parent +_spec = importlib.util.spec_from_file_location("hooks", SCRIPTS / "hooks/hooks.py") +hooks = importlib.util.module_from_spec(_spec) +sys.modules["hooks"] = hooks +_spec.loader.exec_module(hooks) + +REGISTRY = {"modules": [ + {"id": "domain-core", "gradle_path": ":domain-core", "source_path": "src/domain-core", "allowed_dependencies": []}, + {"id": "shared-contract", "gradle_path": ":shared-contract", "source_path": "src/shared-contract", + "allowed_dependencies": []}, + {"id": "application-core", "gradle_path": ":application-core", "source_path": "src/application-core", + "allowed_dependencies": ["domain-core", "shared-contract"]}, + {"id": "adapter-inbound-web", "gradle_path": ":adapter:inbound:web", "source_path": "src/adapter/inbound/web", + "allowed_dependencies": ["application-core"]}, + {"id": "adapter-outbound-persistence-jpa", "gradle_path": ":adapter:outbound:persistence-jpa", + "source_path": "src/adapter/outbound/persistence-jpa", "allowed_dependencies": ["application-core"]}, +]} +PACKAGES = { + "src/domain-core": "dev/caskeleton/domain/order/Order.java", + "src/shared-contract": "dev/caskeleton/shared/error/ApiErrorCode.java", + "src/application-core": "dev/caskeleton/application/order/PlaceOrderUseCase.java", + "src/adapter/inbound/web": "dev/caskeleton/adapter/inbound/web/order/OrderRequest.java", + "src/adapter/outbound/persistence-jpa": "dev/caskeleton/adapter/outbound/persistence/order/OrderEntity.java", +} + + +class Repository: + """A throwaway project with a registry, one class per leaf and the migration manifest.""" + + def __init__(self) -> None: + self._directory = tempfile.TemporaryDirectory() + self.root = Path(self._directory.name).resolve() + self.write(hooks.REGISTRY, json.dumps(REGISTRY)) + for leaf, source in PACKAGES.items(): + package = Path(source).parent.as_posix().replace("/", ".") + self.write(f"{leaf}/src/main/java/{source}", f"package {package};\n\nclass {Path(source).stem} {{}}\n") + self.write(hooks.MIGRATION_MANIFEST, + "# comment line\n" + "a" * 64 + " jpa/core/V1__initialize_or_adopt.sql\n") + self.write(hooks.CATALOG, 'googleJavaFormat = "1.35.0"\n') + + def write(self, path: str, text: str) -> Path: + target = self.root / path + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(text, encoding="utf-8") + return target + + def payload(self, path: str, tool: str = "Edit", **extra) -> dict: + return {"session_id": "s1", "cwd": str(self.root), "tool_name": tool, + "tool_input": {"file_path": str(self.root / path)}, **extra} + + def close(self) -> None: + self._directory.cleanup() + + +def run_event(event: str, payload: dict, environment: dict | None = None) -> tuple[int, str, str]: + out, err = io.StringIO(), io.StringIO() + with mock.patch.dict(os.environ, environment or {}, clear=False), \ + mock.patch.object(sys, "stdin", io.StringIO(json.dumps(payload))), redirect_stdout(out), redirect_stderr(err): + os.environ.pop("CLAUDE_PROJECT_DIR", None) + code = hooks.main([event]) + return code, out.getvalue(), err.getvalue() + + +def fake_cache(home: Path, version: str = "1.35.0") -> Path: + """A Gradle user home whose module cache holds the jars the formatter looks for.""" + cache = home / "caches/modules-2/files-2.1" + for group, artifact_version in (("com.google.googlejavaformat/google-java-format", version), + ("com.google.guava/guava", "33.6.0-jre"), + ("com.google.guava/guava", "33.2.1-android"), + ("com.google.guava/failureaccess", "1.0.3")): + artifact = group.rsplit("/", 1)[1] + jar = cache / group / artifact_version / "0123abcd" / f"{artifact}-{artifact_version}.jar" + jar.parent.mkdir(parents=True, exist_ok=True) + jar.write_bytes(b"jar") + return cache + + +def fake_java(folder: Path, body: str) -> str: + """A `java` on PATH that records its arguments in args.json, then runs `body` (Python) on the file.""" + folder.mkdir(parents=True, exist_ok=True) + script = folder / "java" + script.write_text(textwrap.dedent(f"""\ + #!{sys.executable} + import json, sys + from pathlib import Path + Path({str(folder / 'args.json')!r}).write_text(json.dumps(sys.argv[1:])) + target = Path(sys.argv[-1]) + {body} + """), encoding="utf-8") + script.chmod(script.stat().st_mode | stat.S_IXUSR) + return f"{folder}{os.pathsep}{os.environ.get('PATH', '')}" + + +def added_context(stdout: str) -> str: + return json.loads(stdout)["hookSpecificOutput"]["additionalContext"] if stdout else "" + + +class RepositoryTestCase(unittest.TestCase): + def setUp(self) -> None: + self.repo = Repository() + self.addCleanup(self.repo.close) + # The formatter is tested on its own; elsewhere a `java` that changes nothing keeps post-edit quiet. + self.cache = tempfile.TemporaryDirectory() + self.addCleanup(self.cache.cleanup) + home = Path(self.cache.name) + fake_cache(home) + self.environment = {"GRADLE_USER_HOME": str(home), "PATH": fake_java(home / "quiet-java", "pass")} + + +class MigrationGuardTest(RepositoryTestCase): + """H13 — PreToolUse blocks an edit of an applied migration, and only that.""" + + MIGRATION = "src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/core/V1__initialize_or_adopt.sql" + + def test_editing_an_applied_migration_is_blocked_with_the_way_out(self) -> None: + self.repo.write(self.MIGRATION, "create table x();\n") + code, _, err = run_event("pre-edit", self.repo.payload(self.MIGRATION)) + self.assertEqual(code, 2) + self.assertIn("[H13 적용된 migration 편집 금지]", err) + self.assertIn("새 버전 파일", err) + + def test_a_migration_in_another_leaf_is_found_by_its_manifest_key(self) -> None: + path = "src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/core/V1__initialize_or_adopt.sql" + self.assertEqual(run_event("pre-edit", self.repo.payload(path, tool="Write"))[0], 2) + + def test_a_new_migration_version_is_allowed(self) -> None: + path = self.MIGRATION.replace("V1__initialize_or_adopt", "V3__add_column") + self.assertEqual(run_event("pre-edit", self.repo.payload(path, tool="Write")), (0, "", "")) + + def test_other_files_and_other_tools_are_allowed(self) -> None: + self.assertEqual(run_event("pre-edit", self.repo.payload("docs/x.md"))[0], 0) + self.assertEqual(run_event("pre-edit", self.repo.payload(self.MIGRATION, tool="Read"))[0], 0) + + +class FormatterTest(RepositoryTestCase): + """The formatter runs one JVM on one file with the jar Gradle cached; it never downloads one.""" + + SOURCE = "src/domain-core/src/main/java/dev/caskeleton/domain/order/Order.java" + + def fake_cache(self, version: str = "1.35.0") -> Path: + return fake_cache(Path(tempfile.mkdtemp(dir=self.cache.name)), version) + + def fake_java(self, body: str) -> dict: + folder = Path(tempfile.mkdtemp(dir=self.cache.name)) + self.args_file = folder / "args.json" + return {"PATH": fake_java(folder, body)} + + def test_the_classpath_is_the_catalog_version_and_the_newest_jre_guava(self) -> None: + classpath, version = hooks.formatter_classpath(self.repo.root, self.fake_cache()) + self.assertEqual(version, "1.35.0") + self.assertEqual([jar.name for jar in classpath], + ["google-java-format-1.35.0.jar", "guava-33.6.0-jre.jar", "failureaccess-1.0.3.jar"]) + + def test_a_cache_without_the_catalog_version_skips_and_says_so(self) -> None: + lines = hooks.format_java(self.repo.root, self.SOURCE, self.fake_cache(version="1.28.0")) + self.assertEqual(len(lines), 1) + self.assertIn("google-java-format 1.35.0 jar가 Gradle 캐시", lines[0]) + self.assertIn("받거나 설치하지 않는다", lines[0]) + + def test_the_formatter_gets_the_spotless_flags_and_the_one_file(self) -> None: + cache = self.fake_cache() + with mock.patch.dict(os.environ, self.fake_java("pass")): + self.assertEqual(hooks.format_java(self.repo.root, self.SOURCE, cache), []) + args = json.loads(self.args_file.read_text()) + self.assertEqual(args[-3:], ["--skip-reflowing-long-strings", "--replace", str(self.repo.root / self.SOURCE)]) + self.assertIn("com.google.googlejavaformat.java.Main", args) + + def test_a_rewritten_file_tells_the_model_to_read_it_again(self) -> None: + cache = self.fake_cache() + with mock.patch.dict(os.environ, self.fake_java("target.write_text(target.read_text() + '\\n')")): + lines = hooks.format_java(self.repo.root, self.SOURCE, cache) + self.assertEqual(len(lines), 1) + self.assertIn("다시 읽는다", lines[0]) + + def test_a_formatter_error_is_reported_with_its_first_lines(self) -> None: + cache = self.fake_cache() + body = "sys.stderr.write('Order.java:3:1: error: class, interface, enum, or record expected\\n'); sys.exit(1)" + with mock.patch.dict(os.environ, self.fake_java(body)): + lines = hooks.format_java(self.repo.root, self.SOURCE, cache) + self.assertIn("읽지 못했다", lines[0]) + self.assertIn("error: class, interface", lines[1]) + + def test_a_skipped_format_is_said_once_per_session(self) -> None: + environment = {"GRADLE_USER_HOME": str(Path(tempfile.mkdtemp(dir=self.cache.name)))} + first = added_context(run_event("post-edit", self.repo.payload(self.SOURCE), environment)[1]) + second = run_event("post-edit", self.repo.payload(self.SOURCE), environment)[1] + self.assertIn("포맷을 건너뛰었다", first) + self.assertEqual(second, "") + + def test_build_logic_and_non_java_files_are_not_formatted(self) -> None: + self.assertFalse(hooks.wants_format("src/build-logic/src/main/java/A.java")) + self.assertFalse(hooks.wants_format("src/app/build/generated/A.java")) + self.assertFalse(hooks.wants_format("docs/a.md")) + self.assertTrue(hooks.wants_format(self.SOURCE)) + + @unittest.skipUnless(hooks.formatter_classpath(REPO, hooks.gradle_cache())[0], "no google-java-format jar in the Gradle cache") + def test_the_real_formatter_matches_spotless_on_a_badly_indented_file(self) -> None: + # Only on a machine whose Gradle cache holds the catalog version (the owner's laptop). + self.repo.write(self.SOURCE, "package dev.caskeleton.domain.order;\nimport java.util.List;\n" + "class Order{ List lines(){return List.of(\"a\");}}\n") + lines = hooks.format_java(self.repo.root, self.SOURCE, hooks.gradle_cache()) + self.assertIn("다시 썼다", lines[0]) + self.assertEqual((self.repo.root / self.SOURCE).read_text(), textwrap.dedent("""\ + package dev.caskeleton.domain.order; + + import java.util.List; + + class Order { + List lines() { + return List.of("a"); + } + } + """)) + + +class BoundaryNudgeTest(RepositoryTestCase): + """N1 — imports of one main source against the registry and the purity lists.""" + + def nudge(self, leaf: str, relative: str, imports: str) -> str: + package = Path(relative).parent.as_posix().replace("/", ".") + path = f"{leaf}/src/main/java/{relative}" + self.repo.write(path, f"package {package};\n\n{imports}\nclass {Path(relative).stem} {{}}\n") + code, out, _ = run_event("post-edit", self.repo.payload(path), self.environment) + self.assertEqual(code, 0) + return added_context(out) + + def test_spring_in_the_domain_is_hard_stop_1(self) -> None: + text = self.nudge("src/domain-core", "dev/caskeleton/domain/order/Line.java", + "import org.springframework.stereotype.Component;") + self.assertIn("HARD-STOP 1 의심: `domain-core`가 `org.springframework.stereotype.Component`", text) + self.assertIn("architectureCheck", text) + + def test_an_inbound_dto_in_the_application_is_hard_stop_3(self) -> None: + text = self.nudge("src/application-core", "dev/caskeleton/application/order/Place.java", + "import dev.caskeleton.adapter.inbound.web.order.OrderRequest;") + self.assertIn("HARD-STOP 3 의심: `dev.caskeleton.adapter.inbound.web.order.OrderRequest`는 leaf " + "`adapter-inbound-web`의 것인데 `application-core`", text) + + def test_a_persistence_entity_in_a_controller_is_hard_stop_2(self) -> None: + text = self.nudge("src/adapter/inbound/web", "dev/caskeleton/adapter/inbound/web/order/OrderController.java", + "import dev.caskeleton.adapter.outbound.persistence.order.OrderEntity;\n" + "import org.springframework.data.repository.CrudRepository;") + self.assertIn("HARD-STOP 2 의심: `dev.caskeleton.adapter.outbound.persistence.order.OrderEntity`", text) + self.assertIn("HARD-STOP 2 의심: `adapter-inbound-web`가 `org.springframework.data.repository.CrudRepository`", text) + + def test_a_transitive_registry_edge_nested_and_static_imports_pass(self) -> None: + text = self.nudge("src/adapter/inbound/web", "dev/caskeleton/adapter/inbound/web/order/OrderController.java", + "import dev.caskeleton.application.order.PlaceOrderUseCase;\n" + "import dev.caskeleton.domain.order.Order.Line;\n" + "import static dev.caskeleton.shared.error.ApiErrorCode.of;\n" + "import dev.caskeleton.domain.order.*;\n" + "import org.springframework.web.bind.annotation.RestController;") + self.assertEqual(text, "") + + def test_test_sources_and_files_outside_any_leaf_are_not_checked(self) -> None: + path = "src/domain-core/src/test/java/dev/caskeleton/domain/order/OrderTest.java" + self.repo.write(path, "package dev.caskeleton.domain.order;\nimport org.springframework.util.Assert;\nclass OrderTest {}\n") + self.assertEqual(hooks.boundary_findings(self.repo.root, path, (self.repo.root / path).read_text()), []) + self.assertEqual(hooks.boundary_findings(self.repo.root, "src/other/src/main/java/A.java", "import org.springframework.X;"), []) + + +class DocumentNudgeTest(RepositoryTestCase): + """N2 — a document edit runs the two document checks and passes on their failure lines.""" + + def checks(self, work_docs_failures: list[str], docs_failures: list[str]) -> None: + for name, failures in (("check-work-docs.py", work_docs_failures), ("check-docs.py", docs_failures)): + body = "import sys\n" + "".join(f"print({' ' + line!r}, file=sys.stderr)\n" for line in failures) + body += "sys.exit(1)\n" if failures else "" + self.repo.write(f"scripts/{name}", body) + + def test_failures_naming_the_edited_document_come_back(self) -> None: + self.checks(["docs/guide.md:3: broken relative link 'x.md'", "docs/other.md:1: history ID"], + ["[link] docs/guide.md:3: 없는 곳을 가리키는 상대 링크다: x.md"]) + self.repo.write("docs/guide.md", "# 안내\n") + code, out, _ = run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment) + text = added_context(out) + self.assertEqual(code, 0) + self.assertIn("문서 검사 알림(N2) docs/guide.md", text) + self.assertIn("broken relative link 'x.md'", text) + self.assertIn("없는 곳을 가리키는 상대 링크다", text) + self.assertNotIn("docs/other.md", text) + self.assertNotIn("print(", text) + + def test_failures_elsewhere_are_shown_when_none_names_the_document(self) -> None: + self.checks(["AGENTS.md: 41 lines, limit 40"], []) + self.repo.write("docs/guide.md", "# 안내\n") + text = added_context(run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment)[1]) + self.assertIn("AGENTS.md: 41 lines, limit 40", text) + + def test_passing_checks_add_nothing(self) -> None: + self.checks([], []) + self.repo.write("docs/guide.md", "# 안내\n") + self.assertEqual(run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment), (0, "", "")) + + +class TurnEndNudgeTest(RepositoryTestCase): + """N5 — Java edited and no desktop Gradle run since: the turn end says so once.""" + + SOURCE = "src/domain-core/src/main/java/dev/caskeleton/domain/order/Order.java" + + def edit_java(self) -> None: + run_event("post-edit", self.repo.payload(self.SOURCE), self.environment) + + def stop(self, **extra) -> dict | None: + out = run_event("stop", {"session_id": "s1", "cwd": str(self.repo.root), **extra})[1] + return json.loads(out) if out else None + + def bash(self, command: str) -> None: + run_event("post-bash", {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash", + "tool_input": {"command": command}}) + + def test_a_java_edit_blocks_the_turn_end_once_with_the_reason(self) -> None: + self.edit_java() + first = self.stop() + self.assertEqual(first["decision"], "block") + self.assertIn(f"Java 파일 1개를 고쳤고(`{self.SOURCE}`)", first["reason"]) + self.assertIn("HARD-STOP 6", first["reason"]) + self.assertIsNone(self.stop()) + + def test_a_desktop_gradle_run_clears_the_pending_edits(self) -> None: + self.edit_java() + self.bash("ssh -o BatchMode=yes desktop 'cd ~/w && flock /tmp/claude-gates/heavy.lock ./gradlew :domain-core:check'") + self.assertIsNone(self.stop()) + + def test_a_laptop_command_or_another_host_does_not_count(self) -> None: + self.edit_java() + self.bash("git log --oneline -1 && echo gradlew") + self.bash("ssh buildbox ./gradlew check") + self.assertEqual(self.stop()["decision"], "block") + + def test_a_new_java_edit_after_the_reminder_reminds_again(self) -> None: + self.edit_java() + self.stop() + self.edit_java() + self.assertEqual(self.stop()["decision"], "block") + + def test_an_active_stop_hook_never_blocks_again(self) -> None: + self.edit_java() + self.assertIsNone(self.stop(stop_hook_active=True)) + + def test_no_java_edit_no_reminder(self) -> None: + self.assertIsNone(self.stop()) + + +class SettingsWiringTest(unittest.TestCase): + """The committed project settings call these hooks on the events they are written for.""" + + def setUp(self) -> None: + self.settings = json.loads((REPO / ".claude/settings.json").read_text(encoding="utf-8")) + + def commands(self, event: str, matcher: str | None) -> list[str]: + groups = [group for group in self.settings["hooks"][event] if group.get("matcher") == matcher] + return [hook["command"] for group in groups for hook in group["hooks"]] + + def test_every_event_calls_its_hook(self) -> None: + script = 'python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py' + self.assertEqual(self.commands("PreToolUse", "Edit|Write|MultiEdit"), [f"{script} pre-edit"]) + self.assertEqual(self.commands("PostToolUse", "Edit|Write|MultiEdit"), [f"{script} post-edit"]) + self.assertEqual(self.commands("PostToolUse", "Bash"), [f"{script} post-bash"]) + self.assertEqual(self.commands("Stop", None), [f"{script} stop"]) + + def test_real_env_files_are_denied_and_the_examples_are_not(self) -> None: + deny = self.settings["permissions"]["deny"] + for name in (".env", ".env.local", ".env.lane"): + self.assertIn(f"Read(**/{name})", deny) + self.assertIn(f"Edit(**/{name})", deny) + self.assertFalse([rule for rule in deny if "example" in rule or rule.endswith(".env.*)")]) + + def test_the_hook_script_runs_from_the_command_line(self) -> None: + with tempfile.TemporaryDirectory() as project: + result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), "stop"], input="{}", + capture_output=True, text=True, cwd=project, + env={**os.environ, "CLAUDE_PROJECT_DIR": project}) + self.assertEqual((result.returncode, result.stdout), (0, "")) + + +if __name__ == "__main__": + unittest.main() diff --git a/src/adapter/outbound/AGENTS.md b/src/adapter/outbound/AGENTS.md index 5246830f..9af08751 100644 --- a/src/adapter/outbound/AGENTS.md +++ b/src/adapter/outbound/AGENTS.md @@ -11,7 +11,7 @@ - 유스케이스 정책을 adapter에 둔다(HARD-STOP 4). - registry `allowed_dependencies`에 없는 adapter끼리의 edge(HARD-STOP 5). 허용 edge는 registry만 정한다. -- 이미 적용된 migration 파일을 고친다. 새 버전 파일을 더하고 `persistence-jpa`의 `src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다. +- 이미 적용된 migration 파일을 고친다. 새 버전 파일을 더하고 `persistence-jpa`의 `src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다. 편집 훅이 목록에 있는 파일의 편집을 막는다. ## 테스트 diff --git a/src/build-logic/AGENTS.md b/src/build-logic/AGENTS.md index 51480a45..76de3ad1 100644 --- a/src/build-logic/AGENTS.md +++ b/src/build-logic/AGENTS.md @@ -35,4 +35,4 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 ## 테스트 -- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. +- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다. -- 2.54.0 From c67c713177e72d06f7112e9ecde56ad8a051f933 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:08:42 +0900 Subject: [PATCH 04/12] =?UTF-8?q?feat(agents)!:=20Agent=20=EA=B8=88?= =?UTF-8?q?=EC=A7=80=EB=A5=BC=20=ED=92=80=EA=B3=A0=20=EA=B2=B0=EA=B3=BC?= =?UTF-8?q?=EB=A7=8C=20=EB=8F=8C=EB=A0=A4=EC=A3=BC=EB=8A=94=20=EC=84=9C?= =?UTF-8?q?=EB=B8=8C=EC=97=90=EC=9D=B4=EC=A0=84=ED=8A=B8=20=EC=85=8B?= =?UTF-8?q?=EC=9D=84=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을 띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나 하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만 받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션으로 나누기로 정했다(design-docs harness/01-harness-design.md 8절, 13절 Q5). - .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다). - .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고 판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을 띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지 않는 단순화 제안). 셋 다 Edit·Write 도구가 없다. - 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md 4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. - scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동 조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를 따르는지 본다. 버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만 허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다). 위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지 못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고, 노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다. 데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지 못했다. 검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에 Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다. check-work-docs·check-docs rc=0. BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스 설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행. --- .claude/agents/arch-reviewer.md | 28 +++++++++++++ .claude/agents/code-simplifier.md | 26 ++++++++++++ .claude/agents/verify-api.md | 32 +++++++++++++++ .claude/settings.json | 1 - .gitignore | 3 +- AGENTS.md | 2 +- CLAUDE.md | 1 + docs/upgrade/2026-11-harness.md | 1 + docs/work/README.md | 2 +- docs/work/delegate.md | 7 +++- docs/work/operate.md | 2 +- scripts/tests/test_claude_setup.py | 65 ++++++++++++++++++++++++++++++ 12 files changed, 163 insertions(+), 7 deletions(-) create mode 100644 .claude/agents/arch-reviewer.md create mode 100644 .claude/agents/code-simplifier.md create mode 100644 .claude/agents/verify-api.md create mode 100644 scripts/tests/test_claude_setup.py diff --git a/.claude/agents/arch-reviewer.md b/.claude/agents/arch-reviewer.md new file mode 100644 index 00000000..ce18c098 --- /dev/null +++ b/.claude/agents/arch-reviewer.md @@ -0,0 +1,28 @@ +--- +name: arch-reviewer +description: 바뀐 Java·Gradle·registry가 이 repo의 계층 규칙(HARD-STOP 1~5, registry allowed_dependencies, leaf 지역 규칙)을 지키는지 읽기만 하고 판정을 돌려준다. 구현이나 수정 묶음을 끝내고 커밋이나 PR 전에, 또는 사용자가 "구조 리뷰", "경계 확인", "레이어 위반 없나"라고 할 때 쓴다. 파일을 고치지 않는다. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# arch-reviewer — 계층 규칙 리뷰(읽기 전용) + +맡긴 쪽이 준 범위(기준 커밋, diff, 경로)만 본다. 결과만 돌려주고 파일을 쓰거나 고치지 않는다. Bash는 `git diff`, `git log`, `git grep`, `python3 scripts/check-*.py` 같은 읽기 명령에만 쓴다. Gradle·Docker는 돌리지 않는다(노트북에서 막히고, 게이트는 맡긴 쪽이 desktop에서 돌린다). + +## 순서 + +1. 루트 `AGENTS.md`의 HARD-STOP과 지도를 읽는다. +2. 바뀐 파일마다 registry `src/config/architecture/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다. +3. 운영 소스의 import를 본다: 순수성(`domain-core`·`application-*`·`shared-contract`의 framework import), inbound의 repository·Spring Data·entity 사용, inbound DTO가 core로 들어가는지, `dev.caskeleton.*` 주인 leaf가 `allowed_dependencies`(전이 포함)에 있는지. +4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 가지 않았는지 본다(HARD-STOP 4). 이것은 import로 안 보이니 코드를 읽는다. +5. `build.gradle`·registry를 바꿨으면 새 edge가 registry에 있고 방향 그림(`app-bootstrap → adapter → application-core → domain-core`)을 거스르지 않는지 본다. + +## 돌려줄 것 + +```text +판정: 통과 / 위반 있음 / 판단 못 함 +발견: (위반마다) HARD-STOP 번호 · 파일:줄 · 무엇이 무엇을 쓰나 · 근거 규칙(문서 경로) +확인 못 한 것: (읽지 못한 파일, 게이트로만 판정할 것 — 예: architectureCheck) +``` + +발견이 없으면 "발견 0"과 본 파일 수를 적는다. 추측은 발견에 넣지 않고 「확인 못 한 것」에 넣는다. diff --git a/.claude/agents/code-simplifier.md b/.claude/agents/code-simplifier.md new file mode 100644 index 00000000..9f19a020 --- /dev/null +++ b/.claude/agents/code-simplifier.md @@ -0,0 +1,26 @@ +--- +name: code-simplifier +description: 지정한 파일·diff에서 동작을 바꾸지 않고 줄일 수 있는 곳(중복, 죽은 코드, 불필요한 분기·래퍼, 더 단순한 표준 API)을 찾아 제안만 돌려준다. 구현을 마친 뒤 "단순하게", "정리할 곳", "중복 없나"라고 할 때나 리뷰 전에 쓴다. 파일을 고치지 않는다. 고치는 일은 맡긴 세션이 한다. +tools: Read, Grep, Glob +model: inherit +--- + +# code-simplifier — 단순화 제안(읽기 전용) + +맡긴 범위만 본다. 제안만 돌려주고 파일을 쓰지 않는다. + +## 지킬 것 + +- 동작을 바꾸는 제안을 하지 않는다. 공개 계약(HTTP wire, 오류 코드, env 키, API surface)을 바꾸는 제안은 하지 않는다. +- 계층 규칙(루트 `AGENTS.md` HARD-STOP, 가장 가까운 `AGENTS.md`)을 어기게 만드는 제안을 하지 않는다. 예: 포트를 지우고 adapter를 직접 부르게 하기. +- 테스트를 줄이는 제안은 단언이 약해지지 않을 때만 한다(`.claude/rules/java-tests.md`). +- 요청 범위 밖의 큰 리팩터링은 제안하지 않고 「범위 밖에서 본 것」에 한 줄로 적는다. + +## 돌려줄 것 + +```text +제안: (하나마다) 파일:줄 · 지금 모양 · 바꿀 모양(짧은 코드) · 왜 동작이 같은가 · 그것을 보일 테스트 +범위 밖에서 본 것: (있으면) +``` + +제안이 없으면 "제안 0"과 본 파일 수를 적는다. diff --git a/.claude/agents/verify-api.md b/.claude/agents/verify-api.md new file mode 100644 index 00000000..8b1d5faa --- /dev/null +++ b/.claude/agents/verify-api.md @@ -0,0 +1,32 @@ +--- +name: verify-api +description: 지정한 브랜치나 커밋의 앱을 desktop에서 실제로 띄워 health와 지정한 HTTP endpoint를 호출하고, 응답 코드·본문 요약·로그 경로만 돌려준다. 동작을 바꾼 변경을 끝내고 "직접 돌려 봐", "앱이 뜨나", "API 확인"이라고 할 때나 PR 전 확인으로 쓴다. 노트북에서 Gradle·Docker를 돌리지 않고, 노트북 checkout의 파일을 고치지 않는다. +tools: Bash, Read, Grep, Glob +model: inherit +--- + +# verify-api — desktop에서 앱을 띄워 확인 + +Gradle·Docker는 desktop에서만 돈다. 절차의 정본은 `docs/work/operate.md` 4.1절(실행 위치)이고, 이 문서는 그 안에서 앱을 띄우는 순서만 적는다. 노트북 checkout은 읽기만 한다. + +## 받을 것 + +- 확인할 브랜치(push된 것) 또는 기준 커밋 + 패치(4.1절 「push 전에 검증하기」), 작업 이름. +- 부를 endpoint 목록과 기대 응답. 없으면 `GET /api/healthcheck`만 본다. + +## 순서 + +1. desktop에 따로 worktree를 만든다. 기존 checkout `~/workspace/clean-architecture-backend-template`의 브랜치와 `stash@{0}`는 건드리지 않는다. +2. 로그 폴더 `~/<작업 이름>-logs/`를 만들고 `uptime`으로 부하를 본다. +3. worktree 루트에서 `flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh > ~/<작업 이름>-logs/bootstrap.log 2>&1; echo "rc=$?"`를 돌린다. 스크립트가 컴파일 → DB 기동 → 앱 기동 → health 200과 `status=UP`을 차례로 본다. +4. 앱이 떠 있는 동안 받은 endpoint를 `curl --silent --show-error --max-time 5 --write-out '\n%{http_code}'`로 부르고 응답을 로그 폴더에 남긴다. +5. 저장소 루트에서 `docker compose --profile '*' down`으로 내린다. 컨테이너가 만든 root 소유 폴더가 남으면 4.1절의 정리법을 따른 뒤 worktree를 지운다. + +## 돌려줄 것 + +```text +결과: 떴다 / 안 떴다(멈춘 bootstrap 단계) +호출: (endpoint마다) 메서드 경로 · HTTP 코드 · 기대와 같은가 · 본문 요약 한 줄 +증거: desktop 로그 경로, 트리 해시(git rev-parse HEAD^{tree}) +남은 것: 지우지 못한 worktree·컨테이너, 확인 못 한 endpoint +``` diff --git a/.claude/settings.json b/.claude/settings.json index ba08091d..4be5930d 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,7 +1,6 @@ { "permissions": { "deny": [ - "Agent", "Read(**/.env)", "Read(**/.env.local)", "Read(**/.env.lane)", diff --git a/.gitignore b/.gitignore index 47cfcf38..ec43691f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,11 @@ .vscode/ src/**/bin/ # Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project -# settings and the path rules are committed: everyone who opens the repository gets them (CLAUDE.md). +# settings, the path rules and the subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md). .claude/* !.claude/settings.json !.claude/rules/ +!.claude/agents/ # Operator input, not a build input. The examples beside it are the tracked contract; # verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one. diff --git a/AGENTS.md b/AGENTS.md index 2449fa91..f990d2ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,4 +34,4 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버 - 커밋 정책은 `human-only`다. brief가 허용한 것만 자기 브랜치에 한다(`docs/work/README.md` 4절). - 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다. -- 일을 나눌 때는 소유자가 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). Gradle·Docker는 누가 돌려도 desktop에서다. +- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(`docs/work/delegate.md`). diff --git a/CLAUDE.md b/CLAUDE.md index 4df9a8b5..65152b19 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,4 +4,5 @@ - 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. - 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다. +- 서브에이전트는 `.claude/agents/`다: `arch-reviewer`(구조 리뷰), `verify-api`(desktop에서 앱 띄워 확인), `code-simplifier`(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다. - 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index 127155a8..512f04a6 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -15,3 +15,4 @@ | 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 | | 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 | | 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 | +| 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 | diff --git a/docs/work/README.md b/docs/work/README.md index c7cdd40c..50c06dd8 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -32,7 +32,7 @@ 1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. 2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. 3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다. -4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다([delegate.md](delegate.md) 4.3절). +4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절). 5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. 6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. 7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). diff --git a/docs/work/delegate.md b/docs/work/delegate.md index eb09419d..567bc6ab 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | -| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | | `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | 나눌 때 지킬 것: @@ -84,7 +84,10 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 하위 세션을 띄우는 법, 하위 세션 보고가 총괄에게 전달되는 길이, 공유 노트 폴더, 프론트 repo 일의 경로 같은 소유자 환경 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 다시 쓰지 않는다. 이 repo에서 더할 것은 둘이다. -- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 그 세션이 직접 하거나, 이 playbook대로 별도 세션에 맡긴다. 막혔다고 Agent로 우회하지 않는다. +- 나누는 기준(소유자 결정 2026-11-07): + - 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다. + - 결과만 받는 일(넓은 검색, 구조 리뷰 `arch-reviewer`, 앱을 띄워 보는 확인 `verify-api`, 단순화 제안 `code-simplifier`)은 서브에이전트(Agent 도구, 정의는 `.claude/agents/`)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. + - Gradle·Docker는 누가 돌려도 desktop에서다. 서브에이전트 안에서도 소유자 전역 훅이 노트북 실행을 막는다. - 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다. - 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다. diff --git a/docs/work/operate.md b/docs/work/operate.md index 04165e4d..8df229a0 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -106,7 +106,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다. - 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다. - 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. -- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. +- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. ## 5. 완료 기준 diff --git a/scripts/tests/test_claude_setup.py b/scripts/tests/test_claude_setup.py new file mode 100644 index 00000000..fb774b90 --- /dev/null +++ b/scripts/tests/test_claude_setup.py @@ -0,0 +1,65 @@ +"""`.claude/`의 서브에이전트 정의가 소유자 결정(2026-11-07)대로인지 본다. + +결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절). + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import json +import re +import unittest +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent.parent +AGENTS = REPO / ".claude/agents" +WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"} + + +def front_matter(path: Path) -> dict[str, str]: + text = path.read_text(encoding="utf-8") + match = re.match(r"^---\n(.*?)\n---\n", text, re.S) + if not match: + return {} + fields = {} + for line in match.group(1).splitlines(): + key, _, value = line.partition(":") + fields[key.strip()] = value.strip() + return fields + + +class SubagentTest(unittest.TestCase): + def test_the_agent_tool_is_no_longer_denied(self) -> None: + settings = json.loads((REPO / ".claude/settings.json").read_text(encoding="utf-8")) + deny = settings.get("permissions", {}).get("deny", []) + self.assertFalse([rule for rule in deny if rule == "Agent" or rule.startswith("Agent(")]) + + def test_each_definition_names_itself_and_says_when_to_use_it(self) -> None: + definitions = sorted(AGENTS.glob("*.md")) + self.assertEqual([path.stem for path in definitions], ["arch-reviewer", "code-simplifier", "verify-api"]) + for path in definitions: + fields = front_matter(path) + self.assertEqual(fields.get("name"), path.stem, path) + self.assertRegex(fields.get("description", ""), r"쓴다", path) + self.assertTrue(fields.get("tools"), f"{path} must list its tools; an empty list inherits every tool") + + def test_no_subagent_can_edit_files(self) -> None: + for path in AGENTS.glob("*.md"): + tools = {tool.strip() for tool in front_matter(path).get("tools", "").split(",")} + self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}") + + def test_the_reviewers_have_no_shell_that_could_change_the_tree_except_read_commands(self) -> None: + self.assertNotIn("Bash", front_matter(AGENTS / "code-simplifier.md")["tools"]) + reviewer = (AGENTS / "arch-reviewer.md").read_text(encoding="utf-8") + self.assertIn("파일을 쓰거나 고치지 않는다", reviewer) + + def test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock(self) -> None: + text = (AGENTS / "verify-api.md").read_text(encoding="utf-8") + for fragment in ("docs/work/operate.md", "flock /tmp/claude-gates/heavy.lock", "scripts/bootstrap-local.sh", + "stash@{0}", "down"): + self.assertIn(fragment, text) + + +if __name__ == "__main__": + unittest.main() -- 2.54.0 From 67ecae2cc2957afb390e459d6d782044b4068180 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:10:08 +0900 Subject: [PATCH 05/12] =?UTF-8?q?feat(skills)!:=20=EC=83=88=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=EA=B3=BC=20desktop=20=EA=B2=8C=EC=9D=B4=ED=8A=B8=20?= =?UTF-8?q?=EC=A0=88=EC=B0=A8=EB=A5=BC=20=EB=AA=A8=EB=8D=B8=EC=9D=B4=20?= =?UTF-8?q?=EB=B6=80=EB=A5=B4=EB=8A=94=20=EC=8A=A4=ED=82=AC=EB=A1=9C=20?= =?UTF-8?q?=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을 할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야 하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가 2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고 설명에 발동 조건을 문단으로 적기로 정했다(design-docs harness/01-harness-design.md 5.5절, 13절 Q9·Q18). - .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의 실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터 → 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트). - .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행 순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc → 테스트 수 → 잠금 대기 → 정리 → 보고 칸). - 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은 327자·268자로 목록 상한(1,536자) 안이다. - 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다. - test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본 가리키기, skills-lock.json 없음)을 더했다. 버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함), verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편 몫이라 여기서는 만들지 않는다). 위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른 스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다. 검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아 고쳤다), check-work-docs, check-repo-layout 모두 rc=0. BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/ 2026-11-harness.md 2절 6행. --- .claude/skills/desktop-gates/SKILL.md | 17 ++++++++++ .claude/skills/new-feature/SKILL.md | 18 ++++++++++ .gitignore | 3 +- CLAUDE.md | 1 + docs/upgrade/2026-11-harness.md | 1 + docs/work/README.md | 2 +- docs/work/delegate.md | 2 +- docs/work/new-feature.md | 2 +- docs/work/operate.md | 2 +- scripts/check-repo-layout.py | 1 - scripts/tests/test_claude_setup.py | 32 +++++++++++++++++- skills-lock.json | 47 --------------------------- 12 files changed, 74 insertions(+), 54 deletions(-) create mode 100644 .claude/skills/desktop-gates/SKILL.md create mode 100644 .claude/skills/new-feature/SKILL.md delete mode 100644 skills-lock.json diff --git a/.claude/skills/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md new file mode 100644 index 00000000..1ec3abdd --- /dev/null +++ b/.claude/skills/desktop-gates/SKILL.md @@ -0,0 +1,17 @@ +--- +name: desktop-gates +description: 이 repo에서 Gradle·Docker·테스트·게이트·성능 측정을 돌려야 할 때 쓴다. 노트북에서는 돌리지 않고 desktop에서 공유 잠금 아래 돌린다. 사용자가 "테스트 돌려", "게이트", "검증해", "check 돌려", "PR 단계 돌려"라고 하거나, 편집 훅이 턴 끝에 desktop 검증이 없다고 알렸거나, 노트북의 gradlew·docker 실행이 훅에 막혔을 때 부른다. 커밋 전 트리를 패치로 보내 같은 트리에서 돌리는 법, 로그·rc 남기기, 정리까지 준다. +--- + +# desktop에서 게이트 돌리기 + +정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. CI 재편에서 검증 진입점 스크립트(설계 이름 `verify.sh`)가 생기면 이 절차를 그 스크립트가 대신한다. + +1. 돌릴 게이트를 고른다: 바꾼 것에 맞는 게이트는 `gates.md` 2절, PR·main 단계 묶음은 3절이다. leaf의 Gradle path는 registry `gradle_path`에서 읽는다. +2. 트리를 정한다. push가 허용됐으면 push한 브랜치, 아니면 4.1절 「push 전에 검증하기」대로 기준 커밋 + 패치를 보내고 노트북 `git write-tree`와 desktop `git write-tree`가 같은지 본다. +3. desktop에 따로 worktree를 만든다. 기존 checkout의 브랜치와 `stash@{0}`는 건드리지 않는다. 로그 폴더는 `~/<작업 이름>-logs/`다. +4. `uptime`을 적고, 게이트마다 `flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"`로 하나씩 돌린다. 증거로 쓸 실행은 `--rerun`이나 `--no-build-cache`로 캐시 결과를 쓰지 않는다(`gates.md` 4절). +5. 테스트 수는 결과 XML 사본에서 센다(`gates.md` 4절). 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다(`operate.md` 7절). +6. 다른 세션이 잠금을 쥐고 있으면 기다린다. 기다리는 동안 다른 일을 하고, 잠금 대기는 완료나 첫 실패에서 끝나는 대기 하나로 둔다. +7. 끝나면 compose를 내리고(`docker compose … down`) worktree를 지운다. root 소유 폴더가 남으면 4.1절의 정리법을 쓴다. +8. 보고에는 게이트, rc, 직전 부하, 로그 경로, 대상 트리 해시, 캐시 여부를 적는다. diff --git a/.claude/skills/new-feature/SKILL.md b/.claude/skills/new-feature/SKILL.md new file mode 100644 index 00000000..223336a1 --- /dev/null +++ b/.claude/skills/new-feature/SKILL.md @@ -0,0 +1,18 @@ +--- +name: new-feature +description: 이 백엔드 템플릿에 새 업무 기능(도메인 개념, 유스케이스, endpoint)이나 새 capability 모듈을 더할 때 쓴다. 사용자가 "기능 추가", "새 API", "새 유스케이스", "새 도메인", "capability 모듈 만들기", "/new-feature <이름>"이라고 하거나, brief의 작업 종류가 docs/work/new-feature.md일 때 부른다. 생성 명령 scripts/new-feature.sh부터 시작해 안쪽 계층부터 채우고 desktop에서 검증하는 순서를 준다. 있는 기능을 고치는 일은 이 스킬이 아니라 docs/work/improve.md다. +--- + +# 새 기능 만들기 + +정본은 `docs/work/new-feature.md`(크기·완료 기준·하지 말 것)와 `docs/manual/`(만드는 순서와 판단 지점)이다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. + +1. `docs/work/README.md`와 `docs/work/new-feature.md`를 끝까지 읽는다. 크기를 정한다. 새 capability 모듈, 새 leaf, 새 공개 계약(HTTP 경로·오류 코드·env 키)은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다. +2. 받을 것을 확인한다: 기능 이름(PascalCase), 저장소 선택(어떤 persistence leaf, migration 번호대), 권한, 재전송될 수 있는 쓰기인지. 저장소 선택은 사람이 정한다. brief에 없으면 묻는다. +3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. +4. 뼈대: 노트북에서는 `scripts/new-feature.sh --no-format`. 포맷은 편집 훅이 파일마다 맞추고, 마지막에 desktop `./gradlew spotlessApply`로 한 번 더 본다. +5. 안쪽부터 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립(`docs/manual/02-new-feature.md`). 필요한 장만 더 읽는다: 저장 04, 재시도될 쓰기 05, 오류 06, 권한 07, 테스트 08, 이벤트 09, capability 10. +6. 동작은 테스트를 먼저 쓴다(`.claude/rules/java-tests.md`). 포트마다 fake 하나와 공유 계약(`XxxContract`)을 포트 소유 leaf의 testFixtures에 두고, 실제 adapter도 실 DB lane에서 같은 계약을 상속한다. +7. 편집 훅의 레이어 의존 알림(N1)이 나오면 그 자리에서 고친다. 의도한 edge면 registry가 먼저다. +8. 건드린 leaf마다 `:check`, 경계를 넘었으면 `architectureCheck`, 바뀐 표면의 검사(공개 경로·env 키·의존성 잠금)를 desktop에서 돌린다(스킬 `desktop-gates`). 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(구조 리뷰)와 `verify-api`(앱을 띄워 호출)에 맡긴다. +9. `docs/manual/11-checklist.md`를 한 줄씩 확인하고, `docs/work/new-feature.md` 8절 형식으로 보고한다. diff --git a/.gitignore b/.gitignore index ec43691f..e5fbb33d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,12 @@ .vscode/ src/**/bin/ # Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project -# settings, the path rules and the subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md). +# settings, path rules, skills and subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md). .claude/* !.claude/settings.json !.claude/rules/ !.claude/agents/ +!.claude/skills/ # Operator input, not a build input. The examples beside it are the tracked contract; # verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one. diff --git a/CLAUDE.md b/CLAUDE.md index 65152b19..f30f0dfc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,5 +4,6 @@ - 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. - 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다. +- 스킬은 `.claude/skills/`다: `new-feature`(새 기능), `desktop-gates`(Gradle·Docker를 desktop에서). 발동 조건이 설명에 있어 모델이 부른다. - 서브에이전트는 `.claude/agents/`다: `arch-reviewer`(구조 리뷰), `verify-api`(desktop에서 앱 띄워 확인), `code-simplifier`(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다. - 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index 512f04a6..d9a91804 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -16,3 +16,4 @@ | 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 | | 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 | | 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 | +| 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 | diff --git a/docs/work/README.md b/docs/work/README.md index 50c06dd8..8694a08c 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -32,7 +32,7 @@ 1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. 2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. 3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다. -4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절). +4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 `.claude/skills/`다(`new-feature`, `desktop-gates`). 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절). 5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. 6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. 7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). diff --git a/docs/work/delegate.md b/docs/work/delegate.md index 567bc6ab..e48ee7bc 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | -| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | | `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | 나눌 때 지킬 것: diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index a3808e56..04e39663 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -24,7 +24,7 @@ - 업무 기능 하나는 보통 중간이다: 계층 leaf 여러 곳에 파일이 생기지만 판단은 매뉴얼이 정해 둔 범위 안이다. - 큼: 새 capability 모듈, 새 leaf, 새 공개 계약, 파생 서비스가 따라 고쳐야 하는 변경. 큰 일은 설계와 소유자 검토가 먼저다([research-design.md](research-design.md)). - 선행 사례는 생성 명령의 출력 하나다. 개별 기법의 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)로 가리킨다. -- 스킬: 설계가 바뀌면 `superpowers:brainstorming`, 여러 단계면 `superpowers:writing-plans`, 구현은 `superpowers:test-driven-development`. +- 스킬: 이 repo의 `new-feature`(이 playbook의 실행 순서표), 설계가 바뀌면 `superpowers:brainstorming`, 여러 단계면 `superpowers:writing-plans`, 구현은 `superpowers:test-driven-development`. ## 4. 절차 diff --git a/docs/work/operate.md b/docs/work/operate.md index 8df229a0..36702f19 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -106,7 +106,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다. - 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다. - 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. -- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다. +- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `skills/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. ## 5. 완료 기준 diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py index 5e5a4c95..41a5e414 100755 --- a/scripts/check-repo-layout.py +++ b/scripts/check-repo-layout.py @@ -55,7 +55,6 @@ ROOT_ALLOWED = { "README.md": "저장소 소개", "compose.yaml": "개발 환경(하나뿐)", "renovate.json": "의존성 갱신 봇 설정", - "skills-lock.json": "에이전트 스킬 고정", "testcontainers.properties.example": "Testcontainers 로컬 설정 예", } diff --git a/scripts/tests/test_claude_setup.py b/scripts/tests/test_claude_setup.py index fb774b90..464c7881 100644 --- a/scripts/tests/test_claude_setup.py +++ b/scripts/tests/test_claude_setup.py @@ -1,6 +1,7 @@ -"""`.claude/`의 서브에이전트 정의가 소유자 결정(2026-11-07)대로인지 본다. +"""`.claude/`의 서브에이전트 정의와 스킬이 소유자 결정(2026-11-07)대로인지 본다. 결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절). +새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 문단으로 적는다. python3 -m unittest discover -s scripts/tests """ @@ -14,6 +15,9 @@ from pathlib import Path REPO = Path(__file__).resolve().parent.parent.parent AGENTS = REPO / ".claude/agents" +SKILLS = REPO / ".claude/skills" +# Claude Code cuts a skill description at this many characters in the listing. +DESCRIPTION_LIMIT = 1536 WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"} @@ -61,5 +65,31 @@ class SubagentTest(unittest.TestCase): self.assertIn(fragment, text) +class SkillTest(unittest.TestCase): + CANON = {"new-feature": "docs/work/new-feature.md", "desktop-gates": "docs/work/operate.md"} + + def test_the_repository_skills_are_the_two_the_manual_names(self) -> None: + self.assertEqual(sorted(path.parent.name for path in SKILLS.glob("*/SKILL.md")), sorted(self.CANON)) + + def test_each_skill_is_model_invoked_and_says_when_in_its_description(self) -> None: + for name in self.CANON: + fields = front_matter(SKILLS / name / "SKILL.md") + self.assertEqual(fields.get("name"), name) + self.assertNotIn("disable-model-invocation", fields) + description = fields.get("description", "") + self.assertLessEqual(len(description), DESCRIPTION_LIMIT, name) + self.assertIn("쓴다", description, f"{name}: say when to use it") + self.assertIn("부른다", description, f"{name}: say what the user says that calls it") + + def test_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None: + for name, canon in self.CANON.items(): + body = (SKILLS / name / "SKILL.md").read_text(encoding="utf-8") + self.assertIn(f"정본은 `{canon}`", body) + self.assertIn("정본이 맞다", body) + + def test_the_uninstalled_skill_lock_is_gone(self) -> None: + self.assertFalse((REPO / "skills-lock.json").exists()) + + if __name__ == "__main__": unittest.main() diff --git a/skills-lock.json b/skills-lock.json deleted file mode 100644 index c3044cd8..00000000 --- a/skills-lock.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "version": 1, - "skills": { - "cavecrew": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/cavecrew/SKILL.md", - "computedHash": "505d836228d1c5e14834ff5d62aad72390c7d27f79c6aa7f9a7a55ed6606d6a2" - }, - "caveman": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/caveman/SKILL.md", - "computedHash": "1902fa0b569912d0c05736d8d98a72097d9b82719aac88c0c1d03bb546f9176d" - }, - "caveman-commit": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/caveman-commit/SKILL.md", - "computedHash": "790a4eeace0be35c6691faf923518ba5bd50f1f1305d1101d09dd4971be94e00" - }, - "caveman-compress": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/caveman-compress/SKILL.md", - "computedHash": "1e9b3e2bf68b75dc0252c4328c8514bea79d4d8f7d7259da616ba7d12cad6865" - }, - "caveman-help": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/caveman-help/SKILL.md", - "computedHash": "dd85267e76baad76995157e7b9f762dfa557cd58951ee92af0c283f48aa26537" - }, - "caveman-review": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/caveman-review/SKILL.md", - "computedHash": "fb7214a1c5793bae6ba8b1be4329e2e6f40dbec6dd911dfb335ad29f09c316a1" - }, - "caveman-stats": { - "source": "JuliusBrussee/caveman", - "sourceType": "github", - "skillPath": "skills/caveman-stats/SKILL.md", - "computedHash": "47ce2de3d6cb39a75047b5c962e4eb3da15594e7397c94103e9a104d42626553" - } - } -} -- 2.54.0 From 37c88fedd4c9d022f44f97884805f05f0223bdd0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:11:27 +0900 Subject: [PATCH 06/12] =?UTF-8?q?docs(ledger):=20=EC=9E=91=EC=97=85?= =?UTF-8?q?=EB=A7=88=EB=8B=A4=20=EC=98=88=EC=B8=A1=EA=B3=BC=20=EC=8B=A4?= =?UTF-8?q?=EC=B8=A1=EC=9D=84=20=EC=8C=93=EB=8A=94=20repo=20=EC=9E=A5?= =?UTF-8?q?=EB=B6=80=EB=A5=BC=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서 하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로 repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs harness/01-harness-design.md 10절, 13절 Q11). - docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의 뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것. - 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값). 실측 줄은 끝 보고 직전에 더한다. - 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에 merge=union을 줬다(설계가 걱정한 병합 충돌). - docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를 더했고, docs/README.md 지도에 ledger/ 행을 더했다. - scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과 근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다. 버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가 repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다. 위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지 못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다. 검증: unittest, check-docs(지도 검사 포함), check-work-docs, check-repo-layout rc=0. git check-attr로 merge: union을 확인했다. --- .gitattributes | 4 +++ docs/README.md | 1 + docs/ledger/README.md | 49 ++++++++++++++++++++++++++++++ docs/ledger/estimates.jsonl | 1 + docs/upgrade/2026-11-harness.md | 1 + docs/work/README.md | 1 + docs/work/delegate.md | 2 ++ scripts/tests/test_ledger.py | 53 +++++++++++++++++++++++++++++++++ 8 files changed, 112 insertions(+) create mode 100644 docs/ledger/README.md create mode 100644 docs/ledger/estimates.jsonl create mode 100644 scripts/tests/test_ledger.py diff --git a/.gitattributes b/.gitattributes index 892aae23..094c0eb7 100644 --- a/.gitattributes +++ b/.gitattributes @@ -7,6 +7,7 @@ *.yml text eol=lf *.yaml text eol=lf *.json text eol=lf +*.jsonl text eol=lf *.md text eol=lf gradlew text eol=lf gradlew.bat text eol=crlf @@ -20,3 +21,6 @@ gradlew.bat text eol=crlf *.jar binary *.zip binary *.gz binary + +# Ledger lines are only appended; a union merge keeps both branches' new lines (docs/ledger/README.md). +docs/ledger/estimates.jsonl merge=union diff --git a/docs/README.md b/docs/README.md index 95b1489b..0a204bd6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,7 @@ | --- | --- | | `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `AGENTS.md` 다음에 읽는다 | | `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` | +| `ledger/` | 예측·실측 장부: 작업마다 착수 예측(p30·p50·p80과 근거)과 끝 실측을 한 줄씩 쌓는다(`ledger/estimates.jsonl`, 형식은 `ledger/README.md`) | | `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 | ### 계약과 스냅숏 diff --git a/docs/ledger/README.md b/docs/ledger/README.md new file mode 100644 index 00000000..2e514004 --- /dev/null +++ b/docs/ledger/README.md @@ -0,0 +1,49 @@ +# 예측·실측 장부 + +작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07). + +```text +착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거 +끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 +회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계 +``` + +- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. +- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다. +- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다. +- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다. +- 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다. + +## 줄의 칸 + +모든 줄: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `schema` | 정수 | 이 형식의 판. 지금 1 | +| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 | +| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) | +| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | +| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects//<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | + +`estimate`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `started_at` | ISO 8601 | 세션 첫 기록 시각 | +| `base` | 문자열 | 기준 커밋 | +| `task_kind`, `size` | 문자열 | `docs/work/` playbook 이름, 작음·중간·큼(`small`·`medium`·`large`) | +| `minutes`, `calls`, `output_tokens` | `{"p30","p50","p80"}` 정수 | 작업 중 시간(분), 모델 호출 수, 출력 토큰 | +| `basis` | 문자열 | 근거: 비교한 선례와 그 실측, 바꿀 파일 수, 검증 대기 | + +`actual`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 기록 사이 5분 넘는 빈틈을 뺀 시간 | +| `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 | +| `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 | +| `result`, `commits` | 문자열, 배열 | 완료·부분·못 함, 만든 커밋 | +| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 | + +`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서). diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl new file mode 100644 index 00000000..411083b5 --- /dev/null +++ b/docs/ledger/estimates.jsonl @@ -0,0 +1 @@ +{"schema": 1, "kind": "estimate", "task": "h3-backend-harness", "recorded_at": "2026-11-07T21:46+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "started_at": "2026-11-07T21:37:50+09:00", "base": "b3f63be6", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 150, "p50": 210, "p80": 300}, "calls": {"p30": 450, "p50": 600, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 600000, "p80": 850000}, "basis": "선례 h1-harness-design 작업 중 23분·호출 100·출력 13.6만(바꾼 파일 3, Gradle 없음)에서 분당 호출 4.3, 호출당 출력 1,400. 이번에 바꿀 파일 약 120(하위 문서 이동 28, 새 CLAUDE.md 32, 문서의 AGENTS.md 참조 93줄, 검사기 2, 훅 6, 시험 3, Java 테스트 3, 에이전트·스킬·규칙 8), 매뉴얼 항목 약 60(선례 manual-gap-fix-2가 52건을 한 세션에), desktop 대기 30~50분"} diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index d9a91804..e6f68de7 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -17,3 +17,4 @@ | 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 | | 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 | | 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 | +| 7 | 예측·실측 장부 `docs/ledger/estimates.jsonl`(형식 `docs/ledger/README.md`)을 두었다. `.gitattributes`가 이 파일에 `merge=union`을 준다 | 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다 | diff --git a/docs/work/README.md b/docs/work/README.md index 8694a08c..f90a056e 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -58,6 +58,7 @@ - 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다. - 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다. - 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. 테스트 수는 성공한 Gradle 로그에 없으니 결과 XML 사본에서 센다([reference/gates.md](reference/gates.md) 4절). +- 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다(형식 `docs/ledger/README.md`). - 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 3절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다. ## 7. 필요할 때만 읽는 문서 diff --git a/docs/work/delegate.md b/docs/work/delegate.md index e48ee7bc..fadabd29 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -30,6 +30,8 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 이 repo에서 더할 것: +- 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)는 하위 세션이 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. 위임 장부 줄은 그 `task`를 가리킨다. + - brief의 「작업 종류」는 이 repo의 `docs/work/<종류>.md`다. 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 검증 명령은 [reference/gates.md](reference/gates.md)와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다. - 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다. - 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸과 「정한 기본값」부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」와 README 남은 항목을 다시 판정시킬지도 적는다. diff --git a/scripts/tests/test_ledger.py b/scripts/tests/test_ledger.py new file mode 100644 index 00000000..8d868a5e --- /dev/null +++ b/scripts/tests/test_ledger.py @@ -0,0 +1,53 @@ +"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import json +import unittest +from datetime import datetime +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent.parent +LEDGER = REPO / "docs/ledger/estimates.jsonl" +KINDS = {"estimate", "actual", "retro"} +COMMON = ("schema", "kind", "task", "recorded_at") +RANGES = ("minutes", "calls", "output_tokens") + + +def lines() -> list[dict]: + return [json.loads(line) for line in LEDGER.read_text(encoding="utf-8").splitlines() if line.strip()] + + +class LedgerTest(unittest.TestCase): + def test_every_line_is_json_with_the_common_fields(self) -> None: + for number, entry in enumerate(lines(), start=1): + self.assertTrue(set(COMMON) <= entry.keys(), f"line {number}: {sorted(set(COMMON) - entry.keys())}") + self.assertEqual(entry["schema"], 1, number) + self.assertIn(entry["kind"], KINDS, number) + datetime.fromisoformat(entry["recorded_at"]) + + def test_an_estimate_has_ordered_ranges_and_a_basis(self) -> None: + for entry in (e for e in lines() if e["kind"] == "estimate"): + for field in RANGES: + values = entry[field] + self.assertLessEqual(values["p30"], values["p50"], (entry["task"], field)) + self.assertLessEqual(values["p50"], values["p80"], (entry["task"], field)) + self.assertTrue(entry["basis"].strip(), entry["task"]) + + def test_an_actual_follows_its_estimate_and_names_the_band_it_fell_in(self) -> None: + entries = lines() + for position, entry in enumerate(entries): + if entry["kind"] != "actual": + continue + estimates = [e for e in entries[:position] if e["kind"] == "estimate" and e["task"] == entry["task"]] + self.assertTrue(estimates, f"{entry['task']}: an actual line needs an earlier estimate line") + bands = estimates[-1]["minutes"] + expected = next((band for band in ("p30", "p50", "p80") if entry["active_minutes"] <= bands[band]), "over") + self.assertEqual(entry["within"], expected, entry["task"]) + + +if __name__ == "__main__": + unittest.main() -- 2.54.0 From 59dff0041c525e9c9409b37e48f8f94ffbc7d950 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:20:18 +0900 Subject: [PATCH 07/12] =?UTF-8?q?ci(docs):=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EA=B2=80=EC=82=AC=EC=97=90=20=EB=AC=B8=EC=B2=B4=EB=A5=BC=20?= =?UTF-8?q?=EB=8D=94=ED=95=98=EA=B3=A0=20=EB=B2=88=EC=97=AD=ED=95=9C=20?= =?UTF-8?q?=EA=B2=B0=EC=A0=95=20=EA=B8=B0=EB=A1=9D=EC=9D=98=20=EB=A8=B8?= =?UTF-8?q?=EB=A6=AC=20=EB=AC=B8=EA=B5=AC=EB=A5=BC=20=EB=A7=9E=EC=B6=98?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만 지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다. 그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데, 2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다. - check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다· 입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드, 따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다. - runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가 울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다. - 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명, docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안). - docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고, 링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs docs-system.md 6.2절 다섯 칸)을 더했다. 버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다). 위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo 밖이라 고치지 않았다(총괄에게 알린다). 검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함), check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시 worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건, 1건 실패했다. --- docs/README.md | 18 +++++-- ...001-one-convention-for-shared-test-code.md | 2 +- ...1-graphql-context-and-storage-ownership.md | 2 +- ...-001-platform-family-and-registry-shape.md | 2 +- ...PC-002-schema-governance-without-protoc.md | 2 +- ...-GRPC-003-three-axis-execution-evidence.md | 2 +- ...retry-ownership-and-durable-idempotency.md | 2 +- ...rver-streaming-single-writer-and-resume.md | 2 +- ...stable-discovery-and-kubernetes-routing.md | 2 +- ...-capability-promotion-is-per-capability.md | 2 +- ...R-JPA-001-domain-owns-persistence-model.md | 2 +- .../adr/ADR-JPA-002-full-transaction-retry.md | 2 +- docs/adr/ADR-JPA-003-completion-unknown.md | 2 +- ...R-JPA-004-flyway-schema-source-of-truth.md | 2 +- .../ADR-JPA-005-postgresql-real-contract.md | 2 +- .../ADR-JPA-006-canonical-technical-audit.md | 2 +- docs/adr/ADR-MONGO-001-platform-boundary.md | 2 +- docs/adr/ADR-MONGO-002-bson-representation.md | 2 +- docs/adr/ADR-MONGO-003-transaction-retry.md | 2 +- .../ADR-MONGO-004-index-schema-admin-plane.md | 2 +- .../ADR-MONGO-ADV-001-capability-promotion.md | 2 +- ...-WEB-ADV-001-streaming-is-live-delivery.md | 2 +- ...virtual-threads-do-not-remove-admission.md | 2 +- ...ADV-003-openapi-32-remains-experimental.md | 2 +- ...platform-as-packages-and-its-boundaries.md | 2 +- docs/adr/ADR-WS-002-resume-and-cluster.md | 2 +- docs/adr/ADR-WS-003-stomp-and-broker-relay.md | 2 +- docs/adr/NOTIF-ADR-001-durable-acceptance.md | 2 +- .../NOTIF-ADR-002-event-ledger-projection.md | 2 +- .../adr/NOTIF-ADR-003-ambiguous-submission.md | 2 +- docs/adr/NOTIF-ADR-004-fcm-fid-primary.md | 2 +- docs/adr/NOTIF-ADR-005-canonical-namespace.md | 2 +- docs/runbooks/auth-token-rotation-failure.md | 2 +- docs/runbooks/authz-cross-tenant-violation.md | 2 +- docs/runbooks/dependency-unavailable.md | 2 +- docs/runbooks/internal-error-spike.md | 2 +- docs/runbooks/job-dead-letter.md | 2 +- docs/runbooks/job-executor-rejected.md | 2 +- docs/runbooks/job-timeout.md | 2 +- docs/runbooks/outbox-dead-letter.md | 2 +- docs/runbooks/outbox-publish-failed.md | 2 +- docs/runbooks/rate-limit-exceeded.md | 2 +- scripts/check-docs.py | 49 +++++++++++++++++-- scripts/tests/test_check_docs.py | 26 ++++++++++ 44 files changed, 128 insertions(+), 47 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0a204bd6..82879364 100644 --- a/docs/README.md +++ b/docs/README.md @@ -140,7 +140,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 - 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서, `history/evidence/`·`history/plans/evidence/` 증거, `history/packages/` 납품 패키지, `history/study/` 학습 문서. ADR의 둘째 줄은 - `> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다. + `> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다. - 상태는 종류마다 고정 어휘다. | 종류 | 상태 | @@ -159,6 +159,16 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 `capability-status.md` 「제거된 코드」로 지운 것이 확인된 설계서 다섯은 「폐기」다. - 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다. +## 모듈 README + +leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것(정본은 design-docs `conventions/docs-system.md` 6.2절): + +1. 책임 한 문장과 소유하지 않는 것 +2. 공개 표면(포트·API·설정 prefix) +3. 조립: 더할 한 줄, 끄는 키, 필요한 env 키 +4. 테스트: registry의 Gradle 경로로 만든 명령(숫자·버전을 복사하지 않는다) +5. 더 읽을 곳: 그 폴더의 `AGENTS.md`(지역 규칙), 영역 운영 문서 + ## 문서와 코드를 같은 변경에서 고친다 - 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: @@ -173,7 +183,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 ## 문서 검사 -`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여섯을 본다. PR마다 workflow `docs-check`가 +`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow `docs-check`가 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 문서를 낡게 만든다. @@ -185,6 +195,8 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | +| `link` | 살아 있는 문서의 상대 링크(`[글](경로)`)가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 | +| `style` | 살아 있는 문서의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안의 인용은 보지 않는다 | - 하나만 돌리기: `python3 scripts/check-docs.py --only head`. - 소스 세트의 resources 폴더 아래 `.md`(`src/**/src/<세트>/resources/`)는 테스트가 읽는 입력이라 문서로 보지 않는다. @@ -194,7 +206,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 - 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은 지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다. - 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`. -- 마크다운 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. +- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`link-check` workflow)가 본다. 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다. ## 여기에 없는 것 diff --git a/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md b/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md index e2292be7..dce3295c 100644 --- a/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md +++ b/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-09-07 diff --git a/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md b/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md index d228397c..51de206f 100644 --- a/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md +++ b/docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-24 diff --git a/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md b/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md index 617992bf..540cbaa0 100644 --- a/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md +++ b/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-30 diff --git a/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md b/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md index 67320b8e..b0a745c8 100644 --- a/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md +++ b/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 대체됨 - 작성일: 2026-08-30 diff --git a/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md b/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md index c40c9fd9..2caa19dd 100644 --- a/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md +++ b/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-30 diff --git a/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md b/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md index f86b2b31..9e2f827c 100644 --- a/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md +++ b/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-30 diff --git a/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md b/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md index a210de5d..e6661771 100644 --- a/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md +++ b/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-30 diff --git a/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md b/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md index c58764b0..ec3ebf71 100644 --- a/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md +++ b/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-31 diff --git a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md index 07decf9c..eeea17b6 100644 --- a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md +++ b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-30 diff --git a/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md b/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md index 65d7427e..a53a87a2 100644 --- a/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md +++ b/docs/adr/ADR-JPA-001-domain-owns-persistence-model.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-11 diff --git a/docs/adr/ADR-JPA-002-full-transaction-retry.md b/docs/adr/ADR-JPA-002-full-transaction-retry.md index fb5f1e36..cfbe6f33 100644 --- a/docs/adr/ADR-JPA-002-full-transaction-retry.md +++ b/docs/adr/ADR-JPA-002-full-transaction-retry.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 대체됨 - 작성일: 2026-08-11 diff --git a/docs/adr/ADR-JPA-003-completion-unknown.md b/docs/adr/ADR-JPA-003-completion-unknown.md index eef2a271..f4a4dcd3 100644 --- a/docs/adr/ADR-JPA-003-completion-unknown.md +++ b/docs/adr/ADR-JPA-003-completion-unknown.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택(보완) - 작성일: 2026-08-11 diff --git a/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md b/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md index fbd69256..dbdebcc0 100644 --- a/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md +++ b/docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-11 diff --git a/docs/adr/ADR-JPA-005-postgresql-real-contract.md b/docs/adr/ADR-JPA-005-postgresql-real-contract.md index 26223db6..629e43f0 100644 --- a/docs/adr/ADR-JPA-005-postgresql-real-contract.md +++ b/docs/adr/ADR-JPA-005-postgresql-real-contract.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-11 diff --git a/docs/adr/ADR-JPA-006-canonical-technical-audit.md b/docs/adr/ADR-JPA-006-canonical-technical-audit.md index 476d9ce3..a955c616 100644 --- a/docs/adr/ADR-JPA-006-canonical-technical-audit.md +++ b/docs/adr/ADR-JPA-006-canonical-technical-audit.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-24 diff --git a/docs/adr/ADR-MONGO-001-platform-boundary.md b/docs/adr/ADR-MONGO-001-platform-boundary.md index 7da70fc2..ea91488c 100644 --- a/docs/adr/ADR-MONGO-001-platform-boundary.md +++ b/docs/adr/ADR-MONGO-001-platform-boundary.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-13 diff --git a/docs/adr/ADR-MONGO-002-bson-representation.md b/docs/adr/ADR-MONGO-002-bson-representation.md index a53a5915..c5bac280 100644 --- a/docs/adr/ADR-MONGO-002-bson-representation.md +++ b/docs/adr/ADR-MONGO-002-bson-representation.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-13 diff --git a/docs/adr/ADR-MONGO-003-transaction-retry.md b/docs/adr/ADR-MONGO-003-transaction-retry.md index ec655164..fbdb3641 100644 --- a/docs/adr/ADR-MONGO-003-transaction-retry.md +++ b/docs/adr/ADR-MONGO-003-transaction-retry.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-13 diff --git a/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md b/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md index f26ca08d..45c0430d 100644 --- a/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md +++ b/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-13 diff --git a/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md b/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md index 1ac930b9..8acaafbe 100644 --- a/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md +++ b/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택(보완) - 작성일: 2026-08-13 diff --git a/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md b/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md index d83135de..7de79933 100644 --- a/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md +++ b/docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-25 diff --git a/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md b/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md index 4f3a9397..fd17c4da 100644 --- a/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md +++ b/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-25 diff --git a/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md b/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md index 32782c1e..09ebffbb 100644 --- a/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md +++ b/docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-25 diff --git a/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md b/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md index 81465281..1c61f635 100644 --- a/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md +++ b/docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 대체됨 - 작성일: 2026-08-25 diff --git a/docs/adr/ADR-WS-002-resume-and-cluster.md b/docs/adr/ADR-WS-002-resume-and-cluster.md index 30ad5578..61ba4b48 100644 --- a/docs/adr/ADR-WS-002-resume-and-cluster.md +++ b/docs/adr/ADR-WS-002-resume-and-cluster.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 대체됨 - 작성일: 2026-08-25 diff --git a/docs/adr/ADR-WS-003-stomp-and-broker-relay.md b/docs/adr/ADR-WS-003-stomp-and-broker-relay.md index b87857ec..15739326 100644 --- a/docs/adr/ADR-WS-003-stomp-and-broker-relay.md +++ b/docs/adr/ADR-WS-003-stomp-and-broker-relay.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 대체됨 - 작성일: 2026-08-25 diff --git a/docs/adr/NOTIF-ADR-001-durable-acceptance.md b/docs/adr/NOTIF-ADR-001-durable-acceptance.md index de2293f7..bb096b79 100644 --- a/docs/adr/NOTIF-ADR-001-durable-acceptance.md +++ b/docs/adr/NOTIF-ADR-001-durable-acceptance.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-14 diff --git a/docs/adr/NOTIF-ADR-002-event-ledger-projection.md b/docs/adr/NOTIF-ADR-002-event-ledger-projection.md index bcbf6ada..8e25e6a3 100644 --- a/docs/adr/NOTIF-ADR-002-event-ledger-projection.md +++ b/docs/adr/NOTIF-ADR-002-event-ledger-projection.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-14 diff --git a/docs/adr/NOTIF-ADR-003-ambiguous-submission.md b/docs/adr/NOTIF-ADR-003-ambiguous-submission.md index 08bf8113..1304212f 100644 --- a/docs/adr/NOTIF-ADR-003-ambiguous-submission.md +++ b/docs/adr/NOTIF-ADR-003-ambiguous-submission.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-14 diff --git a/docs/adr/NOTIF-ADR-004-fcm-fid-primary.md b/docs/adr/NOTIF-ADR-004-fcm-fid-primary.md index 4a885de3..d0af8e58 100644 --- a/docs/adr/NOTIF-ADR-004-fcm-fid-primary.md +++ b/docs/adr/NOTIF-ADR-004-fcm-fid-primary.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-14 diff --git a/docs/adr/NOTIF-ADR-005-canonical-namespace.md b/docs/adr/NOTIF-ADR-005-canonical-namespace.md index a6b6e491..eacf2386 100644 --- a/docs/adr/NOTIF-ADR-005-canonical-namespace.md +++ b/docs/adr/NOTIF-ADR-005-canonical-namespace.md @@ -1,5 +1,5 @@ -> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. +> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택(보완) - 작성일: 2026-08-15 diff --git a/docs/runbooks/auth-token-rotation-failure.md b/docs/runbooks/auth-token-rotation-failure.md index 90564407..1290ffe5 100644 --- a/docs/runbooks/auth-token-rotation-failure.md +++ b/docs/runbooks/auth-token-rotation-failure.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `auth_401_error_rate_high` 또는 `jwks_refresh_failure_spike` - alert payload 필수 field: `operation`, `error.code`, `error.category`, `runbook_link`, `dependency_name` diff --git a/docs/runbooks/authz-cross-tenant-violation.md b/docs/runbooks/authz-cross-tenant-violation.md index 8aec86c6..5ef14248 100644 --- a/docs/runbooks/authz-cross-tenant-violation.md +++ b/docs/runbooks/authz-cross-tenant-violation.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `authz_cross_tenant_violation` 또는 `authz_403_spike` - alert payload 필수 field: `operation`, `error.code`, `error.category`, `principal_id_pseudonymized`, `tenant_id`, `runbook_link` diff --git a/docs/runbooks/dependency-unavailable.md b/docs/runbooks/dependency-unavailable.md index a8d21080..f207c45c 100644 --- a/docs/runbooks/dependency-unavailable.md +++ b/docs/runbooks/dependency-unavailable.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `dependency_error_rate_critical` 또는 `circuit_breaker_open` - alert payload 필수 field: `operation`, `error.code`, `error.category`, `dependency_name`, `dependency_kind`(required|optional), `runbook_link` diff --git a/docs/runbooks/internal-error-spike.md b/docs/runbooks/internal-error-spike.md index 83e6d561..2822a4ab 100644 --- a/docs/runbooks/internal-error-spike.md +++ b/docs/runbooks/internal-error-spike.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `http_5xx_error_rate_critical` - alert payload 필수 field: `operation`, `error.code`, `error.category`, `request_id`, `traceId`, `runbook_link` diff --git a/docs/runbooks/job-dead-letter.md b/docs/runbooks/job-dead-letter.md index 38faf6c3..1ea39f43 100644 --- a/docs/runbooks/job-dead-letter.md +++ b/docs/runbooks/job-dead-letter.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `job_dead_letter` - alert payload 필수 field: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`, `runbook_link` diff --git a/docs/runbooks/job-executor-rejected.md b/docs/runbooks/job-executor-rejected.md index ea9fa91d..0424c44e 100644 --- a/docs/runbooks/job-executor-rejected.md +++ b/docs/runbooks/job-executor-rejected.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `executor_rejected` - alert payload 필수 field: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`, `runbook_link` diff --git a/docs/runbooks/job-timeout.md b/docs/runbooks/job-timeout.md index dafd084b..fe049126 100644 --- a/docs/runbooks/job-timeout.md +++ b/docs/runbooks/job-timeout.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `job_timeout` - alert payload 필수 field: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`, `runbook_link` diff --git a/docs/runbooks/outbox-dead-letter.md b/docs/runbooks/outbox-dead-letter.md index c42fdda9..1189736b 100644 --- a/docs/runbooks/outbox-dead-letter.md +++ b/docs/runbooks/outbox-dead-letter.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `outbox_dead_letter` - alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link` diff --git a/docs/runbooks/outbox-publish-failed.md b/docs/runbooks/outbox-publish-failed.md index fd6d7491..0f29b13b 100644 --- a/docs/runbooks/outbox-publish-failed.md +++ b/docs/runbooks/outbox-publish-failed.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long` - alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link` diff --git a/docs/runbooks/rate-limit-exceeded.md b/docs/runbooks/rate-limit-exceeded.md index 225512a1..05cc641a 100644 --- a/docs/runbooks/rate-limit-exceeded.md +++ b/docs/runbooks/rate-limit-exceeded.md @@ -12,7 +12,7 @@ status: 초안 ## 1. Trigger -이 runbook은 다음 alert에서 발동됩니다. +이 runbook은 다음 alert가 울리면 쓴다. - alert name: `rate_limit_429_high` - alert payload 필수 field: `operation`, `error.code`, `error.category`, `rate_limit_key_type`(ip|principal|tenant), `runbook_link` diff --git a/scripts/check-docs.py b/scripts/check-docs.py index a7708bda..36c123e9 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -61,7 +61,7 @@ from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt" REGISTRY_FILE = "src/config/architecture/modules.json" -CHECKS = ("language", "head", "reference", "number", "map", "readme", "link") +CHECKS = ("language", "head", "reference", "number", "map", "readme", "link", "style") # 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다. RECORD_KINDS = [ @@ -91,7 +91,7 @@ STATUS = { HEAD_START = "" HEAD_END = "" RECORD_LABEL = "> **기록 · {kind}** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다." -DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다." +DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다." HEAD_FIELDS = ("상태", "작성일", "요약", "현재 정본") HEAD_OPTIONAL = ("대체", "대체됨") HEAD_SEARCH_LINES = 20 @@ -152,6 +152,9 @@ LINK_TEXT = re.compile(r"\[([^\]\n]*)\]\([^)\s]*\)") # 정해진 경로만 보고, 그 밖의 문서(`src/**/AGENTS.md`, `.claude/**`, 루트 `AGENTS.md`)의 상대 링크는 이 검사만 본다. LINK_TARGET = re.compile(r"\[[^\]\n]*\]\(([^)\s]+)\)") URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I) +# 문체: 살아 있는 문서는 「~한다」로 쓴다(docs/README.md 「문서 수명과 언어」). 높임 문장 끝을 잡는다. +CORNER_QUOTED = re.compile(r"「[^」\n]*」") +POLITE = re.compile(r"(?:습니다|합니다|입니다|됩니다|십시오|하세요|주세요)(?=[.!?)\]」\s]|$)") @dataclass(frozen=True) @@ -414,6 +417,45 @@ def check_link(root: Path, files: list[str]) -> list[Problem]: return problems +def prose_lines(lines: list[str]) -> list[tuple[int, str]]: + """(줄 번호, 인라인 코드를 뺀 줄) — 코드 블록과 「이력」 인용 블록 밖에서만.""" + kept, fence, history = [], None, False + for number, line in enumerate(lines, start=1): + match = FENCE.match(line) + if fence: + if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence): + fence = None + continue + if match: + fence = match.group(1) + continue + quoted = line.lstrip().startswith(">") + if quoted and HISTORY_QUOTE.match(line): + history = True + elif not quoted: + history = False + if not history: + kept.append((number, INLINE.sub("", line))) + return kept + + +def check_style(root: Path, files: list[str]) -> list[Problem]: + problems = [] + for path in files: + if not is_living(path): + continue + text = (root / path).read_text(encoding="utf-8") + lines = body_lines(text) + offset = len(text.split("\n")) - len(lines) + for number, line in prose_lines(lines): + # 「~합니다」처럼 낫표나 따옴표 안의 말은 이 문서의 문장이 아니라 인용이다. + found = POLITE.search(CORNER_QUOTED.sub("", QUOTED.sub("", line))) + if found: + problems.append(Problem("style", path, line.strip()[:80], f"높임 문체다(「~한다」로 쓴다): …{found.group(0)}", + number + offset)) + return problems + + def registry_projects(root: Path) -> set[str]: registry = root / REGISTRY_FILE if not registry.is_file(): @@ -681,7 +723,8 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]: RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number, - "map": check_map, "readme": check_readme, "link": check_link} + "map": check_map, "readme": check_readme, "link": check_link, + "style": check_style} def read_exceptions(text: str) -> list[str]: diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index 17dd28d0..7e54169a 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -471,6 +471,32 @@ class LinkTest(RepositoryTestCase): self.assertEqual(self.repo.run(("link",)), []) +class StyleTest(RepositoryTestCase): + def errors_for(self, text: str, path: str = "docs/guide.md") -> list[str]: + self.repo.write(path, KOREAN + text) + return self.repo.run(("style",)) + + def test_a_polite_sentence_fails(self) -> None: + self.assertFailsWith(self.errors_for("이 runbook은 다음 alert에서 발동됩니다.\n"), "높임 문체다") + + def test_a_polite_request_at_the_end_of_a_line_fails(self) -> None: + self.assertFailsWith(self.errors_for("- 설정을 바꾼 뒤 다시 실행하세요\n"), "…하세요") + + def test_the_plain_style_passes(self) -> None: + self.assertEqual(self.errors_for("이 runbook은 다음 alert가 울리면 쓴다.\n"), []) + + def test_quoted_code_and_history_mentions_are_skipped(self) -> None: + text = ("문체는 「~한다」다. 「~합니다」와 섞지 않는다.\n" + "응답 본문은 \"요청을 처리할 수 없습니다.\"다. `처리합니다.`는 코드다.\n" + "```json\n{\"message\": \"처리할 수 없습니다.\"}\n```\n" + "> 이력: 이 문서는 예전에 「~합니다」로 썼습니다.\n") + self.assertEqual(self.errors_for(text), []) + + def test_a_record_is_not_checked(self) -> None: + self.repo.write("docs/design/2026-08-11-x-design.md", head() + "이 설계는 채택되었습니다.\n") + self.assertEqual(self.repo.run(("style",)), []) + + class CommandLineTest(unittest.TestCase): def test_an_unknown_check_is_a_usage_error(self) -> None: self.assertEqual(check_docs.main(["--only", "spelling"]), 2) -- 2.54.0 From c8db79a78fb5c7ba1357f9f7f322a9ed5c4fa936 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:20:38 +0900 Subject: [PATCH 08/12] =?UTF-8?q?docs(work):=20=EC=8C=93=EC=9D=B8=20?= =?UTF-8?q?=EB=A7=A4=EB=89=B4=EC=96=BC=20=EB=B9=88=ED=8B=88=EA=B3=BC=20?= =?UTF-8?q?=EC=A1=B0=EC=82=AC=20=EB=AC=B8=EC=84=9C=EC=9D=98=20=EB=A7=A4?= =?UTF-8?q?=EB=89=B4=EC=96=BC=20=EA=B7=9C=EC=B9=99=EC=9D=84=20=ED=95=9C=20?= =?UTF-8?q?=EB=AC=B6=EC=9D=8C=EC=9C=BC=EB=A1=9C=20=EB=84=A3=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이 「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에 없다. 세션마다 같은 판단을 스스로 다시 했다. 넣은 자리(항목별 표는 PR 본문): - delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드 연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌 없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로). - improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다, 그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로. - docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다, 이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml, 머리말 없는 runbook, MANIFEST는 납품 당시 해시). - operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1, 12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에. - reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패, lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음, 원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거 실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e), 새 7절 「workflow·검사 스크립트를 더할 때」. - reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함, Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사). - reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값. - reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻. - README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는 leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check· check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙. 버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음). 위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용, 병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로 상한에 가깝다. 검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0. --- .claude/rules/settings-and-runtime.md | 2 +- docs/ci-cd/template-vs-consumer.md | 3 +++ docs/work/README.md | 3 ++- docs/work/delegate.md | 6 ++++- docs/work/docs-writing.md | 16 +++++++++---- docs/work/improve.md | 7 +++--- docs/work/new-feature.md | 1 + docs/work/operate.md | 6 +++-- docs/work/reference/decisions.md | 4 ++-- docs/work/reference/gates.md | 32 ++++++++++++++++++++++---- docs/work/reference/review-criteria.md | 25 ++++++++++---------- docs/work/reference/terms.md | 25 ++++++++++++++++++++ 12 files changed, 99 insertions(+), 31 deletions(-) create mode 100644 docs/work/reference/terms.md diff --git a/.claude/rules/settings-and-runtime.md b/.claude/rules/settings-and-runtime.md index 861e9cae..8610ae5d 100644 --- a/.claude/rules/settings-and-runtime.md +++ b/.claude/rules/settings-and-runtime.md @@ -30,5 +30,5 @@ paths: - `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다. - container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다. -- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다. 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`). +- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다(「개발 환경」과 lane overlay의 차이는 `docs/work/reference/terms.md`). 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`). - Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절). diff --git a/docs/ci-cd/template-vs-consumer.md b/docs/ci-cd/template-vs-consumer.md index 715189bc..cd0bf320 100644 --- a/docs/ci-cd/template-vs-consumer.md +++ b/docs/ci-cd/template-vs-consumer.md @@ -32,6 +32,9 @@ | `dependency-vulnerability.yml` | dependency-review + Trivy | | `ci-quality-gates.yml` | PR 게이트 | | `release.yml` | 이미지 · SBOM 생산 | +| `docs-check.yml` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) | +| `link-check.yml` | 문서의 외부 URL과 상대 링크(lychee) | +| `scripts/check-repo-layout.py`(`ci-quality-gates.yml` 안) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 | | action의 full SHA 핀 | 공급망 | ## 파생 프로젝트가 할 일 diff --git a/docs/work/README.md b/docs/work/README.md index f90a056e..f770bacd 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -24,7 +24,7 @@ - brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. - brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다. - 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다. -- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책. +- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 저장소 루트나 `src/` 최상위에 폴더를 새로 만들거나 옮기는 일, 보안 정책. - 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다. ## 3. 모든 작업의 공통 단계 @@ -69,6 +69,7 @@ | [reference/review-criteria.md](reference/review-criteria.md) | 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식 | | [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 | | [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법 | +| [reference/terms.md](reference/terms.md) | 영어 그대로 쓰는 말과 정한 표기의 뜻 | | [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID | ## 8. 이 폴더를 고칠 때 diff --git a/docs/work/delegate.md b/docs/work/delegate.md index fadabd29..40716eff 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -63,7 +63,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | 파일 | 왜 | | --- | --- | -| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹친다 | +| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹치고, 머리 「커밋:」 줄을 여럿이 고치면 충돌한다. 묶음은 「커밋:」 줄을 고치지 않고 보고에 커밋을 적는다. 총괄이 합칠 때 한 번에 적는다 | | `docs/reviews/<폴더>/README.md` | 처리 표·결정의 답·게이트 기록·남은 것은 총괄이 쓴다. 리뷰어는 자기 라운드 색인 절 하나만 쓴다([improve.md](improve.md) 4.1절 7단계) | | `src/config/architecture/modules.json`, `src/settings.gradle` | registry 하나가 모든 leaf를 정한다 | | `src/gradle/libs.versions.toml`, lockfile | 의존성을 바꾸면 lockfile 전체가 바뀐다 | @@ -80,6 +80,8 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - 묶음 크기 상한을 지킨다([improve.md](improve.md) 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하). - 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다. - 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. +- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 다음 묶음은 수정이 아니라 「이 장치가 필요한가, 형식을 좁혀 없앨 수 있나」를 보는 조사([research-design.md](research-design.md))로 맡긴다. +- 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 병합 뒤 따로 커밋한다. 병합 커밋에는 충돌 해결만 둔다. - 합칠 때는 하위 브랜치를 모아 [reference/gates.md](reference/gates.md) 3절 묶음을 돌린다. 합치기와 그 게이트도 하위 세션에 맡길 수 있다. ### 4.3 소유자 환경 @@ -125,3 +127,5 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다. - 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다. - 같은 범위를 두 리뷰에 따로 맡기고(비교 시험 등) ID를 매길 쪽을 정하지 않아, 같은 ID가 다른 결함을 가리킨다. brief에 ID를 매길 리뷰 하나를 정한다(규칙은 [reference/review-criteria.md](reference/review-criteria.md) 10절 「ID」). +- brief에 「다른 PR과 충돌 없음」을 대상 파일 몇 개만 비교해 적는다. 쓰려면 바뀌는 모든 파일을 `git merge-tree --write-tree <브랜치 A> <브랜치 B>`로 본다. +- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아, 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos///pulls?state=all`)로 먼저 본다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md index df4c0fe5..844d18d2 100644 --- a/docs/work/docs-writing.md +++ b/docs/work/docs-writing.md @@ -30,18 +30,24 @@ 1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다". 2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. 3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. -4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. +4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 문체는 「~한다」다. 높임 문장은 `check-docs.py` `style`이 막는다. 용어는 [reference/terms.md](reference/terms.md)의 표기를 쓰고, 새 용어를 정하면 거기에 더한다. 언어 규칙(`docs/README.md` 「문서 수명과 언어」)은 문서(`.md`)에 걸린다. 코드 주석·Javadoc은 그 파일이 쓰는 언어를 따른다. 5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다. 6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 걷어낸 문서 묶음(예: `docs/manual/`, 진입 문서)마다 절 하나를 두고, 같은 묶음을 다시 걷어내면 그 절에 표를 더한다. ID가 무엇을 가리키는지는 evidence.md 머리말 「표기」로 찾는다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다. 7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. 8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. 9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다). -10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. +10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. 어느 문서든 바꿨으면 `python3 scripts/check-docs.py`도 돌린다(언어, 머리 블록, 참조, 복사한 숫자, 문서 지도, 상대 링크, 문체). 11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`. - 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다. - 기본 검사를 넓히는 커밋은 그 검사가 새로 잡는 문서를 고친 커밋 뒤에 둔다(또는 같은 커밋). 그래야 어느 커밋에서도 기본 모드가 rc=0이다. -13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다. +13. 파일·폴더를 옮기는 커밋에는 옮긴 경로를 가리키는 참조 수정(문서 링크, 테스트가 읽는 경로)을 같이 넣는다. 그래야 커밋마다 검사가 통과한다. 내용 수정은 다음 커밋으로 나눈다. 같은 이름의 새 파일이 옛 자리에 생기면 git이 이동으로 잡지 못하니 커밋 본문에 옛 이력을 보는 법을 적는다. +14. 옮겨 쓰는(번역하는) 문서의 기준: + - 코드·다른 문서가 영어 절 제목으로 인용하는 절은 제목을 「한국어 (English)」로 둔다. 그 제목을 글자로 비교하는 테스트가 있으면 같은 변경에서 고친다. + - 레지스트리 yaml(`docs/registries/`)은 값 칸·머리 설명·행별 설명 주석을 한국어로 옮긴다. 출처 줄, 인용, 테스트가 글자로 비교하는 줄은 원문으로 둔다. + - 머리말(`docs/runbooks/template.md`의 front matter)이 없는 runbook에 머리말을 새로 만들지 않는다. `error_codes`·`severity`를 채우는 것은 새 결정이라 그 runbook을 맡은 작업에서 한다. + - 납품 묶음의 해시 목록(`MANIFEST.sha256`)은 납품 당시 바이트의 해시다(`docs/README.md`). 머리 블록을 달거나 번역해 지금 바이트와 맞지 않게 돼도 목록을 고치지 않고, 지금 파일을 맞춰 보는 검사로 쓰지 않는다. +15. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다. **playbook을 새로 만들 때의 뼈대** (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다): @@ -52,7 +58,7 @@ - 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다. - 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다. - 정본을 복사한 문장이 없다. 가리키는 줄만 있다. -- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. +- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. 어느 문서든 `scripts/check-docs.py`가 rc=0이다. - 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그). - 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다. @@ -74,7 +80,7 @@ [README](README.md) 6절에 더해 적는다. - 바꾼 문서와 줄 수, 분량 상한 대비. -- 검사 결과: `check-work-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로. +- 검사 결과: `check-work-docs.py`, `check-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로. - cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것. - 정본과 다른 곳을 찾았으면 그 위치. diff --git a/docs/work/improve.md b/docs/work/improve.md index ab77a9de..c1710cc7 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -58,13 +58,13 @@ 1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다. 2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지가 그 결함을 말해야 한다. 컴파일 오류나 준비 실패는 RED가 아니다. 3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다. RED용 임시 파일은 테스트든 main 리소스(임시 마이그레이션 등)든 그 worktree에만 둔다. - - RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다. + - RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 절차 문서(runbook)의 결함이면 기준 문서의 단계를 그대로 따르는 임시 테스트를 기준 커밋에 얹어 실패를 보이고, 최종 테스트는 새 단계를 따르게 한다. 한 단계가 다른 단계를 기다려 막히는 결함은 시간 제한으로 끊는 도우미로 "기다렸다"를 실행으로 보인다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다. 4. 가장 작은 수정으로 GREEN을 본다. 5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. 찾은 자리가 brief 영역 안이고 공개 동작이 바뀌지 않으면 함께 고치고 보고에 적는다. 공개 동작이 바뀌거나 brief 영역 밖이면 고치지 않고 「범위 밖에서 본 것」에 권하는 안과 함께 적는다. 묶음 상한(4.4절)도 지킨다. -6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. +6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. 넘겨받은 발견이 테스트 Javadoc·주석이어도 고친다(동작이 바뀌지 않으면 "RED 없음 — 이유"). 7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다). - 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다. -8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). +8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). registry는 lane을 모른다. 그 lane은 바꾼 클래스·기능 이름으로 leaf `build.gradle`의 `strictTestLanes` 블록과 lane source set(`src//`)의 테스트를 grep해 찾는다. brief의 lane 목록에 없는 lane이 걸리면 그것도 돌리고 보고에 적는다. ### 4.3 리팩터링, 성능, 구조, 테스트 구조 @@ -118,6 +118,7 @@ - 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다. 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이라 묻지 않는다(4.2절 7단계의 안내 행은 적는다). 약속한 곳끼리 다르면 셋째 줄대로 한다. - RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다. +- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 그 다음은 수정이 아니라 [research-design.md](research-design.md)로 "이 장치가 필요한가, 형식을 좁혀 없앨 수 있나"를 먼저 본다. - 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다. ## 8. 보고 형식 diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 04e39663..5ff0fde4 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -56,6 +56,7 @@ - 저장 adapter를 `persistence-jpa` leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다. - 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절). - bootstrap에 capability 이름·스위치 목록·scan 정규식을 넣지 않는다. 모듈이 자기 `AutoConfiguration.imports`로 켜진다. +- 새 capability가 테스트 환경(compose, 스크립트)을 더하면 그 leaf 안에 둔다. 저장소 루트에 두지 않는다. leaf가 가진 기능 데이터(readiness card, release registry)는 그 leaf의 `release/`에 둔다. - 노트북에서 Gradle을 돌리지 않는다. ## 7. 막혔을 때 diff --git a/docs/work/operate.md b/docs/work/operate.md index 36702f19..2bc00406 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -32,6 +32,8 @@ - desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다. - desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다. - design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다. +- desktop 기본 셸은 zsh다. 파이프의 rc는 `bash -o pipefail -c '<명령> | tee <로그>'; echo "rc=$?"`로 받는다(zsh에는 `PIPESTATUS`가 없다). 자기 실행을 멈출 때는 시작할 때 남긴 PID로 `kill `를 쓴다. `pkill -f <경로>`는 그 경로가 든 ssh 명령줄 자신과도 맞아 세션을 끊는다. +- CI runner(2026-11-07): Gitea Actions가 켜졌고, desktop에 `desktop-runner` 하나(`gitea/runner` dind, `capacity: 1`, label `ubuntu-latest`)가 돈다. desktop은 12코어·31GB다. CI job은 공유 잠금을 쓰지 않으므로, 손으로 돌린 게이트가 느리면 `docker ps`로 runner job이 함께 도는지 본다. 절차: @@ -58,7 +60,7 @@ git worktree remove ~/workspace/<작업 이름> - 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절). - RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다. -- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. +- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다. - compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`. - Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다. @@ -75,7 +77,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업 - 그다음 위 3) 4)대로 돌리고 지운다. 결과를 본문에 적어 커밋한 뒤 `git rev-parse HEAD^{tree}`가 같은 해시인지 본다. 같으면 desktop이 돌린 트리가 그 커밋이다. - RED는 같은 방법으로 테스트 파일만 stage해 보낸다. 한 파일의 일부만 stage하는 법은 design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」이다. -- 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다. +- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다. ```bash ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain' diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 34e651ea..0c307a94 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -10,7 +10,7 @@ ## 1. 결정을 다시 묻지 않는 규칙 -1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다. +1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다. brief가 옮긴 내용과 원문이 다르면 원문을 따르고, 차이를 보고에 적는다(brief가 요약하며 빠뜨린 것일 수 있다). 2. 다시 열 수 있는 경우는 셋뿐이다. - 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다. - 두 결정이 서로 충돌한다. @@ -38,7 +38,7 @@ | 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`(2026-11-07부터 `src/**/AGENTS.md`, 루트 `CLAUDE.md`, `.claude/` 아래 문서). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 | | 커밋 단위 | 커밋 하나에 논리 변경 하나(`conventions/commit-and-pr.md` 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf `check`를 돌리고, 무거운 묶음은 마지막 트리에서 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 | | 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 | -| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 | +| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니라 받아도 된다(기본값 2026-11-07, 갱신 시각을 기록에 적는다) | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 | | 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 `~/.claude/CLAUDE.md` 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 | 기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「보고」 | | 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 | | 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | `1103` 16절 | diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 211a17a4..6fa6446f 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -66,6 +66,7 @@ - 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다. - strict lane에 `--tests`를 붙여 탐침만 돌려도 된다. 단 `requires`(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(`StrictTestLanePlugin`의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다. +- 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew :resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다. - 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다. **링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다): @@ -90,7 +91,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':( - 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·gRPC·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다. -**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다. +**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. workflow 명령에 그 옵션이 없어도(예: `tasks --group verification`) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다. - `mainCheck` 안의 `verifyFeatureScaffold`는 생성한 복사본에서 Gradle을 따로 띄워(`scripts/verify-feature-scaffold.sh`) 바깥의 `--no-build-cache`를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다. @@ -133,15 +134,16 @@ bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lan - `pr-adapters.yml`의 `changes` job에 있는 `emit` 줄. lane(web·websocket·httpclient·jpa)마다 정규식이고, `grep -E`로 맞춘다. 3. 걸린 workflow·job의 `run` 줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의 `docker compose … up`·`down` 단계도 같이 한다. 4. 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다. +5. 경로로 처음 켜진 lane이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 lane이 켜짐), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 lane 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다. (다) 로컬에 도구가 없는 것: | job | 로컬에서 | 대체가 못 보는 것 | | --- | --- | --- | -| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사 | 외부 URL | -| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 | +| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL | +| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf나 desktop에 이미 있는 buf 공식 이미지가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 | | `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 | -| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy가 있으면 job의 검사 줄 그대로. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) | +| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) | ## 4. 결과 기록 @@ -166,6 +168,12 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | - 같은 트리 해시에서 돈 자기 실행 로그가 있다(맡은 발견이 이미 커밋된 수정에 들어 있을 때 등). 로그에 적힌 트리 해시와 지금 트리 해시를 함께 적는다. - 트리가 다르거나 다른 세션 보고의 「통과」는 증거가 아니다(E0). 다시 돌린다. +**smoke 이미지가 이 트리에서 만들어졌음을 보이기.** smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 `CACHED`가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다. + +**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다. + +**공유 잠금 기다리기.** 순서는 `flock`이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 `ps -o pid,etime,args -C flock`으로 쥔 쪽을 보고 맡긴 쪽에 알린다([operate.md](../operate.md) 7절). + 함께 적는다: - 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다. @@ -206,5 +214,21 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | | 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) | | 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 `--no-build-cache`로 돌리고 FROM-CACHE 0을 보인다(3절) | | 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` | +| smoke rc=0인데 앱이 OOM으로 재시작함 | `scripts/run-compose-runtime-smoke.sh`가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 `restarts.txt`·`app-memory-peak-bytes.txt`를 남긴다. 그 밖의 compose 실행은 `docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>`로 본다 | +| 셸 함수·`if` 조건 안에서 `set -e`가 꺼져 중간 실패가 지나감 | 실패를 받아야 하는 명령은 `if`·`&&`·`||` 조건 밖에 두거나 rc를 직접 본다(`<명령>; rc=$?; [ "$rc" -eq 0 ] \|\| exit "$rc"`) | 게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다. + +## 7. workflow·검사 스크립트를 더할 때 + +리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다. + +1. 어느 단계인가(PR·main·nightly·release), 그리고 그 단계의 기존 workflow에 job으로 넣을 수 없는 이유를 한 줄로 쓴다. 모듈 이름의 workflow 파일은 만들지 않는다. +2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 `--dry-run` 태스크 목록으로 보인다. +3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 `run:`은 한 줄이다. +4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다. +5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다. +6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 [operate.md](../operate.md) 4.1절의 값으로 판단한다. +7. 실행 환경(Gitea)에서 돌지 않는 action·권한(`id-token`, ghcr, GitHub 의존성 그래프, `upload-artifact@v4` 이상)을 쓰지 않는다. 써야 하면 `github.server_url` 조건을 단다. +8. Gradle 밖 검사 스크립트는 `scripts/`에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `docs-check.yml`이 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다. +9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다([improve.md](../improve.md) 7절). diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index f331c4be..5d0dd5f0 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -56,7 +56,7 @@ | 등급 | 정의 | | --- | --- | | Critical | 전체 리뷰의 Critical과 같다 | -| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서 | +| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자·개발자에게 틀린 조치를 시키는 문서(예: README·`AGENTS.md`가 지운 타입을 지금 것으로 설명, 지운 설정 키를 켜라고 함) | | Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 | 확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다. @@ -101,14 +101,14 @@ | # | 관점 | 볼 곳 | 이런 증거면 결함 | | --- | --- | --- | --- | | 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 | -| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | +| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 지도에 적힌 예외 `platforms/`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 | | 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | -| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 | +| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수, 루트 README만 읽고 구조·매뉴얼·첫 실행을 5분 안에 찾는가(cold-read 결과), 이벤트별 workflow job 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음, 같은 Gradle 태스크를 두 단계 이상이 돎(의도한 행렬 제외) | | 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | | 6 | 실패 성숙도 | 예외 분류, `retryable`, 결과 불명 | 결과 불명을 확실함으로, 재시도 가능을 확정 실패로 기록 | | 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 | | 8 | 디버깅 가능성 | `ServerFailureLog`, correlation id, 오류 코드 | 서버 실패를 남기지 않음, 원인이 다른 실패를 같은 코드로 | -| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석 | 갈라진 복사본, 현재 동작과 다른 주석·문서 | +| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석, 살아 있는 문서의 표본 주장(문서 종류마다 1~2개 파일, 파일마다 주장 2~5개를 코드와 대조하고 틀린 비율을 README에 적는다), 기록 문서의 상태 칸 | 갈라진 복사본, 현재 동작과 다른 주석·문서, 코드·테스트·workflow·스크립트 어디서도 읽지 않는 비소스 파일(compose, 셸 스크립트, 설정, README. 파일마다 `git grep -l -F <경로> -- ':!docs/history' ':!docs/reviews'`가 0건. 경로를 변수로 조립하는 workflow `matrix`는 따로 본다) | | 10 | 테스트 성숙도 | 7절 | 이름의 성질을 단언하지 않음, 변이 생존, 계약 밖 fake | | 11 | 데이터 성숙도 | 마이그레이션 스트림, 유일 제약, `@Version`, 잠금 시간 제한 | 중복 규칙에 DB 제약 없음, 적용된 마이그레이션 수정, `lock_timeout` 없는 강한 잠금 | | 12 | 동시성 성숙도 | claim·lease, `SKIP LOCKED`, 트랜잭션 경계 | 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim | @@ -117,16 +117,16 @@ | 15 | 보안 성숙도 | 인증·인가 체인, `docs/security/public-paths-snapshot.txt`, `docs/registries/secrets-classification.yaml`, 로그 | 기본으로 꺼진 검증, 권한 검사 없는 경로, 로그로 새는 입력값 | | 16 | 의존성 성숙도 | `src/gradle/libs.versions.toml`, lockfile, `src/config/testing/container-images.properties` | 사라진 외부 이미지, 운영 jar의 테스트용 드라이버 | | 17 | API·계약 성숙도 | `docs/web/http-contract.md`, `docs/registries/error-codes.yaml`, `docs/architecture/*-api-surface.txt`, 짝 프론트 계약 | 코드·문서·짝 계약이 서로 다름 | -| 18 | 배포 성숙도 | `src/Dockerfile`, compose, `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서 | +| 18 | 배포 성숙도 | 저장소 루트 `compose.yaml`, `src/Dockerfile`, 테스트 lane 계약(`compose-profile-contracts.json`), `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서, README의 개발 환경 기동 명령이 실제로 뜨지 않음, 개발 환경을 띄우는 길이 둘 이상, 개발 환경 compose와 테스트 fixture가 한 파일에 섞임, Kubernetes 매니페스트·프록시 설정·IaC가 이 repo에 있음(배포 경계 `docs/ci-cd/boundary.md`) | | 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 | -| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함 | -| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 | +| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간, 빈 clone에서 README 명령만으로 개발 환경을 띄우고 내리기(compose 파일 하나), 문서 지도가 모든 문서 폴더를 덮는가(`check-docs.py` `map`), 템플릿 CI 변경이 파생 서비스 동기화에서 건드리는 파일 수 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함, 개발 환경에 compose 파일이 둘 이상 필요함 | +| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계, 편집 훅(`scripts/hooks/`), CI 실행 기록(URL) | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사, CI 최근 실행 기록이 없음(확인 못 하면 「미검증」이 아니라 결함 후보), 검사 장치가 지키는 대상보다 큼, 같은 장치에서 두 라운드 연속 결함, 개수·문서·배선 검사가 PR 단계에 있음, 실행 환경(Gitea)에서 돌지 않는 action·권한 | | 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 | -| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 | +| 23 | 일관성 | 같은 역할의 이름·모양·규칙, 문서의 언어·문체·상태 어휘(`check-docs.py` `language`·`style`·`head`) | 같은 개념이 여러 벌, 한 문서 안에서 문체가 섞임 | | 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | | 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 | -| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | -| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 | +| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README(자기 것이나 family 것) | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | +| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, 샘플·예시 모듈 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎, 매뉴얼·생성 명령이 같은 역할을 하는데 남은 샘플(그 샘플이 어떤 게이트의 유일한 검증 대상이면 그 역할과 옮길 곳이 적혀 있는지) | | 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 | **따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다. @@ -201,7 +201,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신 - 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). - 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. -- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. +- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. - source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). - 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다). - 문서 위치 규칙은 `docs/README.md`가 정본이다. @@ -212,11 +212,12 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 - [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` -- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키) +- [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키 - [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표 - [ ] ArchUnit 규칙과 그 위반·허용 fixture - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) - [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행 +- [ ] 문서를 바꿨으면 `python3 scripts/check-docs.py`와 `python3 scripts/check-work-docs.py` 검증은 [gates.md](gates.md) 2절의 "leaf 경계·의존·registry" 행이다. diff --git a/docs/work/reference/terms.md b/docs/work/reference/terms.md new file mode 100644 index 00000000..85a7a699 --- /dev/null +++ b/docs/work/reference/terms.md @@ -0,0 +1,25 @@ +# 용어 + +이 repo가 영어 그대로 쓰는 말과, 한국어로 정한 말의 뜻이다. 문서는 처음 나올 때 이 표기를 쓴다. 용어 순서(자연스러운 한국어 → 한국어(영어) → 영어 그대로)의 정본은 design-docs `conventions/docs-system.md` 3절이다. + +| 표기 | 뜻 | +| --- | --- | +| leaf | registry(`src/config/architecture/modules.json`)에 등록된 Gradle 프로젝트 하나. 경계의 단위다 | +| family | 이름 앞부분이 같은 leaf 묶음(`adapter:inbound:*`, `messaging:*`). 공통 규칙은 그 폴더의 `AGENTS.md`다 | +| registry | leaf 목록·경로·허용 의존의 정본 파일 `src/config/architecture/modules.json` | +| capability | `runtimeOnly` 한 줄로 켜고 끄는 부가 기능 모듈(`docs/manual/10-capabilities.md`) | +| 조립(composition) | 기능을 엮기만 하는 leaf(`src/composition/*`)나 `app-bootstrap`의 배선 | +| lane | 같은 조건(실 DB, 컨테이너, 시간)으로 묶어 돌리는 테스트 실행 단위. strict lane은 build-logic `strictTestLanes`가 정의한 것 | +| 단계 | workflow가 게이트를 도는 때: PR, main, nightly, 태그 | +| 개발 환경 | 루트 `compose.yaml` 하나로 띄우는 로컬 스택(앱 컨테이너의 Spring 프로필은 `local`). `src/app-bootstrap/compose-lanes/`의 overlay는 테스트 lane fixture다. 그중 `dev.yaml`·`prod-smoke.yaml`은 앱을 Spring 프로필 `dev`·`prod`로 띄워 그 프로필의 기동을 보는 lane이고, 개발 환경이 아니다 | +| 게이트 | 통과해야 병합·릴리스하는 검사(`docs/work/reference/gates.md`) | +| outbox | 트랜잭션 안에 남긴 이벤트를 relay가 나중에 발행하는 방식 | +| HARD-STOP | 어기면 동작해도 완료가 아닌 일곱 조건(루트 `AGENTS.md`) | +| brief | 다른 세션에 일을 맡기는 지시문(`docs/work/delegate.md`) | +| 총괄 | 일을 나누고 brief를 쓰고 결과를 대조하는 세션 | +| 하위 세션 | 총괄이 띄운 별도 세션. 파일을 바꾸는 위임을 맡는다. 소유자가 열어 보고 멈출 수 있다 | +| 서브에이전트 | 한 세션 안에서 Agent 도구로 띄우는 도우미(`.claude/agents/`). 결과만 돌려준다 | +| 훅, 넛지 | 훅은 Claude Code가 정해진 때 대신 돌리는 명령(`scripts/hooks/`). 넛지는 막지 않고 알리기만 하는 훅이다 | +| 탐침 | 의심 결함을 보려고 버릴 worktree에서 잠깐 돌리는 테스트(`docs/work/reference/gates.md` 2절) | +| RED, GREEN | 수정 전 실패를 실행으로 본 것, 수정 뒤 통과를 본 것 | +| 살아 있는 문서, 기록 | 코드와 같이 고치는 문서, 쓴 때의 글로 두고 머리 블록만 고치는 문서(`docs/README.md`) | -- 2.54.0 From d9059806766e5330eca3c32a0bbfb9f848bdc162 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:23:01 +0900 Subject: [PATCH 09/12] =?UTF-8?q?test(scripts):=20=ED=95=98=EC=9C=84=20CLA?= =?UTF-8?q?UDE.md=EA=B0=80=20AGENTS.md=EB=A7=8C=20=EA=B0=80=EC=A0=B8?= =?UTF-8?q?=EC=98=A4=EB=8A=94=EC=A7=80=20=EB=B3=B4=EA=B3=A0=20=EA=B2=80?= =?UTF-8?q?=EC=82=AC=EA=B8=B0=20=EC=8B=9C=ED=97=98=EC=9D=84=20=EB=91=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 폴더 지역 규칙은 이제 src/**/AGENTS.md이고 옆의 CLAUDE.md는 `@AGENTS.md` 한 줄이다. 누가 CLAUDE.md에 규칙을 다시 쓰거나, AGENTS.md만 만들고 CLAUDE.md를 빠뜨리면 Claude Code가 그 폴더 규칙을 못 읽거나 규칙이 두 벌이 된다. 그리고 check-work-docs.py에는 자기 시험이 하나도 없었다. - check-work-docs.py: src/**/AGENTS.md마다 옆 CLAUDE.md가 있고, 모든 src/**/CLAUDE.md가 정확히 `@AGENTS.md`이며 옆에 AGENTS.md가 있는지 본다 (build 출력 제외). - scripts/tests/test_check_work_docs.py(13건): 최소 매뉴얼 통과, 지도 41줄· CLAUDE.md 11줄 실패, CLAUDE.md 첫 줄이 가져오기가 아니면 실패, 진입 경로가 네 파일(AGENTS.md + CLAUDE.md + README + playbook) 합인지, 짝 셋, 하위 규칙과 .claude/rules·skills·agents의 이력 ID, 로컬 .claude 상태는 안 봄, 하위 규칙의 깨진 링크. - gates.md 「링크 검사」: lychee 범위 밖 지침 문서는 check-docs.py `link`가 보고, 손으로 돌리는 범위를 src/**/AGENTS.md로 바꿨다. docs/README.md의 검사 설명에서 링크 문법 예를 뺐다(링크 검사기가 링크로 읽었다). 위험: 진입 경로 상한 350은 파일별 상한의 합(40+10+80+150=280)보다 커서 지금 구조에서는 닿지 않는다. 옛 상한(120+80+150=350)도 같았다. 상한은 그대로 두고 시험은 상한을 낮춰 계산식을 본다. 검증: unittest(전체), check-work-docs, check-docs, 같은 범위 --links 모두 rc=0(깨진 링크 0). 조건 다섯(짝 검사, 지도 상한, 진입 경로의 CLAUDE.md, 첫 줄 가져오기, .claude 문서 이력)을 하나씩 끈 사본마다 시험이 1~3건 실패했다. --- docs/README.md | 2 +- docs/work/reference/gates.md | 6 +- scripts/check-work-docs.py | 19 +++- scripts/tests/test_check_work_docs.py | 141 ++++++++++++++++++++++++++ 4 files changed, 163 insertions(+), 5 deletions(-) create mode 100644 scripts/tests/test_check_work_docs.py diff --git a/docs/README.md b/docs/README.md index 82879364..f399bcfd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -195,7 +195,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | -| `link` | 살아 있는 문서의 상대 링크(`[글](경로)`)가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 | +| `link` | 살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 | | `style` | 살아 있는 문서의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안의 인용은 보지 않는다 | - 하나만 돌리기: `python3 scripts/check-docs.py --only head`. diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 6fa6446f..d0b5893c 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -69,13 +69,13 @@ - 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew :resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다. - 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다. -**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다): +**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 그 범위 밖의 지침 문서(루트 `AGENTS.md`·`CLAUDE.md`, 지역 규칙 `src/**/AGENTS.md`, `.claude/` 아래 문서)의 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 본다. `src/**/CLAUDE.md`는 `@AGENTS.md` 한 줄이라 링크가 없다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다): ```bash -python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/CLAUDE.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md') +python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/AGENTS.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md') ``` -`--links docs`만 돌리면 `src/**/README.md`·`src/**/CLAUDE.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). +`--links docs`만 돌리면 `src/**/README.md`·`src/**/AGENTS.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). ## 3. 라운드 끝 — 합친 트리의 전체 묶음 diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index 96c55053..32dceaad 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -19,7 +19,8 @@ things break that, and both are mechanical: map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only). It also checks that every playbook keeps the shared nine-section skeleton, that the -"common mistakes" section stays short, and that relative links in the checked files resolve. +"common mistakes" section stays short, that every folder rule book src/**/AGENTS.md has a CLAUDE.md +beside it that only imports it, and that relative links in the checked files resolve. This lives outside Gradle on purpose: the build does not parse documents. @@ -214,6 +215,21 @@ def module_guides() -> list[Path]: ) +def check_guide_pairs(errors: list[str]) -> None: + """Every folder rule book src/**/AGENTS.md has a CLAUDE.md beside it that only imports it, so Claude + Code reads the same book when it opens a file there. A CLAUDE.md that holds rules is a second book.""" + for guide in module_guides(): + if not guide.with_name("CLAUDE.md").is_file(): + errors.append(f"{rel(guide.with_name('CLAUDE.md'))}: missing; it must be the one line '{IMPORT_LINE}'") + for entry in sorted(path for path in (REPO_ROOT / "src").rglob("CLAUDE.md") + if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)): + lines = [line.strip() for line in entry.read_text(encoding="utf-8").splitlines() if line.strip()] + if lines != [IMPORT_LINE]: + errors.append(f"{rel(entry)}: must be exactly '{IMPORT_LINE}'; the rules live in AGENTS.md beside it") + if not entry.with_name("AGENTS.md").is_file(): + errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist") + + def check_claude_entry(errors: list[str]) -> None: """The root CLAUDE.md starts with the import, so a Claude Code session reads the map.""" lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines() @@ -334,6 +350,7 @@ def main() -> int: if check_exists(errors): check_limits(errors, report) check_claude_entry(errors) + check_guide_pairs(errors) check_skeleton(errors) check_history(errors, report) check_links(errors, report) diff --git a/scripts/tests/test_check_work_docs.py b/scripts/tests/test_check_work_docs.py new file mode 100644 index 00000000..f4ff5e88 --- /dev/null +++ b/scripts/tests/test_check_work_docs.py @@ -0,0 +1,141 @@ +"""scripts/check-work-docs.py의 시험. 고장 낸 지침 배치에서 실패하고, 맞는 배치에서 통과하는지 본다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import importlib.util +import io +import sys +import tempfile +import unittest +from contextlib import redirect_stderr, redirect_stdout +from pathlib import Path + +SCRIPTS = Path(__file__).resolve().parent.parent +_spec = importlib.util.spec_from_file_location("check_work_docs", SCRIPTS / "check-work-docs.py") +check_work_docs = importlib.util.module_from_spec(_spec) +sys.modules["check_work_docs"] = check_work_docs +_spec.loader.exec_module(check_work_docs) + +PLAYBOOK = "".join(f"## {heading}\n\n- 한 줄.\n\n" for heading in check_work_docs.SKELETON) + + +class Repository: + """A throwaway repository with the smallest work manual the checker accepts.""" + + def __init__(self) -> None: + self._directory = tempfile.TemporaryDirectory() + self.root = Path(self._directory.name) + self.write("AGENTS.md", "# 정본\n\n- 지도 한 줄.\n") + self.write("CLAUDE.md", "@AGENTS.md\n\n- Claude 전용 한 줄.\n") + self.write("docs/work/README.md", "# 작업 매뉴얼\n") + self.write("docs/work/evidence.md", "# 근거\n\n`1101/05-18`은 여기에 둔다.\n") + for name in check_work_docs.PLAYBOOKS: + self.write(f"docs/work/{name}", f"# {name}\n\n{PLAYBOOK}") + for name in check_work_docs.REFERENCES: + self.write(f"docs/work/{name}", "# 참고\n") + self.write("src/app/AGENTS.md", "# app\n\n- 지역 규칙.\n") + self.write("src/app/CLAUDE.md", "@AGENTS.md\n") + self.saved = {name: getattr(check_work_docs, name) for name in ("REPO_ROOT", "MAP", "CLAUDE_ENTRY", "WORK", "README")} + check_work_docs.REPO_ROOT = self.root + check_work_docs.MAP = self.root / "AGENTS.md" + check_work_docs.CLAUDE_ENTRY = self.root / "CLAUDE.md" + check_work_docs.WORK = self.root / "docs/work" + check_work_docs.README = check_work_docs.WORK / "README.md" + + def write(self, path: str, text: str) -> None: + target = self.root / path + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(text, encoding="utf-8") + + def run(self) -> tuple[int, str]: + out, err = io.StringIO(), io.StringIO() + argv = sys.argv + sys.argv = ["check-work-docs.py"] + try: + with redirect_stdout(out), redirect_stderr(err): + code = check_work_docs.main() + finally: + sys.argv = argv + return code, err.getvalue() + + def close(self) -> None: + for name, value in self.saved.items(): + setattr(check_work_docs, name, value) + self._directory.cleanup() + + +class CheckWorkDocsTest(unittest.TestCase): + def setUp(self) -> None: + self.repo = Repository() + self.addCleanup(self.repo.close) + + def assertFailsWith(self, fragment: str) -> None: + code, err = self.repo.run() + self.assertEqual(code, 1, err) + self.assertIn(fragment, err) + + def test_the_smallest_valid_manual_passes(self) -> None: + self.assertEqual(self.repo.run(), (0, "")) + + def test_a_map_over_forty_lines_fails(self) -> None: + self.repo.write("AGENTS.md", "# 정본\n" + "- 줄.\n" * 40) + self.assertFailsWith("AGENTS.md: 41 lines, limit 40") + + def test_a_claude_entry_over_ten_lines_fails(self) -> None: + self.repo.write("CLAUDE.md", "@AGENTS.md\n" + "- 줄.\n" * 10) + self.assertFailsWith("CLAUDE.md: 11 lines, limit 10") + + def test_a_claude_entry_that_does_not_import_the_map_fails(self) -> None: + self.repo.write("CLAUDE.md", "# 지도\n\n@AGENTS.md\n") + self.assertFailsWith("CLAUDE.md: the first line must be '@AGENTS.md'") + + def test_the_entry_path_counts_the_map_the_claude_entry_the_readme_and_one_playbook(self) -> None: + # Each file's own limit keeps the sum under ENTRY_PATH_LIMIT today, so lower it to see the sum. + lines = sum(len((self.repo.root / name).read_text(encoding="utf-8").splitlines()) + for name in ("AGENTS.md", "CLAUDE.md", "docs/work/README.md", "docs/work/improve.md")) + original = check_work_docs.ENTRY_PATH_LIMIT + check_work_docs.ENTRY_PATH_LIMIT = lines - 1 + self.addCleanup(setattr, check_work_docs, "ENTRY_PATH_LIMIT", original) + self.assertFailsWith(f"docs/work/improve.md: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {lines} lines") + + def test_a_folder_rule_book_without_its_claude_import_fails(self) -> None: + self.repo.write("src/web/AGENTS.md", "# web\n") + self.assertFailsWith("src/web/CLAUDE.md: missing; it must be the one line '@AGENTS.md'") + + def test_a_folder_claude_file_that_holds_rules_fails(self) -> None: + self.repo.write("src/app/CLAUDE.md", "@AGENTS.md\n\n- 여기에도 규칙을 쓴다.\n") + self.assertFailsWith("src/app/CLAUDE.md: must be exactly '@AGENTS.md'") + + def test_a_folder_claude_file_without_a_rule_book_fails(self) -> None: + self.repo.write("src/old/CLAUDE.md", "@AGENTS.md\n") + self.assertFailsWith("src/old/CLAUDE.md: imports src/old/AGENTS.md, which does not exist") + + def test_build_output_is_not_a_folder_rule_book(self) -> None: + self.repo.write("src/app/build/tmp/AGENTS.md", "# 복사본\n") + self.assertEqual(self.repo.run()[0], 0) + + def test_a_history_id_in_a_folder_rule_book_fails(self) -> None: + self.repo.write("src/app/AGENTS.md", "# app\n\n- 리뷰 05-18에서 정했다.\n") + self.assertFailsWith("src/app/AGENTS.md:3") + + def test_a_history_id_in_a_claude_rule_skill_or_agent_fails(self) -> None: + for path in (".claude/rules/x.md", ".claude/skills/x/SKILL.md", ".claude/agents/x.md"): + with self.subTest(path=path): + self.repo.write(path, "# 규칙\n\n- RR-03-03에서 고쳤다.\n") + self.assertFailsWith(f"{path}:3") + (self.repo.root / path).unlink() + + def test_local_claude_state_is_not_checked(self) -> None: + self.repo.write(".claude/worktrees/other/AGENTS.md", "# 다른 worktree\n\n- 리뷰 05-18.\n") + self.assertEqual(self.repo.run()[0], 0) + + def test_a_broken_link_in_a_folder_rule_book_fails(self) -> None: + self.repo.write("src/app/AGENTS.md", "# app\n\n[설계](README.md)\n") + self.assertFailsWith("src/app/AGENTS.md:3: broken relative link 'README.md'") + + +if __name__ == "__main__": + unittest.main() -- 2.54.0 From 7140f279481da688712c815de4635a3678af87c0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:33:08 +0900 Subject: [PATCH 10/12] =?UTF-8?q?docs(agents)!:=20200=EC=A4=84=20=EB=84=98?= =?UTF-8?q?=EB=8A=94=20leaf=20=EC=A7=80=EC=97=AD=20=EA=B7=9C=EC=B9=99=20?= =?UTF-8?q?=EC=85=8B=EC=9D=98=20=ED=91=9C=EC=99=80=20=EA=B7=BC=EA=B1=B0?= =?UTF-8?q?=EB=A5=BC=20README=EB=A1=9C=20=EC=98=AE=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로 읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데, persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이 2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정 「자료대로 해 본다」의 방향). - 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역 규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림). 지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때 지킬 규칙 몇 줄을 남겼다. - application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양, 멱등성(KEYED) → 337줄에서 190줄. - persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기, TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서 194줄. - graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄. - 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서 TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로 찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤 AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를 가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다. - persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새 자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은 코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에 맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드 `lock/DistributedLockPersistenceConfig`로 바꿨다. - check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다. 위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의 표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README 포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은 그 범위를 건드리지 않는다. 검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0. 상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java 변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다. BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/ 2026-11-harness.md 2절 8행. --- .claude/skills/new-feature/SKILL.md | 2 +- docs/manual/03-placement.md | 4 +- docs/manual/05-idempotency.md | 2 +- docs/manual/09-outbox-events.md | 2 +- docs/manual/11-checklist.md | 2 +- docs/manual/README.md | 2 +- docs/upgrade/2026-11-harness.md | 1 + docs/work/README.md | 2 +- docs/work/new-feature.md | 2 +- docs/work/reference/review-criteria.md | 4 +- scripts/check-work-docs.py | 17 +- scripts/tests/test_check_work_docs.py | 8 + src/adapter/inbound/graphql/AGENTS.md | 37 +-- src/adapter/inbound/graphql/README.md | 43 ++++ .../web/authz/RolePermissionPolicyTest.java | 2 +- .../outbound/persistence-jpa/AGENTS.md | 207 ++-------------- .../outbound/persistence-jpa/README.md | 231 +++++++++++++++++- .../architecture/NamingConventionTest.java | 2 +- .../TemplatePackageOwnershipRuleTest.java | 2 +- .../TemplatePackageOwnership.java | 4 +- .../TemplatePackageOwnershipDocumentTest.java | 4 +- src/application-core/AGENTS.md | 177 ++------------ src/application-core/README.md | 182 ++++++++++++++ 23 files changed, 527 insertions(+), 412 deletions(-) diff --git a/.claude/skills/new-feature/SKILL.md b/.claude/skills/new-feature/SKILL.md index 223336a1..b7ee5925 100644 --- a/.claude/skills/new-feature/SKILL.md +++ b/.claude/skills/new-feature/SKILL.md @@ -9,7 +9,7 @@ description: 이 백엔드 템플릿에 새 업무 기능(도메인 개념, 유 1. `docs/work/README.md`와 `docs/work/new-feature.md`를 끝까지 읽는다. 크기를 정한다. 새 capability 모듈, 새 leaf, 새 공개 계약(HTTP 경로·오류 코드·env 키)은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다. 2. 받을 것을 확인한다: 기능 이름(PascalCase), 저장소 선택(어떤 persistence leaf, migration 번호대), 권한, 재전송될 수 있는 쓰기인지. 저장소 선택은 사람이 정한다. brief에 없으면 묻는다. -3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. +3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다. 4. 뼈대: 노트북에서는 `scripts/new-feature.sh --no-format`. 포맷은 편집 훅이 파일마다 맞추고, 마지막에 desktop `./gradlew spotlessApply`로 한 번 더 본다. 5. 안쪽부터 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립(`docs/manual/02-new-feature.md`). 필요한 장만 더 읽는다: 저장 04, 재시도될 쓰기 05, 오류 06, 권한 07, 테스트 08, 이벤트 09, capability 10. 6. 동작은 테스트를 먼저 쓴다(`.claude/rules/java-tests.md`). 포트마다 fake 하나와 공유 계약(`XxxContract`)을 포트 소유 leaf의 testFixtures에 두고, 실제 adapter도 실 DB lane에서 같은 계약을 상속한다. diff --git a/docs/manual/03-placement.md b/docs/manual/03-placement.md index 06c626f9..cf26df08 100644 --- a/docs/manual/03-placement.md +++ b/docs/manual/03-placement.md @@ -55,8 +55,8 @@ - ``는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과 겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를 이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다. -- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md` - 「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 +- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/README.md` + 「패키지 소유 (Package ownership)」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다. - 이름 규칙은 같은 파일 「Naming convention」이 정본이다. diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md index 707251aa..e2b6be64 100644 --- a/docs/manual/05-idempotency.md +++ b/docs/manual/05-idempotency.md @@ -16,7 +16,7 @@ DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false) ``` -정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」 +정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/README.md` 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」 (executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명). ## 판단: 이 쓰기를 KEYED로 만드나 diff --git a/docs/manual/09-outbox-events.md b/docs/manual/09-outbox-events.md index 48a560ce..7ccf0d17 100644 --- a/docs/manual/09-outbox-events.md +++ b/docs/manual/09-outbox-events.md @@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을 없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다. -정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, +정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, `docs/messaging/delivery-guarantees.md`. ## 순서 diff --git a/docs/manual/11-checklist.md b/docs/manual/11-checklist.md index 2282613d..7c1cf0f9 100644 --- a/docs/manual/11-checklist.md +++ b/docs/manual/11-checklist.md @@ -5,7 +5,7 @@ ## 배치·이름 - [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `` 패키지). -- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. +- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. - [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다. ## domain diff --git a/docs/manual/README.md b/docs/manual/README.md index 33a4068d..bd3c82f8 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -44,7 +44,7 @@ | 테스트 작성 규칙 | `.claude/rules/java-tests.md` | | leaf 목록·허용 의존 | `src/config/architecture/modules.json` | | 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` | -| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 | +| 유스케이스 모양·트랜잭션 모양 | `src/application-core/README.md` 「정해진 유스케이스 모양 (Canonical use case shape)」, `src/application-core/AGENTS.md` 「허용하는 트랜잭션 모양 (Allowed transactional shapes)」 | | HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` | | 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` | | 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` | diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index e6f68de7..7a3e871e 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -18,3 +18,4 @@ | 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 | | 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 | | 7 | 예측·실측 장부 `docs/ledger/estimates.jsonl`(형식 `docs/ledger/README.md`)을 두었다. `.gitattributes`가 이 파일에 `merge=union`을 준다 | 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다 | +| 8 | 지역 규칙이 200줄을 넘던 셋(`src/application-core`, `src/adapter/outbound/persistence-jpa`, `src/adapter/inbound/graphql`)의 표와 계약을 같은 폴더 `README.md` 끝 「지역 규칙에서 옮긴 표와 계약」 절로 옮겼다. 템플릿 패키지 목록(「패키지 소유」 표)의 정본도 `src/application-core/README.md`다 | 서비스가 그 절을 고쳤다면 README의 같은 절로 옮긴다. 서비스 문서·테스트가 `src/application-core/AGENTS.md`의 「Package ownership」 표를 읽으면 `README.md`로 바꾼다 | diff --git a/docs/work/README.md b/docs/work/README.md index f770bacd..1de50824 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -74,6 +74,6 @@ ## 8. 이 폴더를 고칠 때 -- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. +- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 폴더 지역 규칙(`src/**/AGENTS.md`) 200줄(넘으면 표·근거를 그 leaf README로), 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. - 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다. - 이 폴더, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 5ff0fde4..3ae4367d 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -29,7 +29,7 @@ ## 4. 절차 1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다. -2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. +2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다. 3. capability 모듈이면 `docs/manual/10-capabilities.md`의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. 4. 뼈대를 만든다: `scripts/new-feature.sh `(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」). 5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index 5d0dd5f0..f72f5daf 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신 - 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다. - 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다. - 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). -- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. +- 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. - vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. - source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). @@ -213,7 +213,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` - [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키 -- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표 +- [ ] 템플릿 패키지를 더하거나 지우면 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표와 `TemplatePackageOwnership` - [ ] ArchUnit 규칙과 그 위반·허용 fixture - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) - [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행 diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index 32dceaad..ebcdc7b4 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -14,7 +14,7 @@ things break that, and both are mechanical: `CLAUDE.md`, and every folder rule book `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and `docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository. -2. Length. Each entry file has a line limit, and the entry path (map + root `CLAUDE.md` + README + +2. Length. Each entry file has a line limit (a folder rule book src/**/AGENTS.md too: 200), and the entry path (map + root `CLAUDE.md` + README + one playbook) has a total limit, so a session reads the whole path instead of skimming it. The map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only). @@ -67,6 +67,9 @@ HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-pattern MAP_LIMIT = 40 CLAUDE_ENTRY_LIMIT = 10 +# A folder rule book is read whole whenever a file in that folder is opened. Claude Code's guidance is +# under 200 lines per instruction file; tables and design reasons go to the leaf README. +MODULE_GUIDE_LIMIT = 200 README_LIMIT = 80 PLAYBOOK_LIMIT = 150 ENTRY_PATH_LIMIT = 350 @@ -230,6 +233,17 @@ def check_guide_pairs(errors: list[str]) -> None: errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist") +def check_guide_limits(errors: list[str], report: list[str]) -> None: + longest = 0 + for guide in module_guides(): + lines = line_count(guide) + longest = max(longest, lines) + if lines > MODULE_GUIDE_LIMIT: + errors.append(f"{rel(guide)}: {lines} lines, limit {MODULE_GUIDE_LIMIT}" + " (move tables and design reasons to the leaf README and leave a pointer)") + report.append(f"longest src/**/AGENTS.md: {longest}/{MODULE_GUIDE_LIMIT}") + + def check_claude_entry(errors: list[str]) -> None: """The root CLAUDE.md starts with the import, so a Claude Code session reads the map.""" lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines() @@ -351,6 +365,7 @@ def main() -> int: check_limits(errors, report) check_claude_entry(errors) check_guide_pairs(errors) + check_guide_limits(errors, report) check_skeleton(errors) check_history(errors, report) check_links(errors, report) diff --git a/scripts/tests/test_check_work_docs.py b/scripts/tests/test_check_work_docs.py index f4ff5e88..f035c530 100644 --- a/scripts/tests/test_check_work_docs.py +++ b/scripts/tests/test_check_work_docs.py @@ -101,6 +101,14 @@ class CheckWorkDocsTest(unittest.TestCase): self.addCleanup(setattr, check_work_docs, "ENTRY_PATH_LIMIT", original) self.assertFailsWith(f"docs/work/improve.md: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {lines} lines") + def test_a_folder_rule_book_over_two_hundred_lines_fails(self) -> None: + self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 200) + self.assertFailsWith("src/app/AGENTS.md: 201 lines, limit 200") + + def test_a_folder_rule_book_of_two_hundred_lines_passes(self) -> None: + self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 199) + self.assertEqual(self.repo.run(), (0, "")) + def test_a_folder_rule_book_without_its_claude_import_fails(self) -> None: self.repo.write("src/web/AGENTS.md", "# web\n") self.assertFailsWith("src/web/CLAUDE.md: missing; it must be the one line '@AGENTS.md'") diff --git a/src/adapter/inbound/graphql/AGENTS.md b/src/adapter/inbound/graphql/AGENTS.md index bec9db91..36ba5fec 100644 --- a/src/adapter/inbound/graphql/AGENTS.md +++ b/src/adapter/inbound/graphql/AGENTS.md @@ -142,42 +142,9 @@ health 스키마만 소유한다. ## 구현된 플랫폼 범위 — 등급으로 말한다 -"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 -쓰고, **현재 등급보다 높게 표현하지 않는다.** +표와 자세한 계약은 [README.md](README.md) 「구현된 플랫폼 범위 — 등급으로 말한다」 절이다. 지킬 것: -| 등급 | 의미 | -| --- | --- | -| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. | -| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. | -| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. | -| `production-verified` | 실부하·장애 시나리오 증거가 있다. | - -| Capability | 등급 | 증거 | -| --- | --- | --- | -| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) | -| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 | -| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 | -| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 | -| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` | -| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) | -| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 | -| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` | -| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) | -| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 | -| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 | -| 실부하·장애 | 미달성 | 증거 없음 | - -여전히 미구현인 것: - -- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음). -- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`, - `advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에 - 삭제했다. -- 실제 datastore 통합 증거 — 없다. -- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription - replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 - (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 - 형태로 새로 만든다. +- capability마다 그 표의 등급을 쓰고, 현재 등급보다 높게 표현하지 않는다(README·문서·커밋 본문 모두). ## 테스트 diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index edc1cf9a..015de45f 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -365,3 +365,46 @@ GraphQL/graphql-java SPI 를 구현한 타입이 없어 2026-09-25 에 삭제했 feature GraphQL schema/resolver 는 여전히 이 leaf 밖이다(스켈레톤은 health 표면만 소유). 실부하 성능 증거와 실 datastore 통합 증거도 없다. + +## 지역 규칙에서 옮긴 표와 계약 + +이 절의 표와 계약은 지역 규칙 [AGENTS.md](AGENTS.md)에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 `AGENTS.md`를 같은 변경에서 고친다. + +### 구현된 플랫폼 범위 — 등급으로 말한다 + +"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 +쓰고, **현재 등급보다 높게 표현하지 않는다.** + +| 등급 | 의미 | +| --- | --- | +| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. | +| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. | +| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. | +| `production-verified` | 실부하·장애 시나리오 증거가 있다. | + +| Capability | 등급 | 증거 | +| --- | --- | --- | +| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) | +| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 | +| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 | +| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 | +| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` | +| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) | +| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 | +| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` | +| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) | +| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 | +| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 | +| 실부하·장애 | 미달성 | 증거 없음 | + +여전히 미구현인 것: + +- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음). +- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`, + `advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에 + 삭제했다. +- 실제 datastore 통합 증거 — 없다. +- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription + replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 + (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 + 형태로 새로 만든다. diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java index 2a7c8cba..ae6743e3 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java @@ -12,7 +12,7 @@ import org.springframework.boot.test.context.runner.ApplicationContextRunner; import org.springframework.context.annotation.Configuration; /** - * Binding test for {@link RolePermissionPolicy} (AGENTS.md §설정과 런타임: every new + * Binding test for {@link RolePermissionPolicy} (.claude/rules/settings-and-runtime.md: every new * {@code @ConfigurationProperties} class gets a binding test). Verifies the {@code * app.authz.role-permissions.=} YAML/env shape binds to the {@code Map>} the registry consumes, and that an absent block is null-safe. diff --git a/src/adapter/outbound/persistence-jpa/AGENTS.md b/src/adapter/outbound/persistence-jpa/AGENTS.md index b6131bef..e8a178c9 100644 --- a/src/adapter/outbound/persistence-jpa/AGENTS.md +++ b/src/adapter/outbound/persistence-jpa/AGENTS.md @@ -11,7 +11,8 @@ 패키지 루트: `dev.caskeleton.adapter.outbound.persistence`. 예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산 -lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다. +lock TTL)과 계약 표(트랜잭션 모드, SQLState → 오류 코드, vendor, lane)는 [README.md](README.md)에 있다. 이 파일은 이 +폴더를 고칠 때 지킬 모듈 규칙의 정본이다. 이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다. 앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다. @@ -43,33 +44,11 @@ lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 ### Spring 조립 소유 -`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다: -`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다** -`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. -둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은 -`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은 -2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 -않는다. +표와 자세한 계약은 [README.md](README.md) 「Spring 조립 소유」 절이다. 지킬 것: -`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가 -Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource, -pool, EntityManagerFactory, Flyway가 하나도 없다. - -소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL -store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다), -`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 -고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability -registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌 -data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다. - -이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본 -조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: -migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 -(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정 -(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 -안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다. -기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 -실수로 `verifyJpaApiSurface`가 늘지 않게 한다. +- `AutoConfiguration.imports`의 두 항목(`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`)은 둘 다 `app.persistence-jpa.enabled=true`를 요구한다. `enabled=false`는 DataSource·pool·Flyway까지 완전히 끈다. +- 트랜잭션 엔진은 `SpringTransaction` 하나다. 두 번째 엔진을 만들지 않는다. +- 이 leaf는 유스케이스를 만들거나 부르지 않는다(outbox relay는 `composition:outbox-relay`). `dev.caskeleton.bootstrap`을 import하지 않고, 기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치며, 새 조립 도우미는 package-private로 둔다. ### 양보할 수 없는 것 @@ -92,26 +71,9 @@ migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·T ### 플랫폼 lane -```bash -cd src -./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour -# Release blocking composition is CI-owned; locally run the exact database qualification set: -./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \ - :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \ - :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \ - :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \ - :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \ - :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest -``` +표와 자세한 계약은 [README.md](README.md) 「플랫폼 lane」 절이다. 지킬 것: -Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 -아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. +- Docker를 쓰는 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 뜨지 못하면 건너뛰기가 아니라 오류다. ## 책임 @@ -137,44 +99,10 @@ Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것 ## vendor 고르기 -vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 -등록한다: +표와 자세한 계약은 [README.md](README.md) 「vendor 고르기」 절이다. 지킬 것: -| vendor | 패키지 | 고르는 것 | schema 소유 | -| --- | --- | --- | --- | -| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` | -| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 | - -outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와 -`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 -driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도 -`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다. - -`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 -`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 -`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를 -`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 -성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가 -고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤 -속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다: -`postgresql` provider는 기동 때 H2 data source를 거절한다. - -H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — -capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 -`postgresqlIntegrationTest`에 남는다. - -outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 -정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다. - -### capability로 막은 store - -선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver` -패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는 -`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다. - -그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 -필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 -capability의 store는 있으면 안 된다. +- vendor 선택은 `config/PersistenceVendorSettings`(enum) 하나이고 모듈 기본값은 PostgreSQL이다. H2는 `bootRunH2`로만 고르는 로컬 저장소이고 prod에서 거절된다. +- 선택 capability 하나를 위한 어댑터(지금 `fileserver` 패키지)는 그 capability의 스위치(`@ConditionalOnProperty`)를 단다. 아무도 켜지 않은 capability의 store는 bean이 되면 안 된다. ## 허용 @@ -203,117 +131,26 @@ capability의 store는 있으면 안 된다. ## TransactionPort 구현 계약 -`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: +표와 자세한 계약은 [README.md](README.md) 「TransactionPort 구현 계약」 절이다. 지킬 것: -| 모드 | 전파 | 격리 | 읽기 전용 | timeout | -|---|---|---|---|---| -| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) | -| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 | -| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) | -| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 | - -격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이 -`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용), -`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 -`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다. - -모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 -취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 -`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다. -후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에 -던진 업무 예외는 바꾸지 않고 넘긴다. - -미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기 -template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥 -트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시 -`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다. - -`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 -올리고 호출자에게 성공 값을 돌려주지 않는다. - -### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract) - -`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다: - -``` -hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 -``` - -레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나, -반복문을 트랜잭션 밖으로 뺀다. +- 모드마다 미리 만든 `TransactionTemplate`을 만든 뒤 바꾸지 않는다. 격리 수준은 template이 아니라 pool(READ COMMITTED, `HikariPoolConstraintValidator`)에 고정한다. +- 모든 모드에 시간 한계가 있다. `inRootWrite`는 실제 바깥 트랜잭션이 있으면 action 전에 `NestedRootTransactionRejectedException`을 던지고, 커밋한 뒤에만 값을 돌려준다. +- `inNew` 풀 크기 제약과 반복문 금지는 [application-core/AGENTS.md](../../../application-core/AGENTS.md)와 같다. ## 영속 실패 번역 계약 (feature-persistence-failure-baseline) -날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. -`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 -분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. +표와 자세한 계약은 [README.md](README.md) 「영속 실패 번역 계약 (feature-persistence-failure-baseline)」 절이다. 그 SQLState → 오류 코드 표가 정본이다. 지킬 것: -**표준 행(core):** - -| SQLState | code | category | http | retryable | -|---|---|---|---|---| -| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true | -| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true | -| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false | -| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | -| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false | -| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | - -**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):** - -| SQLState | code | vendor | -|---|---|---| -| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) | -| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL | -| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL | -| `57014` | `DB_QUERY_CANCELED` | PostgreSQL | -| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL | -| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 | -| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 | - -PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. -`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와 -`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는 -것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에 -따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든 -다르면 `SqlStateClassificationParityTest`가 실패한다. - -**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA -`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`) -→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring -data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`. - -**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기 -트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`: -PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라 -`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 -수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다. - -- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다 - (`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 - `INTERNAL` envelope으로 답하게 한다(새는 것 없음). -- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT). +- 날것의 `DataAccessException`(과 그 안의 SQLState·제약 이름)은 표현 계층에 닿지 않는다. `DataAccessException`을 잡는 repository 어댑터는 `PersistenceExceptionTranslator`로 번역해 carrier를 다시 던지고, 빈 결과면 원래 예외를 다시 던진다. +- PostgreSQL 행은 손으로 두 번째 표를 만들지 않고 `PostgreSqlState`와 classifier에 더한다(`SqlStateClassificationParityTest`). +- 커밋 중 결과를 모르는 실패는 `DB_COMPLETION_UNKNOWN`이고 절대 재시도하지 않는다. ## 영속 감사 계약 (feature-persistence-auditing-contract) -감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. -`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 -명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. -ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 -`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. +표와 자세한 계약은 [README.md](README.md) 「영속 감사 계약 (feature-persistence-auditing-contract)」 절이다. 지킬 것: -- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 - 감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로 - 넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다. -- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 - (scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은 - feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다. -- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를 - 상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / - feature-transaction-concurrency-contract가 가진다. -- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity` - 계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data - listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. +- 감사 필드는 `audit/AuditableEntity`에만 있고 도메인 aggregate에는 없다(ArchUnit `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`). +- repository 어댑터가 `Clock`과 `AuditContextPort`로 감사 값을 손으로 넣는다. bulk·native `@Query` UPDATE도 감사 열을 명시해 넣는다. ## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules) diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 4688c323..a2e0f42e 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -2,11 +2,10 @@ RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.persistence`. -허용/금지 의존, 테스트 명령, 그리고 **계약 테이블**(TransactionPort 모드표, SQLState → Error -Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [AGENTS.md](AGENTS.md) 다. -이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 -"왜 이렇게 했나"가 궁금할 때 본다. 표가 AGENTS.md 에 있으면 여기서는 중복하지 않고 그 근거만 -적는다. +허용/금지 의존과 테스트 명령은 [AGENTS.md](AGENTS.md) 가 정본이다. **계약 테이블**(TransactionPort +모드표, SQLState → Error Code 매트릭스, auditing 계약, vendor·lane 표)은 이 문서 끝 「지역 규칙에서 옮긴 +표와 계약」 절이 정본이다. 나머지는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 +기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. ## capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env @@ -106,8 +105,8 @@ promotion gate, 생성하는 곳 없는 `JpaTransactionObservation` 등)은 `doc `TransactionTemplate` 은 문서상 thread-safe 지만 **mutable** 하다. 매 호출마다 propagation / readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로 (`WRITE` / `READ_ONLY` / `REQUIRES_NEW`) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가 -사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 `READ_COMMITTED` -로 고정한다(모드표는 AGENTS.md §TransactionPort implementation contract). +사라지고, 각 모드를 따로 감사(audit)할 수 있다. isolation 은 템플릿이 아니라 pool 에 `READ_COMMITTED` +로 고정한다(모드표와 이유는 아래 「TransactionPort 구현 계약」). ### 왜 `inRootWrite`가 별도 템플릿이나 `NEVER` propagation을 만들지 않나 `inRootWrite`의 실행 속성은 `inWrite`와 같은 `WRITE + REQUIRED + READ_COMMITTED`라 기존 @@ -179,8 +178,8 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto ## failure — 퍼시스턴스 실패 변환 SPI -매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 AGENTS.md §Persistence -failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다. +매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 정본은 아래 「영속 실패 번역 계약 +(feature-persistence-failure-baseline)」 절이다. 여기서는 SPI 구조와 fallback 근거만 적는다. ### SPI-pluggable 설계 (vendor 추출) `PersistenceExceptionTranslator` 는 exact-state → code 맵을 등록된 모든 `SqlStateErrorMapping` @@ -502,7 +501,7 @@ stream migration이 중단되면 history/registry/object 상태를 먼저 확인 ## lock — 분산 락 -provider 선택표(flag → bean → registry)의 SSOT 는 AGENTS.md(또는 app-bootstrap 와이어링)다. +provider 선택(flag → bean → registry)의 정본은 설정 코드 `lock/DistributedLockPersistenceConfig`(bean 이름 `distributedLockProvider`)다. 여기서는 어댑터/설정 결정 근거만 적는다. ### `LockRegistryDistributedLock` 계약 @@ -683,3 +682,215 @@ holder 가 락을 잡을 수 있다. - **검사는 이 guard 하나다.** prod만 보던 `JpaSchemaSafetyValidator`는 이 guard보다 늦게 돌아 한 번도 발동하지 않았고, 실제 prod 거부는 `PROFILE_MISMATCH`가 아닌 `IllegalStateException`이었다. 두 검사를 합치면서 guard가 `PROFILE_MISMATCH`를 던진다. + +## 지역 규칙에서 옮긴 표와 계약 + +이 절의 표와 계약은 지역 규칙 [AGENTS.md](AGENTS.md)에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 `AGENTS.md`를 같은 변경에서 고친다. + +### Spring 조립 소유 + +`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다: +`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다** +`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다. +둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은 +`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은 +2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지 +않는다. + +`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가 +Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource, +pool, EntityManagerFactory, Flyway가 하나도 없다. + +소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL +store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다), +`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를 +고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability +registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌 +data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다. + +이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본 +조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다: +migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고 +(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정 +(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면 +안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다. +기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선 +실수로 `verifyJpaApiSurface`가 늘지 않게 한다. + +### 플랫폼 lane + +```bash +cd src +./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour +# Release blocking composition is CI-owned; locally run the exact database qualification set: +./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \ + :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \ + :adapter:outbound:persistence-jpa:jpaPlatformFailureTest \ + :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \ + :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \ + :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest +``` + +Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 +아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. + +### vendor 고르기 + +vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 +등록한다: + +| vendor | 패키지 | 고르는 것 | schema 소유 | +| --- | --- | --- | --- | +| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` | +| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 | + +outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와 +`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중 +driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도 +`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다. + +`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고 +`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그 +`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를 +`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01 +성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가 +고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤 +속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다: +`postgresql` provider는 기동 때 H2 data source를 거절한다. + +H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 — +capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는 +`postgresqlIntegrationTest`에 남는다. + +outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 +정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다. + +#### capability로 막은 store + +선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver` +패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는 +`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다. + +그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가 +필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은 +capability의 store는 있으면 안 된다. + +### TransactionPort 구현 계약 + +`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: + +| 모드 | 전파 | 격리 | 읽기 전용 | timeout | +|---|---|---|---|---| +| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) | +| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 | +| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) | +| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 | + +격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이 +`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용), +`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다 +`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다. + +모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가 +취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의 +`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다. +후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에 +던진 업무 예외는 바꾸지 않고 넘긴다. + +미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기 +template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥 +트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시 +`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다. + +`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를 +올리고 호출자에게 성공 값을 돌려주지 않는다. + +#### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract) + +`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다: + +``` +hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 +``` + +레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나, +반복문을 트랜잭션 밖으로 뺀다. + +### 영속 실패 번역 계약 (feature-persistence-failure-baseline) + +날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. +`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 +분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. + +**표준 행(core):** + +| SQLState | code | category | http | retryable | +|---|---|---|---|---| +| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true | +| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true | +| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false | +| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | +| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false | +| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false | + +**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):** + +| SQLState | code | vendor | +|---|---|---| +| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) | +| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL | +| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL | +| `57014` | `DB_QUERY_CANCELED` | PostgreSQL | +| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL | +| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 | +| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 | + +PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다. +`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와 +`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는 +것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에 +따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든 +다르면 `SqlStateClassificationParityTest`가 실패한다. + +**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA +`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`) +→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring +data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`. + +**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기 +트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`: +PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라 +`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을 +수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다. + +- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다 + (`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반 + `INTERNAL` envelope으로 답하게 한다(새는 것 없음). +- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT). + +### 영속 감사 계약 (feature-persistence-auditing-contract) + +감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. +`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 +명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. +ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 +`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. + +- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 + 감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로 + 넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다. +- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면 + (scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은 + feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다. +- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를 + 상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline / + feature-transaction-concurrency-contract가 가진다. +- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity` + 계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data + listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java index e271b74a..a8175b20 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java @@ -55,7 +55,7 @@ class NamingConventionTest { // Package ownership — a business feature package does not take a template package's name. The // template's own packages are listed in TemplatePackageOwnership (machine copy of the "Package - // ownership" table in src/application-core/AGENTS.md); everything else under the two roots is a + // ownership" table in src/application-core/README.md); everything else under the two roots is a // feature, so a derived service adds features without editing the list. A feature always has a // domain package (docs/manual/03-placement.md ①), which is where a feature named after an // application template package — `operation`, `lock`, `cache` — shows up. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java index 9a2d7991..76369981 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java @@ -110,7 +110,7 @@ class TemplatePackageOwnershipRuleTest { .as( "a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was" + " renamed or removed without the list (and the table in" - + " src/application-core/AGENTS.md) following it") + + " src/application-core/README.md) following it") .containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet()); assertThat(domain) .as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists") diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java index 460dfacb..a291a243 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java @@ -15,7 +15,7 @@ import java.util.TreeSet; * owns each, and which packages are a service's business features. * *

This is the machine copy of the "Package ownership" tables in {@code - * src/application-core/AGENTS.md}, which are the rule book. A template change that adds, renames, + * src/application-core/README.md}, which are the rule book. A template change that adds, renames, * moves or removes one of these packages changes the table and this class together. Two tests hold * them to it: {@code TemplatePackageOwnershipDocumentTest} (document-contract lane, main stage) * fails when the table and this class differ in a name or an owning leaf, or when a listed package @@ -107,7 +107,7 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) { + name.get() + "', a name the template already uses. A feature beside a template package" + " of the same name merges into the same tree on every upstream update." - + " Rename the feature (template packages: src/application-core/AGENTS.md" + + " Rename the feature (template packages: src/application-core/README.md" + " \"Package ownership\").")); } } diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java index 45d436d7..690ceac8 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java @@ -19,7 +19,7 @@ import org.junit.jupiter.api.Test; /** * The template package list exists twice — the "Package ownership" tables in {@code - * src/application-core/AGENTS.md}, which people and agents read, and {@link + * src/application-core/README.md}, which people and agents read, and {@link * TemplatePackageOwnership}, which the architecture rules read — and nothing held the two together * (original review 2026-11-01 §16.3). Changing either one alone fails here: a name or an owning * leaf that differs, or a listed package that is not in the leaf the table says owns it. @@ -29,7 +29,7 @@ import org.junit.jupiter.api.Test; @Tag("document-contract") class TemplatePackageOwnershipDocumentTest { - private static final String RULE_BOOK = "src/application-core/AGENTS.md"; + private static final String RULE_BOOK = "src/application-core/README.md"; private static final String REGISTRY = "src/config/architecture/modules.json"; private static final String APPLICATION_TABLE = "| 패키지 (`dev.caskeleton.application.*`) |"; private static final String DOMAIN_TABLE = "| 패키지 (`dev.caskeleton.domain.*`) |"; diff --git a/src/application-core/AGENTS.md b/src/application-core/AGENTS.md index 56e4d359..1797cfb5 100644 --- a/src/application-core/AGENTS.md +++ b/src/application-core/AGENTS.md @@ -52,29 +52,9 @@ ## 계약 타입 -| 타입 | 용도 | -|---|---| -| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | -| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | -| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | -| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | -| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | -| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | -| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | -| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | -| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | -| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | -| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | -| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | -| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | -| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | -| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | -| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | -| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | -| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | -| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | -| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | -| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | +표와 자세한 계약은 [README.md](README.md) 「계약 타입」 절이다. 지킬 것: + +- 구체 inbound 포트는 `CommandUseCase`나 `QueryUseCase`를 상속하고, 그 구현은 `@UseCaseCapability`를 단다(ArchUnit `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY`). ## 알림 (NOTIF-ADR-005) @@ -107,113 +87,19 @@ architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 ## 패키지 소유 (Package ownership) -이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. -`docs/manual/03-placement.md`가 이곳을 가리킨다. +표와 자세한 계약은 [README.md](README.md) 「패키지 소유 (Package ownership)」 절이다. 그 표가 템플릿 패키지 목록의 정본이다. 지킬 것: -- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, - `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 - 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. -- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 - 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. -- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 - 않는다. -- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 - 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. - -| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | -|---|---|---| -| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | -| `capability` | application-core | `@UseCaseCapability`와 그 enum | -| `transaction` | application-core | `TransactionPort`와 그 모드 | -| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | -| `tenant` | application-core | `TenantId` | -| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | -| `secret` | application-core | `SecretSourcePort`, `SecretReference` | -| `messaging` | application-core | integration event semantic contract | -| `outbox` | application-core | 트랜잭션 outbox append와 relay | -| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | -| `operation` | application-core | durable(오래 걸리는) operation | -| `lease`, `lock` | application-core | 분산 lease·lock 포트 | -| `cache` | application-core | cache region 포트 | -| `realtime` | application-core | live event 재생 포트 | -| `notification` | application-notification | 알림 capability | -| `fileserver` | application-fileserver | 파일 서버 capability | -| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | - -| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | -|---|---|---| -| `identifier` | domain-core | `ResourceId`, `IdFactory` | -| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | - -강제하는 곳: - -- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 - 거절한다. 템플릿 패키지도 모두 여기 걸린다. -- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 - 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 - `dev.caskeleton.domain.operation`에서 걸린다. -- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 - 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. -- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap - `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). - `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 - 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. - `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 - 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. -- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 - (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 - 더하는 일이다. -- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 - 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 - 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). +- 업무 기능은 루트마다 바로 아래에 기능 하나당 패키지 하나다(`dev.caskeleton.application.`, `dev.caskeleton.domain.` 등). `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 템플릿 패키지 이름이 아니다. 업무 코드를 템플릿 패키지에 넣지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다(`NamingConventionTest`). +- 템플릿 패키지를 더하거나 이름을 바꾸거나 지우면 README 표와 `TemplatePackageOwnership`을 같은 변경에서 고친다. `TemplatePackageOwnershipDocumentTest`가 둘을 대조한다. ## 정해진 유스케이스 모양 (Canonical use case shape) -```java -@RequiresPermission("user:register") -@UseCaseCapability( - transactionMode = TransactionMode.WRITE, - idempotency = Idempotency.KEYED, - repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) -public class RegisterUserUseCase implements CommandUseCase { +표와 자세한 계약은 [README.md](README.md) 「정해진 유스케이스 모양 (Canonical use case shape)」 절이다. 지킬 것: - private final UserRepository users; - private final TransactionPort tx; - - public RegisterUserUseCase(UserRepository users, TransactionPort tx) { - this.users = users; - this.tx = tx; - } - - @Override - public User handle(RegisterUserCommand cmd) { - return tx.inWrite(() -> { - // ... domain coordination - }); - } -} -``` - -이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI -프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 -`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final -클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. -`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 -소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 -사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 -모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 -작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 -위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: -`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 -의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. -`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 -클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 -전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). -`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 -타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 -경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 -곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 -(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). +- 유스케이스는 평범한 Java이고 final이 아니다(web 어댑터가 CGLIB proxy로 `@RequiresPermission`을 강제한다). 조립 루트가 bean으로 만든다. application-core는 DI 프레임워크에 스스로 등록하지 않는다. +- 상태를 바꾸면 `@RequiresPermission`, 시스템만 부르면 `@SystemInvoked(reason = ...)`를 달고 bean으로 두지 않는다. 시스템 호출자 목록의 정본은 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」다. +- 일은 `TransactionPort`로 감싼다(아래 「허용하는 트랜잭션 모양」). ## 허용하는 트랜잭션 모양 (Allowed transactional shapes) @@ -250,45 +136,10 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract -`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 -`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 -유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. +표와 자세한 계약은 [README.md](README.md) 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」 절이다. 지킬 것: -- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation - code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 - store에도 닿지 않는다. -- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 - 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). - 운영에서 메모리 저장소는 금지다. -- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 - 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 - 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. -- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 - 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 - `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. - `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 - 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. -- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. - 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 - 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 - 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 - 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 - lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 - 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. -- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). - 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 - 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). -- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 - 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 - handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 - 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, - `IdempotencyStoreContract`). -- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 - 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — - retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). - -예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 -이 브랜치가 병합될 때 지웠다. +- KEYED 유스케이스는 일을 `IdempotencyExecutor`로 감싼다. 원본 `Idempotency-Key`는 이 계층에 들이지 않고 `IdempotencyScopeDigest`만 받는다. +- executor는 `composition:idempotency`가 만든다. 유스케이스나 서비스 설정에서 만들지 않는다. 운영에서 메모리 저장소는 금지다. ## 읽기·query 경로 (feature-application-query-bypass-contract) diff --git a/src/application-core/README.md b/src/application-core/README.md index 5aa32fe9..792fb1e0 100644 --- a/src/application-core/README.md +++ b/src/application-core/README.md @@ -656,3 +656,185 @@ leaf의 코드 Javadoc과 `docs/notification/`이 정본이다. R1 오케스트 `application-objectstorage`의 `objectstorage.content`로, 항상 함께 다니는 `CancellationView` 옆에 옮겼다. 다른 전송(HTTP client·gRPC·GraphQL)은 각자의 deadline 타입을 쓴다. - 포트 계약 `secret.testkit.SecretSourceContract`, fake `InMemorySecretSource`(testFixtures). + +## 지역 규칙에서 옮긴 표와 계약 + +이 절의 표와 계약은 지역 규칙 [AGENTS.md](AGENTS.md)에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 `AGENTS.md`를 같은 변경에서 고친다. + +### 계약 타입 + +| 타입 | 용도 | +|---|---| +| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | +| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | +| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | +| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | +| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | +| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | +| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | +| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | +| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | +| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | +| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | +| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | +| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | +| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | +| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | +| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | +| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | +| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | +| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | + +### 패키지 소유 (Package ownership) + +이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. +`docs/manual/03-placement.md`가 이곳을 가리킨다. + +- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, + `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 + 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 + 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. +- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 + 않는다. +- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 + 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. + +| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | +|---|---|---| +| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | +| `capability` | application-core | `@UseCaseCapability`와 그 enum | +| `transaction` | application-core | `TransactionPort`와 그 모드 | +| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | +| `tenant` | application-core | `TenantId` | +| `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | +| `secret` | application-core | `SecretSourcePort`, `SecretReference` | +| `messaging` | application-core | integration event semantic contract | +| `outbox` | application-core | 트랜잭션 outbox append와 relay | +| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | +| `operation` | application-core | durable(오래 걸리는) operation | +| `lease`, `lock` | application-core | 분산 lease·lock 포트 | +| `cache` | application-core | cache region 포트 | +| `realtime` | application-core | live event 재생 포트 | +| `notification` | application-notification | 알림 capability | +| `fileserver` | application-fileserver | 파일 서버 capability | +| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | + +| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | +|---|---|---| +| `identifier` | domain-core | `ResourceId`, `IdFactory` | +| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | + +강제하는 곳: + +- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 + 거절한다. 템플릿 패키지도 모두 여기 걸린다. +- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 + 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 + `dev.caskeleton.domain.operation`에서 걸린다. +- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 + 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. +- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap + `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). + `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 + 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. + `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 + 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. +- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 + (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 + 더하는 일이다. +- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 + 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 + 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). + +### 정해진 유스케이스 모양 (Canonical use case shape) + +```java +@RequiresPermission("user:register") +@UseCaseCapability( + transactionMode = TransactionMode.WRITE, + idempotency = Idempotency.KEYED, + repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) +public class RegisterUserUseCase implements CommandUseCase { + + private final UserRepository users; + private final TransactionPort tx; + + public RegisterUserUseCase(UserRepository users, TransactionPort tx) { + this.users = users; + this.tx = tx; + } + + @Override + public User handle(RegisterUserCommand cmd) { + return tx.inWrite(() -> { + // ... domain coordination + }); + } +} +``` + +이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI +프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 +`@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final +클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. +`new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 +소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 +사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 +모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 +작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 +위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: +`@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 +의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. +`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 +클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 +전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). +`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 +타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 +경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 +곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 +(`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). + +### 멱등성 (KEYED) — feature-rate-limit-idempotency-contract + +`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 +`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 +유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. + +- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation + code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 + store에도 닿지 않는다. +- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 + 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). + 운영에서 메모리 저장소는 금지다. +- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 + 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 + 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. +- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 + 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 + `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. + `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 + 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. +- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. + 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 + 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 + 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 + 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 + lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 + 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. +- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). + 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 + 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). +- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 + 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 + handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 + 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, + `IdempotencyStoreContract`). +- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 + 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — + retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). + +예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 +이 브랜치가 병합될 때 지웠다. -- 2.54.0 From 93b70b067307f4bf99691280315505cf0355501e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:33:16 +0900 Subject: [PATCH 11/12] =?UTF-8?q?docs(work):=203=ED=9A=8C=EC=B0=A8=20?= =?UTF-8?q?=EB=B9=88=ED=8B=88=EA=B3=BC=20=EC=8C=93=EC=9D=B8=20=EB=A7=A4?= =?UTF-8?q?=EB=89=B4=EC=96=BC=20=EA=B7=9C=EC=B9=99=EC=9D=98=20=EC=B2=98?= =?UTF-8?q?=EB=A6=AC=20=ED=91=9C=EB=A5=BC=20=EA=B7=BC=EA=B1=B0=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=EC=97=90=20=EB=82=A8=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 매뉴얼 보강 묶음이 각 빈틈을 어디에 넣었는지, 넣지 않았으면 왜인지를 다음 cold-read 시험과 총괄 대조가 찾을 곳이 없다. 1·2회차는 evidence.md 9·11절에 처리 표를 두었다. 같은 방식으로 12절을 더한다. - 22행: 3회차 빈틈 9건(R3-1~R3-8), 장부의 통합·배치·문서·번역 세션 빈틈, 공유 노트 목록, repo-structure 세 문서의 매뉴얼 규칙. 고침 21행(기본값 2), 고치지 않음 1행(design-docs 몫). - 리뷰 ID와 세션 이름은 이 근거 문서에만 둔다(매뉴얼 본문 이력 ID 0 규칙). 검증: check-work-docs, check-docs rc=0. --- docs/work/evidence.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/work/evidence.md b/docs/work/evidence.md index 96aaecf8..85683ff9 100644 --- a/docs/work/evidence.md +++ b/docs/work/evidence.md @@ -377,3 +377,38 @@ - 합계: 52건, 34행. 고침 34행(그중 기본값 7행), 고치지 않음 0, 소유자 결정 필요 0. - 소유자 결정(2026-11-07)으로 한 일: 이력 ID 0 규칙을 진입 문서로 넓혔다(10절, 결정 색인 2.1 「이력 ID 0 규칙의 범위」). - 「자주 하는 실수」에 넣은 줄: `improve.md`(탐침의 Error Prone을 기존 줄에 더함). + +## 12. cold-read 시험 3회차 빈틈과 쌓인 매뉴얼 규칙 처리 (2026-11-07) + +하네스 재설계를 적용한 묶음(design-docs `harness/01-harness-design.md`, 소유자 결정 2026-11-07 「매뉴얼 보강은 한 묶음」)에서 함께 넣었다. 원천은 넷이다: cold-read 3회차(수정 세션 넷 `r9-g1`~`r9-g4`의 빈틈 9건), 위임 장부(design-docs `delegation-loop/ledger.jsonl`)의 `"to": "manual"` 줄 중 백엔드 몫, 공유 노트의 매뉴얼 보강 목록, design-docs `repo-structure/01-backend-layout.md` 10·12절·`02-docs.md` 9절·`03-ci.md` 8절. + +- 처리 칸: 고침(고친 곳) / 이미 있음(그 자리) / 고치지 않음(이유). 「고침(기본값)」은 이 묶음이 정하고 결정 색인에 기본값으로 남긴 것이다. +- 1·2회차 빈틈(장부 6~22줄)은 9절·11절에서 이미 처리했다. 다시 넣지 않았다. + +| # | 출처 | 빈틈 | 처리 | +| --- | --- | --- | --- | +| R3-1 | G1-1 | brief가 옮긴 결정 설명과 결정 원문이 다를 때 무엇을 따르나 | 고침 — `reference/decisions.md` 1절 1(원문을 따르고 차이를 보고) | +| R3-2 | G1-3 | desktop 잠금을 여러 세션이 기다릴 때 순서와 시간 | 고침 — `reference/gates.md` 4절 「공유 잠금 기다리기」 | +| R3-3 | G2-1 | 커밋하는 수정에서 lockfile을 손으로 고쳐도 되나 | 고침 — `reference/gates.md` 2절 탐침 첫 줄(desktop `resolveAndLockAll --write-locks`) | +| R3-4 | G2-2 | desktop에서 자기 실행을 멈추는 법(`pkill -f`가 ssh 세션을 끊음) | 고침 — `operate.md` 4.1절 | +| R3-5 | G3-1, G3-3 | 절차 문서 결함과 대기 결함의 RED 모양 | 고침 — `improve.md` 4.2절 3 | +| R3-6 | G3-2 | 검증 뒤 앞 커밋에 형식 수정을 넣는 법 | 고침 — `operate.md` 4.1절(커밋을 나누기 전에 확인, 편집 훅이 파일마다 맞춤) | +| R3-7 | G4-1 | 그 코드를 지키는 lane을 찾는 법 | 고침 — `improve.md` 4.2절 8 | +| R3-8 | G4-2 | upgrade 안내 「커밋:」 줄을 여러 묶음이 고칠 때 | 고침 — `delegate.md` 4.2절 표 | +| R3-9 | 장부 r9 통합(5건) | OOM 재시작 거짓 통과, 자원 의존 실패의 판정, `--no-build-cache` 차이, zsh 파이프 rc, 처음 켜진 lane의 이전 실패 | 고침 — `reference/gates.md` 6절 표·4절 「원래 있던 실패 가리기」·3절, `operate.md` 4.1절, `reference/gates.md` 3절 (나) 5 | +| R3-10 | 장부 t1(5건) | smoke 이미지 재사용, `if` 안 `set -e`, leaf 데이터 폴더, 트리 해시로 커밋에 묶기, 코드 주석 언어 | 고침 — `reference/gates.md` 4절·6절, `new-feature.md` 6절, 이미 있음 — `operate.md` 4.1절 「push 전에 검증하기」, 고침 — `docs-writing.md` 4절 4 | +| R3-11 | 장부 d1(5건) | 이동 커밋과 검사, Gradle 밖 검사의 자리, 줄기만 하는 예외 목록, MANIFEST, scripts 시험 위치 | 고침 — `docs-writing.md` 4절 13·14, `reference/gates.md` 7절 1·8, 이미 있음 — `docs/README.md` 「문서 검사」 | +| R3-12 | 장부 i1(4건+2) | 병합에서만 생긴 수정, FROZEN 지문, smoke 이미지, 순서 의존 재현, check-docs 줄 누락, lychee·buf·trivy | 고침(기본값) — `delegate.md` 4.2절(병합 커밋에는 충돌 해결만), 이미 있음 — `docs/README.md`, 고침 — `reference/gates.md` 4절 둘, `docs-writing.md` 4절 10·5절·8절, `review-criteria.md` 9절, `reference/gates.md` 3절 (다) | +| R3-13 | 장부 i2(4건) | smoke 이미지 출처, trivy DB 받기, 문체 검사의 주인, 테스트 Javadoc | 고침 — `reference/gates.md` 4절, 고침(기본값) — `operate.md` 4.1절·결정 색인 「desktop 도구 설치」, 고침 — `check-docs.py` `style`, `improve.md` 4.2절 6 | +| R3-14 | 장부 d2a, d2c(4건) | 레지스트리 yaml 번역, 영어 절 제목 인용, 머리말 없는 runbook, `@DisplayName` 범위 | 고침 — `docs-writing.md` 4절 14, `.claude/rules/java-tests.md` 규칙 2 | +| R3-15 | 장부 41(프론트 총괄) | brief의 「충돌 없음」, 중복 PR | 고침 — `delegate.md` 9절 | +| R3-16 | 공유 노트 | 결정 기록 머리 둘째 줄이 번역한 ADR에 맞지 않음 | 고침 — `check-docs.py` `DECISION_LABEL`, `docs/README.md`, ADR 머리 블록. design-docs `docs-system.md` 4.1절과 프론트는 이 repo 밖 | +| R3-17 | 공유 노트 | `check-repo-layout.py` 설명과 지도 범위, `template-vs-consumer.md` 분류 | 고침 — 루트 `AGENTS.md` 지도, `check-repo-layout.py`, `docs/ci-cd/template-vs-consumer.md` | +| R3-18 | 01-backend-layout 10.1·10.3 | 리뷰 기준의 최상위 폴더·참조 0 파일·배포·개발자 경험·삭제 가능성, 최상위 폴더 일의 크기, 테스트 환경 위치 | 고침 — `review-criteria.md` 관점 2·9·18·20·27, `README.md` 2절, `new-feature.md` 6절 | +| R3-19 | 01-backend-layout 12절 | 개발 환경의 뜻 | 고침 — `reference/terms.md`(새) | +| R3-20 | 02-docs 9절 | 용어집, 모듈 README 칸, 리뷰의 문서 기준, Important 예시 | 고침 — `reference/terms.md`, `docs/README.md` 「모듈 README」, `review-criteria.md` 관점 4·9·20·23·26·3절 | +| R3-21 | 03-ci 8절 | workflow·스크립트를 더하는 기준, 빌드·CI 비례성, 같은 장치 결함 되풀이, runner 사실 | 고침 — `reference/gates.md` 7절, `review-criteria.md` 관점 4·20·21, `improve.md` 7절·`delegate.md` 4.2절, `operate.md` 4.1절 | +| R3-22 | 장부 1·33·43줄, 01 10.2·12절 6, 02·03의 design-docs 몫 | 결정 질문 상자, 훅 빈틈, live 클러스터 적용, 성숙도 리뷰 가이드, design-docs README | 고치지 않음 — design-docs(총괄) 몫. 이 repo 밖 | + +- 합계: 22행. 고침 21행(그중 기본값 2), 고치지 않음 1행(이 repo 밖). +- 「자주 하는 실수」에 넣은 줄: `delegate.md` 둘. -- 2.54.0 From a0a77575486e2bf09199ebdd5e8236b64cb40036 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 23:12:49 +0900 Subject: [PATCH 12/12] =?UTF-8?q?docs(ledger):=20=ED=95=98=EB=84=A4?= =?UTF-8?q?=EC=8A=A4=20=EC=A0=81=EC=9A=A9=20=EC=9E=91=EC=97=85=EC=9D=98=20?= =?UTF-8?q?=EC=8B=A4=EC=B8=A1=EA=B3=BC=20=ED=8B=80=EB=A6=B0=20=EC=9D=B4?= =?UTF-8?q?=EC=9C=A0=EB=A5=BC=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 착수 예측(21:46, p30 150분·호출 450·출력 45만) 뒤 끝 보고 직전의 실측을 세션 기록에서 뽑아 같은 task로 한 줄 더한다: 벽시계 94분, 작업 중 68분, 호출 270, 출력 34.6만 토큰, 다시 읽은 입력 1.33억 토큰, 최대 컨텍스트 80.5만. 모두 p30 안이다. 틀린 이유와 다음에 바꿀 근거는 줄의 why 칸에 있다. 작업 중 시간의 정의를 선례(design-docs harness 설계 14절)가 잰 방식과 같게 「빈틈을 5분까지만 더한 시간」으로 README에 적었다. 검증: test_ledger(예측보다 뒤의 실측, 구간 판정), check-docs, check-work-docs rc=0. --- docs/ledger/README.md | 2 +- docs/ledger/estimates.jsonl | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ledger/README.md b/docs/ledger/README.md index 2e514004..f6e01776 100644 --- a/docs/ledger/README.md +++ b/docs/ledger/README.md @@ -40,7 +40,7 @@ | 칸 | 형식 | 뜻 | | --- | --- | --- | -| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 기록 사이 5분 넘는 빈틈을 뺀 시간 | +| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간. 긴 대기와 다음 지시를 기다린 시간이 빠진다) | | `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 | | `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 | | `result`, `commits` | 문자열, 배열 | 완료·부분·못 함, 만든 커밋 | diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl index 411083b5..ace6e564 100644 --- a/docs/ledger/estimates.jsonl +++ b/docs/ledger/estimates.jsonl @@ -1 +1,2 @@ {"schema": 1, "kind": "estimate", "task": "h3-backend-harness", "recorded_at": "2026-11-07T21:46+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "started_at": "2026-11-07T21:37:50+09:00", "base": "b3f63be6", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 150, "p50": 210, "p80": 300}, "calls": {"p30": 450, "p50": 600, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 600000, "p80": 850000}, "basis": "선례 h1-harness-design 작업 중 23분·호출 100·출력 13.6만(바꾼 파일 3, Gradle 없음)에서 분당 호출 4.3, 호출당 출력 1,400. 이번에 바꿀 파일 약 120(하위 문서 이동 28, 새 CLAUDE.md 32, 문서의 AGENTS.md 참조 93줄, 검사기 2, 훅 6, 시험 3, Java 테스트 3, 에이전트·스킬·규칙 8), 매뉴얼 항목 약 60(선례 manual-gap-fix-2가 52건을 한 세션에), desktop 대기 30~50분"} +{"schema": 1, "kind": "actual", "task": "h3-backend-harness", "recorded_at": "2026-11-07T23:13+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "minutes": 94, "active_minutes": 68, "calls": 270, "output_tokens": 345525, "cache_read_tokens": 132822591, "max_context": 805096, "within": "p30", "result": "done", "commits": ["08f93212", "3c73fc33", "38891071", "c67c7131", "67ecae2c", "37c88fed", "59dff004", "c8db79a7", "d9059806", "7140f279", "93b70b06", "248df518"], "why": "모든 값이 p30보다 작았다. 바꿀 파일 수(약 120, 실제 190여)를 호출 수로 옮겼는데, 이동·참조 수정 수십 파일을 스크립트 한 번으로 묶어 파일당 호출이 거의 없었다. desktop 대기는 예측과 비슷했지만(합친 트리 한 번 27분, 중단한 두 번) 작업 중 시간에서는 빈틈마다 5분으로 잘린다. 다음 예측은 파일 수가 아니라 손으로 판단할 결정 수(이번 약 25)와 desktop 실행 횟수를 근거로 쓴다. 실측은 23:12까지의 세션 기록이고, 뒤의 커밋·PR·보고는 들어 있지 않다"} -- 2.54.0