docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다

문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.

고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.

위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).

검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
  lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
  'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
  rc=0(3건)
This commit is contained in:
DongHyeonka
2026-11-07 07:02:09 +09:00
parent 83948d58f3
commit 6b253c6c75
26 changed files with 223 additions and 113 deletions
+3 -3
View File
@@ -80,7 +80,7 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
`performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
@@ -199,7 +199,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
쓴다(소유자 결정 5). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
@@ -264,7 +264,7 @@ capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
자체를 두지 않는다.
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
constructor에서 한다.
예외(리뷰 05-18): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
예외(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와 실제 어댑터가 모두
+1 -1
View File
@@ -50,7 +50,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다.
- `docs/work/`나 이 파일을 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다.
- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
## 5. 코드만 보고는 헷갈리는 곳
+2 -2
View File
@@ -72,5 +72,5 @@
## 8. 이 폴더를 고칠 때
- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다.
- 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
- 본문에 지난 리뷰 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)다.
+2 -2
View File
@@ -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 명령과 결과를 보고에 적는다.
10. `docs/work/`나 루트 `CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크를 본다.
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `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 <파일 또는 폴더>`.
13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
@@ -50,7 +50,7 @@
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
- `docs/work/`·루트 `CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
+70
View File
@@ -4,6 +4,13 @@
표기: `1101/05-01`은 `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01이다. `1103/RR6-01-05`는 `docs/reviews/2026-11-03-rereview/`의 발견이다. 접두어와 문서: `RR-`는 1차 재리뷰(폴더 바로 아래 `01`~`07` 영역 문서)와 round2의 `01`~`03` 영역 문서(1차 번호를 이어 썼다), `RR2-`는 round2의 `04` 영역 문서, `RR3-`~`RR7-`는 round3~round7이다. `1101` README, `1103` README는 각 폴더의 `README.md`다. 「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번이다.
더 오래된 표기:
- 「1라운드」·「2라운드」·「3라운드」: `1101` README 13·14·15.1절의 수정 라운드(2026-11-01~03). `r2-05a`, `r3-I`처럼 `r<라운드>-<묶음>`은 그 라운드의 수정 묶음 이름이다. `r9-a`, `r10-02`는 `1103` README 16·17절의 묶음이다.
- `P<N>`·`W<n>-P<N>`: 2026-09-25 리뷰 후속 작업(`docs/reviews/2026-09-25-review-followup-status.md`)의 묶음 이름(Wave n의 묶음 N). 같은 문서는 2026-09-24 리뷰들의 발견을 `S<n>-#<m>`, `S<n>-lead-<m>`, `X<n>-#<m>`, `X<n>-P<k>-<m>`, `G-3a`처럼 부른다. 그 행을 찾으면 내용과 처리 묶음이 있다.
- `MSG-`·`BOOT-`·`JPA-`·`MNG-`·`GQL-`·`NTF-` + 세 자리: 2026-11 전의 모듈 리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md`, `2026-09-07-app-bootstrap-module-code-review.md` 등)의 발견이다.
- `D<N>`: 문맥에 따라 둘이다. 이 매뉴얼의 설계 결정(design-docs `delegation-loop/02-design.md` 13절, D1~D14)이거나, leaf `CLAUDE.md`가 이름을 댄 설계 기록(`feature-*-contract` 등)의 결정 번호다. 그 설계 기록들은 이 repo에 없다(10절).
## 1. 이 매뉴얼이 나온 곳
- 조사와 설계: design-docs `delegation-loop/01-research.md`(1~5단계), `delegation-loop/02-design.md`(6단계, 4·5·6·7·10절). 2026-11-06 소유자가 결정 D1~D14를 모두 권하는 안대로 승인했다.
@@ -247,3 +254,66 @@
- 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 이를 근거로 확인 리뷰를 독립 리뷰어 둘로 할지 소유자에게 물었고, 2026-11-07 소유자가 세 경우에만 둘로 하는 안을 골랐다(소유자 원문 "(c)로 받기"). 넣은 곳: `improve.md` 4.1절 「독립 리뷰어 둘」·4.5절 1, `delegate.md` 4.1·4.3절, `reference/review-criteria.md` 10절 「ID」, `reference/decisions.md` 2.1, design-docs `conventions/delegation-loop.md` 3절 5·9절 M11, `delegation-loop/metrics.md`.
- 「자주 하는 실수」에 넣은 줄: `improve.md`(strict lane 탐침), `operate.md`(`--rerun` 범위를 기존 줄에 더함, push 뒤 검증), `docs-writing.md`(`--history` 0을 믿음), `delegate.md`(두 리뷰의 ID).
## 10. 진입 문서에서 걷어낸 이력 ID (2026-11-07)
2026-11-07 소유자가 이력 ID 0 규칙을 진입 문서로 넓혔다: `AGENTS.md`와 `src/**/CLAUDE.md`다(`1103` README 19.4절 ③의 (b)). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. 새 세션이 처음 읽는 규칙 문서에서만 ID가 이해를 막고, 나머지는 같은 repo의 리뷰 문서로 따라갈 수 있어서다. `scripts/check-work-docs.py` 기본 모드가 이제 이 문서들을 본다.
걷어낸 줄은 87줄이다. 넓힌 범위에서 옛 패턴이 74줄을 잡았고, 그중 2줄은 날짜로 쓴 소유자 결정을 잘못 잡은 것이었다. 새 패턴과 줄바꿈 검사가 15줄을 더 잡았다. 줄 번호는 기준 커밋 `83948d58`의 줄이다. `feature-*-contract` 같은 설계 기록은 이 repo에 없다(`git ls-files`로 0건). 그래서 그 번호의 근거 칸은 가리키는 규칙과 코드 위치를 적는다.
| 원래 위치 | 원래 괄호 | 지금 본문 | 근거 |
| --- | --- | --- | --- |
| `AGENTS.md:83`, `:202` | "소유자 결정 4", "소유자 결정 5" | "2026-09-25 소유자 결정" | 결정 4(`verifyEnvKeys`는 app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), 결정 5(`@DisplayName`은 한국어). 결정 색인 2.7·2.1 |
| `AGENTS.md:267`, `src/adapter/outbound/cache-redis/CLAUDE.md:197`~`198` | "리뷰 05-18", "review finding 05-18" | "2026-11-03 정함", "decided 2026-11-03" | `1101/05-18`(설정 prefix·바인딩 방식이 capability 기준 4와 다르다, `05-outbound-capabilities.md`). 결정은 `1101` README 15절(2026-11-03, 위임), 결정 색인 2.6 「Redis prefix 예외」 |
| `src/adapter/inbound/graphql/CLAUDE.md:76`, `:130` | "owner decision 25", "소유자 결정 25" | "owner decision 2026-09-25", "2026-09-25 소유자 결정" | 결정 25(GraphQL DataLoader 키 실패는 등록된 `ApiErrorCode`만 노출). 결정 색인 2.3 |
| `src/adapter/inbound/graphql/CLAUDE.md:104` | "servlet 단일 스택(D4)" | 괄호를 지웠다 | D4는 servlet 단일 스택 결정의 번호다. 결정 9 행의 "D4를 outbound에도 적용"이 같은 번호다(`2026-09-25-review-followup-status.md` 「소유자 결정」). D4를 적은 원래 설계 기록은 이 repo에 없다 |
| `src/adapter/inbound/web/CLAUDE.md:45`~`46`(줄바꿈으로 갈림), `src/adapter/outbound/support/CLAUDE.md:30` | "review 2026-11-01 07-10" | "since 2026-11-01" | `1101/07-10`(설정 오타·죽은 키가 기동에서도 게이트에서도 안 잡히는 곳이 있다, `07-bootstrap-composition-config.md`). 그 수정이 `app.security`를 `StrictSettingsBinder`로 묶었다 |
| `src/adapter/inbound/web/CLAUDE.md:136`, `:143`, `:154`, `:161`, `:163`, `:164` | "D2", "D3", "D3 / SBMS-C3", "D5", "D6", "D7" | 괄호를 지웠다. S1~S5는 이 문서의 항목 이름이라 남겼다 | 설계 기록 `feature-schema-serialization-contract`(이 repo에 없음)의 결정 번호. 규칙은 각 항목 본문, `JacksonSerializationPolicyTest`, ArchUnit `no_bigdecimal_double_constructor`가 가진다 |
| `src/adapter/inbound/web/CLAUDE.md:191` | "C3 / C7 / D9" | "C3 / C7" | 설계 기록 `feature-business-rule-validation-contract`(이 repo에 없음)의 결정 번호. 규칙은 `BusinessRuleValidationContractTest`와 누출 테스트 |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:222` | "persistence-multi-db-extensibility D3" | 괄호를 지웠다 | 설계 기록 `persistence-multi-db-extensibility`(이 repo에 없음)의 결정 번호. 규칙은 같은 문장의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`·`PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2` |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:239` | "review 09-05" | 괄호를 지웠다. 이유는 같은 문단 끝 문장(시작마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복)이 적는다 | `1101/09-05`(트랜잭션마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복 1회, `09-performance-measurement.md`) |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:246` | "review 04-10" | "since 2026-11-01" | `1101/04-10`(기본 쓰기·읽기 트랜잭션에 시간 제한이 없다, `04-persistence.md`) |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:251` | "review RR-03-03" | 지웠다 | `1103/RR-03-03`(JPA 경로에서 트랜잭션 마감 초과가 분류되지 않고 500이 된다, `03-persistence.md`) |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:265`, `:277`, `:367` | "D12 of …", "… D1", "D9 of …" | 설계 기록 이름만 남겼다 | `feature-application-port-usecase-contract`의 D12(`inNew` 풀 크기 제약), `feature-persistence-failure-baseline`의 D1(영속성 실패 번역 계약), `feature-architecture-enforcement-rules`의 D9(MapStruct 생성 mapper 예외). 셋 다 이 repo에 없다 |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:309` | "review 04-06" | "before 2026-11-01 a hand-kept second table had already drifted" | `1101/04-06`(SQLState 분류표가 두 벌이고 이미 갈라졌다, `04-persistence.md`) |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:318` | "review 04-05" | 지웠다 | `1101/04-05`(`@Version` 충돌이 변환되지 않고 500 INTERNAL_ERROR로 나간다, `04-persistence.md`) |
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:340`, `:341`, `:343`, `:348`, `:349`, `:357`, `:361` | "D3", "D2", "D6", "D1", "D4", "D5" | 지웠다 | 설계 기록 `feature-persistence-auditing-contract`(같은 문서 「Persistence auditing contract」 절 제목이 이름을 댄다, 이 repo에 없음)의 결정 번호. 규칙은 `AuditableEntity`와 ArchUnit `domain_is_pure`가 가진다 |
| `src/application-core/CLAUDE.md:40`, `:42`, `:44`, `:242`, `:250`, `:332` | "D3", "ArchUnit D11", "per D12", "(D11)", "(D12)" | D11 하나는 ArchUnit 규칙 이름 `application_does_not_depend_on_application_context`로 바꿨다. 나머지는 지웠다 | 설계 기록 `feature-application-port-usecase-contract`(이 repo에 없음)의 결정 번호: D3 `TransactionPort`, D11 콜백 시그니처와 `ApplicationContext` 금지, D12 `inNew` 풀 크기(문자열 키 bean 조회의 정적 분석 사각지대 문장도 같은 번호를 썼다) |
| `src/application-core/CLAUDE.md:174` | "review 2026-11-01 01-10 (b)" | "weighed in the 2026-11-01 maturity review" | `1101/01-10`(application-core 한 이름공간에 커널·플랫폼 기능·업무 기능이 섞인다, `01-core-and-feature-pattern.md`)의 대안 (b) |
| `src/application-core/CLAUDE.md:288`, `:290` | "re-review RR5-01-02·03", "re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04" | 앞은 "owner decision 2026-11-04"만 남겼다. 뒤 줄은 지웠다 | `1103/RR5-01-02`(`renew`·`inspect` 결과 값의 뜻이 하나씩 늘었다)·`RR5-01-03`(포트 javadoc의 "주인의 마지막 보고를 기록이 갖는다"가 동작과 다르다), `round5/review.md`. `1103/RR-01-11`(lease가 지나면 Redis 저장소가 작업을 다시 돌린다, `round2/01-core-app-inbound.md`), `1103/RR-03-11`(replay TTL이 lease보다 짧으면 key가 lease 도중 사라진다, `round2/03-outbound.md`), `1103/RR3-03-04`(watchdog·계약으로 바뀐 뒤 옛 표현이 남은 문서, `round3/03-outbound.md`) |
| `src/application-core/CLAUDE.md:293`, `:297` | "owner decision 2026-11-06" | 그대로 | 걷어낼 ID가 아니다. 옛 패턴 `owner decision \d+`가 날짜를 번호로 잡은 오탐이라 패턴을 고쳤다(아래) |
| `src/application-core/CLAUDE.md:311`, `:317`, `:319`, `:322`, `:326`, `:336` | "D1", "D3", "D4", "D5", "D2", "query-bypass D1" | 항목 이름만 남겼다(Purity guardrail, Strict ceremony, Transaction, Capability) | 설계 기록 `feature-application-query-bypass-contract`(같은 문서 「Read / query path」 절 제목, 이 repo에 없음)의 결정 번호. D1은 ArchUnit `query_ports_do_not_leak_domain_jpa_or_web_types`가 지킨다 |
| `src/adapter/outbound/cache-redis/CLAUDE.md:137`, `:138`, `src/adapter/outbound/httpclient/CLAUDE.md:93` | "review 2026-11-01 05-16", "review 2026-11-03 RR-04-05" | "since 2026-11-01", "until 2026-11-03", httpclient는 지웠다 | `1101/05-16`(capability 완료 기준 5가 영역 전체에서 지켜지지 않는다, `05-outbound-capabilities.md`), `1103/RR-04-05`(Redis 멱등성 계약의 실서버 실행이 어느 게이트에도 없다, `04-outbound-capabilities.md`) |
| `src/adapter/outbound/cache-redis/CLAUDE.md:186`~`187`(줄바꿈으로 갈림) | "review 2026-11-03 README §4, RR-04-02" | "decided 2026-11-03" | `1103/RR-04-02`(캐시 조건부 쓰기가 멱등성·rate-limit·lease와 SCRIPT lane을 나눠 쓴다, `04-outbound-capabilities.md`). 결정은 `1103` README 4절(위임), 결정 색인 2.4 「Redis 연결 예산」 |
| `src/adapter/outbound/cache-redis/CLAUDE.md:190` | "RR-04-10" | 지웠다 | `1103/RR-04-10`(`DEGRADED` 정렬 순서를 상태를 내지 않는 leaf가 싣는다, `04-outbound-capabilities.md`) |
| `src/adapter/outbound/httpclient/CLAUDE.md:27` | "decision 9 (2026-09-25)" | "the 2026-09-25 owner decision" | 결정 9(httpclient reactive 스택 삭제). 결정 색인 2.7 |
| `src/adapter/outbound/identifier/CLAUDE.md:22` | "review 2026-11-01 06-06" | 지웠다 | `1101/06-06`(application EventId 문법과 platform MessageId(UUID)가 다르다, `06-messaging.md`) |
| `src/adapter/outbound/identifier/CLAUDE.md:24` | "README, review 05-21" | "README" | `1101/05-21`(identifier leaf: 이름·문서가 내용과 맞지 않는다, `05-outbound-capabilities.md`) |
| `src/adapter/outbound/identifier/CLAUDE.md:32`, `src/adapter/outbound/persistence-mongo/CLAUDE.md:53`~`54`(줄바꿈), `src/messaging/CLAUDE.md:33`, `src/grpc/CLAUDE.md:44`, `src/grpc-advanced/CLAUDE.md:21`, `src/shared-contract/CLAUDE.md:34` | "review 2026-11-01 01-11"(shared-contract는 "…, decision in the review README §15") | 지웠다. shared-contract는 "decided 2026-11-03" | `1101/01-11`(공용 다이제스트 헬퍼가 있는데 복사본이 남아 있고, 일부 leaf는 registry 때문에 복사가 강제된다, `01-core-and-feature-pattern.md`). 결정은 `1101` README 15절(2026-11-03, 위임), 결정 색인 2.2 「edge 없는 복사본」 |
| `src/adapter/outbound/messaging/CLAUDE.md:42` | "owner decision 29" | "owner decision 2026-09-25" | 결정 29(messaging 카드 검증기의 YAML 라이브러리는 테스트에서만). 결정 색인 2.6 |
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:15`, `src/adapter/outbound/persistence-notification/CLAUDE.md:9` | "review 04-16" | 지웠다 | `1101/04-16`(notification·fileserver leaf에 가까운 안내 문서가 없고 패키지가 평평하다, `04-persistence.md`) |
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:26` | "review 04-17" | 지웠다 | `1101/04-17`(미리 정한 UUID + primitive `long` version이라 `save()`가 merge로 동작한다, `04-persistence.md`) |
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:58`~`59` | "added in review 2026-11-03 RR-01-04" | "added on 2026-11-03" | `1103/RR-01-04`(application-fileserver 저장 포트 9개 중 7개는 공유 계약이 없다, `01-core-application.md`) |
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:64` | "review 04-04" | 지웠다 | `1101/04-04`(실 PostgreSQL lane 9개가 어떤 게이트·workflow에서도 돌지 않는다, `04-persistence.md`) |
| `src/adapter/outbound/persistence-notification/CLAUDE.md:20` | "review RR-03-09" | 지웠다 | `1103/RR-03-09`(notification 엔티티의 변경 메서드가 public이 됐다, `03-persistence.md`) |
| `src/adapter/outbound/persistence-notification/CLAUDE.md:40` | "owner decision 33" | "owner decision 2026-09-25" | 결정 33(caller 트랜잭션 guard: `persistence-jpa` edge, `CallerTransaction` 하나). 결정 색인 2.2 |
| `src/adapter/outbound/support/CLAUDE.md:32` | "review 15절, r3-I" | "decided 2026-11-03" | `1101` README 15절(2026-11-03) 「선택 숫자 설정의 빈 env 값 (r3-I 발견)」 행. r3-I는 3라운드 수정 묶음이다. 결정 색인 2.6 「빈 env 값」 |
| `src/app-bootstrap/CLAUDE.md:49` | "BOOT-006 / BOOT-007" | 리뷰 문서 경로만 남겼다 | `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`의 BOOT-006(패키지 분류가 두 축으로 섞이고 `Settings` 배치 규칙이 없다), BOOT-007(같은 분해 문제를 두 방식으로 푼다) |
| `src/messaging/CLAUDE.md:29` | "S7-#5b" | "2026-09-25 리뷰 후속 작업에서 나눴다" | `2026-09-25-review-followup-status.md` S7-#5b 행(한 leaf가 relay 로직·PG repository·admin journal을 함께 가졌다, W3-P18에서 완료) |
| `src/messaging/CLAUDE.md:38`, `src/grpc/CLAUDE.md:50`, `src/grpc-advanced/CLAUDE.md:25`, `src/shared-contract/CLAUDE.md:31`~`32` | "MSG-023 §6.2", "MSG-023" | "2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치" 등 | `docs/reviews/2026-08-14-messaging-module-code-review.md` MSG-023(module 이름·폴더 구조와 canonical 정책 문서가 실제 구조를 설명하지 못한다). vendored 플랫폼은 Clean Architecture 계층이 아니라는 결정은 `1101/06-messaging.md` 머리의 "소유자 결정 유지" 줄 |
| `src/messaging/CLAUDE.md:43` | "review 2026-11-01 06-01" | 지웠다 | `1101/06-01`(다시 시도하면 될 거부를 relay가 즉시 DEAD로 보낸다, `06-messaging.md`) |
| `src/messaging/CLAUDE.md:66` | "재리뷰 2026-11-03 RR-05-07" | "2026-11-03" | `1103/RR-05-07`(vendored 제품 안에 두 재시도 규칙이 생겼고 고른 이유가 제품 쪽에 없다, `05-messaging.md`) |
| `src/messaging/CLAUDE.md:98`, `:113`, `src/grpc/CLAUDE.md:98` | "MSG-015", "MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7)", "MSG-015(bridge 부재)" | "cutover 완료", "application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정)", "bridge 부재(2026-08-14 messaging 모듈 리뷰)" | MSG-015(기존 application/runtime과 신규 platform 사이에 semantic bridge와 cutover 권한이 없다, 같은 messaging 리뷰). 결정 7(outbox append를 canonical `OutboxAppendPort`로 통일) |
| `src/messaging/CLAUDE.md:140` | "MSG-022" | 지웠다 | MSG-022(experimental adapter가 class 이름 문자열로 오류를 추측한다, 같은 messaging 리뷰) |
| `src/grpc/CLAUDE.md:167`, `:169` | "03-11 (b)", "The review", "re-review 2026-11-03, RR-02-07" | "option (b)", "The 2026-11-01 maturity review", "(b) was chosen on 2026-11-03" | `1101/03-11`(`app.grpc.platform.operation-ledger-enabled`가 검증만 통과시키고 key를 처리하는 코드가 없다, `03-inbound-realtime-graphql-grpc.md`)의 대안 (a)·(b), `1103/RR-02-07`(같은 문제를 다시 본 발견, `02-inbound-transports.md`). 고른 안은 ADR-GRPC-004 |
| `src/grpc/CLAUDE.md:185` | "re-review RR-02-04" | ADR 이름만 남겼다 | `1103/RR-02-04`(ledger에 시도 구분이 없어 takeover 뒤 옛 owner의 기록이 새 시도를 덮는다, `02-inbound-transports.md`) |
| `src/grpc-advanced/CLAUDE.md:64` | "리뷰 2026-09-24 S5-lead-4" | "2026-09-25 리뷰 후속 작업에서 삭제했다" | `2026-09-25-review-followup-status.md` S5-lead-4 행(release·promotion gate가 websocket·grpc에도 반복되는지, W3-P16에서 삭제). 같은 ID가 `docs/runbooks/grpc-advanced-capabilities.md`와 `docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md`에 남아 있다(검사 대상 밖) |
| `src/shared-contract/CLAUDE.md:27` | "review X2-P1-5, X2-P1-4b, X1-#9" | "moved here in the 2026-09-25 review follow-up" | `2026-09-25-review-followup-status.md`의 X2-P1-5(SHA-256 보일러플레이트 → `Sha256`), X2-P1-4b(서명 헬퍼만 shared-contract로), X1-#9(Backoff 계산식 10개 → `Backoff`). 셋 다 W3-P19 |
`scripts/check-work-docs.py`에 더하고 고친 것(2026-11-07):
- 기본 검사 대상: `AGENTS.md`와 `src/**/CLAUDE.md`(build 출력 밖)를 더했다. `AGENTS.md`는 링크 검사에도 더했다(lychee 범위 밖이다).
- 새 패턴 넷: 모듈 리뷰 발견(`MSG-023`, `BOOT-006` — 접두어는 `docs/reviews/`에서 세 자리 번호로 쓰인 여섯), 리뷰 후속 발견(`S6-#10a`, `X2-P1-5`, `S5-lead-4`), 고른 대안이 붙은 발견 번호(`03-11 (b)`), 영어 리뷰 README 절(`review README §15`). 「결정 N」 패턴에 영어 `decision 9`를 더했다.
- 고친 오탐: 날짜로 쓴 결정(`owner decision 2026-11-06`, `소유자 결정 2026-11-07`)은 잡지 않는다.
- 줄바꿈 검사: 한 줄에서 안 걸려도 다음 줄과 이었을 때 줄 경계를 넘는 ID(`(review` ↵ `2026-11-01 07-10)`)를 잡는다. 이번에 2줄(web·persistence-mongo)이 이 꼴이었다. persistence-fileserver·cache-redis의 갈린 괄호는 둘째 줄의 `RR-` 접두어가 따로 잡혔다.
- 오탐 시험(`docs-writing.md` 4절 12단계): 잡아야 할 문장 10개는 모두 잡혔다. 잡지 말아야 할 문장 8개 중 하나가 걸렸다: 일부러 만든 "line 10-12 (b)"(콜론 없는 줄 범위 뒤 대안 표시)다. repo에는 그 꼴이 없어 그대로 뒀다. `docs/reviews/**` 밖 전체에 돌리면 새로 125줄이 걸린다. 모두 검사 대상 밖(모듈 README, ADR, `docs/httpclient/` 등)의 실제 ID이고, 검사 대상 안의 오탐은 0이다.
+1 -1
View File
@@ -100,7 +100,7 @@
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다.
- 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다.
- `docs/work/`나 루트 `CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
- `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
## 6. 하지 말 것
+1
View File
@@ -33,6 +33,7 @@
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 |
| 커밋 예외 | 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에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 총괄이 쓴다 | 기본값 | 2026-11-06 | `docs/work/evidence.md` 9절 |
| 이력 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절 |
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. 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절 |
+1 -1
View File
@@ -48,7 +48,7 @@
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
| 의존성 | `verifyDependencyLocks` |
| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) |
| `docs/work/`, 루트 `CLAUDE.md` | `python3 scripts/check-work-docs.py` |
| `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md` | `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` 안) |
+51 -11
View File
@@ -8,6 +8,9 @@ to finish the job from those alone. Two things break that, and both are mechanic
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/**/CLAUDE.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.
@@ -32,6 +35,7 @@ from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
MAP = REPO_ROOT / "CLAUDE.md"
RULE_BOOK = REPO_ROOT / "AGENTS.md"
WORK = REPO_ROOT / "docs/work"
README = WORK / "README.md"
@@ -100,10 +104,21 @@ HISTORY_PATTERNS = [
("round number in Korean (1라운드, 라운드6)",
re.compile(r"(?<![\w.~-])\d{1,2} ?라운드(?! ?(?:동안|마다|씩|간))|라운드 ?\d{1,2}(?![\w.])", re.ASCII)),
("review README section number (리뷰 README 13절)", re.compile(r"리뷰 README \d", re.ASCII)),
# A decision named by its date ("owner decision 2026-11-06") is content plus a date, not a number.
("decision named by number only",
re.compile(r"결정 ?(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))|owner decision \d+", re.ASCII)),
re.compile(r"결정 ?(?!\d{4}-)(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))"
r"|(?<![A-Za-z])[Dd]ecision (?!\d{4}-)\d+", re.ASCII)),
("old manual decision number (M-3)", re.compile(r"\bM-\d+\b", re.ASCII)),
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", re.ASCII)),
# Module code reviews before 2026-11 numbered findings per module: MSG-023, BOOT-006, GQL-012.
("module review finding (MSG-023, BOOT-006)",
re.compile(r"(?<![\w-])(?:BOOT|MSG|JPA|MNG|GQL|NTF)-\d{3}\b", re.ASCII)),
# The 2026-09-24 reviews and their follow-up named findings S6-#10a, X2-P1-5, S5-lead-4.
("review follow-up finding (S6-#10a, X2-P1-5)",
re.compile(r"\b[SX]\d-(?:#\d+|P\d-\d+|lead-\d+)", re.ASCII)),
("finding number with its chosen option (03-11 (b))",
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
("review README section (review README §15)", re.compile(r"review README §", re.ASCII)),
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
]
@@ -119,7 +134,7 @@ def line_count(path: Path) -> int:
def check_exists(errors: list[str]) -> bool:
expected = [MAP, README, WORK / EVIDENCE]
expected = [MAP, RULE_BOOK, 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:
@@ -180,23 +195,48 @@ 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."""
skipped = {"build", ".gradle", "node_modules"}
return sorted(
path
for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
)
def history_checked_files() -> list[Path]:
files = [MAP]
files = [MAP, RULE_BOOK]
for path in sorted(WORK.rglob("*.md")):
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
files.append(path)
return files
return files + module_guides()
def history_match(line: str, following: str) -> tuple[str, str] | None:
"""The first history ID on this line, or one that a line break splits ("review\n2026-11-01 07-10")."""
for label, pattern in HISTORY_PATTERNS:
match = pattern.search(line)
if match:
return label, match.group(0)
if not following.strip():
return None
joined = line.rstrip() + " " + following.strip()
for label, pattern in HISTORY_PATTERNS:
for match in pattern.finditer(joined):
if match.start() < len(line.rstrip()) < match.end():
return label, match.group(0)
return None
def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]:
hits = []
for path in files:
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
for label, pattern in HISTORY_PATTERNS:
match = pattern.search(line)
if match:
hits.append((path, number, label, match.group(0)))
break
lines = path.read_text(encoding="utf-8").splitlines()
for number, line in enumerate(lines, start=1):
found = history_match(line, lines[number] if number < len(lines) else "")
if found:
hits.append((path, number, *found))
return hits
@@ -225,7 +265,7 @@ 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] + sorted(WORK.rglob("*.md")))
checked, broken = broken_links([MAP, RULE_BOOK] + sorted(WORK.rglob("*.md")))
for path, number, target in broken:
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
report.append(f"relative links checked: {checked}")
+3 -3
View File
@@ -73,7 +73,7 @@ platform wire-code catalogue in `GraphQlErrorCode`.
- application/domain `ApiErrorCode` values remain a separate namespace and pass through with
`GraphQlErrorCode.of(...)`; GraphQL must not rename product errors. Only a registered
`ApiErrorCode` reaches the wire this way — a DataLoader per-key failure carries one, never a free
string (owner decision 25).
string (owner decision 2026-09-25).
- new GraphQL-owned platform codes use the `GRAPHQL_` prefix. The existing unprefixed platform
values are frozen legacy wire contracts and are listed explicitly by
`legacyUnprefixedPlatformCodes()`.
@@ -101,7 +101,7 @@ application/platform namespace split.
`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 단일 스택(D4)이라 실행
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
@@ -127,7 +127,7 @@ application 매핑(`GraphQlExceptionResolver`) → `IllegalArgumentException`·
걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category →
wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다.
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 소유자 결정 25).
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정).
## 향후 adopter 의 feature 기여 방법
+9 -9
View File
@@ -42,8 +42,8 @@ ArchUnit `WEB-ARCH-ADV`).
- `:domain-core`
- `:shared-contract`
- `:adapter:outbound:support` — `StrictSettingsBinder` only. `app.security` (`SecuritySettings`, the
authentication mode included) is bound by the one strict binder every module uses (review
2026-11-01 07-10); the ArchUnit inbound/outbound rules allow that class and nothing else from the
authentication mode included) is bound by the one strict binder every module uses (since
2026-11-01); the ArchUnit inbound/outbound rules allow that class and nothing else from the
leaf.
- Spring Web/Security/Validation dependencies.
@@ -133,14 +133,14 @@ live in `app-bootstrap` (`application.yml` `spring.jackson.serialization.*` /
`spring.jackson.generator.*`); ArchUnit + effective-config tests live in
`app-bootstrap` (`JacksonSerializationPolicyTest`, `no_bigdecimal_double_constructor`).
- **S1 — Date / time / timezone (D2).** `WRITE_DATES_AS_TIMESTAMPS=false` is
- **S1 — Date / time / timezone.** `WRITE_DATES_AS_TIMESTAMPS=false` is
pinned, so `java.time` values serialize as ISO-8601 strings via `JavaTimeModule`
(`OffsetDateTime` → `"...Z"`, `LocalDate` → `"YYYY-MM-DD"`), never a numeric
epoch or `[y,m,d,...]` array. Server timezone is **UTC**: emit instants as
`OffsetDateTime`/`Instant` with a `Z` offset. Use `LocalDate` only for
date-only calendar fields. Do **not** put timezone-less `LocalDateTime` on a
response DTO — it serializes without an offset and breaks the contract.
- **S2 — Money / BigDecimal (D3).** Default scale 2, rounding `HALF_UP` unless
- **S2 — Money / BigDecimal.** Default scale 2, rounding `HALF_UP` unless
the domain documents otherwise (KRW/JPY = scale 0 with a schema note).
`WRITE_BIGDECIMAL_AS_PLAIN=true` is pinned so values never serialize in
scientific notation. Pick **one** JSON representation per API and state it in
@@ -151,17 +151,17 @@ live in `app-bootstrap` (`application.yml` `spring.jackson.serialization.*` /
- **S3 — `new BigDecimal(double)` is banned.** The `double`/`float` constructors
capture binary floating-point error (`new BigDecimal(0.1)` ≠ `0.1`). Build from
a `String` (`new BigDecimal("0.1")`) or `BigDecimal.valueOf(double)`. Enforced
by the `no_bigdecimal_double_constructor` ArchUnit rule (D3 / SBMS-C3).
by the `no_bigdecimal_double_constructor` ArchUnit rule.
- **S4 — Enum / null·empty·missing.** Request-side unknown enum →
`VALIDATION_FAILED` (B1 `read-unknown-enum-values-as-null=false`); legacy values
map through an explicit adapter, never a silent fallback. The
absent / explicit-null / value distinction is owned by the inbound web mapper
(Controller DTO → Command), expressed with `Patch<T>` (B2); `domain-core` and
`application-core` receive the already-resolved 3-state, never a wire type.
- **S5 — Out of this branch's scope.** OpenAPI drift enforcement (D5) is owned by
- **S5 — Out of this branch's scope.** OpenAPI drift enforcement is owned by
the verification suite / api-contract-baseline; removed-field-reuse ban tooling
(D6, `x-removed-fields` vs markdown catalog) is `needs-confirmation`; Avro
Schema Registry for outbox/event (D7) and response field rename/versioning
(`x-removed-fields` vs markdown catalog) is `needs-confirmation`; Avro
Schema Registry for outbox/event and response field rename/versioning
(`feature-api-compatibility-deprecation-contract`) are separate branches.
## Business rule validation contract
@@ -188,7 +188,7 @@ above and is enforced by ArchUnit + contract tests (not new runtime mechanism).
the type immutable, so no application-service or persistence path can hand out an
invariant-violating instance. A DB constraint is a backstop, never the only check
(Forbidden: "DB constraint as only invariant").
- **C3 / C7 / D9 — Persistence integrity maps to an operational error, leak-free.** A
- **C3 / C7 — Persistence integrity maps to an operational error, leak-free.** A
unique/FK/check/serialization failure maps to `DATA_INTEGRITY` / `CONFLICT` with a
**client-safe message only**. The raw SQL, constraint/index name, SQLState code,
exception class, and stack frame must never reach `error.message` or
+7 -7
View File
@@ -134,8 +134,8 @@ not in this leaf's `mainCheck` too, which ran it twice per push to main) starts
runs `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest` and
`LiveRedisIdempotencyStoreContractTest` (the `application-core` port contracts the in-memory fakes
also pass), `LiveRedisSemanticPortsTest` and `LiveRedisSemanticScriptAclProbeTest`; a skip fails it
(review 2026-11-01 05-16). The idempotency contract was on the explicit-only topology lane alone
until review 2026-11-03 RR-04-05, so the Lua state machine's stale-handle, renew-refusal and
(since 2026-11-01). The idempotency contract was on the explicit-only topology lane alone
until 2026-11-03, so the Lua state machine's stale-handle, renew-refusal and
retry cases reached a real server in no gate. `RedisTestContainer`
starts the server only when that lane names the ACL file.
@@ -183,19 +183,19 @@ that reads a cache entry cannot execute a script.
The cache's conditional writes run on the same account but on a lane of their own,
`CacheScriptLane.CACHE_SCRIPT` (`app.capabilities.cache.maximum-script-connections`, contributed by
`RedisCacheConfig` as a `RedisLaneContribution`). Do not move them back to `SCRIPT`: that lane is the
idempotency, rate-limit and lease budget, and a cache under load must not take it (review 2026-11-03
README §4, RR-04-02). Each lane's wait, refusals and reconnects are meters of `redis-runtime`
idempotency, rate-limit and lease budget, and a cache under load must not take it (decided
2026-11-03). Each lane's wait, refusals and reconnects are meters of `redis-runtime`
(`RedisLaneMetrics`, `redis.lane.*`, tag `lane`), so whether the cache stays off `SCRIPT` is a query,
not an assumption. The `DEGRADED` health order ships with `redis-runtime`, which reports the
status (`config/module-defaults/redis-runtime.yml`, RR-04-10).
status (`config/module-defaults/redis-runtime.yml`).
A Cluster transaction runs on one node, so the SDK's `RedisTransactionRunner` derives a routing key
from the watched keys (or an explicit `RedisSlotTag`) and borrows `RedisSdkLane.TRANSACTION`, which
is pinned to its key's owner, on the node that owns that slot. Routed leases are never pooled: a pooled connection is pinned to the previous caller's
node.
Settings binding is a recorded exception to capability criterion 4 (one prefix, `StrictSettingsBinder`,
review finding 05-18): `app.redis.*` is bound by `redis-runtime` with setters and `validate()`,
Settings binding is a recorded exception to capability criterion 4 (one prefix, `StrictSettingsBinder`;
decided 2026-11-03): `app.redis.*` is bound by `redis-runtime` with setters and `validate()`,
because that leaf has no project dependencies and cannot reach `StrictSettingsBinder` (support);
`app.capabilities.*` (cache, lease, rate-limit provider) is bound strictly by this leaf under the
shared capability-selector root; `app.rate-limit.*` is the HTTP boundary's switch that this leaf only
+2 -2
View File
@@ -24,7 +24,7 @@ moving a type between packages.
- Own the public call surfaces: H1 typed service clients (default), H2 generic exchange, H3 dynamic
target. H4 native engine access stays internal to `apache`, `jdk`, and `http3`.
- Blocking only: calls run on the caller's (virtual) thread through `RestClient`. The reactive stack
(`WebClient`, Reactor Netty) was removed by decision 9 (2026-09-25); do not add it back.
(`WebClient`, Reactor Netty) was removed by the 2026-09-25 owner decision; do not add it back.
- Own Named Client Profiles, runtime generations, transport SPI, deadlines, evidence-based retry,
resilience, authentication, TLS, SSRF defence, streaming lifecycle, and observability.
- Adapt external HTTP calls behind application/domain ports.
@@ -90,4 +90,4 @@ The transport port (`BlockingTransportProvider`) has one abstract contract in th
(`StableTransportProviderContractTest`, the contract lane, once per selected transport) and the
scripted fake the gateway tests stand on passes it in the default lane
(`ScriptedTransportContractTest`). A new transport, or a change to `ScriptedTransport`, inherits the
same class rather than a copy (AGENTS.md rule 6; review 2026-11-01 05-16).
same class rather than a copy (AGENTS.md rule 6).
+3 -3
View File
@@ -19,9 +19,9 @@ build choices) live in [README.md](README.md).
(HMAC-SHA-256 of the UTF-8 principal, lowercase hex).
- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` implementation (UUIDv7 via
`uuid-creator`). The operation id is also the submission event's id, and the messaging platform's
message id accepts only UUIDv7 (review 2026-11-01 06-06). Wired by `composition:durable-operation`.
message id accepts only UUIDv7. Wired by `composition:durable-operation`.
- The leaf name says "identifier"; general-purpose clock and random sources are not here.
The name is kept because Gradle paths and consumers use it (README, review 05-21).
The name is kept because Gradle paths and consumers use it (README).
- Wiring is `composition/service-runtime` (`PseudonymizationConfig`), not this leaf.
## Allowed
@@ -29,7 +29,7 @@ build choices) live in [README.md](README.md).
Declared in [build.gradle](build.gradle); the registry entry is the SSOT.
- `:application-core` — the ports both classes implement.
- `:shared-contract`, for `HmacSha256` only (review 2026-11-01 01-11). The pseudonym is the hex HMAC
- `:shared-contract`, for `HmacSha256` only. The pseudonym is the hex HMAC
of the principal; `HmacUserPrincipalPseudonymizerVectorTest` pins it to a vector computed outside
the JVM, because logs written before and after a release are joined on it.
- `:domain-core` — a feature's server-assigned id adapter implements its domain `*IdFactory` port
+1 -1
View File
@@ -39,7 +39,7 @@ Package root: `dev.caskeleton.adapter.outbound.messaging`.
removed on 2026-09-25 (see `docs/capability-status.md`).
- No JSON Schema engine (NetworkNT) on the main classpath. The evidence manifest schema check and the
capability card check (`config/messaging`) are this leaf's tests (`evidence/`); snakeyaml is
test-only (owner decision 29).
test-only (owner decision 2026-09-25).
- Do not hide use-case sequencing or business routing policy in broker adapters.
- `OutboxMessagePublishAdapter` is delegate-only and emits no dependency log. The confirmed
FAILED/DEAD transition owns the one canonical ERROR.
@@ -12,7 +12,7 @@ store adapters that implement `application-fileserver` ports. Root `AGENTS.md` a
classes that register them as beans.
`persistence-notification` follows the same rule (`platform.entity`, `platform.repository`, adapters
in `platform`), so the two capability leaves read the same way (review 04-16).
in `platform`), so the two capability leaves read the same way.
## Rules
@@ -23,7 +23,7 @@ in `platform`), so the two capability leaves read the same way (review 04-16).
extend `AssignedIdEntity` (`Persistable<UUID>`). Without it `save` merges — a SELECT before every
insert, and a second insert under an existing id overwrites the row instead of failing on the
primary key. A new `@Version` column may stay primitive `long`; newness comes from
`Persistable`, not from the version (review 04-17).
`Persistable`, not from the version.
- **No policy here.** Retry budgets, lease lengths and other decisions belong to
`application-fileserver` and arrive as port arguments. A claim token or other fence travels in
the port type (`CleanupItem.claimToken`), never in a field of the adapter.
@@ -55,13 +55,13 @@ in `platform`), so the two capability leaves read the same way (review 04-16).
- Port contracts live in `application-fileserver` testFixtures (`*PortContract`, and
`FileQuotaLedgerContract` for the three quota ports, which share one table). The in-memory fakes
and the PostgreSQL tests both extend them; every port this leaf implements has one
(`docs/testing/TESTING_STRATEGY.md` 9.3). The PostgreSQL side of the seven added in review
2026-11-03 RR-01-04 is tagged `jpa-contract` and runs in persistence-jpa's
(`docs/testing/TESTING_STRATEGY.md` 9.3). The PostgreSQL side of the seven added on
2026-11-03 is tagged `jpa-contract` and runs in persistence-jpa's
`jpaPlatformContractTest` lane on `FileserverPostgreSqlStack`, whose clock a case moves.
- The real-PostgreSQL tests are still in `persistence-jpa`'s `postgresqlIntegrationTest` source
set, which owns the container and Flyway wiring, and the JPA readiness card
(`config/jpa/readiness-cards.yaml`, checked by `JpaReadinessRegistryTest`) names them as that
leaf's tasks — moving them means moving the card's tasks and selectors with them (review 04-04):
leaf's tasks — moving them means moving the card's tasks and selectors with them:
`postgresqlFileserverMigrationIntegrationTest`, `postgresqlFileserverMetadataIntegrationTest`,
`postgresqlFileserverReclamationIntegrationTest`
(`./gradlew :adapter:outbound:persistence-jpa:<lane> --console=plain`).
+17 -17
View File
@@ -218,8 +218,8 @@ should not exist.
[application-core/CLAUDE.md](../../../application-core/CLAUDE.md)).
- **DB drivers** (`org.postgresql..`, `org.h2..`) or **`org.flywaydb.database.postgresql..`** —
those are vendor-specific and belong only in this module's matching vendor package (`.postgresql`,
`.h2`); NoSQL-specific dependencies belong only in their own future modules
(persistence-multi-db-extensibility D3). This is enforced by ArchUnit
`.h2`); NoSQL-specific dependencies belong only in their own future modules.
This is enforced by ArchUnit
`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL` and `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2` in
`CleanArchitectureTest`.
- NoSQL adapter code. MongoDB/Redis/DynamoDB adapters are sibling modules, not children of this module.
@@ -236,19 +236,19 @@ should not exist.
| `inRead` | `REQUIRED` | `READ_COMMITTED` (pool) | `true` | `app.persistence-jpa.transaction.read-timeout` (30 s) |
| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED` (pool) | `false` | 30 s, fixed |
Isolation is pinned on the pool, not on the templates (review 09-05): the templates use
Isolation is pinned on the pool, not on the templates: the templates use
`ISOLATION_DEFAULT`, the module defaults set `spring.datasource.hikari.transaction-isolation:
TRANSACTION_READ_COMMITTED` (applied once per physical connection), and
`HikariPoolConstraintValidator` refuses to boot with any other level. Naming the level per template
made Spring call `getTransactionIsolation()` at every begin, which pgjdbc answers with a
`SHOW TRANSACTION ISOLATION LEVEL` round trip.
Every mode is time-bounded (review 04-10). Spring hands the remaining time to each statement, so a
Every mode is time-bounded (since 2026-11-01). Spring hands the remaining time to each statement, so a
slow query or lock wait is cancelled by the server (`57014` → `DB_QUERY_CANCELED`), and a deadline
that passed before the next statement gets the same code: Spring's `TransactionTimedOutException`
on the JDBC path, and on the JPA path (`JpaTransactionManager`, production) Hibernate's own
`TransactionException`, which has no SQLState and is classified because `SpringTransaction` knows
its deadline passed (`translateAfterDeadline`, review RR-03-03). A business exception thrown after
its deadline passed (`translateAfterDeadline`). A business exception thrown after
the deadline is passed on unchanged.
Pre-built templates are immutable after construction so concurrent callers cannot
@@ -262,7 +262,7 @@ When an actual ambient transaction exists it MUST throw
committed. A commit failure propagates the transaction exception and no success value
is returned to the caller.
### `inNew` pool-sizing constraint (D12 of feature-application-port-usecase-contract)
### `inNew` pool-sizing constraint (feature-application-port-usecase-contract)
`REQUIRES_NEW` acquires a NEW physical JDBC connection while pinning the outer
transaction's connection. Provision the pool to satisfy:
@@ -274,7 +274,7 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
Loop-per-record `inNew` calls are forbidden (pool exhaustion + deadlock risk).
Batch records inside ONE `inNew`, or move the loop outside the transaction.
## Persistence failure translation contract (feature-persistence-failure-baseline D1)
## Persistence failure translation contract (feature-persistence-failure-baseline)
A raw Spring `DataAccessException` (and the JPA exception / SQLState / constraint name
inside it) must never reach the presentation layer. The
@@ -306,7 +306,7 @@ framework-neutral `shared.error.PersistenceFailureException` carrying one of the
| `23513` | `DB_CHECK_VIOLATION` | H2 (`.h2` package) — H2 reports CHECK as 23513, not the standard 23514 the core table maps |
| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2 collapses statement and lock timeout into one state |
The PostgreSQL rows are not a second table (review 04-06). `PostgreSqlSqlStateErrorMapping` derives
The PostgreSQL rows are not a second table: before 2026-11-01 a hand-kept second table had already drifted. `PostgreSqlSqlStateErrorMapping` derives
them from `PostgreSqlFailureClassifier` (SQLState → `FailureCategory`) and
`FailureCategory.operationalError()` (category → code) — the same classification the library
`PostgreSqlExceptionTranslator` uses — leaving out the standard rows above, categories with no
@@ -315,7 +315,7 @@ state, add it to `PostgreSqlState` and the classifier; `SqlStateClassificationPa
the two paths disagree on any state.
**No SQLState, classified by type:** a lost `@Version` race (`OptimisticLockingFailureException`,
JPA `OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT` (409, review 04-05); an expired Spring
JPA `OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT` (409); an expired Spring
transaction deadline (`TransactionTimedOutException`) → `DB_QUERY_CANCELED`; any other persistence
failure (JPA, Spring data-access or Spring transaction exception) of a transaction
`SpringTransaction` began, once its deadline has passed → `DB_QUERY_CANCELED`.
@@ -337,16 +337,16 @@ PostgreSQL `57P01`, `57P02`) or a transport break with no SQLState becomes
## Persistence auditing contract (feature-persistence-auditing-contract)
Audit metadata (`created_at` / `updated_at` / `created_by` / `updated_by`, D3) is an
infrastructure concern that must never reach `domain-core` (D2). It lives only on the
Audit metadata (`created_at` / `updated_at` / `created_by` / `updated_by`) is an
infrastructure concern that must never reach `domain-core`. It lives only on the
`audit/AuditableEntity` `@MappedSuperclass`; a domain aggregate persistence entity opts in
by extending it (D6 — e.g. the sample `WorkLogEntity`). The domain aggregate itself carries
by extending it (e.g. the sample `WorkLogEntity`). The domain aggregate itself carries
zero audit fields, enforced by ArchUnit `domain_is_pure` (no `jakarta.persistence..`) plus
`domain_entities_do_not_carry_audit_fields` (no `createdAt`/`updatedAt`/`createdBy`/`updatedBy`
fields under `..domain..`).
- **Capture = Manual explicit-set (D1 current default).** The repository adapter
constructor-injects `Clock` (D4) and `AuditContextPort` (D5) and stamps audit on `save`:
- **Capture = Manual explicit-set (current default).** The repository adapter
constructor-injects `Clock` and `AuditContextPort` and stamps audit on `save`:
INSERT (null version) → `initializeAudit(now, actor)`; UPDATE (non-null version) →
carry the persisted `created_*` forward + `applyModification(now, actor)`.
`created_*` is `updatable = false`.
@@ -354,17 +354,17 @@ fields under `..domain..`).
seam and falls back to `"system"` when no principal is bound (scheduler / Flyway / anonymous).
The actor's value semantics are owned by feature-authentication-authorization-contract
(UNSUPPORTED here); the type is fixed to `String`.
- **Excluded (D6).** Infra/immutable entities such as `IdempotencyRecordEntity` (own
- **Excluded.** Infra/immutable entities such as `IdempotencyRecordEntity` (own
`created_at`, no `updated_at`) do NOT extend `AuditableEntity`. `version`/optimistic-lock
is owned by feature-persistence-failure-baseline / feature-transaction-concurrency-contract,
not by this audit base.
- **Growth path (D1, deferred).** There is no second auditing implementation in the tree. If
- **Growth path (deferred).** There is no second auditing implementation in the tree. If
manual stamping becomes too error-prone, migrate the canonical `AuditableEntity` contract
atomically to Spring Data listeners while preserving its `created_*`/`updated_*` schema, actor
bound, `Clock`, and `AuditContextPort` semantics. Bulk/native `@Query` UPDATEs bypass listeners
too, so they must continue to stamp audit columns explicitly.
## MapStruct generated mapper exemption (D9 of feature-architecture-enforcement-rules)
## MapStruct generated mapper exemption (feature-architecture-enforcement-rules)
If MapStruct is introduced for persistence mappers, the generated mapper class will
be annotated with `javax.annotation.processing.Generated`. Architecture rules that
@@ -50,8 +50,8 @@ design package's assumed module layout onto this leaf lives in
## Allowed
- Two project dependencies. `shared-contract` for the `Sha256` and `HmacSha256` helpers (tenant
observable key, admin command digest, credential fingerprint, keyset cursor tag — review
2026-11-01 01-11; `MongoDigestOutputTest` pins the outputs). `application-core`, for
observable key, admin command digest, credential fingerprint, keyset cursor tag;
`MongoDigestOutputTest` pins the outputs). `application-core`, for
`SecretSourcePort` only. The registry entry's `allowed_dependencies` is
`["application-core", "shared-contract"]`, matching what the build actually uses; the
bridge in `MongoProfileClientSettingsAutoConfiguration` resolves a typed profile's `uri-secret`
@@ -6,7 +6,7 @@
`src/config/architecture/modules.json`.
- Focused test: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`.
- Package root: `dev.caskeleton.adapter.outbound.persistence.notification`. The package rule is
the one `persistence-fileserver` uses, so both capability leaves read the same way (review 04-16):
the one `persistence-fileserver` uses, so both capability leaves read the same way:
- `platform.entity` — JPA rows only.
- `platform.repository` — Spring Data interfaces and the SQL text they run (`RecipientClaimSql`).
- `platform` — the store adapters (`Jpa*`, `Jdbc*`, the inbox's `JpaNotificationInbox` and its
@@ -17,7 +17,7 @@
package; an entity never leaves the leaf (the ports carry records). Visibility no longer says so,
so a rule does: `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`, run over the production
graph by `JpaProductionArchitectureTest` (app-bootstrap `architectureTest`) for this leaf and
`persistence-fileserver` (review RR-03-09).
`persistence-fileserver`.
## Where the tests are
@@ -37,7 +37,7 @@ without a contract (the serving-state read model, consent, inbox), and why, are
## Rules
- **Every write joins the caller's transaction.** A store write starts with
`CallerTransaction.require("<what>")`; the use case owns the transaction (owner decision 33).
`CallerTransaction.require("<what>")`; the use case owns the transaction (owner decision 2026-09-25).
- **Migrations** live in `src/main/resources/db/migration/jpa/notification-platform` and run as
their own Flyway stream (`NotificationSchemaStream`, history table
`flyway_jpa_notification_history`). An applied file is never edited: add the next `V<n>__`, pin
+2 -2
View File
@@ -27,9 +27,9 @@ Package roots: `dev.caskeleton.adapter.outbound` and
Fileserver's `LocalStorageFailures`); nothing here knows an error code.
- Own `StrictSettingsBinder`, the one strict settings binding. It is also the only support class an
inbound leaf may use: `adapter:inbound:web` binds `app.security` with it (registry edge and a
class-named ArchUnit exemption, review 2026-11-01 07-10). An empty value for a setting the type
class-named ArchUnit exemption, since 2026-11-01). An empty value for a setting the type
has (`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`) binds as unset; an empty value under a name
the type does not have is still refused (review 15절, r3-I).
the type does not have is still refused (decided 2026-11-03).
- Keep feature-specific clients and routing policies in their owning leaf.
## Boundaries
+1 -1
View File
@@ -46,7 +46,7 @@ Package root: `dev.caskeleton.bootstrap`.
## Package layout
The rules below exist because their absence is what produced the drift this module was reviewed for
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`, BOOT-006 / BOOT-007). Half the
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). Half the
capabilities lived under `autoconfigure/` and half at the package root; `Settings` classes were split
between a `settings/` package and their feature packages with no stated rule; and the same
decomposition problem was solved two different ways in the same leaf — Notification as nine focused
+15 -16
View File
@@ -37,11 +37,11 @@ Package root: `dev.caskeleton.application`.
- Controller request/response DTOs.
- JPA entities and Spring Data repositories.
- HTTP status, transport types (`org.springframework.web..`).
- `org.springframework.transaction.annotation.Transactional` (use `TransactionPort` instead — D3).
- `org.springframework.transaction.annotation.Transactional` (use `TransactionPort` instead).
- `org.springframework.context.ApplicationContext` — direct dependency forbidden
(`getBean(Class)` reflection-style bypass blocked by ArchUnit D11). String-key
(`getBean(Class)` reflection-style bypass blocked by the ArchUnit rule `application_does_not_depend_on_application_context`). String-key
bean lookup / `Class.forName(String)` / `BeanFactory#getBeansOfType` remain
ArchUnit's static-analysis blind spot per D12 — guard via code review checklist.
ArchUnit's static-analysis blind spot — guard via code review checklist.
- Lombok (`lombok..`) — also forbidden in `domain-core`. Within `application-core`,
Lombok is currently not in scope for the contract; if you intend to use it,
weigh the bytecode opacity cost first.
@@ -171,7 +171,7 @@ Enforcement:
is part of adding it.
- Rejected alternatives: allowing only the listed top-level packages (every derived feature would
have to edit the template's list — a merge conflict per feature), and a separate
`application-platform` leaf for the platform packages (review 2026-11-01 01-10 (b): clearer
`application-platform` leaf for the platform packages (weighed in the 2026-11-01 maturity review: clearer
boundary, but more registry edges than a naming rule needs).
## Canonical use case shape
@@ -239,7 +239,7 @@ beans but no enforcing advisor fails startup too (`composition:service-runtime`
Both `inWrite` and `inRootWrite` satisfy the direct boundary fitness rule for a
`WRITE_REPOSITORY + WRITE` use case. READ and REQUIRES_NEW mappings remain exclusive.
### Callback signature contract (D11)
### Callback signature contract
`TransactionPort` callbacks are `Supplier<T>` / `Runnable` and cannot throw checked
exceptions. This matches Spring's `TransactionCallback<T>` constraint. Wrap domain
@@ -247,7 +247,7 @@ checked exceptions into `RuntimeException` subclasses
(`DomainException extends RuntimeException`); `IOException` → `UncheckedIOException`;
`SQLException` is auto-translated by Spring's `DataAccessException` hierarchy.
### `inNew` pool-sizing constraint (D12)
### `inNew` pool-sizing constraint
`inNew` acquires a new physical JDBC connection. Pool size MUST satisfy:
@@ -285,9 +285,8 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
leaves the record to its holder: the holder's first late `complete`/`markFailed` is recorded, a
lease that ran out is not renewed and a claim whose lease ran out is not started — both answer
`LEASE_EXPIRED`, not `NOT_OWNER`, and the executor turns a refused start into "not applied"
(owner decision 2026-11-04, re-review RR5-01-02·03). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
(owner decision 2026-11-04). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases.
- Every transition names the operation its record was claimed under (`IdempotencyOwner.claimOperationId()`).
Another one is `OPERATION_CONFLICT` in every store and changes nothing; so is an inspection that
brings the owner token under another operation (owner decision 2026-11-06).
@@ -308,32 +307,32 @@ The read side has two equally-valid shapes; pick per read, do not force one:
| **Through-aggregate** (default for simple reads) | domain aggregate via a `*Repository` port | read shape == write aggregate **and** the aggregate is the minimal invariant boundary (no lazy collections needed) | `QueryUseCase` → repository port → `WorkLog` |
| **Projection (CQRS-lite)** | application-layer projection DTO via a `*QueryPort` | read shape ≠ write, or to skip aggregate hydration / lazy-collection joins | `QueryUseCase` → `*QueryPort` → `WorkLogSummary` (record); query via JPQL `SELECT new` / JdbcTemplate |
- **D1 — purity guardrail (core, machine-enforced):** a read port whose simple name ends
- **Purity guardrail (core, machine-enforced):** a read port whose simple name ends
with `QueryPort` MUST return application-layer projection DTOs only — never a domain
aggregate, JPA entity, or web type, **including through generic type arguments**
(`List<DomainType>`). Enforced by ArchUnit `query_ports_do_not_leak_domain_jpa_or_web_types`.
Projection usage itself is **opt-in**, not a forced default; the demo lives in
`sample-portfolio` (`WorkLogSummaryQueryPort` / `WorkLogSummary`).
- **D3 — Strict ceremony:** every read goes through a `QueryUseCase` bean. There is no thin
- **Strict ceremony:** every read goes through a `QueryUseCase` bean. There is no thin
web→read-port path — that would bypass the mandatory `@UseCaseCapability` fitness function.
- **D4 — transaction:** reads default to `TransactionPort.inRead`. A no-tx (autocommit) read
- **Transaction:** reads default to `TransactionPort.inRead`. A no-tx (autocommit) read
is an opt-in only when `spring.jpa.open-in-view=false` is confirmed **and** the read is
projection-only (no lazy access) **and** a single statement; otherwise keep `inRead`.
- **D5 — capability:** a repository-backed projection read is still
- **Capability:** a repository-backed projection read is still
`repositoryAccess = READ_REPOSITORY`. "Projection vs aggregate" is the return *shape* axis,
orthogonal to the repository-access *level* axis — no new enum. Outbound-HTTP reads (no
repository) stay `RepositoryAccess.NONE`.
- Full CQRS with a separate physical read store (**D2**) is out of scope — escalation only.
- Full CQRS with a separate physical read store is out of scope — escalation only.
## ArchUnit guardrails (enforced)
- `application_does_not_depend_on_adapters_or_transport`
- `application_does_not_use_spring_transactional_annotation`
- `application_does_not_depend_on_application_context` (D11)
- `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` (query-bypass D1 — `*QueryPort` return purity)
- `query_ports_do_not_leak_domain_jpa_or_web_types` (`*QueryPort` return purity)
## Test
+3 -3
View File
@@ -18,11 +18,11 @@ grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의
같은 절과 이유가 같다(vendored 플랫폼, MSG-023 §6.2와 같은 배치).
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
## Capability grade와 feature flag
@@ -61,7 +61,7 @@ property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
리뷰 규칙이다.
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
+7 -7
View File
@@ -41,13 +41,13 @@ server profile·named channel profile·method size profile·method policy 기본
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`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가 같은 이유로 고른 배치(MSG-023 §6.2)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
같은 규칙인지 함께 본다.
## 증거 등급 — testkit이 하나의 leaf인 이유
@@ -95,7 +95,7 @@ soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위
## application이 이 family에 도달하는 경로
`messaging:*`의 MSG-015(bridge 부재)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
```text
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
@@ -164,9 +164,9 @@ These keys are not in `docs/registries/env-keys.yaml`: no `app.grpc.platform.*`
optional build is not part of the shipped runtime. They join the registry when a composition root
adopts the platform.
**Why the starter assembles the interceptor (03-11 (b)), and not (a).** The review proposed (a):
delete the flag and judge by whether a ledger bean exists. (b) was chosen and is recorded in
ADR-GRPC-004 (re-review 2026-11-03, RR-02-07): the flag stays and means what it says — when true, the
**Why the starter assembles the interceptor (option (b)), and not (a).** The 2026-11-01 maturity review proposed (a):
delete the flag and judge by whether a ledger bean exists. (b) was chosen on 2026-11-03 and is recorded in
ADR-GRPC-004: the flag stays and means what it says — when true, the
decision function is assembled and its TTL comes from configuration. (a) would have removed the false promise but left every adopter to rebuild the same
assembly and TTL validation by hand; (b) keeps that in one place. The interceptor bean has no
`@ConditionalOnMissingBean` on purpose: a replacement would silently ignore `operation-ledger-claim-ttl`.
@@ -182,7 +182,7 @@ its typed service adapter: `decide(...)` before the mutation, `recordCommit(...)
transaction, `recordFailure(...)` on a terminal failure. Both record calls take the `GrpcClaimToken`
the `PROCEED` decision carried: a commit by an attempt whose claim was taken over is refused (its
transaction rolls back) and its failure is ignored, so a slow owner cannot write over the attempt that
took its claim (re-review RR-02-04, ADR-GRPC-004).
took its claim (ADR-GRPC-004).
**Purge scheduling is the adopter's.** `GrpcOperationLedgerRetention.purgeExpired(now)` deletes
expired finished rows in bounded batches (500 per statement) until a batch comes back short. The
+8 -8
View File
@@ -26,21 +26,21 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
`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도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(MSG-023 §6.2), `messaging:*` leaf는
계층이 아니라 자기 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 (review 2026-11-01 06-01)
### Publish retryability of authentication and authorization
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
@@ -63,7 +63,7 @@ registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(재리뷰 2026-11-03 RR-05-07).
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
## Public surface 정책
@@ -95,7 +95,7 @@ RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
qualification/support 상태를 함께 변경한다.
## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료)
## 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` 경로는 이제 존재한다.
@@ -110,7 +110,7 @@ lease/transport/outcome normalization/observation은 platform 중앙 publish pat
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical
**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
@@ -137,7 +137,7 @@ adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
증거가 아니다.
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
Experimental에서도 금지다(MSG-022).
Experimental에서도 금지다.
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
있을 때만.
+3 -3
View File
@@ -24,14 +24,14 @@ envelope shape, metric cardinality bounds, tracing seam, domain-context propagat
- Tracing contract types (`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C
`traceparent` value type and the span-error-recording seam (feature-distributed-tracing-contract; the OTel
tracer runtime is a fork-activated seam, so these stay Java-stdlib-only).
- Stdlib helpers every leaf used to copy (review X2-P1-5, X2-P1-4b, X1-#9): `digest/Sha256` (the
- Stdlib helpers every leaf used to copy (moved here in the 2026-09-25 review follow-up): `digest/Sha256` (the
SHA-256 digest value and the one `MessageDigest.getInstance("SHA-256")`), `digest/HmacSha256`
(sign and constant-time verify), `retry/Backoff` (capped exponential ceiling; "full jitter" means
`U[0, ceiling]` and nothing else). Vendored `messaging:*` and the optional gRPC build do not depend
on this module and keep their own copies; each family's CLAUDE.md says why (a different product,
MSG-023). Every template leaf that needs one of these has the `shared-contract` edge and uses them
decided after the 2026-08-14 messaging module review). Every template leaf that needs one of these has the `shared-contract` edge and uses them
instead of copying: identifier, persistence-mongo, application-objectstorage and redis-sdk took the
edge for exactly this (review 2026-11-01 01-11, decision in the review README §15), each with a test
edge for exactly this (decided 2026-11-03), each with a test
that pins its output to a vector computed outside the JVM.
- `observability/MdcKeys`: the snake_case MDC key names (registry `docs/registries/mdc-keys.yaml`)
every transport puts a request's correlation under — web, GraphQL, STOMP and gRPC alike.