문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).
고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.
위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.
검증(트리 f43dbc29, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/C-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0, check-review-index.py 2026-11-03-rereview rc=0
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- MongoNamespaceContractTest --rerun rc=0(3건)
- 테스트 수 세는 명령은 desktop의 지난 결과 XML로 시험했다
30 KiB
30 KiB
결정 색인
이미 정한 것을 한곳에서 찾는 색인이다. 결정의 원문은 「출처」 칸의 문서에 있고, 원문이 정본이다. 이 표와 원문이 다르면 원문이 맞고 이 표를 고친다. 이 문서는 지난 리뷰 ID와 결정 번호를 출처로 쓴다(매뉴얼 본문에는 쓰지 않는다).
작업 시작 ─> 이 색인에서 주제를 찾는다 ─> 있으면: 원문을 읽고 그대로 따른다
└> 없으면: 소유자 몫인가? ─> 그렇다: 묻는다(3절)
└> 아니다: 정하고 기록한다(3절)
1. 결정을 다시 묻지 않는 규칙
- 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 내용을 옮겨 적는다.
- 다시 열 수 있는 경우는 셋뿐이다.
- 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다.
- 두 결정이 서로 충돌한다.
- 결정이
AGENTS.mdHARD-STOP과 충돌한다.
- 다시 열 때는 "다시 따져 본 것"과 권하는 안을 붙여 소유자에게 묻는다. 예: 2026-11-04 소유자가 수정 묶음의 기본값 셋을 다시 물었을 때, 총괄은 각각 근거를 다시 따져 적었고 소유자가 다시 정했다(
docs/reviews/2026-11-03-rereview/README.md15절). - 위임·기본값으로 정한 것은 보고에 따로 적는다. 소유자가 뒤집을 수 있게 한다.
- 뒤집힌 결정은 원문에서 지우지 않는다. 취소선이나 "→ N절에서 바꿈"으로 새 위치를 가리킨다.
- 리뷰어는 정한 결정을 결함으로 다시 올리지 않는다.
2. 색인
「누가」 칸: 소유자는 소유자가 직접 정했다. 위임은 소유자가 "지금 정하고 진행하라"고 맡겨 총괄이 정했다(소유자가 뒤집을 수 있다). 기본값은 수정 묶음이 정하고 처리 표에 남겼다(소유자 확인 대상). 총괄 지시는 소유자 환경을 운영하려고 총괄 세션이 정한 작업 규칙이다. 정책은 AGENTS.md에 적힌 규칙이다.
「결정 N」은 docs/reviews/2026-09-25-review-followup-status.md 「소유자 결정」의 N번, 1101은 docs/reviews/2026-11-01-maturity-review/README.md, 1103은 docs/reviews/2026-11-03-rereview/README.md다.
날짜 칸은 2.1 표에만 있다. 2.2~2.7 표에 행을 더할 때는 날짜를 「누가」 칸(예: "기본값(2026-11-07)")이나 「출처」 칸 끝에 쓴다.
2.1 작업 방식
| 주제 | 결정 | 누가 | 날짜 | 출처 |
|---|---|---|---|---|
| 커밋 정책 기본 | 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에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 총괄이 쓰고, 리뷰어는 보고의 색인 표를 check-review-index.py --extra-index로 대조해 rc=0을 보인다 |
기본값 | 2026-11-06, 2026-11-07 | docs/work/evidence.md 9·11절 |
| 이력 ID 0 규칙의 범위 | docs/work/·docs/manual/ 본문에 더해 진입 문서 AGENTS.md와 src/**/CLAUDE.md. 모듈 README·설계 문서·docs/reviews/**는 넓히지 않는다. check-work-docs.py 기본 모드가 진입 문서까지 본다 |
소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), 1103 19.4절 ③, docs/work/evidence.md 10절 |
| 커밋 단위 | 커밋 하나에 논리 변경 하나(conventions/commit-and-pr.md 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf check를 돌리고, 무거운 묶음은 마지막 트리에서 |
기본값(옛 "묶음마다 커밋 하나"를 정본에 맞춤) | 2026-11-07 | docs/work/evidence.md 11절 |
| 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 기본값 | 2026-11-07 | docs/work/evidence.md 11절 |
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 기본값(소유자 기계를 바꾸는 일) | 2026-11-07 | docs/work/operate.md 4.1절 |
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 ~/.claude/CLAUDE.md 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 |
기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs conventions/delegation-loop.md 11절 「보고」 |
| 커밋 예외(지난 것) | refactor/review-followup에 Wave마다 커밋(2026-09-25), 리뷰 수정을 refactor/maturity-review-2026-11에 커밋·push(2026-11-03) |
소유자 | 2026-09-25, 2026-11-03 | 결정 1, 1101 17절 |
| 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | 1103 16절 |
| 옛 멈춤 기준 | "새 Important 0이면 멈춤", "Minor는 기록만" — 거둠 | 위임 → 소유자가 거둠 | 2026-11-05 | 1103 9.1·11.1·16절 |
| 두 repo의 종료 조건 | 각자 유지한다. 백엔드는 발견이 0이 될 때까지, 짝 프론트는 자기 매뉴얼의 조건 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 전달(소유자 원문 "각자 유지") |
| 무거운 실행 위치 | 노트북에서 Gradle·Docker를 돌리지 않는다. desktop에서 브랜치를 받아 돌린다 | 소유자 | 2026-11-05 | 1103 17.1절 |
| desktop 공유 잠금 | desktop의 Gradle·Docker 실행은 flock /tmp/claude-gates/heavy.lock으로 감싼다. 프론트와 부하·포트(4173·4174)가 겹치지 않게 |
총괄 지시 | 2026-11-05 | 2026-11-05 총괄 세션 brief, design-docs conventions/delegation-loop.md 11절 |
| 세션 분업 | 총괄 세션은 지휘만, 실제 작업은 하위 세션 | 소유자 | 2026-11-05 | design-docs conventions/delegation-loop.md 2절 |
| 하위 에이전트 | Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(.claude/settings.json) |
소유자 | 2026-11-06 | design-docs delegation-loop/02-design.md 13절 D5 |
| 매뉴얼 체계 | 짧은 지도(CLAUDE.md) + 작업 종류별 playbook(docs/work/) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작 |
소유자 | 2026-11-06 | 같은 문서 D1, D4 |
| 크기별 생략 | 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 | 소유자 | 2026-11-06 | 같은 문서 D2, design-docs conventions/work-thinking-order.md |
| 매뉴얼 검사 장치 | 이력 ID·분량 검사와 리뷰 색인 검사는 Gradle 밖 scripts/(check-work-docs.py, check-review-index.py) |
소유자 | 2026-11-06 | 같은 문서 D6 |
| 규칙 ID | 규칙마다 ID(R-…)는 아직 붙이지 않는다. 원장이 생길 때 붙인다 |
소유자 | 2026-11-06 | 같은 문서 D7 |
| 옛 개선 매뉴얼 | 브랜치 claude/improvement-manual-6ae516은 병합하지 않고 재료로만 쓴다 |
소유자 | 2026-11-06 | 같은 문서 D12 |
| 개선 매뉴얼을 먼저(지난 것) | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 brief |
| 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 | 1103 2절 |
@DisplayName 언어 |
한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, AGENTS.md 테스트 작성 규칙 2 |
| 학습 문서 | 삭제된 코드를 설명하는 학습 문서(docs/study/*.ko.md, docs/*-superpowers-package/)는 현재 코드에 맞게 갱신 |
소유자 | 2026-09-25 | 결정 6 |
| client 오류 문구 | 한국어. Category별 문구 표 하나를 shared-contract에 |
소유자 | 2026-09-25 | 결정 11 |
| 확인 리뷰 독립 리뷰어 둘 | 세 경우에 서로 결과를 보지 않는 리뷰어 둘이 같은 범위를 리뷰하고 총괄이 합친다: 반복을 멈추기 직전 확인 리뷰(리뷰어 하나가 0을 내면 두 번째가 본다), 수정 diff가 상한에 가까운 리뷰("가까움"은 추가 1,000줄 이상 — 기본값), Critical·Important를 고친 수정의 리뷰. 그 밖은 하나. 2~3라운드 두 리뷰의 겹침 비율을 기록하고 그 결과로 언제나 하나·언제나 둘로 옮길지 다시 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 원문 "(c)로 받기"), docs/work/improve.md 4.1·4.5절, docs/work/delegate.md 4.1절 |
2.2 구조·조립
| 주제 | 결정 | 누가 | 출처 |
|---|---|---|---|
| outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 composition:* 모듈 |
소유자 | 결정 3 |
| 새 leaf | composition:durable-operation, adapter:inbound:messaging 등록 승인 |
위임 | 1101 15절 |
| edge 없는 복사본 | 템플릿 leaf는 shared-contract edge를 더해 정본을 쓴다. vendored(messaging:*·grpc:*)는 복사본을 두고 family CLAUDE.md에 이유 |
위임 | 1101 15절(01-11) |
| caller 트랜잭션 guard | persistence-notification·persistence-fileserver → persistence-jpa edge, CallerTransaction 하나 |
소유자 | 결정 33 |
| id 포트 | notification·fileserver id 포트를 domain IdFactory로 옮기지 않음(보류) |
소유자 | 결정 34 |
| 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 |
notification TenantId |
통합하지 않음. 차이와 이유는 그 타입 Javadoc | 위임 | 1101 15절(01-03) |
| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | 1101 15절(r2-10) |
@SystemInvoked |
bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | 1103 4절(RR-01-02) |
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 @SystemInvoked에 닿지 못한다. 메시지 소비자·스케줄러는 @SystemCaller(reason) 표시로 허용 |
위임 | 1103 9.1절(RR-01-12), 10절 r5-b |
2.3 계약·오류
| 주제 | 결정 | 누가 | 출처 |
|---|---|---|---|
| HTTP 오류 응답 | Envelope 하나. fileserver problem+json도 Envelope로, tus 프로토콜 헤더만 유지 | 소유자 | 결정 2 |
| 처리 중 409 | IDEMPOTENT_IN_FLIGHT는 retryable=true + Retry-After: 2, 계약 문서에 고정 |
소유자 | 1101 5절(02-01), 15절 |
| Envelope null 필드 | 백엔드가 생략(NON_NULL) |
소유자 | 1101 5절(02-02) |
INTERNAL_ERROR retryable |
false. 일시적 실패는 전용 코드가 retryable을 가진다 |
소유자 | 결정 28 |
| 새 오류 코드 소유 | 코드를 쓰는 leaf의 enum. 계약은 docs/web/http-contract.md §4 |
위임 | 1101 15절 |
| correlation ID | 규칙 밖이면 서버가 새 값으로 교체 | 위임 | 1101 15절(02-11) |
| JSON 아닌 본문 상한 | 전역 상한 없음. 엔드포인트가 직접 둔다 | 위임 | 1101 15절(02-09) |
| GraphQL 복잡도 | 크기 미선언 list = 20, first·last 둘 다면 큰 쪽, per-parent 경고 임계 10 |
위임 | 1101 15절(03-01·03-03) |
| GraphQL DataLoader 키 실패 | 등록된 ApiErrorCode만 노출 |
소유자 | 결정 25 |
| Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 |
| 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 |
| 오류 코드 로그 레벨 | error-codes.yaml에 log_level 칸을 두지 않는다. 레벨은 실패 종류·경로가 정한다(ServerFailureLog, 보안 필터 AuthErrorResponseWriter). 칸이 다시 생기면 OperationalErrorRegistryContractTest가 실패한다. 보안 필터는 5xx(AUTH_JWKS_UNAVAILABLE·INTERNAL_AUTH_MISCONFIGURATION)를 ERROR, 4xx를 WARN으로 남긴다. 401 서명·issuer·audience 불일치는 WARN |
소유자 | 2026-11-06, docs/superpowers/specs/2026-11-06-error-code-log-level-design.md 10절 |
| 감싼 carrier를 전송이 읽는 법 | web·GraphQL·STOMP·gRPC 네 전송 모두 원인 사슬의 첫 carrier를 본다. 감싼 carrier의 응답이 500 INTERNAL_ERROR 대신 그 carrier의 코드가 된다 |
소유자 | 1103 18.4절(RR7-01-05), 2026-11-06 |
Retry-After 값 |
web RetryAfterAdvisor 표는 레지스트리 retry_after_seconds 칸과 코드마다 같다. 빠져 있던 7개(DB_UNAVAILABLE 5, DB_SERIALIZATION_FAILURE 1, DB_DEADLOCK 1, DB_IDLE_IN_TX_TIMEOUT 2, OUTBOX_PUBLISH_FAILED 30, JOB_EXECUTOR_REJECTED 5, JOB_TIMEOUT 10)를 채웠고, OperationalErrorRegistryContractTest가 둘을 대조한다 |
소유자 | 2026-11-07 총괄 세션 전달(소유자 원문 "권하는 안대로"), r8-f1 보고 「범위 밖」 1 |
| GraphQL 인자 변환 실패 | Spring GraphQL 인자 binder의 BindException(@Argument 값이 파라미터 타입으로 바뀌지 않음)은 BAD_PARAMETER(REQUEST)로 답하고, WARN 한 줄(예외 타입만, 입력값 없음)을 남긴다. web이 바뀌지 않는 경로 변수에 답하는 것과 같다 |
소유자 | 2026-11-07 같은 전달, r8-f1 보고 「범위 밖」 2 |
| 약속한 응답으로 맞추기 | 레지스트리·docs/web/http-contract.md·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이다. 고치기 전에 묻지 않고, 응답이 바뀌니 업그레이드 안내 행은 적는다. 약속한 곳끼리 다르면 묻는다 |
기본값(2026-11-07) | docs/work/improve.md 7절, docs/work/evidence.md 11절 |
| STOMP 필수 header 누락 | 필수 header·destination 변수가 없을 때 Spring이 던지는 MessageHandlingException은 ERROR 그대로 둔다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패(handler의 Error 등)도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다 |
기본값(2026-11-07) | 2026-11-07 총괄 지시, r8-f1 보고 「범위 밖」 3 |
2.4 멱등성
| 주제 | 결정 | 누가 | 출처 |
|---|---|---|---|
| complete 단계 연결 포화 | UNAVAILABLE 현재 동작 유지 + 문서화 |
소유자 | 결정 24 |
| complete 단계 저장소 실패 | "결과 불명"으로 따로 알린다(실행 전 503과 구분). 같은 키 재전송은 서버가 판정 | 위임 | 1103 4절(RR-02-03) |
| lease 지난 실행 중 기록 | PostgreSQL·Redis store가 같은 계약: 작업을 다시 돌리지 않고 "회복 필요" | 위임 | 1103 9.1절(RR-01-11) |
| Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease), 설정 검사 | 위임 | 1103 9.1절(RR-03-11) |
| 늦은 완료 | 늦게 끝난 첫 시도의 완료는 기록한다(묶음 기본값 "버린다"를 뒤집음). 다시 실행은 여전히 하지 않음 | 소유자 | 1103 15절 ① |
| 보존 기간 관계 | failure-retention < replay-ttl이면 기동 실패 |
소유자 | 1103 15절 ③ |
| 같은 attempt 재claim | lease 지난 CLAIMED·FAILED_RETRYABLE을 넘겨받는다. 같은 attempt를 두 호출이 동시에 쓰는 것은 호출자 계약 |
기본값 | 1103 17절 r10-02 |
| 다른 핸들의 시작 답 | PostgreSQL도 Redis와 같게 NOT_OWNER/NOT_CLAIMED로 답한다 |
기본값 | 1103 17절 r10-02 |
| 전이의 operation id | owner token이 같아도 호출의 operation id가 기록된 claim의 operation id와 다르면 다섯 전이(start·renew·complete·fail·release) 모두 OPERATION_CONFLICT로 거절하고 기록은 그대로 둔다. PostgreSQL·in-memory fake를 Redis에 맞췄다. 그래서 OPERATION_CONFLICT는 "claim과 다른 id"와 "같은 id·다른 인자" 두 뜻이다 |
소유자(2026-11-06) | 2026-11-06 총괄 세션 전달(소유자 원문 "(a)로 진행"), IdempotencyStoreContract |
| 같은 token·다른 operation의 claim·inspect | claim은 진행 중인 기록에 OwnerOperationConflict, inspect는 상태와 상관없이(완료된 기록도) OPERATION_CONFLICT. 거절이 안전한 쪽을 골랐다 |
기본값(2026-11-06) | 위 결정과 같은 전달의 판단 원칙, IdempotencyStoreContract |
| complete 재생 판정 | 완료 확인은 같은 owner token에만 준다. 같은 operation id를 쓴 다른 attempt의 늦은 complete는 NOT_OWNER. → 아래 「넘겨받기 전 핸들의 재전송」이 적용한 핸들 하나로 좁혔다 |
기본값(2026-11-06) | Redis TRANSITION에 맞춤, IdempotencyStoreContract |
| 기록 없는 release | 저장소 셋 다 ABSENT로 답한다(확인할 수 없는 해제를 확인하지 않는다). Redis release도 핸들 revision을 본다. release한 기록을 지울지 남길지는 저장소가 정하므로 release 재시도 답은 ABSENT(Redis·fake)와 ALREADY_RELEASED_SAME_OPERATION(PostgreSQL)으로 갈린다 |
기본값(2026-11-06) | JPA 설계 22.2 "affected row가 0이면 성공으로 간주하지 않는다", IdempotencyStoreContract |
| Redis 연결 예산 | 캐시 조건부 쓰기는 멱등성·lease와 다른 연결 예산(SCRIPT lane) | 위임 | 1103 4절(RR-04-02) |
| 넘겨받기 전 핸들의 재전송 | 같은 attempt를 넘겨받기 전의 핸들이 이미 일어난 complete·markFailed를 다시 보내면, 그 전이를 실제로 적용한 핸들에게만 "이미 처리됨"으로 확인하고 그 밖의 핸들은 거절한다. Redis TRANSITION 주석의 원래 의도를 뒤집는다. 적용: 적용한 핸들은 기록보다 revision이 하나 낮은 핸들이고, 거절은 NOT_OWNER다. 같은 규칙을 start·renew·release에도 맞췄다 |
소유자 | t5 보고 「남은 문제」, 2026-11-06, IdempotencyStoreContract |
| 해제된 핸들로 start | 계약은 ABSENT와 NOT_OWNER를 둘 다 받는다. 포트 Javadoc에 그렇게 적는다 |
소유자 | t5 보고 「남은 문제」, 2026-11-06, IdempotencyStartOutcome, IdempotencyStoreContract |
2.5 영속성
| 주제 | 결정 | 누가 | 출처 |
|---|---|---|---|
| JPA 기본값 | 트랜잭션 제한 30초, JDBC batch 50, H2 운영 jar 제거, 격리 수준 Hikari 고정, upsert DO NOTHING 후 갱신 |
위임 | 1101 15절(04) |
| 포트 시그니처 | claim에 lease·claimFence, fileserver claimDue·markAbandoned·claimToken |
위임 | 1101 15절 |
| 마이그레이션 번호 | 스트림별 순번. 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 V8_1. notification은 V13 |
위임 | 1101 15절 |
| V21 유일 인덱스 | 기존 중복이 있으면 마이그레이션 실패. runbook에 확인 쿼리 | 위임 | 1101 15절 |
| 순서 번호 seed | counter가 없으면 전역 floor부터 | 위임 | 1103 4절(RR-03-02) |
| 마이그레이션 잠금 | 강한 잠금을 거는 마이그레이션은 SET LOCAL lock_timeout, 같은 모양의 lane 테스트 |
위임 | 1103 9.1절(RR-02-09) |
| Flyway PostgreSQL 잠금 | 세션 수준(transactional-lock: false). 전제: Hikari 직접 연결. transaction-mode PgBouncer 뒤에서는 깨진다 |
기본값 | 1103 17절 r10-03(RR6-03-01) |
| persistence-jpa 설정 prefix | 플랫폼 자체는 app.persistence-jpa.*, 공유 기능은 기능 트리(app.outbox·app.lock·app.realtime.replay) |
소유자 | 결정 36 |
| 분산 lock·lease | 둘 다 capability로 유지, 공통 계약 테스트 | 소유자 | 결정 8 |
| 실패한 동시 인덱스 마이그레이션 복구 | runbook에 예외 하나를 둔다: 그 버전의 실패 이력 행(success = false)만 지우고 다시 배포한다. flyway repair는 계속 쓰지 않는다 |
소유자 | 1103 18.4절(RR7-03-03), 2026-11-06 |
2.6 샘플·메시징·보안·설정
| 주제 | 결정 | 누가 | 출처 |
|---|---|---|---|
| 포스터 업로드 abort·reconcile 경합 | 먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409) | 소유자 | 결정 22 |
| work log 권한·batch | 관리자도 남의 work log 수정 불가, batchCreate 상한 1000·한 트랜잭션 |
위임 | 1101 15절(09) |
| 이벤트 tenant·오류 코드 | 이벤트 tenant 범위 global, WORKLOG_INVALID·OPERATION_NOT_FOUND |
위임 | 1101 15절(01) |
| outbox append 모델 | canonical(OutboxAppendPort)로 통일, legacy 포트·legacy Kafka 발행 경로 삭제 |
소유자 | 결정 7 |
| Kafka 소비 | 지원. MessageHandler<T> 하나 + starter-kafka가 consumer 조립 |
소유자 | 결정 10 |
| decode 타입 등록 | handler bean이 선언한 타입으로 decode 목록을 만든다 | 위임 | 1101 15절(06-08 후속) |
| relay 재시도 | 재시도 가능 거부는 무한 재시도(5분 간격), 예산 설정 키 없음, 인증 오류는 경보로 | 위임 | 1101 15절(06-01·06-03) |
| 끝나지 않는 재시도 | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로, runbook에 park·재개 절차와 테스트된 SQL | 위임 | 1103 4절(RR-05-03) |
| 카드 검증기 YAML | messaging leaf 테스트에서만 snakeyaml(main 금지) | 소유자 | 결정 29 |
| JWT audience·role | audience 필수, 자기 client role만(기존 배포는 env 하나를 채움) | 소유자 | 1101 5절(02-03), 15절 |
| 데모 계정 | local·test·demo 프로필이 명시적으로 켜졌을 때만(허용 목록). 각 프로필은 sample이 실제로 뜨는 프로필 |
위임 | 1103 4절(RR-07-02), 9.1절(RR2-04-02) |
fixture- 값 거부 |
비밀로 분류된 키(docs/registries/secrets-classification.yaml)만 검사 |
위임 | 1103 9.1절(RR2-04-01) |
| 파일 서버 인가 | 역할 검사(file:* 권한)와 소유자·tenant 검사(ownerPrincipalId)를 둘 다 |
소유자 | 결정 14, 결정 32 |
| cross-origin redirect | 호출자 헤더 전부 제거, 안전한 헤더만 유지 | 소유자 | 결정 23 |
| 개발 compose Redis | lane Redis에 ACL 계정, "기동 WARN 없음" 검사 유지 | 위임 | 1101 15절(r3-J) |
| 서블릿 오류 디스패치 | 보안 체인이 ERROR 디스패치만 허용 | 기본값 | 1103 6절 r4-b, 8절 |
| 설정 prefix | app.*로 통일, APP_* env 키 유지 |
소유자 | 결정 16 |
| Redis prefix 예외 | app.redis.*·app.capabilities.*·app.rate-limit.* 세 트리 유지, 네 번째 금지 |
위임 | 1101 15절(05-18), AGENTS.md capability 기준 4 |
| 로그 설정 | logback이 app.logging.*을 읽음, APP_CACHE_REDIS_TTL_JITTER deprecated |
위임 | 1101 15절(07) |
| 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | 1101 15절 |
APP_FLYWAY_ENABLED |
dev·prod에도 적용 | 위임 | 1101 15절(r3-F) |
| 전송 상한 기본값 | gRPC 스레드 32·큐 256·동시 100·deadline 10s·drain 2s, ledger claimTtl 5m·보존 24h, WebSocket max-connections 1000(초과 시 1013) |
위임 | 1101 15절(03-06·03-09·03-10) |
2.7 빌드·게이트·capability
| 주제 | 결정 | 누가 | 출처 |
|---|---|---|---|
| 빌드 게이트 | verifyEnvKeys는 app-bootstrap 태스크로 유지(구현은 build-logic ca.config-contract), JPA evidence manifest는 폐기하고 leaf 테스트로, redis topology lane 유지 |
소유자 | 결정 4 |
| API surface 단계 | PR(leaf check 안) |
소유자 | 결정 20 |
PR ci 범위 |
변경 모듈만 돌리지 않음. 전체 실행 + Gradle 캐시(보류) | 소유자 | 결정 30 |
| 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 |
| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 |
| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 |
gRPC .proto |
protobuf Gradle 플러그인 + Buf(CI) | 소유자 | 결정 18 |
| SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | 1101 15절(08-07) |
| 테스트 코드 정적 분석 | testQualityCheck는 main 빌드 mainCheck, optional 빌드 ci |
위임 | 1103 14절 |
| lane 정책과 캐시 | lane 정책 값(rejectSkipped 등)은 모두 캐시 입력 |
위임 | 1103 4절(RR-06-02) |
| workflow 명령의 빌드 판정 | 같은 셸의 cd <상대 경로>도 따라간다 |
소유자 | 1103 15절 ② |
| 성능 lane 단언 | 끄는 스위치 없음. convention이 performance.assertions.enabled=true를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 |
소유자(2026-11-06 병합 승인) | design-docs delegation-loop/02-design.md 13절 D9, 커밋 e6b6e18e, AGENTS.md 「Gradle 정책 권위」 |
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(verifyDocumentedLeafCount 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane |
정책 | AGENTS.md 「Gradle 정책 권위」 |
| MinIO 이미지 | pgsty/minio digest |
위임 | 1101 15절(05-09) |
| Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | 1101 15절(09-11) |
| httpclient reactive | 삭제 | 소유자 | 결정 9 |
| SES 연동 | AWS SDK(sesv2) | 소유자 | 결정 17 |
| durable operation | HTTP 어댑터 추가, 설계 4개(서버 생성 id, payload 지문으로 재제출 판정, 고정 event type, 1일 보존) 승인 | 소유자 | 결정 15, 결정 26 |
| 알림 provider profile 소실 | 일반 재시도 정책 후 FAILED | 소유자 | 결정 21 |
| notification INGEST_ONLY | runtime 없이도 accept 때 route 이름 기록 | 위임 | 1101 15절(r3-I) |
| 파일 서버 쿼터 | 상한 미설정 = 무제한, 동시 예약은 상한을 넘을 수 있음, 정리 worker 기본 켜짐 | 위임 | 1101 15절(r2-05a) |
| objectstorage | provider type 하나 추가 | 위임 | 1101 15절(05-16) |
| 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | docs/reviews/2026-09-25-review-followup-status.md 「소유자 결정」 끝 목록 |
| 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | 1101 13·14·16절, 1103 6·10·12·15·16·17절 표 |
| 경로 필터 workflow와 단계 검사 | paths:·paths-ignore: trigger만 있는 workflow는 strict lane 단계 실행으로 세지 않는다 |
소유자 | 1103 18.4절(RR7-05-01), 2026-11-06 |
| 검사를 더 엄하게 하는 수정 | 이미 문서에 적힌 규칙을 검사(ArchUnit·검사기)가 더 엄하게 지키게 되는 수정은 결함 수정이라 크기를 올리지 않는다. 규칙을 어기던 파생 서비스 코드가 새로 실패하므로 업그레이드 안내 행과 !·BREAKING CHANGE:를 단다. 새 규칙을 만드는 검사는 큼이다 |
기본값(2026-11-07) | docs/work/improve.md 4.2절 7단계, docs/work/evidence.md 11절 |
| 아직 합치지 않은 업그레이드 안내 | 안내 범위가 main에 합쳐지기 전이면 같은 표면의 행을 고쳐 최종 동작을 적고 머리 「커밋:」 목록을 늘린다. 합쳐진 안내는 고치지 않고 새 행 | 기본값(2026-11-07) | 같은 곳 |
| 라운드 끝 태그 단계 범위 | 라운드 끝은 PR·main 단계 전부와 releaseCheck 두 명령. release.yml의 다른 job은 릴리스 전에만 |
기본값(2026-11-07) | docs/work/reference/gates.md 3절 |
| 태그·릴리스 workflow와 단계 검사 | push에 tags:만 있거나(branches·paths 없이) release trigger만 있는 workflow는 releaseCheck 단계에서만 실행으로 센다. 다른 단계(pull request·main·nightly)로는 세지 않는다 |
소유자 | 1103 18.4절(round7 05 Declined ①), 2026-11-07 |
3. 새 결정을 기록하는 법
누가 정하나
| 소유자에게 묻는다 | 직접 정하고 기록한다 |
|---|---|
| 공개 계약·wire 형식 변경, 파생 서비스 동작을 바꾸는 기본값, 보안 정책, 새 leaf, 커밋 정책, 되돌리기 비싼 선택, 비용이 드는 외부 일 | 기존 원칙에서 바로 따라 나오는 것, 결함 수정의 구현 방법, 문서 위치 |
묻는 법: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람을 한 표로 쓴다.
어디에 쓰나
| 결정의 종류 | 위치 |
|---|---|
| 리뷰 라운드에서 나온 결정 | 그 라운드 README의 「결정」 절. 항목 · 결정 · 이유 · 버린 대안 |
| 수정 묶음의 구현 기본값 | 처리 표의 「결정」 칸 |
| 되돌리기 비싼 아키텍처 선택 | docs/adr/ADR-<영역>-<번호>-<제목>.md(기존 번호를 잇는다) |
| 매뉴얼을 만들거나 고치며 정한 것 | 이 색인 + 근거는 docs/work/evidence.md |
| 여러 repo와 소유자 운영에 걸친 결정 | design-docs |
기록한 뒤: 이 색인에 한 줄(주제 · 결정 · 누가 · 날짜 · 출처)을 더한다.