Files
clean-architecture-backend-…/docs/work/reference/decisions.md
T
DongHyeonka 7dc5725fe7 docs!: 메시징 문서를 messaging-library로 보내고 관련 저장소 절을 채운다
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 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절
2026-11-08 17:11:33 +09:00

41 KiB

결정 색인

이미 정한 것을 한곳에서 찾는 색인이다. 결정의 원문은 「출처」 칸의 문서에 있고, 원문이 정본이다. 이 표와 원문이 다르면 원문이 맞고 이 표를 고친다. 이 문서는 지난 리뷰 ID와 결정 번호를 출처로 쓴다(매뉴얼 본문에는 쓰지 않는다).

작업 시작 ─> 이 색인에서 주제를 찾는다 ─> 있으면: 원문을 읽고 그대로 따른다
                                      └> 없으면: 소유자 몫인가? ─> 그렇다: 묻는다(3절)
                                                              └> 아니다: 정하고 기록한다(3절)

1. 결정을 다시 묻지 않는 규칙

  1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 내용을 옮겨 적는다. brief가 옮긴 내용과 원문이 다르면 원문을 따르고, 차이를 보고에 적는다(brief가 요약하며 빠뜨린 것일 수 있다).
  2. 다시 열 수 있는 경우는 셋뿐이다.
    • 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다.
    • 두 결정이 서로 충돌한다.
    • 결정이 AGENTS.md HARD-STOP과 충돌한다.
  3. 다시 열 때는 "다시 따져 본 것"과 권하는 안을 붙여 소유자에게 묻는다. 예: 2026-11-04 소유자가 수정 묶음의 기본값 셋을 다시 물었을 때, 총괄은 각각 근거를 다시 따져 적었고 소유자가 다시 정했다(docs/reviews/2026-11-03-rereview/README.md 15절).
  4. 위임·기본값으로 정한 것은 보고에 따로 적는다. 소유자가 뒤집을 수 있게 한다.
  5. 뒤집힌 결정은 원문에서 지우지 않는다. 취소선이나 "→ N절에서 바꿈"으로 새 위치를 가리킨다.
  6. 리뷰어는 정한 결정을 결함으로 다시 올리지 않는다.

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 「일하는 방식」
커밋 예외 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(2026-11-07부터 src/**/AGENTS.md, 루트 CLAUDE.md, .claude/ 아래 문서). 모듈 README·설계 문서·docs/reviews/**는 넓히지 않는다. check-work-docs.py 기본 모드가 진입 문서까지 본다 소유자 2026-11-07 2026-11-07 총괄 세션 전달(소유자 결정), 1103 19.4절 ③, docs/work/evidence.md 10절
커밋 단위 커밋 하나에 논리 변경 하나(conventions/commit-and-pr.md 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf check를 돌리고, 무거운 묶음은 마지막 트리에서 소유자(2026-11-07, 기본값 확인) 2026-11-07 docs/work/evidence.md 11절
넘어온 「범위 밖」 항목 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 소유자(2026-11-07, 기본값 확인) 2026-11-07 docs/work/evidence.md 11절
desktop 도구 설치 workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니라 받아도 된다(기본값 2026-11-07, 갱신 시각을 기록에 적는다) 소유자(2026-11-07, 기본값 확인) 2026-11-07 docs/work/operate.md 4.1절
하위 세션 보고 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 ~/.claude/CLAUDE.md 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 기본값(전역 규칙의 적용 범위를 적음) 2026-11-06 design-docs conventions/delegation-loop.md 11절 「보고」
커밋 예외(지난 것) refactor/review-followup에 Wave마다 커밋(2026-09-25), 리뷰 수정을 refactor/maturity-review-2026-11에 커밋·push(2026-11-03) 소유자 2026-09-25, 2026-11-03 결정 1, 1101 17절
리뷰 발견 처리 Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 소유자 2026-11-05 1103 16절
옛 멈춤 기준 "새 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
서브에이전트와 하위 세션 Agent 금지를 푼다. 결과만 받는 일(검색, 구조 리뷰, 직접 돌려 보는 검증, 코드 단순화 제안)은 서브에이전트(.claude/agents/)에 맡기고, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션에 맡긴다. Gradle·Docker는 서브에이전트도 desktop에서만 소유자 2026-11-07 design-docs harness/01-harness-design.md 13절 Q5
매뉴얼 체계 짧은 지도(CLAUDE.md) + 작업 종류별 playbook(docs/work/) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작 → 아래 「지침 배치」 행에서 바꿈 소유자 2026-11-06 design-docs delegation-loop/02-design.md 13절 D1, D4
지침 배치 정본은 루트 AGENTS.md(40줄 이하: 비전·지도·HARD-STOP), 루트 CLAUDE.md는 @AGENTS.md와 Claude 전용 몇 줄. 폴더 규칙은 그 폴더 AGENTS.md(CLAUDE.md가 가져옴), 폴더를 가로지르는 파일 종류 규칙은 .claude/rules/, 특정 시점 절차는 모델이 부르는 스킬(.claude/skills/), 예외 없는 규칙은 훅(편집 직후 넛지, 되돌릴 수 없는 것만 차단)·게이트. 편집 훅은 그 파일 하나만 Gradle 없이 포맷한다 소유자 2026-11-07 design-docs harness/01-harness-design.md 13절 Q1·Q2·Q3·Q6·Q9
크기별 생략 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 소유자 2026-11-06 같은 문서 D2, design-docs conventions/work-thinking-order.md
매뉴얼 검사 장치 이력 ID·분량 검사와 리뷰 색인 검사는 Gradle 밖 scripts/(check-work-docs.py, check-review-index.py) 소유자 2026-11-06 같은 문서 D6
규칙 ID 규칙마다 ID(R-…)는 아직 붙이지 않는다. 원장이 생길 때 붙인다 소유자 2026-11-06 같은 문서 D7
옛 개선 매뉴얼 브랜치 claude/improvement-manual-6ae516은 병합하지 않고 재료로만 쓴다 소유자 2026-11-06 같은 문서 D12
개선 매뉴얼을 먼저(지난 것) 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 소유자 2026-11-05 2026-11-05 총괄 세션 brief
스킬 리뷰·수정에 알맞은 스킬을 쓴다 소유자 2026-11-05 1103 2절
@DisplayName 언어 한국어(기본값 영어를 거부) 소유자 2026-09-25 결정 5, .claude/rules/java-tests.md 규칙 2
학습 문서(지난 것) 삭제된 코드를 설명하는 학습 문서(지금 docs/history/study/*.ko.md, docs/history/packages/*-superpowers-package/)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 소유자 2026-09-25 결정 6, design-docs repo-structure/README.md 3.2절
문서 체계 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 docs/history/, 설계서는 docs/design/, 결정 기록은 docs/adr/에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절, 적용은 docs/README.md
한국어의 범위 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절
문서 검사 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(scripts/check-docs.py, workflow docs-check) 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절, docs/README.md 「문서 검사」
학습 문서 docs/history/study/에 기록으로 보관한다. 코드에 맞춰 갱신하지 않고 머리 블록만 단다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절
문서 규칙 정본 design-docs conventions/docs-system.md(두 템플릿 공통). 이 repo의 적용은 docs/README.md에 적는다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절
레지스트리 yaml 설명 칸 번역한다. 그 칸을 읽는 테스트를 먼저 찾는다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절
짝 프론트 문서 체계 적용 백엔드 번역을 끝낸 뒤 한다. 프론트 README와 docs/README.md만 먼저 같이 한다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절
README 필수 절 루트 README는 「프로젝트 구조」 절과 「문서 지도」 절을 둔다 소유자 2026-11-07 design-docs repo-structure/README.md 3.2절, docs/README.md
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를 더해 정본을 쓴다. 별도 repo 라이브러리(messaging-library, grpc-library)는 복사본을 두고 그 repo의 모듈 지침에 이유 위임 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
배치 규칙 검사 저장소 루트와 src/ 최상위 허용 목록을 scripts/check-repo-layout.py로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) 소유자(2026-11-07) design-docs repo-structure/README.md 3.1절, repo-structure/01-backend-layout.md 10.3절
src/ 배치 들여온 플랫폼 넷(messaging, grpc, grpc-advanced, optional 빌드)을 src/platforms/ 아래로 묶는다. registry source_path만 바꾸고 Gradle 경로는 그대로 둔다. build-logic·gradle·config는 Gradle 루트 표준이라 남기고, composition은 조립 계층이라 옮기지 않는다. config/에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다. 넷 모두 2026-11-08 별도 repo로 나갔고 src/platforms/는 지웠다(아래 「라이브러리 repo」) 소유자(2026-11-07) design-docs repo-structure/README.md 3.1절, repo-structure/01-backend-layout.md 6.1절
라이브러리 repo 프로젝트 계층이 아닌 라이브러리(메시징, gRPC)는 템플릿에 두지 않는다. 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포하며, 템플릿은 쓰는 라이브러리만 카탈로그 좌표로 받는다. gRPC가 먼저 grpc-library로 옮겼다(2026-11-08, 템플릿 소비자 없음이라 카탈로그 항목도 없음). 메시징은 messaging-library 1.0.0으로 옮기고 쓰는 leaf가 카탈로그 messagingLibrary로 받는다(2026-11-08). 라이브러리 edge는 registry 「허용 라이브러리」 칸(library_groups·allowed_libraries)이 막는다(설계 Q11 T2). 목록과 고치는 법은 related-repos.md 소유자(2026-11-07) design-docs repo-structure/README.md 3.5절, repo-structure/05-library-repos.md 15절
개발 compose 파일 저장소 루트에 compose.yaml 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 compose/에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap compose-lanes/, Redis topology → redis-sdk, NFS → fileserver). docker-compose.dev.yml은 dev 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 소유자(2026-11-07) design-docs repo-structure/README.md 3.1절, repo-structure/01-backend-layout.md 6.3절
인프라 실행 파일 nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 infra 폴더 파일도 지운다. 지운 목록은 docs/upgrade/2026-11-maturity-review.md B-50 소유자(2026-11-07) design-docs repo-structure/README.md 3.1절, repo-structure/01-backend-layout.md 6.3절
샘플 모듈 샘플 leaf와 샘플 전용 Dockerfile을 폴더째 지운다(지운 경로는 docs/upgrade/2026-11-maturity-review.md B-49). 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 소유자(2026-11-07) design-docs repo-structure/README.md 3.1절, repo-structure/01-backend-layout.md 6.2절
기능 끝까지 도는 fixture 업무 기능 하나가 끝까지 도는 별도 fixture를 두지 않는다. durable operation 조립 테스트가 같은 경로를 실제 PostgreSQL로 본다 소유자(2026-11-07) design-docs repo-structure/README.md 3.1절

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/design/2026-11-06-error-code-log-level-design.md 10절
감싼 carrier를 전송이 읽는 법 web·GraphQL·STOMP·gRPC 네 전송 모두 원인 사슬의 첫 carrier를 본다. 감싼 carrier의 응답이 500 INTERNAL_ERROR 대신 그 carrier의 코드가 된다. 그보다 먼저 답하는 것은 아래 「GraphQL 판정 순서」(등록 매핑)와 「인자 변환 단계의 감싼 carrier」 두 행이다 소유자 1103 18.4절(RR7-01-05), 2026-11-06
GraphQL 판정 순서 플랫폼 거부 → 실패 자신이 carrier → 등록된 application 매핑 → 원인 사슬의 첫 carrier → 거부된 인자(IllegalArgumentException, 인자 binder의 BindException) → 가림(INTERNAL_ERROR). 앱이 등록한 실패는 carrier를 원인으로 들어도 등록한 코드로 답한다(web에서 앱의 도메인 advice가 먼저 받는 것과 같다). 실패 자신이 carrier인 타입(예: LockAcquisitionTimeoutException)을 등록한 매핑은 쓰이지 않는다. 로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier로 정한다 — 등록 매핑이 답해도 그 안의 서버 쪽 carrier 줄은 남는다 소유자(2026-11-07). 로그 줄도 소유자(2026-11-07, 기본값 확인) 1103 19.4절 ①(RR8-01-01), 2026-11-07 총괄 세션 전달
인자 변환 단계의 감싼 carrier 「감싼 carrier를 전송이 읽는 법」은 인자 변환 단계를 덮지 않는다. web MethodArgumentTypeMismatchException·HttpMessageNotReadableException과 GraphQL @Argument binder 실패는 원인에 carrier가 있어도 BAD_PARAMETER·VALIDATION_FAILED다. STOMP는 @DestinationVariable·@Header의 ConversionFailedException과 받은 메시지가 실린 MessageConversionException을 원인 사슬의 carrier보다 먼저 거부로 보고 WARN 한 줄(타입만)을 남긴다. 요청 형식 오류의 코드는 전송이 정한다 소유자(2026-11-07) 1103 19.4절 ④(round8/01 「Declined to judge」), 2026-11-07 총괄 세션 전달
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에도 맞췄다. 마지막 전이 종류 조건은 2026-11-07에 더했다: renew를 적용한 핸들의 start를 Redis만 "이미 시작됨"으로 확인해 호출자가 작업을 다시 돌렸다 소유자(적용 조건 보완도 소유자 2026-11-07, 기본값 확인) t5 보고 「남은 문제」, 2026-11-06, 1103 19절(RR8-04-02), IdempotencyStoreContract
적용한 핸들의 markFailed 재전송 인자 적용한 핸들이 markFailed를 다른 disposition으로 다시 보내면 OPERATION_CONFLICT이고 기록된 실패는 그대로다(「전이의 operation id」의 "같은 id·다른 인자"). retention만 다르면 "이미 처리됨"(ALREADY_MARKED_SAME_OPERATION)이고 처음 retention이 남는다. retention은 complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐 결과를 바꾸지 않아 비교하지 않는다. PostgreSQL fail digest에서 retention을 뺐다. 전에는 다른 disposition에 세 저장소 모두 NOT_OWNER, 다른 retention에 PostgreSQL만 OPERATION_CONFLICT였다 소유자(2026-11-07) 1103 19.4절 ② (a), RR8-04-01, IdempotencyFailOutcome, 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.(샘플과 함께 사라짐, 2026-11-07) 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) 샘플과 함께 사라짐(2026-11-07) 소유자 결정 22
work log 권한·batch 관리자도 남의 work log 수정 불가, batchCreate 상한 1000·한 트랜잭션 샘플과 함께 사라짐(2026-11-07) 위임 1101 15절(09)
이벤트 tenant·오류 코드 이벤트 tenant 범위 global, WORKLOG_INVALID 샘플과 함께 사라짐(2026-11-07). 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이 실제로 뜨는 프로필 샘플과 함께 사라짐(2026-11-07) 위임 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), docs/manual/10-capabilities.md 기준 4
로그 설정 logback이 app.logging.*을 읽음, APP_CACHE_REDIS_TTL_JITTER deprecated 위임 1101 15절(07)
빈 env 값 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 위임 1101 15절
APP_FLYWAY_ENABLED dev·prod에도 적용 위임 1101 15절(r3-F)
전송 상한 기본값 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
취약점이 있는 의존성 버전 고친 버전으로 올리는 것이 먼저다. 고친 버전 중 가장 작은 것을 고르고, 짝으로 움직이는 라이브러리(httpclient5와 httpcore5, gRPC와 protobuf)는 upstream이 선언한 짝을 따른다. Boot BOM이 관리하면 Boot 패치를 먼저 보고, 없으면 BOM 속성 override(build-logic JavaConventionsPlugin, 이유와 지울 조건 옆). 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오면 카탈로그 pinned-*로 모든 구성에 고정한다. 무시 목록(.trivyignore.yaml)은 고친 버전이 없을 때만, 묻고 쓴다 기본값(2026-11-07) src/gradle/libs.versions.toml 「Pinned」, 업그레이드 안내 docs/upgrade/2026-11-maturity-review.md B-54
Querydsl 취약 좌표 com.querydsl:querydsl-jpa(CVE-2024-49203, 고친 버전 없음)를 템플릿이 싣지 않는다. persistence-jpa는 쓰는 타입(Predicate)이 있는 querydsl-core로만 컴파일하고, querydsl-jpa는 capability를 켜는 서비스가 더한다. leaf README는 그 좌표에 고친 버전이 없다고 적고 OpenFeign 포크(io.github.openfeign.querydsl)를 검토하라고 한다 위임(2026-11-07, 총괄이 권한 안 A를 확인) 커밋 「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, src/adapter/outbound/persistence-jpa/README.md 「라이브러리 API」
build-logic 의존성 잠금 잠그지 않음 + 문서화(보류) 소유자 결정 27
릴리스 이미지 서명 cosign keyless, tag 릴리스에서 서명·검증 소유자 결정 31
gRPC .proto protobuf Gradle 플러그인 + Buf. 2026-11-08부터 grpc-library repo의 ci 단계 소유자 결정 18
SpotBugs 신뢰도 MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 위임 1101 15절(08-07)
테스트 코드 정적 분석 testQualityCheck는 mainCheck 위임 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, src/build-logic/AGENTS.md 「lane 캐시와 성능 lane」
문서 파싱 검사 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(verifyDocumentedLeafCount 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane 정책 src/build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」
MinIO 이미지 pgsty/minio digest 위임 1101 15절(05-09)
Jackson 2 기본 jar에 남김(logstash encoder·springdoc 요구) 위임 1101 15절(09-11)
httpclient reactive 삭제 소유자 결정 9
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

기록한 뒤: 이 색인에 한 줄(주제 · 결정 · 누가 · 날짜 · 출처)을 더한다.