From b7d131045993b9b9572f6e27235ca751c65aeb0e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 00:24:58 +0900 Subject: [PATCH 1/2] =?UTF-8?q?fix(scripts):=20=EC=9D=B4=EB=A0=A5=20?= =?UTF-8?q?=EA=B2=80=EC=82=AC=EA=B0=80=20=EC=95=9E=EB=A7=90=20=EC=97=86?= =?UTF-8?q?=EB=8A=94=20=EB=B2=88=ED=98=B8=20=EB=AA=A9=EB=A1=9D=C2=B7?= =?UTF-8?q?=EB=A6=AC=EB=B7=B0=20=EC=98=81=EC=97=AD=C2=B7=EB=AC=B6=EC=9D=8C?= =?UTF-8?q?=20=EB=B2=88=ED=98=B8=EB=A5=BC=20=EC=9E=A1=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: check-work-docs.py --history는 리뷰·라운드 낱말 바로 뒤의 NN-NN만 발견 번호로 본다. 그래서 앞말 없이 나열한 "(05-01, 04-01, 06-01)", "리뷰 01 영역 5.2절", "sample P30 결정"을 놓친다. 2026-11-07 docs/manual 이력 걷어내기에서 검사가 찾은 16줄을 고친 뒤 docs-writing.md 9절대로 grep으로 다시 읽으니 이 꼴 3줄이 더 있었다. 고른 방법: 패턴 셋을 더한다. - 쉼표+공백이나 가운뎃점으로 이은 NN-NN 둘 이상. 콜론 뒤 줄 범위 ("Foo.java:10-12,20-24")와 공백 없는 쉼표 범위는 잡지 않는다 - "리뷰 NN 영역", "NN 영역 N.N절" - 2026-09-25 리뷰 후속 묶음 번호 P10~P49와 "W3-P30" 꼴 버린 대안: - 홀로 선 NN-NN 하나까지 잡기. 장 번호·범위 같은 보통 숫자가 걸린다 - P 뒤 두 자리를 모두 잡기. P95·P99 같은 백분위수가 걸린다 위험·한계: 검사는 여전히 아는 꼴만 잡는다. P1~P9 묶음 번호는 우선순위 P0~P3과 겹쳐 잡지 않는다. 문서가 자기 목록에 P10~P49 번호를 붙이면 이력이 아니어도 잡는다(docs/study/graphql-walkthrough.ko.md의 할 일 번호 P10·P11). 지금 검사 대상인 docs/work 본문과 docs/manual에는 그런 줄이 없다. 이 커밋만 있으면 --history docs/manual이 19줄, rc=1이다. 다음 커밋이 그 19줄을 걷어낸다. 기본 모드(docs/work 본문, 루트 CLAUDE.md)는 0줄 그대로다. 검증(desktop worktree, 다음 커밋까지 얹은 트리 8ff82a67과 같은 스크립트): - 기준 커밋 73d39212의 docs/manual: 옛 스크립트 16줄, 새 스크립트 19줄. 더 잡은 3줄은 03-placement.md:40·:54, 05-idempotency.md:93이다 - 오탐 시험 14줄: 보통 문장 8줄(p95·P99, 콜론 뒤 줄 범위, 날짜 쌍, 홀로 선 번호, 장 번호)은 안 잡고 이력 6줄은 잡았다 - 노트북에서 docs/reviews 밖 *.md에 새 패턴을 돌려 걸린 65줄을 읽었다. 위 할 일 번호 4줄 말고는 모두 실제 이력 번호였다 - 기본 모드 rc=0, 본문 이력 0줄 --- scripts/check-work-docs.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index ed88b94b..1789f6db 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -87,6 +87,15 @@ HISTORY_PATTERNS = [ ("finding number after a review or round word (리뷰 02-01)", re.compile(r"(?:리뷰|라운드|(? Date: Sat, 7 Nov 2026 00:25:22 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs(manual):=20=EB=B3=B8=EB=AC=B8=EC=97=90?= =?UTF-8?q?=20=EB=82=A8=EC=9D=80=20=EC=9D=B4=EB=A0=A5=20ID=2019=EC=A4=84?= =?UTF-8?q?=EC=9D=84=20=EB=82=B4=EC=9A=A9=EA=B3=BC=20=EB=82=A0=EC=A7=9C?= =?UTF-8?q?=EB=A1=9C=20=EB=B0=94=EA=BE=BC=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: docs/manual 본문 19줄이 "리뷰 02-01 결정", "1라운드 06-01·06-03", "리뷰 README 13.2, 09-02", "(05-01, 04-01, 06-01)", "sample P30 결정"처럼 지난 리뷰 번호만으로 이유를 댄다. 그 리뷰를 모르는 독자는 따라갈 수 없고, docs-writing.md 4절 6단계가 금지한다. 16줄은 --history 검사가 찾았고, 3줄은 걷어낸 뒤 grep으로 다시 읽어 찾았다. 고른 방법: 문장의 뜻은 두고 괄호만 바꾼다. - 문장이 이미 내용을 말하는 곳(6줄)은 괄호를 지운다 - 지난 일이 근거인 곳은 날짜와 일어난 일로 바꾼다. 예: "2026-11-01 소유자 결정", "2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다" - README 제목 "1라운드 수정으로 생긴 패턴 (리뷰 README 13절)"은 "리뷰 뒤 첫 수정으로 생긴 패턴"으로 바꾼다. 이 제목을 가리키는 링크는 repo에 없다 걷어낸 번호와 원래 괄호, 원래 리뷰 문서와 발견 내용은 docs/work/evidence.md 8절에 표로 더했다(2026-11-06 표와 같은 칸). 버린 대안: 리뷰 문서로 링크 걸기. 본문이 다시 이력을 가리킨다. 위험·한계: 날짜와 "전에는" 문장은 1101 README 13절·15절과 영역 문서의 색인 문장에서 옮겼다. 코드로 다시 확인하지는 않았다. evidence.md 9절 T4-1 행("16줄은 고치지 않음")은 그때의 기록이라 고치지 않았다. 검증(desktop worktree, 이 커밋과 같은 트리 8ff82a67): - python3 scripts/check-work-docs.py --history docs/manual lines with history IDs: 0, rc=0 - python3 scripts/check-work-docs.py rc=0(분량, 본문 이력 0, 링크) - python3 scripts/check-work-docs.py --links docs/manual docs/work 링크 113개, 깨진 것 0 - ./gradlew :app-bootstrap:documentContractTest rc=0, 22개 클래스 66건 통과, 실패·skip 0. docs/manual과 docs/work를 읽는 테스트는 없다 (src의 Java·Gradle에서 파일 이름·폴더 경로 grep, 주석 2곳만 걸림) - grep -e 리뷰 -e 라운드 -e 결정 docs/manual/*.md로 남은 줄을 읽었다. 모두 날짜와 내용이 있는 문장이다 --- docs/manual/03-placement.md | 4 ++-- docs/manual/04-persistence.md | 4 ++-- docs/manual/05-idempotency.md | 9 +++++---- docs/manual/06-errors.md | 4 ++-- docs/manual/07-authorization.md | 9 +++++---- docs/manual/08-testing.md | 6 ++++-- docs/manual/09-outbox-events.md | 10 +++++----- docs/manual/README.md | 6 +++--- docs/work/evidence.md | 27 ++++++++++++++++++++++++++- 9 files changed, 54 insertions(+), 25 deletions(-) diff --git a/docs/manual/03-placement.md b/docs/manual/03-placement.md index 01ecf57a..3344a841 100644 --- a/docs/manual/03-placement.md +++ b/docs/manual/03-placement.md @@ -37,7 +37,7 @@ - **예외**: ② — 여러 서비스가 쓰는 플랫폼 기능, 배포마다 켜고 끄는 기능, 자기 설정 prefix와 자기 저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(`AGENTS.md`, 10장). - **다시 볼 조건**: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트 - 시간이 문제가 되면 ①을 ②로 옮긴다(리뷰 01 영역 5.2절). + 시간이 문제가 되면 ①을 ②로 옮긴다. ### 판단: ③을 써도 되나 @@ -51,7 +51,7 @@ | 계층 | 패키지 | 하위 패키지 | | --- | --- | --- | | domain | `dev.caskeleton.domain.` | fake·계약은 testFixtures `dev.caskeleton.domain..testkit` | -| application | `dev.caskeleton.application.` | 종류별 하위 패키지(`command`, `usecase`, `port`)를 만들지 않는다. 기능별 한 패키지(sample P30 결정과 같다) | +| application | `dev.caskeleton.application.` | 종류별 하위 패키지(`command`, `usecase`, `port`)를 만들지 않는다. 기능별 한 패키지(`sample-portfolio`도 2026-09-29에 이 배치로 옮겼다) | | outbound | `dev.caskeleton.adapter.outbound..` | | | inbound | `dev.caskeleton.adapter.inbound.web.` | | | bootstrap | `dev.caskeleton.bootstrap.autoconfigure.` | `@AutoConfiguration`만(`BOOTSTRAP_AUTOCONFIGURE_STEREOTYPES_ARE_AUTO_CONFIGURATIONS`) | diff --git a/docs/manual/04-persistence.md b/docs/manual/04-persistence.md index f009b847..8078aa70 100644 --- a/docs/manual/04-persistence.md +++ b/docs/manual/04-persistence.md @@ -127,8 +127,8 @@ capability 스트림 db/migration/jpa/ 각자 histor - 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다 (`docs/jpa/migration-guide.md`). - 같은 스트림 안에서 기존 두 버전 사이에 끼워야 하면 소수 버전(`V8_1`)을 쓴다. 샘플 테스트 일부가 운영 - 스트림과 샘플 스트림을 한 목록으로 합치는데, 정수 V9 이상은 운영이 이미 쓰고 있어서 `V8_1`을 골랐다 - (리뷰 README 13.2, 09-02). + 스트림과 샘플 스트림을 한 목록으로 합치는데, 정수 V9 이상은 운영이 이미 쓰고 있어서 2026-11-01 샘플에 + 포스터 제목 유일 제약을 더할 때 `V8_1`을 골랐다. - 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`V8_1`의 `DO $$` 블록). 조용히 지우지 않는다. - 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존 diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md index 72cde83c..45b62dd5 100644 --- a/docs/manual/05-idempotency.md +++ b/docs/manual/05-idempotency.md @@ -85,13 +85,13 @@ claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 소유자 결정). 거꾸로 말하면 `replay-ttl`(`APP_IDEMPOTENCY_TTL`)은 lease 이상, `failure-retention` 이하로 둔다. -409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시 +409를 `retryable=true`로 바꾼 이유(2026-11-01 소유자 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시 보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다. ## 결과 불명을 만드는 곳마다 같은 규칙 -리뷰가 찾은 반복 원인 1번이 "결과 불명을 확실함으로 기록"이었다(05-01, 04-01, 06-01). 새 경계를 -만들 때 아래 질문에 답한다. +2026-11-01 성숙도 리뷰가 찾은 반복 원인 첫째가 "결과 불명을 확실함으로 기록"이었다. 알림 발송·DB +커밋·메시지 relay 세 경계에서 같은 실수가 나왔다. 새 경계를 만들 때 아래 질문에 답한다. - **고르는 기준**: 실패한 호출이 **상대편에서 이미 효과를 냈을 수 있는가**. - **기본값**: 그럴 수 있으면 "결과 불명"으로 분류한다. 재시도 가능(`retryable=true`)으로 분류하지 @@ -101,7 +101,8 @@ claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 - 메시지 발행 응답 없음 → `OutboxPublishAmbiguousException`(application-core `outbox`) - 알림 발송 시작 뒤 crash → 재발송하지 않고 reconcile(application-notification evidence 모델) - **예외**: 요청이 상대에게 **도달하기 전**에 실패한 것이 증명되면(연결 수립 실패, 실행 전 거부) - 재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(리뷰 05-17). + 재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(2026-11-01 성숙도 리뷰가 + Redis 연결 수립 실패에서 찾았다). - 불명 상태를 푸는 방법(reconcile, 키 재전송, 운영자 확인)을 runbook에 적는다(`docs/runbooks/`). ## 지금 이해하면 되는 것 diff --git a/docs/manual/06-errors.md b/docs/manual/06-errors.md index d80efb4b..20a36e35 100644 --- a/docs/manual/06-errors.md +++ b/docs/manual/06-errors.md @@ -42,8 +42,8 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로 | DB·외부 의존 실패 | adapter가 shared-contract carrier(`PersistenceFailureException`, `DependencyFailureException`)로 | 분류표대로(04·05장) | - `IllegalArgumentException`을 "서버 조립이 틀렸다"에 쓰지 않는다. web은 그것을 400으로 바꾸고 WARN - 한 줄만 남긴다(`GlobalExceptionHandler`). 서버 결함이 클라이언트 오류 통계에 섞여 경보가 울리지 않는다 - (리뷰 01-04). 서버 쪽 잘못은 `IllegalStateException`(500, 로그)이다. + 한 줄만 남긴다(`GlobalExceptionHandler`). 서버 결함이 클라이언트 오류 통계에 섞여 경보가 울리지 않는다. + 서버 쪽 잘못은 `IllegalStateException`(500, 로그)이다. - 메시지는 로그용이다. 클라이언트에는 코드와 category별 고정 문구(`ClientErrorMessages`)만 간다. 메시지에 SQLState·내부 경로·토큰을 넣어도 클라이언트에 새지 않지만, 로그 정책은 지킨다. diff --git a/docs/manual/07-authorization.md b/docs/manual/07-authorization.md index c1f0bd40..ca6d36eb 100644 --- a/docs/manual/07-authorization.md +++ b/docs/manual/07-authorization.md @@ -25,7 +25,8 @@ | 프록시 가능 | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java` | 검사 자동 설정은 인증 체인(`WebSecurityAutoConfiguration`)과 **분리**되어 있다. 서비스가 자기 인증 -방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(1라운드 07-03 수정). +방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(2026-11-01부터. 전에는 샘플이 인증 체인 자동 설정을 +빼자 권한 검사도 함께 빠졌다). ### 지켜야 할 것 셋 @@ -48,8 +49,8 @@ ### 역할은 어디서 오나 JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `resource_access..roles`만 -읽는다. audience는 필수다(1라운드 02-03 수정). 같은 issuer의 다른 client가 같은 이름의 역할을 정의해도 -이 서비스 권한이 되지 않는다(`JwtToAuthenticatedPrincipalConverter`, `docs/runbooks/auth-audience-mismatch.md`). +읽는다. audience는 필수다(2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다). 같은 issuer의 다른 +client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지 않는다(`JwtToAuthenticatedPrincipalConverter`, `docs/runbooks/auth-audience-mismatch.md`). ## 객체 단위 권한 @@ -143,7 +144,7 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re ## web 없는 조립 web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을 검사할 advisor가 없다. 그런 조립에 -권한을 선언한 bean이 있으면 `PermissionEnforcementGuard`가 기동을 실패시킨다(리뷰 01-06). web 없이 +권한을 선언한 bean이 있으면 `PermissionEnforcementGuard`가 기동을 실패시킨다. web 없이 조립하는 서비스는 자기 전송에 맞는 검사 advisor를 함께 넣어야 기동한다. ## 지금 이해하면 되는 것 diff --git a/docs/manual/08-testing.md b/docs/manual/08-testing.md index 8cba48dd..738ae979 100644 --- a/docs/manual/08-testing.md +++ b/docs/manual/08-testing.md @@ -46,7 +46,8 @@ fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스 - **고르는 기준**: 포트 인터페이스가 어느 leaf에 있나. - **기본값**: 그 leaf의 `src/testFixtures/java/...//testkit/`. domain 포트면 domain-core, application 포트면 application-core. 소비 leaf는 `testImplementation testFixtures(project(':'))`. -- **예외**: 없다. 테스트 안 private fake는 계약 밖에 있어 실제와 갈라진다(리뷰 01-05의 lock fake). +- **예외**: 없다. 테스트 안 private fake는 계약 밖에 있어 실제와 갈라진다(2026-11-01 성숙도 리뷰가 + 분산 lock 포트 계약 테스트 안의 fake에서 찾았다). ## lane과 단계 @@ -71,7 +72,8 @@ lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`( - **예외**: 반드시 실행돼야 하는 소수 테스트(계약 자격 검사)는 `requires(클래스)` + `rejectSkipped = true`로 이름을 박는다. 이름이 바뀌거나 지워지면 lane이 실패한다. - 새 lane이 어떤 단계에도 속하지 않으면 PR 게이트의 `verifyStrictLaneStages --dry-run`이 실패한다 - (1라운드 08-01). 단계는 집계 태스크(`integrationCheck` 등)를 통해 붙고, workflow 파일을 고치지 않는다. + (2026-11-01부터. 전에는 어떤 workflow도 돌리지 않는 strict lane이 14개 있었다). 단계는 집계 + 태스크(`integrationCheck` 등)를 통해 붙고, workflow 파일을 고치지 않는다. ## 지금 이해하면 되는 것 diff --git a/docs/manual/09-outbox-events.md b/docs/manual/09-outbox-events.md index 8d884b87..2a208669 100644 --- a/docs/manual/09-outbox-events.md +++ b/docs/manual/09-outbox-events.md @@ -35,7 +35,7 @@ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공 6. schema를 출시한다: `src/test/resources/contracts/released-payload-schemas.sha256`에 새 version 파일의 해시를 한 줄 더한다. 출시한 version 파일은 고치지 않는다 — 바뀌면 `ReleasedPayloadSchemaContract` 테스트가 실패한다. 필드를 바꾸는 변경은 새 version으로 낸다. 절차: `src/application-core/README.md` - "payload version 올리기"(리뷰 06-10). + "payload version 올리기". ## 판단 지점 @@ -61,7 +61,7 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu - event id: 정규 소문자 UUIDv7, 소비자 중복 제거 키. draft(`IntegrationEventDraft`)가 다른 값(대문자, v4, `event-1` 같은 문자열)을 거부하므로 업무 쓰기에서 바로 실패한다 — 커밋된 뒤 relay에서 DEAD가 되지 - 않는다(리뷰 06-06). 같은 작업의 재시도가 같은 event id를 내야 하면(durable operation) 작업 id를 쓰고, + 않는다. 같은 작업의 재시도가 같은 event id를 내야 하면(durable operation) 작업 id를 쓰고, 작업 id가 UUIDv7이 아니면 작업 id와 접수 시각에서 UUIDv7을 파생한다. - correlation: 헬퍼가 정한다. 요청의 correlation id가 `IntegrationIdentity` 문법·길이에 맞으면 그것, 아니면 event id. 문법 밖 헤더가 업무 쓰기를 실패시키지 않는다. 값을 미리 검사해야 하면 문법을 베끼지 @@ -70,7 +70,7 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu - tenant 범위: tenant가 없는 기능은 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`). - aggregate 순서: `OutboxAggregateSequencePort.nextSequence(aggregate)`로 같은 `tx.inWrite` 안에서 받는다(V21 카운터, 커밋 순서를 따른다). 이벤트가 하나뿐인 aggregate는 `AggregateOrder.first()`. 발생 - 시각(벽시계)은 쓰지 않는다 — 서버 시계가 어긋나면 순서가 뒤집힌다(리뷰 06-07). 벽시계 번호를 쓰던 + 시각(벽시계)은 쓰지 않는다 — 서버 시계가 어긋나면 순서가 뒤집힌다. 벽시계 번호를 쓰던 서비스가 포트로 옮기면 V21 floor 덕분에 새 번호는 옛 번호 뒤에서 시작한다. 그래서 첫 번호가 1이 아니라 약 1.7×10¹⁵일 수 있다. 소비자는 번호를 "마지막으로 본 값보다 큰가"로만 비교하고 연속성을 가정하지 않는다. 비교는 aggregate identity(tenant scope 포함) 단위다. tenant scope를 바꾸는 배포는 옛 @@ -83,8 +83,8 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu 선언이 없어서, bean이 되면 전송 계층이 **권한 검사 없이** 닿는다. 그래서 bean으로 등록하면 `PermissionEnforcementGuard`가 기동을 실패시킨다(07장 「시스템이 부르는 쓰기」). - broker의 **재시도 가능한** 거부와 응답 없음은 DEAD가 아니라 backoff 재시도다. broker가 멈춰도 대량 - DEAD가 되지 않는다(1라운드 06-01·06-03). 대신 끝이 없다: 진짜 인증 오류, Kafka adapter가 이름을 모르는 - broker 거부도 영원히 재시도된다. 행의 `last_failure_code`와 로그의 `error.reason`이 원인 코드를 남기고, + DEAD가 되지 않는다(2026-11-01부터. 전에는 broker가 몇 분만 멈춰도 행이 대량으로 DEAD가 됐다). 대신 + 끝이 없다: 진짜 인증 오류, Kafka adapter가 이름을 모르는 broker 거부도 영원히 재시도된다. 행의 `last_failure_code`와 로그의 `error.reason`이 원인 코드를 남기고, `outbox.retry.long.size`가 오래 재시도 중인 행을 센다. 처분(보류·재개·skip)은 publish-failed runbook §4.1이다. - 발행 응답을 못 받으면 결과 불명(`OutboxPublishAmbiguousException`) — 05장 규칙과 같다. diff --git a/docs/manual/README.md b/docs/manual/README.md index 8ad6ff24..ea2ce530 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -56,7 +56,7 @@ ## 따라 할 예시는 하나 예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 -배치가 달라졌다(리뷰 2026-11-01 01-01·07-09). 이제 **새 업무 기능의 예시는 생성 명령의 출력 하나**다. +배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 **새 업무 기능의 예시는 생성 명령의 출력 하나**다. | 코드 | 역할 | 따라 하나 | | --- | --- | --- | @@ -65,9 +65,9 @@ | `src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/**` | ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 | | `application-core/.../operation` + `DurableOperationAutoConfiguration`(composition:durable-operation) | 템플릿 플랫폼 기능 | 조립 모양(`@ConditionalOnBean` + 유스케이스 `@Bean`)만 본다 | -## 1라운드 수정으로 생긴 패턴 (리뷰 README 13절) +## 리뷰 뒤 첫 수정으로 생긴 패턴 -리뷰 뒤 1라운드에서 굳은 모양이다. 각 장에 반영했다. +2026-11-01 성숙도 리뷰 뒤 같은 날 한 첫 수정에서 굳은 모양이다. 각 장에 반영했다. | 패턴 | 근거 코드 | 장 | | --- | --- | --- | diff --git a/docs/work/evidence.md b/docs/work/evidence.md index 05b9697b..1d985b92 100644 --- a/docs/work/evidence.md +++ b/docs/work/evidence.md @@ -150,7 +150,7 @@ - 나머지 20건은 round6 Minor다(`RR6-01-02`~`06`·`08`·`09`, `RR6-02-02`·`04`·`05`, `RR6-03-02`~`05`, `RR6-04-01`~`06`). README 17절은 영역별 건수만 적었고, r10 묶음이 영역 단위로 고쳤다. - 이 검사는 "색인에 이름이 있나"만 본다. 고쳤는지는 처리 표와 확인 리뷰가 본다. 앞으로의 리뷰 README는 모든 ID를 이름으로 적는다(`improve.md` 4.1절 7단계). -## 8. `docs/manual/`에서 걷어낸 이력 ID (2026-11-06) +## 8. `docs/manual/`에서 걷어낸 이력 ID (2026-11-06, 2026-11-07) `docs/manual/` 본문에서 리뷰 ID와 번호만 쓴 결정을 걷어냈다. 문장의 뜻은 그대로이고, 괄호 안 근거만 여기로 옮겼다. 줄 번호는 걷어내기 전 기준 커밋 `06f520e6`의 줄이다. @@ -167,6 +167,31 @@ - `RR-01-11`·`RR-02-10`·`RR-03-11`은 2차 재리뷰(`round2/`) 문서의 발견이다. 그 문서들은 1차 번호에 이어 `RR-` 접두어를 그대로 썼다(머리말 「표기」). +2026-11-07에 남은 19줄을 같은 방식으로 걷어냈다. 16줄은 2026-11-06 검사 패턴을 넓힌 뒤 드러난 줄이다(9절 T4-1). 3줄(아래 표에서 「손으로 찾음」)은 그 패턴도 못 잡아 `docs-writing.md` 9절대로 grep으로 찾았고, 그 꼴을 잡는 패턴 셋을 `scripts/check-work-docs.py`에 더했다. 줄 번호는 걷어내기 전 기준 커밋 `73d39212`의 줄이다. 「1라운드」는 `1101` README 13절 「조치 현황 (개선 순서 1~3)」으로, 리뷰 직후 2026-11-01에 한 첫 수정이다(같은 날 밤 13.1절 게이트, 14절 「2라운드」가 이어졌다). 영역 문서 이름은 `docs/reviews/2026-11-01-maturity-review/` 안의 파일이다. + +| 원래 위치 | 원래 괄호 | 지금 본문 | 근거 | +| --- | --- | --- | --- | +| `docs/manual/README.md:59` | "리뷰 2026-11-01 01-01·07-09" | "2026-11-01 성숙도 리뷰" | `1101/01-01`(새 기능을 어느 leaf에 두는지 세 가지 모양이 있고 고르는 기준이 없다, `01-core-and-feature-pattern.md`), `1101/07-09`(새 기능을 만들 때 따라 할 예시가 세 갈래다, `07-bootstrap-composition-config.md`) | +| `docs/manual/README.md:68`, `:70` | 제목 "1라운드 수정으로 생긴 패턴 (리뷰 README 13절)", 본문 "리뷰 뒤 1라운드" | 제목 "리뷰 뒤 첫 수정으로 생긴 패턴", 본문 "2026-11-01 성숙도 리뷰 뒤 같은 날 한 첫 수정" | `1101` README 13절. 표의 패턴 행은 13절 각 행의 수정 내용이다 | +| `docs/manual/03-placement.md:40` (손으로 찾음) | "리뷰 01 영역 5.2절" | 괄호를 지웠다. 다시 볼 조건 문장이 내용 전부다 | `01-core-and-feature-pattern.md` 5.2절 「새 기능의 배치」 표의 「7. 바뀔 조건」 | +| `docs/manual/03-placement.md:54` (손으로 찾음) | "sample P30 결정과 같다" | "`sample-portfolio`도 2026-09-29에 이 배치로 옮겼다" | P30은 2026-09-25 리뷰 후속 작업 Wave 3 라운드 4의 묶음 이름이다. 그 묶음이 `S6-#10a`(sample 패키지가 종류별·기능별로 섞였다)를 고쳐 sample application을 기능별 패키지로 옮겼다(`docs/reviews/2026-09-25-review-followup-status.md` `S6-#10a` 행, 커밋 `8bbf1bf01`, 2026-09-29). `07-bootstrap-composition-config.md` 07-09 「근거」의 "P30 결정"도 같은 것이다 | +| `docs/manual/04-persistence.md:131` | "리뷰 README 13.2, 09-02" | "2026-11-01 샘플에 포스터 제목 유일 제약을 더할 때" | `1101/09-02`(포스터 제목 중복 규칙이 동시 요청에서 깨지고 검사 쿼리가 순차 스캔이다, `09-performance-measurement.md`). 번호 선택은 `1101` README 13.2절 「09-02 마이그레이션 번호」 행 | +| `docs/manual/05-idempotency.md:88` | "리뷰 02-01 결정" | "2026-11-01 소유자 결정" | `1101/02-01`("처리 중" 409의 클라이언트 행동이 코드·문서·짝 계약에서 서로 다르다, `02-inbound-web.md`). 고른 안은 `1101` README 5절 (A), 소유자 결정은 15절 「처리 중 409」 행 "소유자 결정(11-01)" | +| `docs/manual/05-idempotency.md:93` (손으로 찾음) | "리뷰가 찾은 반복 원인 1번", "(05-01, 04-01, 06-01)" | "2026-11-01 성숙도 리뷰가 찾은 반복 원인 첫째", "알림 발송·DB 커밋·메시지 relay 세 경계" | `1101` README 4절 1번. `1101/05-01`(알림 attempt를 "시작 안 함(확정)"으로 저장한 채 provider를 부른다), `1101/04-01`(커밋 중 끊김을 재시도 가능으로 답한다), `1101/06-01`(재시도 가능한 거부를 즉시 DEAD로 보낸다) | +| `docs/manual/05-idempotency.md:104` | "리뷰 05-17" | "2026-11-01 성숙도 리뷰가 Redis 연결 수립 실패에서 찾았다" | `1101/05-17`(Redis 연결 실패를 결과 불명으로 보고하고, 시간 초과된 연결을 pool에 돌려준다, `05-outbound-capabilities.md`). README 4절 1번의 "반대 방향" | +| `docs/manual/06-errors.md:46` | "리뷰 01-04" | 괄호를 지웠다 | `1101/01-04`(`IllegalArgumentException` 하나가 입력 오류와 서버 조립 오류를 함께 뜻하고, web은 둘 다 로그 없이 400으로 바꾼다, `01-core-and-feature-pattern.md`) | +| `docs/manual/07-authorization.md:28` | "1라운드 07-03 수정" | "2026-11-01부터. 전에는 샘플이 인증 체인 자동 설정을 빼자 권한 검사도 함께 빠졌다" | `1101/07-03`(실행 중인 샘플에서 `@RequiresPermission`이 아무 일도 하지 않았다, `07-bootstrap-composition-config.md`). 수정은 `1101` README 13절 `07-03+09-03` 행 | +| `docs/manual/07-authorization.md:51` | "1라운드 02-03 수정" | "2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다" | `1101/02-03`(JWT audience 검증이 기본으로 꺼져 있고 모든 client의 role을 합친다, `02-inbound-web.md`). 수정은 13절 `02-03+07-05` 행 | +| `docs/manual/07-authorization.md:146` | "리뷰 01-06" | 괄호를 지웠다 | `1101/01-06`(`@RequiresPermission`은 application 계약인데 검사는 web leaf가 켜 주는 AOP에만 있다, `01-core-and-feature-pattern.md`) | +| `docs/manual/08-testing.md:49` | "리뷰 01-05의 lock fake" | "2026-11-01 성숙도 리뷰가 분산 lock 포트 계약 테스트 안의 fake에서 찾았다" | `1101/01-05`(application-core 포트 절반이 fake·adapter 공유 계약 밖에 있다, `01-core-and-feature-pattern.md`). lock fake는 그 근거 칸의 `DistributedLockPortContractTest.java:46` private 클래스다 | +| `docs/manual/08-testing.md:74` | "1라운드 08-01" | "2026-11-01부터. 전에는 어떤 workflow도 돌리지 않는 strict lane이 14개 있었다" | `1101/08-01`(CI가 실행하지 않는 strict lane 14개, `08-build-ci-test.md`). 수정은 13절 `08-01+08-04+03-12` 행 | +| `docs/manual/09-outbox-events.md:38` | "리뷰 06-10" | 괄호를 지웠다 | `1101/06-10`(이벤트 payload 버전을 올리는 방법과 호환성 검사가 없다, `06-messaging.md`. 색인 누락을 정정하며 붙은 번호) | +| `docs/manual/09-outbox-events.md:64` | "리뷰 06-06" | 괄호를 지웠다 | `1101/06-06`(application EventId 문법과 platform MessageId(UUID)가 다르다, `06-messaging.md`) | +| `docs/manual/09-outbox-events.md:73` | "리뷰 06-07" | 괄호를 지웠다 | `1101/06-07`(샘플이 aggregate 순서 번호를 벽시계로 만든다, `06-messaging.md`) | +| `docs/manual/09-outbox-events.md:86` | "1라운드 06-01·06-03" | "2026-11-01부터. 전에는 broker가 몇 분만 멈춰도 행이 대량으로 DEAD가 됐다" | `1101/06-01`(다시 시도하면 될 거부를 relay가 즉시 DEAD로 보낸다), `1101/06-03`(broker가 몇 분만 멈춰도 행이 대량으로 DEAD가 된다), 둘 다 `06-messaging.md`. 수정은 13절 `06-01+06-03` 행 | + +- 더한 패턴 셋: 앞말 없이 나열한 발견 번호(`05-01, 04-01`, `01-01·07-09`), 리뷰 영역 번호(`리뷰 01 영역`, `01 영역 5.2절`), 리뷰 후속 묶음 번호(`P30`, `W3-P30`. P50 이상은 백분위수라 잡지 않는다). 홀로 선 `NN-NN` 하나는 보통 범위나 장 번호일 수 있어 여전히 잡지 않는다. + ## 9. cold-read 시험 1회차 빈틈 처리 (2026-11-06) 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을 시켰다(기준선 1개는 옛 매뉴얼). 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 1~9건씩 나와 모두 불합격이었다. 아래는 시험 기록(design-docs `delegation-loop/trials/2026-11-06-*.md`)의 「질문」·「위반」 표와 각 세션 공유 노트(`~/.config/Claude/side-session-notes/local_fcd89c34-c754-4c5b-a38f-fa322834286f/`)의 「매뉴얼에서 답을 못 찾은 곳」을 한 줄씩 처리한 결과다. 기준 커밋 `2c8a359d`.