시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기,
알림 claim·발송·lease 회복·맞추기·provider event replay는 capability도
트랜잭션 선언도 없는 서비스를 worker가 바로 부르고, 그 worker와 조립은
outbound adapter 안에 있다. 알림 운영자 연산 넷은 permission 없이 서비스
하나에 모여 있고 재시도 시각은 상수다. web stream bridge는 outbound가
구현한 replay 포트를 바로 읽는다. fileserver 관리 HTTP 기본값은
controller가 정한다.
고른 방법: 시스템 쓰기는 @SystemInvoked 유스케이스로 나누고 composition
worker 설정이 new로 만든다(bean 아님). 알림 worker와 fileserver 정리 조립은
composition으로 옮기고, 맞추기의 재시도·포기 시점은 유스케이스가 정한다.
운영자 연산은 platform.admin의 유스케이스 클래스 넷과 notification-admin:*
permission이다(port.in 인터페이스는 port.in과 admin의 cycle을 만들어 두지
않는다). replay 읽기는 조회 유스케이스 둘을 거치고 포트는
LiveEventReplayQueryPort로 이름을 바꾼다. 아키텍처 규칙 둘: 사용자 전송은
저장·id 포트를 쥐지 못하고, inbound는 application 서비스·coordinator를
interface로도 쥐지 못한다. 재시도 시각은 설정, 관리 기본값은 command
팩터리다. 재시도 시각의 규칙은 policy의 값 RetryTiming 하나가 갖고 설정은
그 값을 만든다. retry·routing 값들은 서버가 만드는 값이라 잘못된 값을
IllegalStateException으로 거절한다(manual 06). 모듈 기본값이 role notification-admin에 운영자 permission
넷을 준다(fileserver의 ROLE_FILE_ADMIN과 같다). 버린 대안: 서비스에
@UseCaseCapability만 달기(사용자와 시스템이 같은 진입점을 나눠 써서 권한
규칙이 막지 못한다), 운영자 서비스 삭제, 설정에서 policy를 만들어 버리며
검증하기(규칙이 바뀐 policy bean과 상관없이 남는다).
위험·한계: 공개 타입·생성자·bean 이름·아키텍처 규칙이 바뀐다. 파생
서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1~3·5·6행이다.
claim·fence 커밋 위에 쌓았다.
검증: PR 본문의 desktop 결과.
Refs: RR9-05-06, RR9-05-07, RR9-05-08, RR9-05-10, RR9-05-19
BREAKING CHANGE: NotificationAdminService·NotificationAdminApplicationService가 없어지고 운영자 연산은 platform.admin의 RedriveDeliveryUseCase 등이다(permission notification-admin:*). 알림 worker가 composition:notification-platform으로 옮기고 ReconciliationJobWorker·ProviderEventReplayWorker는 유스케이스가 됐다. MessagingReplayBridge 생성자가 조회 유스케이스를 받고 LiveEventReplayPort는 LiveEventReplayQueryPort다. 사용자 전송이 저장·id 포트나 application 서비스 interface를 쥐면 architectureTest가 실패한다. 운영자 요청 record 이름이 *Request로 바뀌고 DefaultNotificationRetryPolicy 생성자가 RetryTiming을 받는다. RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult가 잘못된 값에 IllegalStateException을 던진다.
durable operation은 core 공통 타입을 따르지 않는다. tenant·principal이
문자열이고 operation id는 controller가 만들며, UUIDv7 파생은 유스케이스가
한다. operation id 문법이 셋인데 이유가 없고, 멱등 판정 셋 중 둘이
executor를 쓰지 않는 이유도 없다. 쓰는 곳 없는 공개 타입이 일곱이고,
final 유스케이스가 둘이며, 포트 둘은 실패 결과를 적지 않았고, 소스
문자열에 NUL 바이트가 있다.
고른 방법: OperationCommand·query·command가 Optional<TenantId>를 받고
SubmitDurableOperationUseCase가 DurableOperationIdFactory로 id를 만든다.
UUIDv7 파생은 IntegrationIdentity로 옮긴다. id 문법 셋은 다니는 곳(URL
경로, header·Redis key, 비교만)이 달라 합치지 않고 OperationId Javadoc에
비교를 적는다. executor를 쓰지 않는 중복 판정 둘은 manual 05에 결정으로
적는다. 안 쓰는 타입은 지우고, final을 떼고, 실패 결과 Javadoc을 쓰고,
NUL은 \u0000으로 쓴다. final을 뗀 유스케이스는 SpotBugs
CT_CONSTRUCTOR_THROW에 걸려, config/spotbugs/exclude.xml의 CGLIB 그룹을
@UseCaseCapability가 붙은 *UseCase class까지 넓힌다(유스케이스 계약이 final을
금한다). 버린 대안: operation id 값 타입 하나로 통일(path
segment가 '/'를 실을 수 있게 되거나 지금 유효한 caller id를 거절한다).
위험·한계: 공개 생성자와 타입이 바뀐다. 파생 서비스가 할 일은
docs/upgrade/2026-11-round9-application.md 1·2행이다(최종 안내에서는 4·7행).
검증: PR 본문의 desktop 결과.
Refs: RR9-05-11, RR9-05-12, RR9-05-13, RR9-05-14, RR9-05-15, RR9-05-16, RR9-05-17, RR9-05-18
BREAKING CHANGE: OperationCommand·GetDurableOperationQuery·CancelDurableOperationCommand의 tenant가 Optional<TenantId>이고 OperationCommand에 operation id 인자가 없다. SubmitDurableOperationUseCase 생성자가 DurableOperationIdFactory를 받는다. ReadConsistency, FileserverSpans, ProviderEventId, NotificationExpiredException, BatchNotificationProviderAdapter, CollapseCapability, ProviderCollapseMapping을 지웠다.
남은 트랜잭션·정리 결함 일곱. live event log는 지우는 곳이 없어 끝없이
자란다. app.lock.wait-time은 읽는 곳이 없다. 알림 scheduler는 poll마다
상태 쿼리 넷을 돌리고, projection 지연은 닫힌 event까지 읽는다.
stateless runner 트랜잭션에 시한이 없다. tenant pool 예산은 새 pool의
크기를 모른 채 열어 연결 합계가 상한을 넘는다. runbook SQL 설명이
lane 넷 중 셋만 말한다.
고른 방법: LiveEventReaper(1000행씩, 트랜잭션 30초)와 공용
BatchedDeletes를 더한다. app.realtime.replay.*는 LiveEventReplaySettings가
엄격하게 묶고, 조립 설정이 SchedulingConfigurer로 reaper를
reaper-interval(기본 10분)마다 등록한다. LockSettings는 lease-ttl 하나만
받는다(모르는 키로 기동 실패). scheduler는 backlogDepth() 한 문장만 읽고,
그 WHERE는 claim과 같은 SQL 조각(RecipientClaimSql.CLAIMABLE_AT_NOW)이다.
projection 지연은 V14 부분 인덱스로 읽는다(lock_timeout, V21 선례대로
CONCURRENTLY 아님). runner 기본 30초(SpringTransaction 쓰기 시한과 같음을
시험이 본다), tenant 예산은 계획된 pool 크기로 열기 전에 본다. 버린
대안: V14를 CONCURRENTLY로(Flyway 트랜잭션 안에서 못 돈다, 큰 DB는
안내대로 미리 만든다), reaper @Scheduled에 SpEL로 settings bean 이름
읽기(문자열 bean 조회는 검사가 못 본다).
위험·한계: LockSettings·TenantDataSourceRegistry·TenantPoolBudget의
공개 생성자가 바뀐다. V14는 큰 notification_provider_event에서 쓰기를
잠깐 막는다(안내 4행에 미리 만드는 법과 INVALID 인덱스 확인). backlog
수치는 창이 닫힌 delivery를 더는 세지 않는다.
검증: desktop RED(pr1-red3) 새 시험 실패 포함. GREEN은 PR 본문.
Refs: RR9-01-03, RR9-01-07, RR9-01-09, RR9-01-10, RR9-01-14, RR9-01-25, RR9-01-26
BREAKING CHANGE: JpaLiveEventReplay.sweepExpired 삭제, app.realtime.replay 아래 모르는 키와 app.lock.wait-time은 기동 실패, HibernateStatelessSessionRunner 트랜잭션 30초 상한, TenantPoolBudget·TenantDataSourceRegistry 시그니처 변경. docs/upgrade/2026-11-round9-claim-fence.md
lease를 넘겨받는 저장소 다섯 곳이 앞 실행의 쓰기를 막지 못한다.
durable operation은 owner만 보고 써서 같은 worker id가 다시 claim하면
앞 실행의 결과가 남는다. 알림 lease 회복은 상태를 다시 읽은 뒤 조건
없이 되돌려 끝난 delivery를 다시 보낸다. 만료 sweep·전체 읽음은
기다린 행의 상태를 다시 보지 않는다. 멱등성 reaper는 앱 시계로 비교하고
한 번에 다 지우며, 같은 키 요청이 되살린 기록까지 지운다. fileserver
recovery enqueue는 동시 삽입에서 25P02로 실패하고, cleanup은 claim
lease가 끝난 뒤에도 항목을 시작한다. 저장소가 행에서 만드는 claim·lease
record는 잘못된 값을 IllegalArgumentException으로 거절해 web이 400으로
바꾼다.
고른 방법: 모든 쓰기를 owner·fence(·상태·만료) 조건을 단 한 문장으로
바꾼다. durable operation은 V23 lease_fence를 더하고 DurableOperationClaim
을 돌려준다. 알림 회복은 requeueAbandoned 한 문장이다. 만료 sweep은
subquery가 SKIP LOCKED로 쥔 행을 건너뛰고 바깥 UPDATE가 상태·만료를 다시
본다. 전체 읽음은 바깥 UPDATE가 상태를 다시 본다. reaper는 DB now()로
1000행씩, 트랜잭션마다 30초(SpringTransaction.DEFAULT_TIMEOUT_SECONDS)이고
바깥 DELETE에도 만료를 둔다. recovery는 INSERT … ON CONFLICT, cleanup은
lease 마지막 2분에 시작하지 않고 시도를 세지 않는 release로 돌려준다.
알림 provider timeout은 lease보다 짧아야 기동한다(호출이 lease를 넘으면
lease 복구가 아직 도는 호출을 맞추기로 넘긴다). 저장소가 만드는 record
일곱은 IllegalStateException으로 거절한다. 버린 대안: 읽고 비교한 뒤
쓰기(경합이 그대로 남음), 앱 쪽 락(인스턴스 사이에서 무의미).
위험·한계: 포트 시그니처가 바뀐다(DurableOperationStorePort,
RecipientLeaseStorePort.expiredDispatching, RecipientDeliveryStorePort
.requeueAbandoned, CleanupQueuePort.release). owner가 없거나 fence가
0인 V4 전 DISPATCHING 행은 회복이 고르지 않는다(안내 4행에 고치는 SQL).
provider timeout 검사는 필요조건일 뿐이고, 호출 전체를 묶는 것은 SES다.
검증: desktop RED(고치기 전 트리 + 새 시험, pr1-red3) 새 시험 13건
실패. GREEN은 PR 본문의 verify.sh pr·PostgreSQL lane 결과.
Refs: RR9-01-02, RR9-01-04, RR9-01-06, RR9-01-12, RR9-01-13, RR9-01-23, RR9-01-24, RR9-01-29, R1 넘김 DurableOperationStoreContractTest
BREAKING CHANGE: DurableOperationStorePort의 heartbeat·reportProgress·succeed·fail이 DurableOperationClaim을 받고 claimNext가 그것을 돌려준다. RecipientLeaseStorePort.expiredDispatching이 List<RecipientLease>를 돌려주고 RecipientDeliveryStorePort.requeueAbandoned, CleanupQueuePort.release가 새로 생긴다. IdempotencyReaper 생성자에서 Clock이 빠진다. 알림 provider timeout이 lease 이상이면 기동이 실패한다. 저장소가 만드는 claim·lease record가 IllegalStateException을 던진다. docs/upgrade/2026-11-round9-claim-fence.md
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.
- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
(registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.
위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.
검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.
Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
로컬 비밀 기본값(compose·lane·application-local의 DB 비밀번호, MinIO
root, Keycloak admin)이 __LOCAL_DEV_ 접두어 규칙을 따르지 않아 prod
sentinel 검사가 그 값을 알아보지 못한다. secrets-classification.yaml은
구현 없는 masking_rule full_except_last_4를 약속하고, full로 적은 키 일부
(salt·PEM·HMAC/signing key, URI 사용자 정보)를 LogMaskingPatterns가 가리지
않는다. required_test는 없는 시험 이름이다. IP 신뢰 설정을 두 문서가
다르게 적는다(application-local은 framework, rate-limiting은 native).
- 기본값을 __LOCAL_DEV_db_password__·__LOCAL_DEV_minio_root__·
__LOCAL_DEV_keycloak_admin__로 바꾼다.
- masking_rule을 full|userinfo|none 셋으로 줄이고, LogMaskingPatterns의
키 목록을 넓히고 URI userinfo와 여러 줄 PEM 블록 가림을 더한다. 시험이 masking_rule 어휘,
required_test 클래스 존재, full·userinfo 행이 실제로 가려지는지 본다.
버린 안: full_except_last_4 구현(끝 네 자리를 남길 값이 없다).
- IP 신뢰는 native + 내부 proxy 목록 하나로 적는다.
위험: 로컬 compose 볼륨이 옛 비밀번호로 만들어졌으면 DB 접속이 실패한다
(docs/upgrade/2026-11-round9-observability.md 6행). 운영 값은 바뀌지
않는다.
검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.
Refs: RR9-02-10, RR9-02-12, RR9-02-13
BREAKING CHANGE: 로컬 compose·lane의 비밀 기본값이 바뀐다. 옛 볼륨은
지우거나 env로 옛 값을 준다(docs/upgrade/2026-11-round9-observability.md 6~7행).
로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 401·403
보안 WARN, route를 못 찾은 요청 로그, 처리하지 못한 예외 ERROR가 원본
request URI(식별자·토큰이 든 경로)를 싣는다. outbox relay·파일 서버 정리
스케줄러는 실패를 통째로 남겨 SQL·제약 이름·값이 원인 사슬로 따라간다.
SamplingTurboFilter는 INFO 이하를 logger 구분 없이 표본으로 버려 감사
logger의 INFO 줄도 사라진다. JSON 로그 profile 칸은 Logback이 처음 읽은
환경 변수 값이라 Spring이 해석한 profile과 다를 수 있다. HeaderSanitizer는
운영 코드가 부르지 않는 공개 유틸리티로 남아 있다.
- LoggedPath: route template이 있으면 그것, 없으면 식별자가 들 수 있는
마디를 {}로 가린 경로. 세 줄이 모두 쓴다. 버린 안: 원본 URI 그대로 두고
문서로 경고(로그 수집기가 이미 받는다).
- 스케줄러 실패는 새 ServerFailureLog.forBackgroundTask로 남긴다: 분류된
persistence 실패는 원인 사슬 없이, 그 밖의 carrier는 client 쪽 코드여도
stack과 함께(요청이 없으니 결함이다). composition:outbox-relay에
shared-contract edge를 더한다(gradle/modules.json).
- SamplingTurboFilter는 AUDIT marker와 이름 끝 마디가 audit·security인
logger를 표본에서 뺀다(이름별 판정은 캐시).
- ResolvedProfileJsonProvider가 줄을 쓸 때의 해석된 profile을 쓴다.
- HeaderSanitizer와 시험을 지우고 capability-status 제거 표에 적는다.
위험: 경로를 보던 로그 검색이 가린 경로를 본다. 감사 줄이 표본에서 빠져
양이 늘 수 있다. docs/upgrade/2026-11-round9-observability.md 1~5행.
검증: desktop에서 바뀐 leaf check·:app-bootstrap:test·systemTest·
documentContractTest·repositoryContractTest, scripts/verify.sh pr rc=0
(묶음 셋을 합친 트리). 새 시험은 고치기 전 트리에서 실패했다(RED).
Refs: RR9-02-09, RR9-02-15, RR9-02-21, RR9-02-22, RR9-02-26
BREAKING CHANGE: 보안·요청·예외 로그 줄의 경로 값과 JSON profile 칸의 출처,
HeaderSanitizer 삭제. docs/upgrade/2026-11-round9-observability.md 1~5행.
@RequiresPermission이 web 밖에서 늘 거부한다. gRPC·STOMP는 인증한
호출자를 SecurityContext에 넣지 않아 권한 있는 호출자도 거부되고, 거부는
web 403, gRPC INTERNAL+ERROR, GraphQL 가린 INTERNAL_ERROR+ERROR로 갈린다.
GraphQL 정책은 하위 좌표(User.salary) 규칙을 받고 판정하지 않는다. 배포
jar가 SPRING_PROFILES_ACTIVE=test로 떠 prod 검사가 꺼진다. JWT 변환은
최상위 roles claim을 권한으로 읽고, sub 없는 token을 통과시켜 뒤에서 500이
되고, 틀린 tenant claim을 AUTH_TOKEN_MALFORMED로 본다. 모르는 profile의
알림 callback은 500+ERROR이고 공격자 문자열을 감사 WARN에 남긴다. patch
거부는 요청이 쓴 이름을 제한 없이 되풀이한다. tenant 입력 이름 거부가
web·GraphQL에서 갈리고, 익명 GraphQL tenant 출처가 SYSTEM이다. STOMP
거부는 자기 로그가 없고 설정 주석이 순서를 틀리게 적는다.
- AuthorizationDeniedException을 AUTHZ_INSUFFICIENT_PERMISSION carrier로
만들고 method security가 그것을 그대로 던진다. 전송마다 이미 있는
carrier 대응이 같은 코드로 답한다(gRPC PERMISSION_DENIED, GraphQL
FORBIDDEN). 버린 안: 전송마다 AccessDeniedException 대응 추가(네 곳에
같은 표를 둔다).
- gRPC listener callback과 STOMP frame 처리 동안 호출자를 SecurityContext에
둔다(spring-security-core 의존, lockfile 갱신). Authentication이면
그대로, 아니면 권한 없는 인증 token이다. 역할은 AuthenticatedPrincipal
에서만 읽는다.
- GraphQL 실행 전 판정이 fragment를 한 번씩 펼치며 typed parent로 좌표를
모은다. root는 늘, 하위 좌표는 규칙이 있을 때 판정하고 interface·구현
좌표의 규칙도 본다.
- 배포 산출물은 test profile을 기동 실패로 거부한다.
- JWT: 최상위 roles를 버리고, sub 없음·틀린 tenant는 401
AUTH_CLAIM_MAPPING_FAILED다.
- callback은 profile을 먼저 찾고 없으면 감사 없이 400이다
(ProviderCallbackAdapterRegistry.require → find).
- patch 거부는 이름을 16개·128자·안전 문자만 되풀이한다.
- tenant 입력 이름 어휘를 TenantId.namesATenant 하나로 모으고, 익명
GraphQL 출처를 ANONYMOUS로 둔다(값 public, 거부는 하지 않는다 — 공개
DataLoader가 그 tenant로 돈다).
- STOMP 거부는 사유·command만 담은 WARN 한 줄을 남긴다(session id는
SockJS가 client URL에서 받아 뺀다).
- 고치며 찾음: decoder를 만든 뒤 JWKS 재조회를 IdP가 받지 않으면 라이브러리
문구("…decode the Jwt: <HTTP 오류>") 때문에 401 AUTH_TOKEN_MALFORMED로
분류됐다. 원인 사슬의 HTTP·I/O 실패를 먼저 보고 503
AUTH_JWKS_UNAVAILABLE로 답한다.
위험: 응답이 바뀐다(gRPC·GraphQL 거부 코드, sub 없음 401, JWKS 재조회
실패 503, 모르는 callback 400, test profile 기동 실패). 할 일은
docs/upgrade/2026-11-round9-authz.md 1~11행이다. registry 구현은 find를
구현해야 컴파일된다.
검증: desktop에서 바뀐 leaf check·systemTest, :app-bootstrap:test·
architectureTest·documentContractTest, verifyDependencyLocks rc=0. 새
시험은 고치기 전 트리에서 실패했다(RED).
Refs: RR9-02-02, RR9-02-16, RR9-02-17, RR9-02-18, RR9-02-20, RR9-02-23,
RR9-02-25, RR9-02-28, RR9-02-29
BREAKING CHANGE: gRPC·GraphQL 권한 거부 코드, JWT sub 없음·틀린 tenant
응답, 모르는 알림 callback 응답, test profile 기동, registry require→find
가 바뀐다. 옮기는 법은 docs/upgrade/2026-11-round9-authz.md 1~11행.
문제:
- ca.spring-library가 모든 spring leaf(30)의 testImplementation에
spring-boot-starter-webmvc-test를 넣어, MockMvc를 쓰지 않는 23 leaf가 Tomcat을
시험 classpath에 resolve하고 lock했다.
- container-images.properties 머리말은 「digest로 고정」이라는데 postgres-17·18이
tag만이었다. 머리말은 「쓰는 lane만 다시 돈다」고 했지만 파일 전체가 모든 Test
task의 입력이라 이미지 하나만 바꿔도 모든 lane이 다시 돈다. postgres-16-4는
아무도 읽지 않았다.
- libs.versions.toml에 아무도 읽지 않는 칸이 있었다(라이브러리 9, 버전 4,
루트에 적용하지 않는 플러그인 4).
- config/spotbugs/exclude.xml에 없는 클래스의 항목이 있었다(exclude-test.xml에
이미 있다).
- notification의 API surface가 상대 경로로 application-notification 소스를
가리켰고, ApiSurface 플러그인은 없는 추가 root를 말없이 건너뛰어 승인 update가
줄어든 표면을 기록할 수 있었다.
- verify-mongodb-platform.sh가 고르는 클래스가 없는 :app-bootstrap:test
--tests '*CleanArchitectureTest'를 불러 늘 실패했고, 이미지 기록이 카탈로그와
다른 tag였다.
고친 것:
- 규약은 spring-boot-starter-test만 준다. 시험이 실제로 쓰는 것을 leaf가 직접
선언한다. MockMvc를 쓰는 web·web-advanced·web-fileserver·web-notification·
app-bootstrap은 webmvc-test starter, graphql은 TestRestTemplate의
spring-boot-resttestclient, durable-operation은 WebApplicationContextRunner의
spring-web, 시험이 JSON을 읽는 objectstorage·persistence-jpa·persistence-mongo·
notification-platform은 jackson-databind, redis-runtime은 jackson-annotations
(compileOnly, 본 코드와 같은 이유)다. 모든 Java source set을 한 빌드에서 컴파일해
빠진 곳이 없음을 확인하고 lockfile을 다시 만들었다(Tomcat·webmvc 시험 자동설정이
빠짐). graphql·persistence-mongo AGENTS의 허용·시험 목록을 같이 고쳤다.
- postgres 17·18을 desktop runner에서 받은 digest로 고정했다(17.11, 18.6). 목록을
읽을 때 digest 없는 값을 GradleException으로 거절한다(ContainerImageCatalogTest).
머리말을 실제 캐시 동작으로 고쳤고 postgres-16-4를 지웠다. persistence-jpa
release registry의 PostgreSQL tag는 아무도 읽지 않아 지우고, 이미지는 카탈로그가
정한다고 적었다.
- 카탈로그의 미사용 칸을 지우고 머리말을 지금 쓰임에 맞췄다.
- 죽은 spotbugs 항목을 지웠다.
- notification은 project(':application-notification')로 root를 잡고, 없는 추가
root는 설정 단계에서 실패한다(ApiSurfaceConventionTest).
- mongo 스크립트는 :app-bootstrap:architectureTest를 부르고, 이미지 기록은
카탈로그 mongo-8 값을 읽는다.
- graphql build.gradle에 앞 커밋의 document-contract lane을 함께 둔다. 저장소 루트
(ca.repository.root)와 읽는 registry 파일은 그 lane만 받고, 시험은 그 속성으로만
루트를 읽는다(cwd에서 거슬러 찾지 않는다).
버린 대안: 이미지마다 쓰는 lane을 선언해 입력을 나누기 — lane 수십 개에 키
목록을 다시 적어야 하고 빠뜨리면 캐시가 거짓 통과한다.
검증: 아래 PR 본문(desktop resolveAndLockAll·build-logic test·모든 source set 컴파일·
leaf check).
BREAKING CHANGE: ca.spring-library가 시험 classpath에 spring-boot-starter-webmvc-test를
넣지 않는다. MockMvc·TestRestTemplate·Jackson을 그 starter로 받던 파생 leaf는 의존을
직접 선언해야 시험이 컴파일된다. 카탈로그의 digest 없는 이미지와 없는 API surface 추가
root는 설정 단계에서 실패한다. version catalog의 미사용 칸을 지웠다. 할 일은
docs/upgrade/2026-11-round9-build.md다.
Refs: RR9-04-06, RR9-04-11, RR9-04-12, RR9-04-13, RR9-04-14, RR9-04-15, RR9-04-16
PR 전 리뷰(계약·시험 렌즈, 구조 리뷰) 발견을 고친다.
- 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)가 SERVER_BUSY·
RATE_LIMIT_EXCEEDED로 나가면서 Retry-After를 싣지 않았다. error dispatch는
싣는데 handleExceptionInternal은 안 실었다. registry 값을 같은 advisor로 단다.
- virtual thread admission filter가 보안 chain 앞이라 cross-origin 거절 503에 CORS
헤더가 없어 브라우저가 본문도 Retry-After도 못 읽었고, 인증 없는 요청도 permit을
썼다. chain 바로 뒤(-99)로 옮겼다.
- permit을 한 번만 돌려주는 가드, onTimeout 뒤 onComplete, onStartAsync 재등록을
지키는 시험이 없었다. 둘을 더했다.
- stream 위치 규칙이 writer와 WebStreamEvidence 두 곳에 있었다. 증거에
requireNext를 두고 writer가 쓰기 전에 부른다.
- fileserver Retry-After가 좁히기 식을 복사했고 SERVER_BUSY 값을 두 번 적었다.
ErrorResponseFactory.effectiveRetryable 하나를 같이 쓰고, 공용 이름의 code는
RetryAfterAdvisor 값을 읽는다. 재시도 불가 code 전부가 헤더를 싣지 않는지 본다.
- batch 전체 성공의 results[]에 "error": null이 나갔다. 항목 record가 null을
생략한다. batch 시험은 envelope wire 규칙을 실은 mapper로 키 집합을 본다.
- 알림 channel·locale 파싱이 두 controller에 있었다. NotificationVocabulary
하나로 모으고, detail은 web 검증 어휘(INVALID)를 쓴다. 예외 이름을
NotificationFieldRejectedException으로 바꿨다(THROWABLES_ARE_NAMED_EXCEPTION).
template 게시의 거절 시험을 더했다.
- patch 전체 검증 설명에서 상태 전이 예를 뺐다. 검증 대상은 web 표현 DTO이고
업무 규칙은 유스케이스의 것이다.
- web README의 RetryAfterHint 예시, upgrade 안내 행 넷(bulk 문구·null 키, stream
역행 항목, 상태만 아는 503·429의 Retry-After, admission filter 순서)과 부분 실패의
part 짚기(index)를 적었다.
Refs: RR9-03-01, RR9-03-02, RR9-03-06, RR9-03-13, RR9-03-15, RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-27
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는
ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지
TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED
(RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버
포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다
(§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류
code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는
Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가
나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을
적었다.
고른 방법(리뷰 README 6절 ②):
- 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable,
Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook
server-busy.md를 같이 둔다.
- web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의
instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는
같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이
같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송
초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다.
- 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만
REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException).
- fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로
붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다.
- docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을
지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다.
- decisions 2.3에 결정 ①②③ 행을 더했다.
- 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지
본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다).
- web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다.
버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가
거절을 읽는 client와 runbook을 잘못 이끈다.
위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError
.ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가
바뀐다(upgrade 안내 8·9·13).
BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced
ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC
RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은
docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
문제: web-advanced의 계약 문서와 코드가 다섯 곳에서 갈렸다.
- patch 거부가 세 코드로 갈렸다. 형식 오류는 PATCH_REJECTED(400), 빈
문서·연산 모양 오류·merge 깊이 초과는 IllegalArgumentException이라
BAD_PARAMETER(400), 너무 깊은 pointer는 권한 거절 PATCH_PATH_FORBIDDEN(403)
이었다. JSON이 아닌 본문과 결과가 대상 타입으로 읽히지 않는 patch는
Jackson 예외로 catch-all에 닿아 500 INTERNAL_ERROR였다.
- patch-contract.md는 결과를 문서 전체로 검증한다고 했지만 두 applier는
검증기를 받지 않았다.
- streaming-contract.md는 서버가 위치 증가를 강제하고 heartbeat·idle·max
age·버퍼 상한·drain 재연결을 한다고 했다. MvcStreamWriter는 그 어느 것도
하지 않았다.
- commit 뒤 Failure 기록이 어디에도 등록되지 않은 DEPENDENCY_FAILURE로
고정이라, STREAM_ITEM_TOO_LARGE 같은 carrier 코드가 사라졌다.
- virtual thread profile은 503 + Retry-After를 약속했지만 admission guard는
bean만 있었고 요청 경로에서 아무도 부르지 않았다.
- web AGENTS B2는 merge patch를 쓰지 않는다고 했고 patch-contract는 필드
변경에 merge patch를 쓰라고 했다(정본 충돌).
고른 방법:
- 형식이 틀린 patch 문서는 모두 JsonPatchRejectedException(PATCH_REJECTED)
이다. 본문 파싱과 결과 변환은 PatchBodies가 감싼다. 너무 깊은 pointer는
권한 검사 앞에서 400으로 거절한다. 대상 타입이 객체가 아닌 것은 서버
결함이라 IllegalStateException이다.
- 두 applier가 Bean Validation Validator를 받아 결과 객체 전체를 검증한다.
위반은 @Valid 본문과 같은 ConstraintViolationException → VALIDATION_FAILED.
- writer는 위치가 앞 항목보다 크지 않으면 그 항목을 쓰지 않고 INTERNAL_ERROR
Failure 기록으로 끝낸다. Failure 기록은 cause 사슬의 carrier 코드, 없으면
INTERNAL_ERROR, 문구는 category 고정 문구다.
- writer가 할 수 없는 것(heartbeat, idle·max age, 버퍼, drain)은 계약
문서를 고쳐 누가 하는지(WebStreamPolicy·Registry·DrainCoordinator를 쓰는
서비스) 적었다. 요청 thread의 동기 writer라 heartbeat를 넣으려면 thread
모델을 바꿔야 해서 버렸다.
- VirtualThreadAdmissionFilter가 모든 요청을 guard 아래 둔다(request-id
filter 바로 뒤). async 요청은 async가 끝날 때 permit을 돌려준다. guard에
Permit API를 더했다.
- 정본 충돌은 리뷰 README 6절 ③대로 patch-contract를 정본으로 두고 web
AGENTS B2가 그쪽을 가리킨다.
위험·한계: patch를 쓰는 서비스는 applier 생성자에 Validator를 넘겨야
컴파일된다. client가 보는 patch·stream 오류 코드가 바뀐다. virtual thread
profile을 켠 배포는 처음으로 상한에 걸릴 수 있다(upgrade 안내 1~5).
BREAKING CHANGE: JsonMergePatchApplier·JsonPatchApplier 생성자가 Validator를
받는다. patch 거부는 모두 PATCH_REJECTED(400), 결과 제약 위반은
VALIDATION_FAILED, stream Failure 코드는 실패의 코드나 INTERNAL_ERROR다. 할
일은 docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-26, RR9-03-27, RR9-03-28
문제: 공개 경로 스냅숏(publicPathSnapshotTest)은 config/security.yml의
기본값 한 줄만 읽었다. 문서(docs/build.md, gates.md 「공개 경로·보안 체인」)는
보안 체인 전체를 지킨다고 했다. 그래서 둘이 검사를 지나갔다.
- application-local.yml이 public-paths를 /api/healthcheck로 덮는다.
- web-notification의 callback chain이 /internal/notification/callbacks/**를
anyRequest().permitAll()로 연다. actuator chain의 health·info·prometheus도
같다.
docs/build.md는 지운 PublicPathSnapshotPlugin.java와 없는
updatePublicPathSnapshot 태스크를 승인 방법으로 적었다.
관리 포트도 문서와 compose가 갈렸다. 관리 포트가 컨테이너 loopback에 묶인
뒤(MANAGEMENT_SERVER_ADDRESS 기본 127.0.0.1) compose.yaml·dev lane의
127.0.0.1:9001 publish는 아무것도 답하지 않는 줄이 됐고, service-runtime
README·Dockerfile은 Kubernetes 프로브가 닿는다고 적었다. dev lane은 원격
JMX(9999)를 인증·TLS 없이, jmxremote.host 없이 열었다(주석은 「localhost
only」).
고른 방법:
- 스냅숏에 두 절을 더한다. profile 파일이 public-paths를 리터럴로 덮으면
그 값, 모든 leaf 운영 코드에서 Spring Security를 import한 파일의
permitAll·securityMatcher 문장(파일 경로와 함께, 정렬). 그 소스와 baseline을
lane 입력으로 선언해 캐시가 변경을 놓치지 않게 했다.
- 기동한 SecurityFilterChain의 matcher를 reflection으로 읽는 안은 버렸다.
matcher가 Spring의 private 필드에 있어 버전마다 깨진다. 문장 글자만 보므로
상수로 만든 matcher의 값은 못 본다. 그 한계를 docs/build.md에 적었다.
- 관리 포트 publish 줄과 dev lane JMX를 지웠다. 컨테이너 안에서 읽는 명령
(docker compose exec app wget …, jcmd)을 주석에 적었다. Kubernetes는
MANAGEMENT_SERVER_ADDRESS를 바꾸거나 sidecar로 읽어야 한다고
service-runtime README·Dockerfile·docs/build.md에 적었다.
위험·한계: 파생 서비스가 자기 chain이나 profile 덮어쓰기를 두었다면 merge 뒤
스냅숏이 실패한다. 읽고 승인하면 된다(upgrade 안내 1). dev lane에서 원격
JMX로 보던 사람은 jcmd로 바꾼다(안내 4).
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10에 permitAll chain을 더한 탐침 트리에서 기존
publicPathSnapshotTest가 통과했다(rc=0) — 틈이 있다.
- GREEN: spotlessApply 뒤 :app-bootstrap:test --tests '*PublicPathSnapshotTest'
(새 렌더링 시험 둘), :app-bootstrap:publicPathSnapshotTest,
repositoryContractTest, spotlessCheck, :verifyComposeProfiles(18 lane) —
67건 실패 0, skip 1, rc=0.
- 변이: 새 스냅숏을 커밋한 트리에서 callback chain의 securityMatcher를
"/internal/**"로 넓히면 publicPathSnapshotTest가 실패한다.
BREAKING CHANGE: 공개 경로 스냅숏이 profile 덮어쓰기와 모든 모듈의
permitAll·securityMatcher 문장을 본다. compose가 관리 포트 9001과 dev lane
JMX 9999를 publish하지 않는다. 할 일은
docs/upgrade/2026-11-round9-public-surface.md.
문제: docs/registries/env-keys.yaml·.env.example·배포 설정(profile 밖의
application.yml, config/*.yml, 모듈 module-defaults)이 서로 갈렸고
verifyEnvKeys는 그 차이를 보지 못했다.
- .env.example을 복사하면 기동이 실패하는 값이 있었다:
APP_DATASOURCE_CONNECTION_TIMEOUT=5s(Hikari long ms, registry 주석이
"기동 실패"라고 적은 그 값), APP_SECURITY_CORS_MAX_AGE=600s(long 초).
- 기본값과 다른 예시 값: cache·rate-limit Redis command timeout(2s·1s vs
200ms), APP_LOG_LEVEL_SQL(WARN vs INFO), FORWARD_HEADERS_STRATEGY(native
vs none — 프록시 없는 배포에서 forwarded 헤더를 믿게 된다),
POSITIVE_SOFT_TTL(빈 줄 — 빈 문자열이 기본값을 덮는다).
- registry가 폐기(deprecated_orphaned)로 적은 키 셋을 cache-redis 모듈 설정이
읽는다(COMMAND_TIMEOUT, SEMANTIC_REGION, KEY_HMAC_SECRET 참조).
- 폐기 키 45개가 .env.example에 값과 함께 남아, 복사하면 아무 일도 하지 않는
값을 켠 것으로 믿는다. 검사가 오히려 registry의 모든 APP_ 행을 예시에
요구해 폐기 행도 넣게 했다.
- 배포 설정이 읽는 APP_ 밖 placeholder 11개(SECURITY_PUBLIC_PATHS,
PRESENTATION_API_BASE_PATH, SPRING_JACKSON_DESER_* 등)에 registry 행이
없었다. 검사가 APP_ 이름만 보고, registry 파서도 APP_ 행만 읽어
MANAGEMENT_SERVER_ADDRESS 같은 행이 보이지 않았다.
- .env.example 머리말은 "빈 키는 기본값을 쓴다", "Seven values"라고 적었다.
고른 방법: 런타임 동작은 바꾸지 않고 registry와 예시를 배포 설정에 맞춘다.
그리고 verifyEnvKeys가 다섯을 더 본다.
1. registry 행은 접두어와 상관없이 읽는다.
2. 배포 설정의 placeholder는 접두어와 상관없이 행이 있어야 한다.
3. deprecated_orphaned 행은 배포 설정이 읽지 않고 .env.example에 없다.
4. .env.example 값은 registry default(행에 example이 있으면 그 값)와 같다.
빈 줄은 빈 문자열로 본다.
5. profile 밖 배포 설정의 placeholder 기본값은 registry default와 같다.
registry에 example 칸을 두었다(SMTP 587·timeout처럼 기본값이 아닌 권장값).
APP_ 밖 이름 11개는 지금 이름 그대로 등록했다. 바꾸면 파생 서비스의 배포
env가 소리 없이 무시된다. 이름 변경은 소유자 결정이다. registry 머리말을
실제 규칙(SPRING_·MANAGEMENT_·SERVER_·OTEL_ 이름공간과 옛 이름 둘)으로
고쳤다. gRPC를 켜려면 꼭 두는 APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL과
.env.example의 MANAGEMENT_SERVER_ADDRESS를 더했다.
버린 대안: SECURITY_PUBLIC_PATHS·PRESENTATION_API_BASE_PATH를 APP_로 바꾸고
옛 이름을 fallback으로 두기 — 공개 경로 기본값이 4중 placeholder가 되고
공개 경로 스냅숏 파서까지 바꿔야 한다. 이름 정리는 따로 정한다.
위험·한계: 파생 서비스가 자기 placeholder를 등록하지 않았거나 예시 값이
기본값과 다르면 이제 verifyEnvKeys(mainCheck)가 실패한다(upgrade 안내 5·6).
예시 값이 바뀌어 옛 예시를 복사한 .env는 그대로 둔다 — 안내 1~4가 고칠
값을 적는다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 시험만으로 EnvContractVerifierTest 22건 중 7건 실패
(새 검사 6건 + 메시지를 바꾼 기존 1건). 새 지킴 시험(example 행 통과)은
기준에서도 통과.
- GREEN: -p build-logic test, :app-bootstrap:verifyEnvKeys(314 env keys, 6
required placeholders, 370 rows), :app-bootstrap:test·repositoryContractTest·
documentContractTest, registry·예시를 읽는 leaf 시험(httpclient env
manifest, notification mode, redis-runtime required_when, support,
fileserver·notification platform, graphql registry parity, web CORS)
682건 실패 0, skip 5. rc=0.
BREAKING CHANGE: verifyEnvKeys가 접두어 밖 placeholder, 폐기 행의 사용,
예시·기본값 차이를 실패로 본다. .env.example에서 폐기 키가 빠지고 값 여덟이
기본값으로 바뀌었다. 할 일은 docs/upgrade/2026-11-round9-env-keys.md.
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은
이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길
측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로
두고 CI 절을 3.10(B-60~B-66)으로 미룬다.
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).
소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.
- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
`./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
(trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
`needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
(build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
.gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
docs/upgrade B-57~B-61.
버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.
위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.
BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms
경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도
지운 docs/messaging/support-matrix.md를 가리킨다.
- docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째
messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09,
messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다.
- 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만
고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱
쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md.
- docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움),
라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때
composite build(Gradle 루트가 src/라 ../../messaging-library), registry
라이브러리 칸. 설계 14절이 근거다.
- src/config/architecture/README.md: library_groups·allowed_libraries 설명.
- docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는
법·패키지·auto-config 이름), B-59(registry 칸).
- 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions,
review-criteria, defect-patterns, gates, capability-status, manual 07,
build-logic·persistence-jpa·inbound messaging·shared-contract 지침,
env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo
라이브러리 문장으로 바꿨다.
위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개
repo라 익명으로 읽힌다).
검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크
깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s
scripts/tests OK.
BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는
messaging-library repo의 docs/messaging/에 있다.
Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
grpc-library가 이름을 com.hyeonworks.grpc에서 dev.cakit.grpc로 바꾼다
(grpc-library PR #2, 소유자 2026-11-08: 개인 도메인 이름을 공용
라이브러리에 쓰지 않는다). 이 브랜치 문서는 옛 이름을 적고 있었다.
- README 재사용 체크리스트 6번: 라이브러리 패키지 dev.cakit.*은 바꾸지
않는다. 2번이 바꾸는 dev.caskeleton과 겹치지 않게 정한 이름이라고 적었다
- related-repos.md(group 두 칸과 받는 법), capability-status, 업그레이드
안내 B-55, 카탈로그 주석
남긴 것: Gitea 서버 주소, 기록(ADR-GRPC-002, 리뷰·history 본문)의 옛
proto 조직 이름 hyeonworks.
검증: check-docs.py OK, check-work-docs.py OK, --links broken 0.
앞 커밋이 ADR-GRPC 7개와 gRPC 설계서를 살아 있는 문서와 함께 지웠다.
그러자 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md의
상대 링크가 깨졌다(desktop: check-work-docs --links broken 1, lychee
Error 1). 기록 본문은 고치지 않는다는 규칙이라 링크를 고칠 수 없다.
기록은 그때 템플릿 안 코드를 두고 한 결정·설계이므로 템플릿에도 남는
것이 맞다(설계 Q15 「리뷰 기록은 템플릿에 남김」과 같은 이유).
- ADR-GRPC 7개와 설계서를 22df3525에서 되살리고, 머리 블록 「현재 정본」을
「없음 — grpc-library로 옮겼다」로 바꿨다. 사본은 grpc-library에도 있다.
- 업그레이드 안내 B-55의 지운 목록에서 그 기록들을 뺐다.
- persistence-jpa testkit 주석 둘을 Spotless 줄바꿈대로 다시 쌌다
(desktop ci의 spotlessJavaCheck 실패).
검증(로컬, 문서만): check-docs.py rc=0, check-work-docs.py --links
broken 0. Gradle 게이트는 desktop에서 다시 돈다.
공통 훅·스킬(되돌릴 수 없는 명령 차단 H12, 비밀 값 알림, 예측·실측
장부 기록, estimate·retro·techdebt)은 claude-harness repo의 플러그인이
준다. 이 repo는 그 플러그인을 켜지 않아 새 세션이 그것들을 받지 못했다.
.claude/settings.json에 extraKnownMarketplaces(claude-harness, git URL)와
enabledPlugins를 더했다. 기존 deny와 repo 훅은 그대로다. 사용자 전역에
같은 H12가 등록돼 있으면 플러그인 H12는 스스로 아무것도 하지 않는다
(소유자 기계가 그렇다). 비대화형(claude -p)은 플러그인을 자동 설치하지
않으므로 CLAUDE.md와 docs/upgrade/2026-11-harness.md 9번에 수동 설치 두
명령을 적었다.
위험: 이 세션은 ~/.claude를 바꾸지 않으므로 플러그인 설치 자체는 하지
않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다(claude-
harness README도 같은 미확인).
검증: settings.json JSON 파싱, check-work-docs.py rc=0(CLAUDE.md 10/10줄).
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼
(src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드
(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데,
registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘,
카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절,
05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다.
gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13).
코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리
해시가 이 기준 커밋 22df3525와 같다).
지운 것:
- src/platforms/grpc, grpc-advanced, optional-build(343파일)
- registry의 "build": "optional-grpc" 9행
- ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs,
integration-main.yml optional 성능 단계와 job
grpc-optional-platform-integration, release.yml job
grpc-stable-release-gate와 이미지 job의 needs 한 줄
- build-logic ca.grpc-platform-module·ca.optional-architecture-registry,
MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의
optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다
- 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14:
채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄
- 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘,
gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리
블록 「현재 정본」만 새 자리를 말하게 했다
- DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험,
adopter API 표면 검사의 optional-build 제외 경로
남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),
src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원
(ModuleRegistry, 일반 기능).
살아 있는 문서: README, docs 지도, capability-status, work/delegate·
gates·decisions(새 행 「라이브러리 repo」)·defect-patterns·
review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로),
manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석.
새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이
고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56.
위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다
(tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전
커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지
않았다.
검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck,
compose smoke, 빠른 시작). 문서 검사 셋 rc=0.
BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:*
프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin
protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로
받는다(docs/upgrade/2026-11-maturity-review.md 3.8절).
Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).
- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.
버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.
위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.
검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).
- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
→ 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
가리키기, skills-lock.json 없음)을 더했다.
버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).
위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.
검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.
BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).
- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
따르는지 본다.
버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).
위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.
검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.
BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).
scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
--skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
(DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).
버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).
위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.
검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.
BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).
- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
.claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
.claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
.claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
읽는다. 단언은 그대로다.
버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.
위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.
검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.
BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).
- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.
위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.
검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.
BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
문제: cb67b879는 `docs/upgrade/2026-11-maturity-review.md` 머리의 「커밋:」 목록에
「의존성 취약점 수정(3.7절 B-54)」을 더했다. 그 안내는 PR #2(03a313ed)로 이미
main에 합쳐졌다. 결정 색인 「아직 합치지 않은 업그레이드 안내」는 합쳐진 안내를
고치지 말고 새 행을 더하라고 한다. 머리의 「범위:」도 main → 리뷰 브랜치라 V1을
포함하지 않는다.
고친 방법: 머리 「커밋:」 목록을 main과 같게 되돌리고, 3.7절 첫머리에 이 절의
범위(`5ab1b418..claude/v1-vuln-fix-e089b9`)와 머리를 고치지 않은 이유를 적는다.
B-54 행은 그대로다. 이제 이 파일의 main과의 차이는 3.7절 하나다.
검증: check-docs.py rc=0, check-work-docs.py rc=0.
main(b3f63be6, 문서 2단계 통합 PR #3)을 V1 브랜치에 합친다. 충돌은 없었다.
- docs/web/repository-adaptation.md: V1이 숫자를 고쳤다가 되돌려(23f04afb) 기준과
같았으므로 main의 번역(숫자 없이 카탈로그를 가리킴)이 그대로 들어왔다.
- src/adapter/outbound/persistence-jpa/README.md: V1의 Querydsl 문장(71~75줄)과
main의 번역이 자동으로 함께 남았다.
- docs/work/reference/decisions.md, docs/upgrade/2026-11-maturity-review.md: V1이
더한 행과 main의 행이 모두 남았다.
- main 쪽에서 들어온 workflow 변경은 없다.
검증(노트북, 합친 트리): check-docs.py rc=0(넓어진 숫자 검사 포함 걸림 0),
자기 시험 OK, check-work-docs.py rc=0, check-repo-layout.py rc=0. 게이트는
desktop에서 이 커밋으로 돌린다.
번역 네 묶음(D2a~D2d)을 합친 트리는 문서만이 아니라 문서를 읽는
테스트의 기대 문구도 바꿨다. runbook 머리말 status 어휘(stub·active →
초안·운영), 루트 README의 「## 시작하기」, 알림 지원 매트릭스의 등급 칸
이름, 파일서버·JPA 문서의 한국어 제목과 문구, 패키지 소유 표의 머리
칸이다. 자기 runbook을 두었거나 그 문서를 고친 파생 서비스는 merge 뒤
mainCheck의 document-contract lane이 실패한다. 그런데 이것을 적은
안내가 없다. docs/README.md도 「아직 옮기지 않은 문서는 예외 목록에
있다」고 적어 지금(목록이 빔)과 맞지 않고, ADR 본문을 옮긴 사실이 「본문은
원문 그대로」라는 기록 규칙 설명과 부딪친다.
- docs/upgrade/2026-11-docs-records.md에 4절(2단계)을 더했다. 할 일
다섯과, 기대 문구가 바뀐 문서·테스트 표다. 범위·「누가 읽나」·3절의
「본문은 원문 그대로」를 2단계에 맞게 고쳤다.
- docs/README.md 「문서 수명과 언어」: 모두 옮겼고 예외 목록이 비었다,
ADR 번역은 뜻을 바꾸지 않은 옮김이고 원문은 03a313ed에 있다.
「기록 문서의 머리 블록」: ADR만 본문을 옮겼다.
버린 대안: 새 업그레이드 문서를 따로 쓰기. 같은 날 같은 문서 체계 일의
두 단계이고, 옮긴 경로 표(2절)를 2단계의 ADR 이동과 함께 한 곳에서
찾게 하는 편이 낫다.
한계: ADR 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 고치지
않았다. 그 문구는 design-docs conventions/docs-system.md가 정하고
check-docs.py가 글자 그대로 본다. 바꾸려면 정본부터 바꿔야 한다.
docs-check를 파생 서비스가 유지할지(docs/ci-cd/template-vs-consumer.md
분류)는 이 변경이 정하지 않는다.
검증(노트북): check-docs.py OK, 자기 시험 68 OK, check-work-docs.py OK.
안내의 테스트 이름·기대 문구는 각 테스트 소스에서 확인했다
(RunbookCoverageContractTest RUNBOOK_STATUSES, DeveloperExperience
ContractTest, NotificationEvidenceVerifier GRADE_COLUMN_HEADER,
NotificationReleaseGateTest, FileserverDocumentationCoverageTest,
JpaDocumentationContractTest, TemplatePackageOwnershipDocumentTest).
결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다.
문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이
모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지
보기」도 두 곳을 가리킨다.
NOTIF-ADR-001~005를 이름 그대로 docs/adr/로 옮긴다(git mv, 본문·머리
블록 그대로). 가리키던 곳을 함께 고친다.
- 루트 README 문서 지도 행, docs/README.md 지도·수명 표·머리 블록 절
- scripts/check-docs.py의 RECORD_KINDS·DECISION_PREFIXES와 설명
- NotificationReleaseGateTest: ADR 넷의 존재를 docs/adr/에서 본다
- docs/upgrade/2026-11-docs-records.md: 옮긴 경로 표와 찾는 명령
파일 이름 앞머리(NOTIF-ADR-)는 바꾸지 않았다. 설계서·리뷰·모듈 문서가
NOTIF-ADR-005처럼 번호로 부르고 있어, 이름을 ADR-NOTIF-로 바꾸면
기록 본문의 부름이 맞지 않게 된다.
위험: 이 ADR을 가리키던 문서·주석을 가진 파생 서비스는 경로를 바꿔야
한다(upgrade 안내 3절). notification-platform.yml의 pull_request 경로
필터 docs/notification/**는 이제 이 ADR을 보지 않는다. ADR 존재 시험
(NotificationReleaseGateTest)은 PR의 ci(:adapter:outbound:notification:
check)에서 계속 돈다. workflow는 이 변경에서 고치지 않았다.
이 ADR을 예외로 둔 줄은 없었다(합친 트리의 예외 목록이 이미 비어 있다).
검증(노트북): check-docs.py OK(language·head·reference·number·map·
readme 걸림 0), 자기 시험 65 OK, check-work-docs.py OK,
check-repo-layout.py OK, 살아 있는 문서에서 notification/adr 참조 0.
BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로
옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로
바꾼다.
문제: 앞 커밋 아홉 개가 파생 서비스가 받는 버전을 바꿨다(Spring Boot 4.0.9,
gRPC 1.75.0, httpclient5·httpcore5, 새 `pinned-*` 고정, Querydsl 컴파일 의존,
lockfile 옛 줄). 업그레이드 안내에 행이 없으면 파생 서비스는 merge 때 lockfile
충돌과 httpcore5의 새 응답 헤더 상한을 미리 알 수 없다. 버전을 고르는 규칙과
Querydsl 처리도 결정 색인에 없어 다음 세션이 다시 묻는다.
고친 방법:
- `docs/upgrade/2026-11-maturity-review.md`: 새 3.7절과 B-54 행(무엇이 바뀌었나,
증상, 할 일, 근거 커밋). 이 안내는 아직 main에 합쳐지지 않았으므로 결정 색인
「아직 합치지 않은 업그레이드 안내」대로 머리 「커밋:」 목록에 한 항목을 더했다.
- `docs/work/reference/decisions.md` 2.7절: 「취약점이 있는 의존성 버전」(고르는
순서와 놓는 곳)과 「Querydsl 취약 좌표」 두 행. 둘 다 기본값이고, Querydsl은
총괄 확인 전이라고 적었다.
- `docs/web/repository-adaptation.md:65`: baseline 숫자 4.0.8→4.0.9만 고쳤다.
같은 숫자가 있는 다른 살아 있는 문서 8곳은 `scripts/check-docs-exceptions.txt`의
number 예외로 얼어 있어 고치지 않았다(고치면 문서 검사가 실패하고, 예외 파일은
이 작업의 범위 밖이다).
위험·한계: 위 8곳은 Boot 4.0.8로 남는다. 번역 작업이 그 문서를 옮길 때 숫자를
정본(카탈로그)을 가리키는 말로 바꾸고 예외 줄을 지워야 한다.
검증: `python3 scripts/check-docs.py` rc=0(number 걸림 28, 예외 28, 실패 0),
`python3 scripts/check-work-docs.py` rc=0. 고친 세 문서를 읽는 테스트는 없다
(`grep -rn --include='*.java'`로 파일 이름을 찾았다).
문제: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이
여덟으로 늘었고, 루트에는 compose 파일과 infra/가 쌓였다. 어느 커밋도
최상위 모양을 묻지 않았고 리뷰 기준에도 그 칸이 없었다.
고른 방법(소유자 결정 2026-11-07, 설계 10.3절): scripts/check-repo-layout.py
- 저장소 루트와 src/ 바로 아래의 추적 항목이 허용 목록 안에 있는가
- registry source_path가 허용된 src/ 폴더 아래인가
- (경고) compose·스크립트·compose 보조 파일을 아무 추적 파일도 가리키지
않는가
를 본다. ci-quality-gates.yml quality-gates job에 한 단계로 붙인다.
Gradle 밖 스크립트다(문서·배치를 파싱하는 Gradle 검사를 두지 않는 정책).
버린 대안: registry에서 허용 폴더를 파생하기. 새 vendored 폴더를 registry
에 등록하는 것만으로 통과해, 막으려는 drift를 막지 못한다.
위험·한계: 참조 0 경고는 경로를 변수로 조립하는 workflow를 따라가지
못해 경고로만 둔다. 리뷰 기준·playbook 문장은 매뉴얼 보강 작업이 넣는다.
검증:
- 노트북·desktop: python3 scripts/check-repo-layout.py rc=0, 경고 0
- 일부러 infra/, src/messaging/, 고아 compose/orphan.sh를 둔 임시 저장소:
rc=1, 실패 3건과 경고 1건
- desktop(트리 c7cacf54): :app-bootstrap:repositoryContractTest
:app-bootstrap:documentContractTest rc=0, :verifyStrictLaneStages --dry-run rc=0
- check-work-docs.py rc=0
- 업그레이드 안내 B-50~B-52의 근거 칸을 커밋 해시로 채운다
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 10.3
BREAKING CHANGE: 저장소 루트나 src/에 허용 목록 밖의 최상위 폴더를 둔 파생 서비스는 PR 게이트가 실패한다. docs/upgrade/2026-11-maturity-review.md B-53.
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
→ 경로를 고침. 두 번째 rc=1: messaging-policy
MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
(2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
--dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
:adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
.local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.
고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).
위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
(YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
lane-services.yaml(smoke client 변수)은 뺀다.
검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
:app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
:adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
:app-bootstrap:documentContractTest, verify-compose rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.
고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
2026-07-20 하네스 설계·계획과 production capability platform 설계는
「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.
버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.
위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.
검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.
고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.
위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.
검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
:app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.
고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
→ docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.
옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.
위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.
검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.