245 lines
44 KiB
Markdown
245 lines
44 KiB
Markdown
# 결정 색인
|
|
|
|
이미 정한 것을 한곳에서 찾는 색인이다. 결정의 원문은 「출처」 칸의 문서에 있고, 원문이 정본이다. 이 표와 원문이 다르면 원문이 맞고 이 표를 고친다. 이 문서는 지난 리뷰 ID와 결정 번호를 출처로 쓴다(매뉴얼 본문에는 쓰지 않는다).
|
|
|
|
```text
|
|
작업 시작 ─> 이 색인에서 주제를 찾는다 ─> 있으면: 원문을 읽고 그대로 따른다
|
|
└> 없으면: 소유자 몫인가? ─> 그렇다: 묻는다(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-08 workflow를 셋으로 접으며 `pr.yml` `done`의 `:prCheck` 안 `documentCheck`로 옮겼다(아래 2.7 「workflow 단계 job 모양」) | 소유자 | 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 루트는 라이브러리 분리 뒤 저장소 루트로 옮겼다(아래 「Gradle 루트 위치」). 넷 모두 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절 |
|
|
| Gradle 루트 위치 | 저장소 루트가 Gradle 루트다(빌드 파일, `gradle/`, `build-logic/`, `config/`). `src/`에는 계층 폴더만 둔다: `domain/core`, `application/{core,fileserver,notification,objectstorage}`, `adapter/`, `shared-contract/`, `bootstrap/`(조립 루트 `app`과 `composition:*` leaf). registry는 `gradle/modules.json`, 시험 컨테이너 이미지 목록은 `gradle/container-images.properties`(카탈로그 옆, 빌드가 고정하는 것). `config/`는 코드 검사 도구 설정만. Gradle path와 registry id는 그대로 둔다(폴더에 맞춘 이름은 프로젝트 이름 `core`가 둘이 되어 jar·capability가 겹친다). 파생 서비스는 태그 `pre-relayout-2026-11`까지 받은 뒤 재배치를 받는다(`docs/upgrade/2026-11-relayout.md`) | 소유자(정리 프로그램 2026-11-07) | design-docs `repo-structure/01-backend-layout.md` 6.1절 가-2·가-3, `repo-structure/05-library-repos.md` 「분리 다음에」 |
|
|
| 라이브러리 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 |
|
|
| 서버 포화 코드 | 서버 쪽 상한(요청 허가, 꽉 찬 work pool)이 찬 거절은 모든 전송이 공용 `SERVER_BUSY`(503, `TRANSIENT_DEPENDENCY`, retryable, `Retry-After: 1`) 하나다. 호출자 자신의 빈도·동시성 초과만 429(`RATE_LIMIT_EXCEEDED`, fileserver `TRANSFER_ADMISSION_REJECTED`)다. 상태만 아는 503도 `SERVER_BUSY`이고, 비동기 요청 시간 초과만 `REQUEST_TIMEOUT`이다 | 기본값(2026-11-12, 소유자가 뒤집을 수 있다) | 2026-11-12 전체 리뷰 기록 README 6절 ② |
|
|
| batch 부분 실패 | fileserver batch도 공용 bulk envelope(web AGENTS B8)다. 하나라도 실패하면 `success:false` + `BATCH_PARTIAL_FAILURE` + 항목별 `details` | 기본값(2026-11-12) | 같은 README 6절 ① |
|
|
| PATCH 정본 | `docs/web/patch-contract.md`가 merge patch·JSON Patch의 정본이다. web AGENTS B2는 `application/json` PATCH DTO만 다루고 그쪽을 가리킨다 | 기본값(2026-11-12) | 같은 README 6절 ③ |
|
|
|
|
### 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) | `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 의존성 잠금 | ~~잠그지 않음 + 문서화(보류)~~ → 지금은 잠근다(`build-logic/build.gradle` `lockMode = LockMode.STRICT`, 2026-09-25 커밋부터). 바꾼 결정의 기록은 없다 | 소유자 | 결정 27 |
|
|
| 릴리스 이미지 서명 | ~~cosign keyless~~, tag 릴리스에서 서명·검증 → 2026-11-07 키 쌍으로 바꿈(아래 「릴리스 이미지 서명 키」) | 소유자 | 결정 31 |
|
|
| 릴리스 이미지 서명 키 | cosign 키 쌍으로 서명한다. Gitea Actions는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다. 개인 키와 비밀번호는 repo secret이다 | 소유자(2026-11-07) | `docs/work/operate.md` 4.3절, `.gitea/workflows/release.yml` |
|
|
| 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 <상대 경로>`도 따라간다~~ → 2026-11-08 셸을 해석하지 않게 바꿈(아래 「workflow 단계 job 모양」) | 소유자 | `1103` 15절 ② |
|
|
| workflow 단계 job 모양 | workflow는 `pr.yml`·`main.yml`·`release.yml` 셋이다. 단계 job의 `run:`은 셸 문법 없는 `./gradlew` 한 줄이나 `bash scripts/<이름>.sh` 한 줄이고, `verifyStrictLaneStages`는 셸을 해석하지 않고 이 고정 형식만 본다 | 소유자(2026-11-08) | design-docs `repo-structure/03-ci.md` 7·11절, `build-logic/AGENTS.md`, `StrictLaneStagesPlugin` Javadoc |
|
|
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 |
|
|
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `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 |
|
|
|
|
**기록한 뒤**: 이 색인에 한 줄(주제 · 결정 · 누가 · 날짜 · 출처)을 더한다.
|