docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
This commit is contained in:
@@ -172,6 +172,23 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. `sample-portfolio`는 모든 계층을 한 leaf에
|
||||
두는 지울 수 있는 샘플이라 배치 예시가 아니다. 실제 기능은 계층 leaf별로 나눈다.
|
||||
|
||||
## 리뷰·개선 작업 기준
|
||||
|
||||
이 repo를 리뷰하거나, 결함을 고치거나, 리팩터링·성능 최적화를 하거나, 폴더·코드·테스트 구조를 바꿀 때는
|
||||
`docs/improvement/`를 기준으로 한다. 새 기능을 추가하는 순서는 `docs/manual/`이다.
|
||||
|
||||
- 리뷰 기준(28개 관점의 이 repo 점검 항목, 결함의 정의, 심각도·증거 수준, 리뷰 문서 형식)은
|
||||
`docs/improvement/02-review-criteria.md`다. 공용 일반론은 프론트 repo의
|
||||
`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`이고, 이 repo는 그것을 복사하지 않고 절 번호로 가리킨다.
|
||||
- 리뷰 발견은 심각도와 상관없이 고치거나 기록한 결정으로 닫는다. 수정 뒤 그 수정 diff만 보는 확인 리뷰를 발견이 0이
|
||||
될 때까지 반복한다(`docs/improvement/09-working-method.md`).
|
||||
- 소유자 결정은 다시 묻지 않는다. 색인은 `docs/improvement/08-decisions-records.md`, 원문은 각 리뷰 문서의 결정 절이다.
|
||||
- 무거운 실행(Gradle·Docker·테스트·게이트)의 위치와 세션 분업은 소유자 환경에 묶인 규칙이라
|
||||
`docs/improvement/07-verification-gates.md`·`09-working-method.md`의 「소유자 환경」 절에 둔다.
|
||||
- 이 문서의 규칙(HARD-STOP, 테스트 작성 규칙, capability 기준)과 매뉴얼이 다르면 이 문서가 맞다.
|
||||
|
||||
`CLAUDE.md` 「Review and improvement work」는 이 절의 요약이다. 둘이 어긋나면 이 절이 우선한다.
|
||||
|
||||
## 테스트 전략
|
||||
|
||||
계층별 테스트 기준:
|
||||
|
||||
@@ -58,6 +58,26 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must
|
||||
|
||||
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
|
||||
|
||||
## Review and improvement work
|
||||
|
||||
Reviewing this repository, fixing defects, refactoring, optimizing, or changing its folder, code or test
|
||||
structure follows `docs/improvement/`; adding a feature follows `docs/manual/`. This is a synchronized
|
||||
summary of `AGENTS.md` 「리뷰·개선 작업 기준」; if they drift, `AGENTS.md` wins.
|
||||
|
||||
- Review criteria — this repository's checklist for the 28 viewpoints, what counts as a defect, severity
|
||||
and evidence levels, the review document format: `docs/improvement/02-review-criteria.md`. The general
|
||||
guide is the frontend repository's `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`; it is referenced by
|
||||
section, not copied.
|
||||
- Every finding, Minor included, is fixed or closed by a recorded decision. A fix is followed by a review
|
||||
of that fix's diff, and the loop repeats until there are no findings
|
||||
(`docs/improvement/09-working-method.md`).
|
||||
- Owner decisions are not asked again. The index is `docs/improvement/08-decisions-records.md`; the
|
||||
originals are the decision sections of the review documents.
|
||||
- Where heavy runs (Gradle, Docker, tests, gates) execute and how sessions split the work are the owner's
|
||||
environment, kept in the 「소유자 환경」 sections of `07-verification-gates.md` and `09-working-method.md`.
|
||||
- Where the manual and the `AGENTS.md` rules (HARD-STOP, test-writing rules, capability criteria)
|
||||
disagree, `AGENTS.md` is right.
|
||||
|
||||
## Proportional workflow
|
||||
|
||||
- Low risk: work in the owning leaf, follow its nearest guidance, and run the focused check.
|
||||
|
||||
@@ -25,6 +25,7 @@
|
||||
| `adr/` | 아키텍처 결정 기록 |
|
||||
| `architecture/` | 공개 API 표면 스냅숏 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`) |
|
||||
| `improvement/` | 개선 작업 매뉴얼: 리뷰·결함 수정·리팩터링·성능 최적화·구조 변경의 절차와 기준, 소유자 결정 색인 |
|
||||
| `evidence/` | 작업 단계별 증거·체크포인트 |
|
||||
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
|
||||
| `reviews/` | 모듈 코드 리뷰 결과 |
|
||||
|
||||
@@ -0,0 +1,241 @@
|
||||
# 01. 작업 종류별 절차
|
||||
|
||||
## 핵심
|
||||
|
||||
개선 작업은 여섯 종류다. 리뷰, 결함 수정, 리팩터링, 성능 최적화, 구조 변경, 테스트 구조 개선.
|
||||
종류마다 **시작 조건 → 단계 → 산출물 → 완료 기준**을 같은 틀로 적는다. 시작 조건이 안 맞으면 다른 종류의 작업이다.
|
||||
|
||||
종류를 고르는 기준은 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"다.
|
||||
|
||||
| 질문 | 답 | 작업 |
|
||||
| --- | --- | --- |
|
||||
| 아직 무엇이 틀렸는지 모른다 | 찾는다 | 리뷰 |
|
||||
| 계약과 다른 동작이 확인됐다 | 동작을 계약에 맞춘다 | 결함 수정 |
|
||||
| 동작은 맞는데 구조 비용이 크다 | 동작을 그대로 두고 모양을 바꾼다 | 리팩터링 |
|
||||
| 숫자로 잰 비용이 크다 | 같은 동작을 더 싸게 | 성능 최적화 |
|
||||
| leaf·패키지·의존 방향이 바뀐다 | 경계를 바꾼다 | 구조 변경 |
|
||||
| 테스트가 주장을 증명하지 못한다 | 테스트를 고친다 | 테스트 구조 개선 |
|
||||
|
||||
## 0. 모든 작업의 공통 단계
|
||||
|
||||
1. **기준 커밋을 고정한다.** `git rev-parse HEAD`를 산출물에 적는다. 리뷰 문서는 모두 기준 커밋으로 시작한다
|
||||
(`1101` README 머리말, `1103` README 머리말).
|
||||
2. **이전 기록을 읽는다.** 가장 최근 리뷰 README의 「결정」「남은 것」 절과 08장 색인을 읽는다. 이미 정한 것을 다시
|
||||
묻지 않는다(08장 2절). 같은 리뷰를 모르고 다시 시작하면 지난 결정과 다른 답이 나온다.
|
||||
3. **위험을 정한다.** 위험은 파일 수가 아니라 바뀌는 경계와 런타임·보안·데이터·공개 계약 영향으로 정한다
|
||||
(`CLAUDE.md` 「Proportional workflow」, `AGENTS.md` 「Gradle 정책 권위」 끝 문단). 위험이 높으면 설계서와 단계별
|
||||
리뷰를 둔다.
|
||||
4. **소유 leaf를 찾는다.** registry의 `source_path`로 소유 leaf를 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다
|
||||
(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
5. **스킬을 고른다.** 아래 표에서 고른다. `AGENTS.md` 「Superpowers Workflow」가 스킬과 트리거의 정본이다.
|
||||
6. **격리된 곳에서 일한다.** 자기 worktree와 브랜치를 쓴다(`superpowers:using-git-worktrees`). 리뷰어의 실험도
|
||||
별도 worktree에서 한다(`1103` README 머리말 "의심 결함은 별도 worktree의 임시 테스트로 확인").
|
||||
7. **무거운 실행 위치를 지킨다.** 07장 「소유자 환경」.
|
||||
8. **보고 전에 검증한다.** `superpowers:verification-before-completion`. 돌리지 못한 검증은 이유와 함께 적는다
|
||||
(`AGENTS.md` HARD-STOP 6).
|
||||
|
||||
### 스킬 고르기
|
||||
|
||||
| 작업 | 절차 스킬 | 영역 스킬(바뀌는 경계에 맞춰) | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| 리뷰 | `superpowers:requesting-code-review`(리뷰어 템플릿) | `clean-architecture`, `domain-driven-design`, `codebase-design`, `api-and-interface-design`, `security-and-hardening`, `jpa-patterns`, `supabase-postgres-best-practices`, `performance-optimization`, `observability-and-instrumentation`, `ci-cd-and-automation`, `refactor`, `documentation-and-adrs`, `doubt-driven-development` | `1103` README 2절 표, `1103/round5/review.md` 「불러온 스킬과 적용한 기준」 |
|
||||
| 리뷰 결과를 받아 고칠 때 | `superpowers:receiving-code-review` | — | `AGENTS.md` 「Superpowers Workflow」 |
|
||||
| 결함 수정 | `superpowers:systematic-debugging` → `superpowers:test-driven-development` | 바뀌는 경계의 영역 스킬 | `1103` README 6·10·12절 "test-driven-development 스킬 절차로 RED→GREEN" |
|
||||
| 리팩터링 | `refactor`, `codebase-design` | `clean-architecture` | `1103` README 2절(06 영역 `refactor`) |
|
||||
| 성능 최적화 | `performance-optimization` | `jpa-patterns`, `supabase-postgres-best-practices` | `1103` README 2절(04 영역) |
|
||||
| 구조 변경 | `superpowers:brainstorming` → `superpowers:writing-plans` | `clean-architecture` | `AGENTS.md` 「기능 개발 프로토콜」 2~4 |
|
||||
| 테스트 구조 개선 | `superpowers:test-driven-development` | — | `AGENTS.md` 「Superpowers Workflow」 |
|
||||
| 문서·결정 기록 | `documentation-and-adrs` | — | `1103` README 2절(06 영역) |
|
||||
| 완료 주장 전 | `superpowers:verification-before-completion` | — | `AGENTS.md` 「테스트 전략」 검증 원칙 |
|
||||
|
||||
리뷰어는 불러온 스킬과 그 스킬에서 적용한 기준을 리뷰 문서 「범위」 절에 표로 적는다(02장 8.2절). 스킬을 불렀다는
|
||||
사실보다 **그 기준으로 무엇을 봤는지**가 증거다.
|
||||
|
||||
## 1. 리뷰
|
||||
|
||||
**시작 조건**
|
||||
|
||||
- 대상이 정해졌다: 전체, 영역, 또는 커밋 범위(`<base>..<head>`).
|
||||
- 기준 커밋과 이전 라운드의 결정·남은 것을 읽었다.
|
||||
|
||||
**단계**
|
||||
|
||||
1. 범위를 고정한다. 확인 리뷰는 pathspec과 `git diff --stat <base>..<head> -- <pathspec>` 결과를 적는다
|
||||
(`1103/round6/01-core-inbound.md` 「pathspec」).
|
||||
2. 전체 리뷰면 가이드 0.1 전제 표(목적·실행 형태·규모 목표…)를 채운다. 템플릿에는 지연·처리량 목표가 없으므로
|
||||
그 칸은 "목표 없음 — 요청당 비용과 비례 여부로 판정"처럼 적는다(`1101/09-performance-measurement.md` 1절).
|
||||
3. 전체 리뷰면 게이트를 먼저 한 번 돌려 결과를 적는다(`1101` README 9절). 확인 리뷰는 고친 묶음이 적은 검증을
|
||||
다시 돌릴 필요가 있는 것만 돌린다.
|
||||
4. 영역을 나눈다. 가장 최근 README의 영역 표를 다시 쓴다(`1101` README 9절 9영역, `1103` README 2절 7영역,
|
||||
`round6` 4영역). 영역마다 하위 세션 하나(09장).
|
||||
5. 영역을 읽는다. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 fixture로
|
||||
옮겨 쓸 수 있게 남긴다(`1103/round6/01-core-inbound.md` 「실행한 명령과 결과」).
|
||||
6. 발견을 02장 형식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합친다(`1101` README 2절).
|
||||
7. 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(`1101` README 2절 "코드 확인").
|
||||
8. 색인을 만든다. 영역 문서의 ID를 손으로 옮기지 말고 문서에서 기계적으로 모은다. 손으로 옮기다 5건이 빠져
|
||||
어떤 수정 묶음에도 배정되지 않은 적이 있다(`1101` README 12절 정정, `1103` README 1절).
|
||||
|
||||
**산출물**
|
||||
|
||||
- 전체 리뷰: `docs/reviews/<YYYY-MM-DD>-maturity-review/README.md` + 영역 문서 `NN-<영역>.md`.
|
||||
- 확인 리뷰: 해당 리뷰 폴더 아래 `roundN/`(예: `docs/reviews/2026-11-03-rereview/round6/`).
|
||||
- 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고, 처리 결과는 README에 적는다
|
||||
(`1101` README 머리말).
|
||||
|
||||
**완료 기준**
|
||||
|
||||
- 모든 발견이 02장 형식이고 증거 수준이 적혀 있다.
|
||||
- 미검증 목록과 이유가 있다.
|
||||
- 결정이 필요한 항목마다 선택지와 권하는 안이 있다(`1101` README 5절).
|
||||
- 「Declined to judge」(판단하지 않음)로 둔 항목은 총괄이 다음 수정 묶음에 배정하거나 결정으로 닫는다.
|
||||
판단하지 않은 채 다음 라운드로 넘기지 않는다(09장 5절).
|
||||
|
||||
## 2. 결함 수정
|
||||
|
||||
**시작 조건**
|
||||
|
||||
- 결함이 02장 형식으로 적혀 있다(근거·발생 조건·영향).
|
||||
- 그 결함에 소유자 결정이 필요하면 결정이 났다. 결정 없이 고칠 수 있는 결함부터 먼저 고친다
|
||||
(`1101` README 7절 개선 순서 1).
|
||||
|
||||
**단계**
|
||||
|
||||
1. 원인을 확인한다(`superpowers:systematic-debugging`). 증상이 아니라 원인 경로를 적는다.
|
||||
2. **RED**: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지를
|
||||
기록한다(05장 4절). 수정 전 실패가 없는 수정은 완료가 아니다(`1101` README 7절 완료 기준 "수정 전 실패하는
|
||||
테스트가 있어야 한다").
|
||||
3. 가장 작은 수정으로 **GREEN**.
|
||||
4. 같은 원인의 다른 자리를 찾는다. 결과 불명 처리처럼 경계마다 다시 구현된 규칙은 한 경계만 고치면 다른 경계에서
|
||||
다시 갈라진다(`1101` README 4절 원인 1).
|
||||
5. 그 동작을 설명하는 문서를 같은 변경에서 고친다: 계약(`docs/web/http-contract.md`), runbook, 매뉴얼, leaf
|
||||
README·`CLAUDE.md`, Javadoc, 레지스트리(`docs/registries/`). 고친 뒤 옛 표현을 grep으로 찾는다(04장 P2).
|
||||
6. 파생 서비스의 동작이 바뀌면 업그레이드 안내(`docs/upgrade/2026-11-maturity-review.md` 형식)에 행을 더하고
|
||||
커밋 제목에 `!`를 붙인다(08장 4절).
|
||||
7. 영향 leaf `check`와 관련 lane을 돌린다(07장).
|
||||
|
||||
**산출물**
|
||||
|
||||
- 테스트, 코드, 문서 변경.
|
||||
- 리뷰 README 처리 표의 한 행: 발견 ID · 상태 · 검증(명령과 테스트 수) · RED(수정 전 실패한 테스트 이름) ·
|
||||
처리 내용 · 결정·남은 것(`1101` README 13절 표, `1103` README 6절 표).
|
||||
|
||||
**완료 기준**
|
||||
|
||||
- RED가 수정 전에 실패했고 GREEN이 수정 뒤 통과했다. 둘 다 실행 기록이 있다.
|
||||
- 같은 원인의 다른 자리를 확인했다.
|
||||
- 07장의 해당 게이트가 통과했다.
|
||||
- 확인 리뷰가 "닫힘"으로 판정했다(02장 8.2절 「항목 재확인」).
|
||||
|
||||
## 3. 리팩터링
|
||||
|
||||
**시작 조건**
|
||||
|
||||
- 동작을 바꾸지 않는다고 말할 수 있다. 동작이 바뀌면 결함 수정이나 구조 변경이다.
|
||||
- 근거가 있다: 리뷰 발견, 부록 패턴(특히 A1 갈라진 복사본), 또는 03·04장 기준 위반.
|
||||
|
||||
**단계**
|
||||
|
||||
1. **보존 조건을 적는다.** 지킬 동작·타입·실패·진단 계약이다(가이드 36.3 「단순화의 보존 조건」, 39.9).
|
||||
2. 보존 조건을 지키는 테스트가 있는지 본다. 없으면 먼저 쓰고 지금 코드에서 통과하는 것을 본다.
|
||||
3. 작은 단계로 바꾼다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다(커밋 규칙 3.1).
|
||||
4. 복사본을 합칠 때는 정본 하나를 정하고 나머지를 지운다. 지울 수 없으면 이유를 가까운 `CLAUDE.md`에 적고
|
||||
두 벌이 같은지 보는 대조 테스트를 둔다. 예:
|
||||
- vendored family는 registry edge가 없어 복사본을 유지하고 이유를 family `CLAUDE.md`에 적었다
|
||||
(`1101` README 15절 01-11 결정, `src/messaging/CLAUDE.md` 「공용 다이제스트 헬퍼를 복사해 두는 이유」).
|
||||
- messaging은 persistence-jpa에 의존할 수 없어 Flyway 정책 값을 사본으로 두고 대조 테스트를 붙였다
|
||||
(`1103` README 17절 r10-03).
|
||||
5. 공개 API 표면이 바뀌면 API surface 검사가 PR에서 잡는다(결정 20). 의도한 변경이면 스냅숏을 갱신한다
|
||||
(`docs/architecture/*-api-surface.txt`).
|
||||
|
||||
**산출물**
|
||||
|
||||
- 구조 변경 커밋(`refactor:`), 지운 복사본 목록, 남긴 사본과 그 이유.
|
||||
|
||||
**완료 기준**
|
||||
|
||||
- 보존 조건 테스트가 변경 전후 모두 통과한다.
|
||||
- `architectureCheck`가 통과한다.
|
||||
- 지운 코드를 가리키던 문서·주석이 없다(grep 결과를 보고에 적는다).
|
||||
|
||||
## 4. 성능 최적화
|
||||
|
||||
**시작 조건**
|
||||
|
||||
- 측정한 숫자가 있다. 추측으로 시작하지 않는다. 이 템플릿에는 지연·처리량 목표가 없으므로 "요청당 비용이 데이터
|
||||
수에 비례해 늘어난다" 같은 측정된 사실이 시작점이다(`1101/09-performance-measurement.md` 1절).
|
||||
|
||||
**단계**
|
||||
|
||||
1. 06장 조건으로 기준선을 잰다.
|
||||
2. 원인을 좁힌다: 요청당 SQL 수, JFR 상위 프레임, 설정만 바꾼 실험(06장 3절).
|
||||
3. 변경 하나만 넣는다.
|
||||
4. 같은 조건으로 다시 잰다. 전후 숫자를 같은 표에 적는다.
|
||||
5. 회귀를 테스트로 고정한다. 예: 요청당 SQL 수를 단언하는 `WorkLogStatementCostSystemTest`(06장 6절).
|
||||
|
||||
**산출물**
|
||||
|
||||
- 측정 조건·명령·전후 숫자·회귀 테스트.
|
||||
|
||||
**완료 기준**
|
||||
|
||||
- 전후 숫자가 같은 조건(커밋 외 변수 하나)에서 나왔다.
|
||||
- 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages`가 통과).
|
||||
|
||||
## 5. 구조 변경 (폴더·모듈)
|
||||
|
||||
**시작 조건**
|
||||
|
||||
- leaf 추가·삭제·이동, 패키지 이동, 허용 의존 변경 중 하나다. 위험이 높은 작업으로 다룬다
|
||||
(`CLAUDE.md` 「Proportional workflow」).
|
||||
- 새 leaf 등록은 소유자 승인을 받는다(`1101` README 15절 "새 leaf … 등록 | 승인").
|
||||
|
||||
**단계**
|
||||
|
||||
1. `superpowers:brainstorming`으로 설계를 정하고 `docs/superpowers/specs/`에 설계서를 둔다.
|
||||
2. `docs/superpowers/plans/`에 계획을 둔다(`AGENTS.md` 「기능 개발 프로토콜」 3~4).
|
||||
3. 03장 체크리스트대로 registry·build·lockfile·문서를 함께 바꾼다.
|
||||
4. 규칙이 바뀌면 ArchUnit 규칙을 함께 바꾼다. 규칙마다 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를
|
||||
둘 다 둔다(05장 5절).
|
||||
5. 패키지 규칙이 바뀌면 생성 명령 왕복(`verifyFeatureScaffold`)이 통과해야 한다(`src/build.gradle`의
|
||||
`verifyFeatureScaffold`).
|
||||
6. 파생 서비스가 따라 할 업그레이드 안내를 쓴다.
|
||||
|
||||
**산출물**
|
||||
|
||||
- 설계서, 계획서, 구조 변경 커밋, 업그레이드 안내 행.
|
||||
|
||||
**완료 기준**
|
||||
|
||||
- `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`(생성 명령 왕복 포함)가 통과한다.
|
||||
- leaf 개수를 문서에 적지 않았다(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
|
||||
## 6. 테스트 구조 개선
|
||||
|
||||
**시작 조건**
|
||||
|
||||
- 05장 기준 위반이 있다: 이름이 말한 성질을 단언하지 않음, 포트 계약 밖의 fake, 어떤 단계에도 속하지 않는 lane,
|
||||
실패한 채 방치된 테스트 코드 정적 분석 등.
|
||||
|
||||
**단계**
|
||||
|
||||
1. 지금 테스트가 무엇을 증명하는지 적는다(이름, 단언, skip 수).
|
||||
2. 05장 기준대로 고친다. fake를 공유 계약으로 옮기면 fake와 실제 adapter가 모두 그 계약을 상속하게 한다.
|
||||
3. **변이로 확인한다.** 테스트가 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지 본다. 예: fake
|
||||
변이 6개를 모두 계약이 잡았다(`1101` README 16절 r3-b).
|
||||
4. 옮긴 뒤 같은 수의 테스트가 같은 lane에서 도는지 테스트 수로 확인한다.
|
||||
|
||||
**산출물**
|
||||
|
||||
- 테스트 변경, 변이 결과, 계약 표 갱신(`docs/testing/TESTING_STRATEGY.md` 9절처럼 표가 있으면).
|
||||
|
||||
**완료 기준**
|
||||
|
||||
- 변이가 잡혔다.
|
||||
- 새 lane이 단계에 속한다(`verifyStrictLaneStages --dry-run`).
|
||||
- `testQualityCheck`가 통과한다(07장).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다.
|
||||
- 결함 수정은 RED(수정 전 실패) 없이 끝나지 않는다.
|
||||
- 어느 작업이든 기준 커밋, 이전 결정, 소유 leaf, 스킬, 검증 위치부터 정한다.
|
||||
@@ -0,0 +1,267 @@
|
||||
# 02. 리뷰 기준
|
||||
|
||||
## 핵심
|
||||
|
||||
리뷰는 **계약과 실제 동작이 다른 곳**을 찾는다. 계약은 코드 이름·Javadoc·문서·레지스트리·테스트 이름·게이트가 약속한
|
||||
것이다. 취향과 결함은 이 기준으로 가른다: 약속을 어긴 증거가 있으면 결함이고, 없으면 개선 제안이다.
|
||||
|
||||
리뷰 결과의 판정은 네 가지를 따로 적는다(가이드 35절).
|
||||
|
||||
```text
|
||||
발견 하나
|
||||
├─ 성격 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안
|
||||
├─ 심각도 피해가 얼마나 큰가 (3절)
|
||||
├─ 증거 수준 무엇으로 확인했나 E0~E4 (4절)
|
||||
└─ 통제 수준 그 규칙을 무엇이 지키나 M0~M4 (5절)
|
||||
```
|
||||
|
||||
심각도는 고칠지 말지를 정하지 않는다. 이 repo는 모든 발견을 고치거나 결정으로 닫는다(3.3절, 09장).
|
||||
|
||||
## 1. 결함이란 — 취향과 구별
|
||||
|
||||
다음 중 하나를 증거로 보이면 결함이다.
|
||||
|
||||
| 결함의 모양 | 증거 | 지난 예 |
|
||||
| --- | --- | --- |
|
||||
| 이름·Javadoc·문서가 말한 동작과 실제 동작이 다르다 | 코드 경로 또는 실행 결과 | `1101/05-03`(`ONLY_IF_SOURCE_REVISION_NEWER`가 조건 없이 덮어씀) |
|
||||
| `AGENTS.md` HARD-STOP을 어긴다 | 의존 방향 게이트·ArchUnit·코드 | `1101/07-08`(기본 조립 루트가 선택 capability를 안다 — capability 기준 7) |
|
||||
| 같은 규칙·값·표가 두 곳 이상에 있고, 서로 다르거나 같게 지키는 장치가 없다 | 두 위치와 차이 | `1101/01-03`(`TenantId` 3벌, 문법이 셋 다 다름), `1101/04-06`(SQLState 표 2벌) |
|
||||
| 테스트나 게이트가 통과하지만 막겠다고 한 것을 막지 못한다 | 변이 실험, 실행 그래프 대조 | `1101/05-08`(소유자 검사를 지워도 442개 통과), `1101/08-01`(어떤 workflow도 돌리지 않는 strict lane 14개) |
|
||||
| 운영자·개발자에게 틀린 조치를 시키는 문서 | 문서대로 실행한 결과 | `1103/RR-05-01`(DEAD 재발행 SQL을 따르면 다시 DEAD) |
|
||||
| 위험한 동작이 기본값·설정 뒤에 숨어 있다 | 기본값과 그 효과 | `1101/02-03`(JWT audience가 비면 검증을 건너뜀) |
|
||||
|
||||
**결함이 아닌 것(개선 제안)**: 계약 위반 없이 이해·비용을 줄일 여지. 예: "이 이름이 더 낫다", "이 패턴이 더 짧다".
|
||||
개선 제안은 가이드 41절처럼 현재 선택과 대안을 비교해 적는다. 받으면 고치고, 받지 않으면 이유를 결정으로 남긴다
|
||||
(README 결정 M-8). 기록만 하고 열어 두지 않는다.
|
||||
|
||||
다음 표현은 결함 근거가 아니다(가이드 36.4).
|
||||
|
||||
| 근거가 아닌 말 | 결함으로 적으려면 |
|
||||
| --- | --- |
|
||||
| "추상화가 많다" | 어느 wrapper가 무엇을 보호하지 않는지, 지우면 무엇이 유지되는지 |
|
||||
| "운영 준비가 안 됐다" | 어떤 절차를 어떤 버전에서 실행한 증거가 없는지 |
|
||||
| "이 패턴은 업계 표준이 아니다" | 이 repo의 어느 계약을 어기는지 |
|
||||
|
||||
## 2. 발견의 성격
|
||||
|
||||
가이드 35.1의 네 가지를 쓴다. 이 repo에서 각각의 뜻:
|
||||
|
||||
| 성격 | 이 repo에서 |
|
||||
| --- | --- |
|
||||
| 확인된 결함 | 현재 커밋의 코드·실행으로 계약 위반을 보였다. 정적 증거만으로도 확정할 수 있다 |
|
||||
| 구조적 위험 | 인과 경로는 있으나 영향 확인이 남았다. 예: 다중 인스턴스 경쟁을 코드 경로로만 봤다(`1101` README 6절) |
|
||||
| 미검증 | 이 환경에서 확인할 수 없다. 예: 실제 CI runner(`1103` README 10.3절 — Gitea Actions가 꺼져 있다) |
|
||||
| 개선 제안 | 1절 "결함이 아닌 것" |
|
||||
|
||||
## 3. 심각도
|
||||
|
||||
이 repo는 심각도 체계를 두 가지 쓴다. 리뷰 종류로 고른다(README 결정 M-3).
|
||||
|
||||
### 3.1 전체 리뷰 — Critical / High / Medium / Low + P0~P3
|
||||
|
||||
가이드 35.2(심각도)와 35.3(우선순위)를 쓴다. `1101` 리뷰가 이 체계였다(`1101` README 12절 색인). 이 repo에서의 예:
|
||||
|
||||
| 등급 | 이 repo에서의 예 |
|
||||
| --- | --- |
|
||||
| Critical | 인증 없이 민감정보 접근, 실제 데이터의 비가역 대량 손상. 지난 라운드에는 없었다 |
|
||||
| High | 지원 조건에서 업무 중복 실행·결과 불명 작업 재실행(`1101/05-01`, `1101/04-02`), 기본 조합의 보안 검사가 꺼짐(`1101/02-03`) |
|
||||
| Medium | 피해가 제한되거나 변경 비용을 반복해서 올림(`1101/04-06` SQLState 표 2벌, `1101/04-05` `@Version` 충돌이 500) |
|
||||
| Low | 가독성·편의, 제한된 문서 불일치(`1101/07-11` 주석·문서가 현재 동작과 다름) |
|
||||
|
||||
우선순위: P1은 해당 용도 도입 전 해결, P2는 계획적 개선, P3는 선택(가이드 35.3). 우선순위는 **고치는 순서**다.
|
||||
|
||||
### 3.2 확인 리뷰 — Critical / Important / Minor
|
||||
|
||||
수정 diff만 보는 확인 리뷰는 `superpowers:requesting-code-review` 리뷰어 템플릿의 체계를 쓴다(`1103` README 2절 이후
|
||||
모든 round).
|
||||
|
||||
| 등급 | 정의 | 출처 |
|
||||
| --- | --- | --- |
|
||||
| Critical | 가이드 35.2의 Critical과 같다 | 가이드 35.2 |
|
||||
| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서 | `1103` README 11절(리뷰어 지침에 적은 기준) |
|
||||
| Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 | `1103/round4/review.md`, `round6/`의 Minor 항목 |
|
||||
|
||||
확인 리뷰 발견에는 "이번 커밋 / 이전부터"를 함께 적는다(`1103/round6/04-build-logic.md` 「결론」). 이번 커밋이
|
||||
만든 결함이면 회귀로 따로 센다.
|
||||
|
||||
### 3.3 심각도가 정하지 않는 것
|
||||
|
||||
- **고칠지 말지.** 소유자 규칙: Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다
|
||||
(`1103` README 16절). 그래서 심각도는 순서, 총괄의 재확인 범위(High·Important 이상은 총괄이 코드에서 다시 확인 —
|
||||
`1101` README 2절), 사용 결정(가이드 35.8)에만 쓴다.
|
||||
- **건수 부풀리기.** 한 결함이 여러 관점에 걸치면 항목 하나에 관점 번호를 모두 붙인다(가이드 0.3). 두 영역이 같은
|
||||
결함을 적으면 색인에서 합친다(`1101` README 2절).
|
||||
|
||||
## 4. 증거 수준 E0~E4 — 이 repo에서
|
||||
|
||||
정의는 가이드 35.5다. 이 repo에서 각 수준에 해당하는 증거:
|
||||
|
||||
| 수준 | 이 repo에서의 증거 | 주장할 수 없는 것 |
|
||||
| --- | --- | --- |
|
||||
| E0 설명·주장 | README·`CLAUDE.md`·Javadoc·리뷰 문서의 이전 실행 기록·묶음 보고서의 "통과" | 현재 커밋의 동작 |
|
||||
| E1 정적 확인 | 현재 커밋의 코드·설정·`build.gradle`·workflow를 `file:line`으로 읽음, `--dry-run` 그래프 | 실행 결과 |
|
||||
| E2 테스트 실행 | 이름을 댄 테스트·leaf `check`·`ci`가 **현재 커밋**에서 통과(명령·rc·테스트 수) | 실 vendor·부하·장애 |
|
||||
| E3 통합·실험 | Testcontainers 실 PostgreSQL·Redis·Kafka·MinIO lane(`integrationCheck`), `java -jar`·compose 실제 기동, 부하·장애 주입·동시 요청 실험 | 운영 환경·운영 기간 |
|
||||
| E4 운영 관찰 | 이 템플릿에는 없다. 실제 CI runner 실행 기록도 아직 없다(`1103` README 10.3절) | — |
|
||||
|
||||
규칙:
|
||||
|
||||
- **이전 라운드의 실행 결과는 현재 증거가 아니다.** 바뀐 커밋에서 다시 돌린다. 2026-11-01 성능 리뷰도 지난 리뷰의
|
||||
숫자를 쓰지 않았다(`1101/09-performance-measurement.md` 1절 「이전 리뷰와 비교」).
|
||||
- **묶음 보고서의 "통과"는 E0이다.** 총괄은 보고를 diff와 실행 기록에 대조한다. 보고서가 없는 태스크 이름을 적은 적이
|
||||
있다(`1103` README 17.2절: `:adapter:outbound:persistence-jpa:documentContractTest`는 없는 태스크).
|
||||
- **build cache로 통과한 실행은 그렇게 적는다.** `ci`가 434초에서 51초로 준 것은 캐시 재사용이었다(`1101` README 16.2절).
|
||||
- 발견마다 증거 수준을 적는다. 예: "E3 — 명령 9·10, Flyway 잠금 동작은 E1"(`1103/round6/03-persistence.md` RR6-03-01).
|
||||
|
||||
## 5. 통제 수준 M0~M4 — 이 repo에서
|
||||
|
||||
정의는 가이드 35.4다. 규칙 하나에 붙인다. 이 repo의 예:
|
||||
|
||||
| 수준 | 뜻 | 이 repo의 예 |
|
||||
| --- | --- | --- |
|
||||
| M0 | 지킬 수단이 없다 | 2026-11-01 시점 JPA 양방향 연관관계 금지(`1101/04-03`) |
|
||||
| M1 | 적혀만 있다 | `@SystemInvoked` 유스케이스를 bean으로 등록하지 말라는 주석(`1103/RR-01-02` — 그래서 결함이었다) |
|
||||
| M2 | 구현되어 있다 | 코드 경로에 규칙이 있고 검사는 없다 |
|
||||
| M3 | 자동 검증이 위반을 잡는다 | ArchUnit 규칙(`src/app-bootstrap/src/architectureTest/`), 공유 계약 테스트, `verifyStrictLaneStages` |
|
||||
| M4 | 경계에서 강제한다 | Gradle 의존 방향 게이트(`verifyCleanArchitectureDependencies`), DB 유일 제약(`1101/09-02` 수정 뒤), 기동 실패 rule |
|
||||
|
||||
- **확인하지 못한 것은 M0가 아니라 `미확인`이다**(가이드 35.4).
|
||||
- "하지 마라"가 주석·문서뿐이면 M1이다. 위험한 규칙이 M1이면 결함으로 적는다(04장 P7).
|
||||
|
||||
## 6. 28개 관점 점검 항목
|
||||
|
||||
관점의 일반 설명은 가이드 1~28절이다. 아래는 **이 repo에서 어디를 보고, 어떤 증거면 결함인가**다. "지난 예"는 그
|
||||
관점에서 실제로 나온 결함이다. 관점 판정 기호는 `1101` README 11절과 같다(O 충족 · P 부분 · X 미충족 · ? 미검증 ·
|
||||
- 적용 제외 · > 다른 영역). 종합은 평균하지 않는다. 한 영역이라도 X면 X다(가이드 35.7).
|
||||
|
||||
| # | 관점 | 이 repo에서 볼 곳 | 이런 증거면 결함 | 지난 예 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로, 불가능한 조건 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 | `1101/05-03`, `1101` README 16.1절(`BC_IMPOSSIBLE_INSTANCEOF`) |
|
||||
| 2 | 구조적 성숙도 | `src/config/architecture/modules.json`의 `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | `1101/07-08`, `1101/08-05` |
|
||||
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | `1101/01-07`(이벤트 ID 문법 5곳) |
|
||||
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래라 고르는 기준이 없음 | `1101/01-01`, `1101/07-09` |
|
||||
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값·설정 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | `1101/02-03`, `1103/RR-07-02` |
|
||||
| 6 | 실패 성숙도 | 예외 분류(`PersistenceExceptionTranslator` 등), `retryable`, 결과 불명 | 결과 불명을 확실함으로 기록, 재시도 가능을 확정 실패로 | `1101/04-01`, `1101/06-01`, `1101/05-01` |
|
||||
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 | `1103/RR-05-01`, `1103` README 6.1절(`redis.capability.*` 6개) |
|
||||
| 8 | 디버깅 가능성 | 서버 실패 로그(`ServerFailureLog`), correlation id, 오류 코드 | 서버 실패를 아무 데도 남기지 않음, 원인이 다른 실패를 같은 코드로 | `1103` README 16절 r9-a(gRPC `INTERNAL_ERROR` 무기록), `1101/01-04` |
|
||||
| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석 | 갈라진 복사본, 현재 동작과 다른 주석·문서 | `1101/04-06`, `1101/07-11` |
|
||||
| 10 | 테스트 성숙도 | 05장 기준 | 이름의 성질을 단언하지 않음, 변이 생존, 계약 밖 fake | `1101/05-08`, `1101/02-02`(`doesNotExist`가 null도 통과) |
|
||||
| 11 | 데이터 성숙도 | 마이그레이션 스트림, 유일 제약, `@Version`, 잠금 시간 제한 | 중복 규칙에 DB 제약 없음, 적용된 마이그레이션 수정, `lock_timeout` 없는 강한 잠금 | `1101/09-02`, `1103/RR-02-09` |
|
||||
| 12 | 동시성 성숙도 | claim·lease, `SKIP LOCKED`, 트랜잭션 경계, 공유 상태 | 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim | `1101/04-02`, `1101/03-10` |
|
||||
| 13 | 확장성 | 연결·구독·동시 호출·본문 크기 상한 | 상한이 없음, 상한이 코드에 드러나지 않음 | `1101/03-06`, `1101/03-09` |
|
||||
| 14 | 성능 성숙도 | 06장 기준 | 데이터 수에 비례하는 SQL 수(N+1), 순차 스캔 | `1101/09-01`, `1101/09-02` |
|
||||
| 15 | 보안 성숙도 | 인증·인가 체인, `docs/security/public-paths-snapshot.txt`, `docs/registries/secrets-classification.yaml`, 로그 | 기본으로 꺼진 검증, 권한 검사 없는 경로, 로그로 새는 입력값 | `1101/02-03`, `1101/07-03`, `1103/RR6-01-05` |
|
||||
| 16 | 의존성 성숙도 | `src/gradle/libs.versions.toml`, lockfile, `src/config/testing/container-images.properties` | 사라진 외부 이미지, 운영 jar에 테스트용 드라이버 | `1101/05-09`, `1101/09-09` |
|
||||
| 17 | API·계약 성숙도 | `docs/web/http-contract.md`, `docs/registries/error-codes.yaml`, `docs/architecture/*-api-surface.txt`, 짝 프론트 계약 | 코드·문서·짝 계약이 서로 다름 | `1101/02-01`, `1101/02-02` |
|
||||
| 18 | 배포 성숙도 | `src/Dockerfile`·`src/Dockerfile.sample`, compose, 종료 순서, `release.yml` | 빌드되지 않는 Dockerfile, 종료 순서가 relay를 모름 | `1101/07-04`, `1101/06-02` |
|
||||
| 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, leaf의 `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 | `1101/05-15`, `1101/07-06` |
|
||||
| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함 | `1103/RR-01-01`, `1103/RR-01-03` |
|
||||
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 게이트가 거짓으로 통과, 어떤 단계도 돌리지 않는 검사 | `1101/08-01`, `1103/RR-06-02`, `1103` README 14절 |
|
||||
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것, 계층별 책임 | adapter가 정책을 소유, 역할 없는 단계 | `1101/04-13`(persistence adapter가 정책 소유) |
|
||||
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 | `1101/01-03`, `1101/01-12` |
|
||||
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | `1101/05-21`(identifier leaf 이름·문서가 내용과 다름) |
|
||||
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳: 템플릿 패키지, 업그레이드 안내 | 기능 패키지가 템플릿 패키지와 섞임 | `1101/01-10` |
|
||||
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | `1101/04-16` |
|
||||
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, sample 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 | `1101/07-08`, `1101/05-19` |
|
||||
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 | `1101/03-10`, `1101/06-03` |
|
||||
|
||||
## 7. 이 repo에서 따라갈 Backend 시나리오
|
||||
|
||||
가이드 31절의 시나리오를 이 repo의 경로로 바꾼 것이다. 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며
|
||||
입력 신뢰 수준·권한 판단 위치·규칙 소유자·트랜잭션 시작과 끝·외부 부작용·오류 변환을 적는다(가이드 31절,
|
||||
`1101/01-core-and-feature-pattern.md` 4.1절 예).
|
||||
|
||||
| 시나리오 | 이 repo에서 따라갈 경로 | 지난 추적 |
|
||||
| --- | --- | --- |
|
||||
| 정상 쓰기 요청 | sample `POST /api/worklogs`, 생성 명령으로 만든 기능 | `1101/01-core-and-feature-pattern.md` 4.1절, `1101/09-performance-measurement.md` 5.3절 |
|
||||
| 중복·동시 요청 | `POST /api/posters` 같은 제목 동시 요청, 멱등 키(`docs/manual/05-idempotency.md`) | `1101/09-performance-measurement.md` 5.2절 |
|
||||
| 외부 응답 지연·유실 | httpclient 시간 예산·breaker, 알림 발송 attempt | `1101/05-05`, `1101/05-06`, `1101/05-01` |
|
||||
| DB 오류·경쟁 | `PersistenceExceptionTranslator`, `@Version`, 트랜잭션 마감 | `1101/04-01`, `1101/04-05`, `1103/RR-03-03` |
|
||||
| 메시지 중복·역순 | outbox relay, inbox 재전달, aggregate 순서 번호 | `1101/06-01`, `1103/RR-03-02` |
|
||||
| 신·구 버전 공존 | 마이그레이션 잠금, 배포 중 섞인 인스턴스 | `1103/RR-02-09`, `1103/RR-02-10` |
|
||||
| 여러 서버의 작업 실행 | 알림 정산 job claim, gRPC ledger claim | `1101/04-02`, `1101/03-10` |
|
||||
| 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, sample 소유자 검사 | `1101/05-08`, `1101/01-core-and-feature-pattern.md` 4.2절 |
|
||||
| 큰 입력·목록 조회 | `GET /api/worklogs?size=100`, GraphQL 복잡도, JSON 아닌 본문 | `1101/09-performance-measurement.md` 5.1절, `1101/03-01`, `1101/02-09` |
|
||||
| 종료·재시작 | relay·platform 종료 순서, 종료 시간 예산 | `1101/06-02`, `1101/07-07` |
|
||||
| 선택 어댑터 제거 | `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄 제거 | `1101/01-core-and-feature-pattern.md` 4.4절, `1101/08-build-ci-test.md` 4절 |
|
||||
|
||||
해당 기능이 없는 시나리오는 적용 제외 사유를 한 줄 적는다(가이드 31절).
|
||||
|
||||
## 8. 리뷰 문서 형식
|
||||
|
||||
### 8.1 전체 리뷰 — README
|
||||
|
||||
`1101` README의 절 순서를 따른다. 가이드 36.5 요약 양식에 이 repo가 더한 것(처리 현황·결정 기록)이 붙는다.
|
||||
|
||||
1. 사용 결정(가이드 35.8 표현) — 용도별 사용 가능·조건부·보류와 막는 항목
|
||||
2. 차단 항목(High·P1) — 총괄의 재확인 방법을 칸으로
|
||||
3. 확인된 강점
|
||||
4. 반복되는 원인 — 부록 패턴 번호를 붙인다
|
||||
5. 결정이 필요한 것 — 선택지·권고·승인자
|
||||
6. 미검증 — 무엇·왜·확인하려면
|
||||
7. 개선 순서 — 순서·대상·이유·완료 기준
|
||||
8. 재검토 조건
|
||||
9. 리뷰 범위(가이드 36.1) — 기준 커밋, 게이트 결과 표, 영역 표
|
||||
10. 28개 관점 판정(6절 기호)
|
||||
11. 발견 색인 — ID·심각도·우선순위·한 줄 내용
|
||||
12. 이후 라운드: 조치 현황 표, 합칠 때 생긴 충돌과 처리, 합친 뒤 게이트, 결정 기록, 남은 것
|
||||
|
||||
### 8.2 영역 문서와 확인 리뷰 문서
|
||||
|
||||
영역 문서(`NN-<영역>.md`): 범위 → 지난 발견 재확인 → 새 발견 → 시나리오 추적 → 설계 선택 검토(가이드 41절) →
|
||||
리팩터링 후보 → 28개 관점 판정표(`1101/01-core-and-feature-pattern.md` 절 순서).
|
||||
|
||||
확인 리뷰 문서(`roundN/NN-<영역>.md`): `1103/round6/*.md`의 절 순서를 따른다.
|
||||
|
||||
| 절 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 범위 | pathspec, `git diff --stat` 결과, 함께 읽은 주변 코드 |
|
||||
| 불러온 스킬과 적용한 기준 | 스킬 · 그 스킬의 기준 · 그 기준으로 본 것 |
|
||||
| 실행한 명령과 결과 | 명령 · rc · 직전 부하(1분) |
|
||||
| 못 본 것 | 무엇과 이유 |
|
||||
| 항목 재확인 | 고쳤다고 한 항목마다 닫힘 / 부분 / 안 닫힘 |
|
||||
| 결함 | `### <ID> · <심각도> · <한 줄 제목>` 아래 8.3절 필드 |
|
||||
| Declined to judge | 판단하지 않은 것과 이유. 총괄이 다음 묶음에 배정하거나 결정으로 닫는다 |
|
||||
| 결론 | Critical·Important·회귀 수, 결함 수와 "이번 커밋 / 이전부터" 구분 |
|
||||
|
||||
### 8.3 발견 하나의 형식
|
||||
|
||||
**전체 리뷰**: 가이드 36.3 표 필드 전체(성격·관련 관점·근거·발생 조건·영향·심각도·확실성·결정의 근거·이해 비용·
|
||||
최소 개선 방향·대안 비교·단순화의 보존 조건·비용·재검토 조건·완료 기준·검증 방법). 선택 비교가 필요 없는 단순 결함은
|
||||
설계 선택 필드를 `적용 제외 — <이유 한 문장>`으로 둔다(가이드 36.3). 예: `1101/08-build-ci-test.md` 08-01.
|
||||
|
||||
**확인 리뷰**: 아래 필드를 목록으로 쓴다(`1103/round6/03-persistence.md` RR6-03-01).
|
||||
|
||||
| 필드 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 위치 | `file:line`. 안내 문서·설정·코드를 나눠서 |
|
||||
| 무엇이 틀렸나 | 한 문장에 사실 하나 |
|
||||
| 발생 조건·영향 | 누가 어떤 입력·순서·배포에서 무엇을 잃나 |
|
||||
| 테스트가 못 본 이유 | 어떤 테스트가 왜 이 경로를 안 보나 |
|
||||
| 고치는 법 | 권장안과 대안, 권장안의 RED 테스트 모양 |
|
||||
| 이번 커밋 / 이전부터 | 회귀인지 |
|
||||
| 증거 | E 수준과 명령 번호 |
|
||||
|
||||
### 8.4 ID
|
||||
|
||||
- 라운드 안에서는 `NN-MM`(영역-순번). 확인 리뷰는 라운드 접두어를 붙인다: `RR-`, `RR2-` … `RR6-`.
|
||||
- 라운드 밖(다른 문서·커밋·주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `1101/05-01`, `1103/RR6-01-05`(가이드 36.3).
|
||||
- 영역 문서의 접두어를 리뷰가 끝난 뒤 바꾸지 않는다. 접두어를 손으로 바꾸다 5건이 색인에서 빠졌다(`1101` README 12절 정정).
|
||||
|
||||
## 9. 리뷰어가 하지 않는 것
|
||||
|
||||
- **코드를 고치지 않는다.** 리뷰는 읽기 전용이다. 실험은 별도 worktree에서 하고 지운다(`1103` README 머리말).
|
||||
- **이전 실행 결과를 현재 증거로 쓰지 않는다**(4절).
|
||||
- **같은 결함을 여러 번 세지 않는다**(3.3절).
|
||||
- **정한 결정을 결함으로 다시 올리지 않는다.** 결정의 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다
|
||||
(08장 2절). 예: round6 build-logic 리뷰는 16절 결정인 거짓 실패 모양을 다시 올리지 않았다
|
||||
(`1103/round6/04-build-logic.md` 「Declined to judge」).
|
||||
- **범위 밖 결함을 버리지 않는다.** pathspec 밖에서 본 결함은 「Declined to judge」에 위치와 함께 적어 총괄에게 넘긴다
|
||||
(`1103/round6/04-build-logic.md` 「Declined to judge」의 httpclient 문서 항목).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 결함은 "약속과 다른 동작"의 증거로 정한다. 증거가 없으면 개선 제안이고, 그것도 받거나 이유를 남겨 닫는다.
|
||||
- 심각도는 고칠지가 아니라 고칠 순서와 재확인 범위를 정한다.
|
||||
- 증거 수준을 발견마다 적는다. 보고서와 이전 실행은 E0다.
|
||||
- 리뷰 문서는 전체 리뷰는 `1101`, 확인 리뷰는 `1103/round6` 모양을 따른다.
|
||||
@@ -0,0 +1,159 @@
|
||||
# 03. 폴더·모듈 구조 기준
|
||||
|
||||
## 핵심
|
||||
|
||||
이 repo의 모듈 구조는 **디렉터리가 아니라 registry가 정한다.** `src/config/architecture/modules.json`이 leaf의 ID·
|
||||
소스 경로·Gradle path·허용 의존을 가진 유일한 목록이고, settings와 의존 방향 게이트가 그 파일을 읽는다
|
||||
(`AGENTS.md` 「Gradle 정책 권위」). 폴더 구조를 바꾸는 일은 곧 registry를 바꾸는 일이다.
|
||||
|
||||
```text
|
||||
src/config/architecture/modules.json leaf 목록과 허용 edge (정본)
|
||||
├─> src/settings.gradle ca.architecture-registry가 읽어 project include·디렉터리 매핑
|
||||
├─> verifyCleanArchitectureDependencies 허용되지 않은 edge를 막는다 (architectureCheck)
|
||||
└─> leaf build.gradle ca.java-library / ca.spring-library / ca.platform-module 중 하나
|
||||
```
|
||||
|
||||
이 장은 구조를 평가하거나 바꿀 때의 기준이다. 새 기능을 **어디에 둘지**는 `docs/manual/03-placement.md`가 정한다.
|
||||
|
||||
## 1. 구조 지도
|
||||
|
||||
leaf 개수는 적지 않는다. 문서에 적은 수는 leaf가 추가되는 순간 틀린다(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
|
||||
```text
|
||||
src/ Gradle 루트 (명령은 여기서 실행)
|
||||
domain-core/ 순수 도메인
|
||||
application-core/ 유스케이스·포트
|
||||
application-<capability>/ 선택 기능의 application (notification, fileserver, objectstorage)
|
||||
shared-contract/ skeleton 전체의 운영 계약
|
||||
adapter/inbound/*/ 전송 경계 (web, graphql, grpc, websocket, messaging …)
|
||||
adapter/outbound/*/ 저장소·외부 능력 (persistence-*, cache-redis, httpclient …)
|
||||
composition/*/ 조립 전용 leaf (bootstrap에서 떼어 낸 조립)
|
||||
messaging/*/ vendored 메시징 제품 — 계층이 아니다
|
||||
grpc/*/, grpc-advanced/*/ optional-platforms 빌드 (`-p optional-platforms`)
|
||||
sample-portfolio/ 지울 수 있는 샘플
|
||||
app-bootstrap/ Spring Boot 진입점·조립 루트
|
||||
build-logic/ convention plugin (included build)
|
||||
config/ architecture registry, spotbugs 제외, testing 이미지 목록 …
|
||||
optional-platforms/ gRPC 플랫폼용 별도 빌드 루트
|
||||
docs/ scripts/ infra/ .github/workflows/
|
||||
```
|
||||
|
||||
| 묶음 | 책임의 정본 |
|
||||
| --- | --- |
|
||||
| family별 책임 | `AGENTS.md` 「모듈 책임」, `CLAUDE.md` 「Module families」 |
|
||||
| leaf별 규칙 | 가장 가까운 `src/**/CLAUDE.md` |
|
||||
| leaf별 Gradle path·허용 의존 | `src/config/architecture/modules.json` |
|
||||
| vendored family의 예외 | `CLAUDE.md` 「Module families」 마지막 문단, `src/messaging/CLAUDE.md` |
|
||||
|
||||
## 2. 기준
|
||||
|
||||
각 기준은 "규칙 → 왜 → 지키는 장치 → 지난 결함" 순서다.
|
||||
|
||||
### 2.1 leaf는 registry 한 곳에서 생기고 사라진다
|
||||
|
||||
- **규칙**: leaf를 더하거나 지우는 일은 `modules.json`에서 시작한다. registry에 없는 디렉터리에 build 스크립트가 있으면
|
||||
빌드가 실패해야 한다.
|
||||
- **왜**: registry에 없는 leaf 디렉터리가 조용히 빌드에서 빠진 적이 있다(`1101/08-05`).
|
||||
- **장치**: `ModuleRegistry.unregisteredBuildScripts`(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java`)가
|
||||
잡는다. git이 무시하는 IDE 출력 `bin/`은 건너뛴다(`1101` README 14.2절).
|
||||
|
||||
### 2.2 문서는 leaf 목록과 개수를 복제하지 않는다
|
||||
|
||||
- **규칙**: root 문서와 매뉴얼은 family만 말하고 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf의 명령은 registry의
|
||||
`gradle_path`에서 만든다.
|
||||
- **왜**: 복제한 목록은 drift한다. 개수를 대조하던 파서(`verifyDocumentedLeafCount`)는 지웠다 — 문서에 틀린 수가 있으면
|
||||
결함이지만 빌드 실패 사유는 아니다(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
- **장치**: 없다(의도). 리뷰가 본다.
|
||||
|
||||
### 2.3 새 기능은 기본적으로 계층 leaf 안의 패키지다
|
||||
|
||||
- **규칙**: 업무 기능은 계층 leaf 안 `<feature>` 패키지, 켜고 끄는 플랫폼 기능만 `application-*` leaf. 고르는 기준표는
|
||||
`docs/manual/03-placement.md`가 정본이다.
|
||||
- **왜**: 모양이 세 갈래이고 고르는 기준이 없던 것이 결함이었다(`1101/01-01`, `1101/07-09`).
|
||||
- **장치**: `scripts/new-feature.sh`가 기본 모양만 만들고, `verifyFeatureScaffold`(`mainCheck`)가 왕복을 검사한다.
|
||||
|
||||
### 2.4 템플릿 패키지와 기능 패키지를 섞지 않는다
|
||||
|
||||
- **규칙**: 템플릿이 소유한 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표가 정본이다. 기능은 그
|
||||
이름을 쓰지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다.
|
||||
- **왜**: 이름이 겹치면 upstream 템플릿 업데이트가 파생 서비스의 기능 패키지에 섞여 들어간다(`1101/01-10`).
|
||||
- **장치**: ArchUnit 2개(템플릿 이름 재사용 금지, 템플릿→기능 import 금지), 표와 `TemplatePackageOwnership`을 대조하는
|
||||
`TemplatePackageOwnershipDocumentTest`(`1103` README 16절 r9-a). `new-feature.sh`가 이미 있는 패키지 이름을 거절한다
|
||||
(`1101` README 16절 r3-g).
|
||||
- **한계**: 표에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수 없다(`1103` README 16절 r9-a "한계로 문서화").
|
||||
템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
|
||||
### 2.5 조립은 그 능력의 모듈이 한다
|
||||
|
||||
- **규칙**: capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan
|
||||
정규식을 갖지 않는다. 여러 leaf에 걸친 조립은 `composition:*` leaf가 한다.
|
||||
- **왜**: 한 줄을 지웠을 때 기능이 완전히 사라져야 한다(capability 기준 7). 기본 조립 루트가 선택 capability를 알던 것이
|
||||
결함이었다(`1101/07-08`, `1101/05-19`).
|
||||
- **정본**: `AGENTS.md` capability 기준 2·7, 결정 3(outbox relay·멱등성 executor 조립은 `composition:*`).
|
||||
|
||||
### 2.6 vendored family는 앱 계층에 기대지 않는다
|
||||
|
||||
- **규칙**: `messaging:*`(그리고 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다.
|
||||
앱은 `adapter:outbound:messaging`의 anti-corruption bridge로만 닿는다.
|
||||
- **왜**: 다른 제품이라 앱 계층에 의존하면 경계가 무너진다(`CLAUDE.md` 「Module families」, messaging 리뷰 MSG-023).
|
||||
- **결과**: 공용 헬퍼를 쓸 수 없어 복사본이 남는다. 복사본은 이유를 family `CLAUDE.md`에 적는다(`1101` README 15절 01-11,
|
||||
`src/messaging/CLAUDE.md` 「공용 다이제스트 헬퍼를 복사해 두는 이유」). 값이 같아야 하는 복사본은 대조 테스트를 붙인다
|
||||
(`1103` README 17절 r10-03 Flyway 정책 사본).
|
||||
|
||||
### 2.7 source set은 실행 조건이 다를 때만 나눈다
|
||||
|
||||
- **규칙**: 별도 source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 만든다. 공유 테스트
|
||||
코드는 `src/testFixtures/java`(`java-test-fixtures`)에 둔다.
|
||||
- **정본**: `docs/testing/TESTING_STRATEGY.md` 4·5절, `docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`.
|
||||
- **왜**: 같은 일을 하는 두 관례(`ca.testkit-publisher`와 `java-test-fixtures`)가 있던 것이 결함이었다(ADR-BUILD-001 「Context」).
|
||||
|
||||
### 2.8 마이그레이션은 스트림마다 따로, 적용된 파일은 고치지 않는다
|
||||
|
||||
- **규칙**: 저장소마다 자기 마이그레이션 디렉터리와 history table을 가진다(예: `.../db/migration/jpa/core`,
|
||||
`.../jpa/notification-platform`, `src/sample-portfolio/src/main/resources/db/sample-migration`). 번호는 스트림 안의 순번이고,
|
||||
샘플은 운영 스트림과 합쳐 도는 테스트가 있어 겹치지 않는 번호를 쓴다(`V8_1`). 어딘가에 적용된 마이그레이션은 고치지
|
||||
않는다.
|
||||
- **정본**: `docs/manual/04-persistence.md`, `docs/jpa/migration-guide.md`.
|
||||
- **장치**: `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`(적용된 파일의 해시 고정),
|
||||
잠금 대기 검사기의 동결 목록(`1103` README 10절 r5-c, 12절 r6-b).
|
||||
- **예외의 근거**: 아직 어디에도 적용되지 않은 마이그레이션만 직접 고쳤다. 고칠 때는 main과 파생 서비스에 그 파일이
|
||||
없음을 확인했다(`1103` README 6절 r4-c "V21 직접 수정", 11절 "고친 마이그레이션 9개가 main `01a8a2a70`과 파생 서비스에
|
||||
없음").
|
||||
|
||||
### 2.9 문서는 정해진 디렉터리에 둔다
|
||||
|
||||
- **규칙**: 문서 위치 규칙은 `docs/README.md`가 정본이다. 리뷰 결과는 `docs/reviews/<YYYY-MM-DD>-<종류>/`, 설계서는
|
||||
`docs/superpowers/specs/`, 계획서는 `docs/superpowers/plans/`, 결정 기록(ADR)은 `docs/adr/`, 파생 서비스용 변경 안내는
|
||||
`docs/upgrade/`.
|
||||
- **왜**: 계획서를 사후에 고치지 않는다. 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 된다
|
||||
(`docs/README.md` 「설계와 계획」).
|
||||
|
||||
## 3. 구조 변경 체크리스트
|
||||
|
||||
leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾸는 것이다. 근거는 `docs/manual/03-placement.md` 기준표의
|
||||
"고칠 공용 파일" 칸과 이 장 2절이다.
|
||||
|
||||
- [ ] `src/config/architecture/modules.json`: ID·`source_path`·`gradle_path`·`allowed_dependencies`
|
||||
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
|
||||
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
|
||||
- [ ] capability면 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄, 자기 `AutoConfiguration.imports`
|
||||
- [ ] leaf `CLAUDE.md`(가까운 안내 — 없으면 `1101/04-16` 같은 결함), capability면 README 세 가지(capability 기준 6)
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 `src/application-core/CLAUDE.md` 「Package ownership」 표
|
||||
- [ ] ArchUnit 규칙과 그 위반·허용 fixture(05장 5절)
|
||||
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
|
||||
- [ ] 파생 서비스에 영향이 있으면 업그레이드 안내 행(`docs/upgrade/2026-11-maturity-review.md` 형식)
|
||||
|
||||
검증은 07장 2절 "leaf 경계·의존·registry" 행이다.
|
||||
|
||||
## 4. 구조 변경에서 하지 않는 것
|
||||
|
||||
- 요청 범위 밖의 대규모 리팩터링(`AGENTS.md` 「금지된 지름길」). 한 계층 안의 일은 그 leaf와 그 테스트 안에서 끝낸다.
|
||||
범위를 넘어야 하면 멈추고 범위를 다시 받는다(`CLAUDE.md` 「Layer workflow」).
|
||||
- 전 leaf의 import를 바꾸는 이동을 다른 수정 묶음과 동시에. 그런 묶음은 나머지를 합친 뒤 단독으로 마지막에 한다
|
||||
(`1101` README 15.1절 r3-G).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 구조의 정본은 registry다. 폴더를 바꾸면 registry·build·문서를 같은 변경에서 바꾼다.
|
||||
- 문서는 leaf 목록과 개수를 적지 않는다.
|
||||
- 템플릿 패키지 목록은 `application-core/CLAUDE.md` 표 하나, 마이그레이션은 스트림마다, 적용된 파일은 고치지 않는다.
|
||||
@@ -0,0 +1,182 @@
|
||||
# 04. 코드 구조 기준
|
||||
|
||||
## 핵심
|
||||
|
||||
계층·경계 규칙의 정본은 `AGENTS.md`다. 이 장은 그 규칙을 다시 쓰지 않는다. 대신 **지난 리뷰에서 반복해 나온 결함을
|
||||
코드 구조 기준으로 바꿔** 적는다. 같은 결함이 영역을 바꿔 가며 다시 나왔기 때문이다(`1101` README 4절 "반복되는 원인").
|
||||
|
||||
```text
|
||||
AGENTS.md (HARD-STOP·모듈 책임·금지된 지름길) ── 무엇을 어기면 안 되나
|
||||
leaf CLAUDE.md, application-core/CLAUDE.md ── 그 계층의 모양
|
||||
docs/manual/ ── 새 기능을 만들 때의 판단
|
||||
이 장 (P1~P11) ── 고치거나 리뷰할 때 반복해서 틀린 곳
|
||||
```
|
||||
|
||||
## 1. 계층·경계 — 정본을 가리킨다
|
||||
|
||||
| 무엇 | 정본 | 지키는 장치 |
|
||||
| --- | --- | --- |
|
||||
| HARD-STOP 7개 | `AGENTS.md` 「Prime Directive」 | 의존 방향 게이트, ArchUnit(`architectureCheck`) |
|
||||
| family 책임과 금지 | `AGENTS.md` 「모듈 책임」, leaf `CLAUDE.md` 「Allowed」「Forbidden」 | 위와 같음 |
|
||||
| 금지된 지름길(controller의 repository 호출, application의 JPA 엔티티 반환 …) | `AGENTS.md` 「금지된 지름길」 | ArchUnit |
|
||||
| 유스케이스 모양, 허용 트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 | `ApplicationBoundaryArchitectureTest` 등 |
|
||||
| 이름 규칙 | `src/application-core/CLAUDE.md` 「Naming convention」 | `NamingConventionTest` |
|
||||
| `@Configuration` 분해 기준(대략 `@Bean` 8개, 서로 무관한 포트 묶음 둘이면 나눔) | `src/app-bootstrap/CLAUDE.md` 「Decomposition threshold」 | 리뷰 |
|
||||
| 설정: typed settings, prefix 하나, `StrictSettingsBinder`, compact constructor 검증 | `AGENTS.md` 「설정과 런타임」, capability 기준 4 | settings 바인딩 테스트 |
|
||||
| 오류 모델·HTTP 계약 | `docs/manual/06-errors.md`, `docs/web/http-contract.md` | 계약 테스트 |
|
||||
| 멱등성·결과 불명 | `docs/manual/05-idempotency.md`, `docs/adr/ADR-JPA-003-completion-unknown.md` | 공유 계약 `IdempotencyStoreContract` |
|
||||
| 권한 | `docs/manual/07-authorization.md` | ArchUnit, 기동 rule |
|
||||
| outbox·이벤트 | `docs/manual/09-outbox-events.md` | 공유 계약, ArchUnit |
|
||||
|
||||
리뷰가 이 표의 규칙 위반을 찾으면 정본의 문장을 근거로 적는다. 정본이 틀렸다고 보이면 정본을 고치는 변경을 따로 낸다.
|
||||
|
||||
## 2. 반복 결함 패턴 → 기준
|
||||
|
||||
각 패턴은 **규칙 · 왜(지난 결함) · 리뷰에서 볼 것 · 막는 장치** 순서다. 부록의 카탈로그와 번호가 다르다: 부록은
|
||||
테스트·게이트·작업 과정 패턴까지 모은 목록이고(A1~A16), 이 장은 그중 코드 구조에 해당하는 것만 다룬다.
|
||||
테스트 패턴은 05장, 게이트 패턴은 07장에 있다.
|
||||
|
||||
### P1. 갈라진 복사본 (부록 A1)
|
||||
|
||||
- **규칙**: 규칙·표·정규식·상수·이미지 참조는 한 곳에 둔다. 두 곳이 꼭 필요하면 하나를 정본으로 명시하고, 다른 하나가
|
||||
정본과 같은지 보는 대조 테스트를 둔다. 정본 없이 복사하지 않는다.
|
||||
- **왜**: `TenantId` 3벌의 문법이 셋 다 달랐다(`1101/01-03`). SQLState 분류표 2벌이 이미 갈라졌다(`1101/04-06`).
|
||||
MinIO 이미지 참조가 네 곳에 있었다(`1101/05-09`). 이벤트 ID 문법이 다섯 곳에 있었다(`1101/01-07`).
|
||||
GraphQL client가 page 규칙 복사본을 가졌다(`1103/RR-01-14`). gRPC 빌드가 마이그레이션 버전 정규식을 한 벌 더 가졌다
|
||||
(`1103` README 16절 r9-c).
|
||||
- **볼 것**: 새로 쓴 상수·정규식·표가 이미 어딘가에 있는지 grep. 같은 판정을 두 클래스가 하는지.
|
||||
- **장치**: 정본을 가져다 쓰기(예: 버전 판정 정본 `VersionedMigrationFiles`를 grpc 빌드가 Sync 태스크로 가져옴 —
|
||||
`1103` README 16절 r9-c), 대조 테스트(예: `TemplatePackageOwnershipDocumentTest`, messaging Flyway 정책 사본의 대조
|
||||
테스트 — `1103` README 17절 r10-03). 테스트 lane의 컨테이너 이미지는 `src/config/testing/container-images.properties`
|
||||
한 곳이다. MinIO qualification 이미지만 objectstorage leaf가 따로 소유한다(그 파일 머리말).
|
||||
|
||||
### P2. 문서와 코드 불일치 (부록 A2)
|
||||
|
||||
- **규칙**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: 계약(`docs/web/http-contract.md`),
|
||||
레지스트리(`docs/registries/`), runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을
|
||||
grep으로 찾아 남은 곳을 없앤다.
|
||||
- **왜**: runbook·`error-codes.yaml`이 없는 헤더와 polling을 말했다(`1101/02-01`). 수정 뒤 매뉴얼 세 곳이 코드와
|
||||
반대가 됐다(`1103/RR-01-03`). 같은 응답의 클라이언트 안내가 계약 표·매뉴얼·runbook에서 서로 달랐다(`1103/RR5-01-01`).
|
||||
고친 설명이 가이드 밖 세 곳에 옛 문장으로 남았다(`1103/RR6-03-05`). 실패 메시지와 문서가 이유를 사실과 반대로 적었다
|
||||
(`1103/RR6-04-05`).
|
||||
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`와 `src/**/README.md`·`CLAUDE.md`를 grep.
|
||||
- **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane(`1103` README 10절 r5-c RR-02-14),
|
||||
runbook SQL을 실 PG에서 그대로 실행하는 lane(`1103` README 6절 r4-e). 나머지는 리뷰가 본다 — 이 repo는 문서 전체를
|
||||
파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절).
|
||||
|
||||
### P3. 선언과 실행이 떨어져 있다 (부록 A3)
|
||||
|
||||
- **규칙**: 선언(설정 키, 레지스트리 행, 지표 이름, 옵션)마다 그것을 실행하는 코드가 있어야 한다. 실행 코드가 없으면
|
||||
선언을 지운다. "동작하지 않는 옵션은 설정 키 자체를 두지 않는다"(capability 기준 3).
|
||||
- **왜**: 바인딩되지만 동작하지 않는 HTTP client 설정 키(`1101/05-15`), 검증만 통과하고 처리 코드가 없는
|
||||
`operation-ledger-enabled`(`1101/03-11`), 레지스트리는 `required: true`인데 코드는 빈 값을 허용한 JWT audience
|
||||
(`1101/02-03`), 어떤 코드도 내보내지 않는 `docs/registries/metrics.yaml`의 `redis.capability.*` 6개(`1103` README 6.1절).
|
||||
기동 rule을 non-static `@Bean`으로 쓰거나 필드 주입으로 만들면 선언한 설정 bean이 조용히 바인딩되지 않았다
|
||||
(`1103/RR-06-01`, `1103/RR2-04-03`).
|
||||
- **볼 것**: 새 설정 키의 읽는 곳, 새 레지스트리 행의 내보내는 곳, 문서가 말한 옵션의 분기.
|
||||
- **장치**: `StrictSettingsBinder`(모르는 키·오타 거부), `verifyEnvKeys`, 레지스트리와 코드를 대조하는 테스트(`ErrorCodeRegistryMappingTest`, `HeaderRegistryRuntimeAlignmentTest` 등).
|
||||
|
||||
### P4. 결과 불명을 "확실함"으로 기록한다 (부록 A4)
|
||||
|
||||
- **규칙**: 외부 효과(DB 커밋, 알림 발송, broker 전송)의 결과를 모르면 "결과 불명"으로 기록·응답한다. 결과 불명을 자동으로
|
||||
다시 실행하지 않는다. 반대로 확실히 실패한 것을 결과 불명으로 부풀리지도 않는다.
|
||||
- **왜**: 결과 불명 처리를 정한 문서(ADR-JPA-003, 알림 evidence 모델)가 있었지만 경계마다 다시 구현되며 갈라졌다
|
||||
(`1101` README 4절 원인 1). 알림 attempt를 "시작 안 함(확정)"으로 저장한 채 provider를 불렀다(`1101/05-01`). 커밋 중
|
||||
끊김을 재시도 가능으로 답했다(`1101/04-01`). 재시도 가능한 거부를 확정 거부로 바꿔 DEAD로 보냈다(`1101/06-01`). 반대
|
||||
방향: Redis 연결 실패를 결과 불명으로 보고했다(`1101/05-17`). 멱등성 complete 단계의 저장소 실패를 "실행 전 거부"로
|
||||
적었다(`1103/RR-02-03`).
|
||||
- **볼 것**: 외부 호출 전후의 상태 기록 순서, 예외를 retryable·terminal·unknown으로 나누는 분기, 응답 코드의 `retryable`.
|
||||
- **장치**: 멱등성 공유 계약(`IdempotencyStoreContract` — PostgreSQL·Redis store가 같은 판정, `1103` README 15절 결정 ①),
|
||||
`PersistenceExceptionTranslator`의 커밋 단계 분류.
|
||||
|
||||
### P5. 중복·경쟁을 코드 순서로 막는다 (부록 A5)
|
||||
|
||||
- **규칙**: 유일성은 DB 유일 제약이 막고, adapter는 그 제약 위반만 기능 예외로 바꾼다. 여러 인스턴스가 집는 작업은
|
||||
트랜잭션 안의 claim + lease로 소유권을 정한다. "조회 후 insert", "찾고 없으면 넣기"는 쓰지 않는다.
|
||||
- **왜**: 포스터 제목 중복 규칙이 동시 요청에서 깨졌다(`1101/09-02`). upsert가 찾고 넣기였다(`1101/04-08`). `SKIP LOCKED`
|
||||
claim이 트랜잭션 없이 돌아 잠금이 바로 풀렸다(`1101/04-02`). ledger claim에 lease가 없었다(`1101/03-10`). counter 첫
|
||||
생성이 겹치면 두 번째 쓰기가 409였다(`1103/RR-03-01`).
|
||||
- **볼 것**: 존재 확인 뒤 쓰기, 트랜잭션 밖 잠금, 프로세스 메모리에 둔 소유권(`1101/04-13`).
|
||||
- **정본·장치**: `docs/manual/04-persistence.md`, 가이드 31절 "비용이 작은 개선부터 비교". `CallerTransaction`
|
||||
(store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(`CreatePosterConcurrencyIntegrationTest`).
|
||||
|
||||
### P6. 이름만 보는 허용·거부 (부록 A9)
|
||||
|
||||
- **규칙**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 **허용 목록**으로 연다. 허용 목록의 각 값은
|
||||
실제로 그 값으로 동작해야 한다.
|
||||
- **왜**: 데모 계정 거부가 정확히 `prod`에서만이라 `production`·`staging`·프로필 없음에서 열렸다(`1103/RR-07-02` →
|
||||
`1103` README 4절 결정: `local`·`test`·`demo` 허용 목록). 그 허용 목록의 `test`·`demo`로는 sample이 뜨지 않았다
|
||||
(`1103/RR2-04-02`). 비밀이 아닌 값까지 `fixture-` 검사에 막혔다(`1103/RR2-04-01` → 비밀로 분류된 키만).
|
||||
- **볼 것**: 프로필·환경 이름 문자열 비교, 허용 목록의 각 값으로 실제 기동하는 테스트가 있는지.
|
||||
- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동).
|
||||
|
||||
### P7. 글로만 있는 규칙 (부록 A10)
|
||||
|
||||
- **규칙**: "하지 마라"는 주석·Javadoc·문서는 규칙을 지키지 못한다(통제 M0~M1, 02장 5절). 위반하면 데이터·권한이 깨지는
|
||||
규칙은 기동 실패·ArchUnit·타입으로 막는다.
|
||||
- **왜**: `@SystemInvoked` 유스케이스를 bean으로 등록하지 말라는 것이 주석뿐이었다. 탐침 테스트로 bean 기동이
|
||||
됐다(`1103/RR-01-02` = `RR-07-01` → 기동 실패 + ArchUnit). JPA 양방향 연관관계 금지를 막는 장치가 없었고, 문서와 fixture는
|
||||
오히려 양방향을 가르쳤다(`1101/04-03` → `JpaArchitectureRules`). capability 완료 기준 5(fake와 실제 adapter가 같은 계약)가
|
||||
영역 전체에서 지켜지지 않았다(`1101/05-16`).
|
||||
- **볼 것**: Javadoc·문서의 "must not", "하지 않는다", "금지", "반드시"가 붙은 문장마다 막는 장치가 있는지.
|
||||
- **장치**: 이유를 요구하는 표시(`@SystemCaller(reason)` — `1103` README 10절 r5-b), 기동 rule, ArchUnit.
|
||||
|
||||
### P8. 로그로 새는 입력값·원인 (부록 A8)
|
||||
|
||||
- **규칙**: 클라이언트 탓 실패(입력 오류)는 WARN 한 줄로 남기고 입력값을 싣지 않는다. 서버 실패는 전송마다 같은 실패 로그
|
||||
줄(`ServerFailureLog`)을 쓰고, 원인 체인의 SQL·입력값을 로그 메시지에 그대로 붙이지 않는다. 클라이언트가 보낸 식별자는
|
||||
규칙 밖이면 서버가 새 값으로 바꾼다.
|
||||
- **왜**: gRPC 서비스가 던진 raw status 설명(입력값 포함)이 로그에 남았다(`1103/RR6-01-05`). STOMP가
|
||||
`IllegalArgumentException`을 ERROR로, 메시지(입력값)까지 남겼다(`1103/RR6-01-06`). STOMP가 persistence 실패의 SQL 원인까지
|
||||
로그에 썼다(`1103` README 16절 r9-a). `X-Correlation-Id` 규칙이 요청 ID와 달라 로그 주입이 열렸다(`1101/02-11` → 15절
|
||||
결정 "규칙 밖이면 서버가 교체").
|
||||
- **볼 것**: 새 `log.warn`/`log.error`의 인자, 예외 메시지에 사용자 입력을 넣는 곳, 전송별 예외 처리기.
|
||||
- **정본·장치**: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java`(`refusedArgument` 포함),
|
||||
비밀 하드코딩 금지(`AGENTS.md` 「설정과 런타임」), 비밀 분류 `docs/registries/secrets-classification.yaml`.
|
||||
|
||||
### P9. 샘플·fixture가 운영 경로와 다르게 조립된다 (부록 A11)
|
||||
|
||||
- **규칙**: 샘플은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다.
|
||||
"새 기능의 모양"이라고 둔 fixture는 실제로 기동되는 모양이어야 한다.
|
||||
- **왜**: 샘플이 보안 자동 설정을 통째로 빼서 `@RequiresPermission`이 동작하지 않았다(`1101/07-03`). 샘플의 런타임
|
||||
기본값이 기본 조합과 달랐다(`1101/09-08`). onboarding fixture의 유스케이스가 기동에 실패하는 모양이었다(`1101/01-02`).
|
||||
`Dockerfile.sample`이 빌드되지 않았다(`1101/07-04`).
|
||||
- **볼 것**: 샘플 `@SpringBootApplication(exclude=…)`, 샘플 `application.yml`과 기본 조합의 차이.
|
||||
- **장치**: sample 전체 기동 lane(`:sample-portfolio:systemTest`, `mainCheck`), sample 실서버 계약(`sampleWebContractCheck`).
|
||||
|
||||
### P10. 타이밍에 기댄 약속 (부록 A14)
|
||||
|
||||
- **규칙**: "스레드를 남기지 않는다", "시간 안에 끊는다" 같은 약속은 join·종료 대기·전용 스레드로 보장한다. 공용 풀이나
|
||||
"보통은 끝나 있다"에 기대지 않는다.
|
||||
- **왜**: `ClientRuntimeRegistry.close()`가 종료 신호만 기다려, 부하가 높으면 돌아온 뒤에도 스레드가 살아 있었다
|
||||
(`1103` README 16.1절). JDK read-idle watchdog이 공용 `ForkJoinPool`에서 돌아, 공용 풀이 막히면 300ms 설정이 2,699ms가
|
||||
됐다(`1103/RR3-03-01`). 전체 시간 예산이 진행 중 attempt를 끊지 못했다(`1101/05-06`).
|
||||
- **볼 것**: `awaitTermination` 뒤 스레드 생존 확인, 시간 제한을 거는 실행기가 공용인지.
|
||||
- **장치**: 부하·자원 한계 lane(`httpClientPerformanceTest` 등, `performanceCheck`).
|
||||
|
||||
### P11. 상한 없는 자원 (부록 A16)
|
||||
|
||||
- **규칙**: 연결 수·구독 수·동시 호출·본문 크기·트랜잭션 시간·큐 길이에는 상한이 있고, 그 값이 코드나 설정에 드러난다.
|
||||
상한을 넘으면 정해진 응답(예: WebSocket 1013, gRPC 즉시 닫기)을 준다.
|
||||
- **왜**: WebSocket 연결·구독·연결 수명 상한이 없었다(`1101/03-06`). gRPC 서버가 io.grpc 기본값으로 떴다(`1101/03-09`).
|
||||
기본 트랜잭션에 시간 제한이 없었다(`1101/04-10`). JSON 아닌 본문 상한이 없었다(`1101/02-09`).
|
||||
- **정한 값**: `1101` README 15절(gRPC 스레드 32·큐 256·동시 100·deadline 10s, WebSocket `max-connections` 1000, 트랜잭션
|
||||
30초). JSON 아닌 본문 상한은 엔드포인트가 직접 둔다(같은 절).
|
||||
|
||||
## 3. 코드에 결정을 드러내는 법
|
||||
|
||||
결함을 고칠 때 "왜 이 모양인가"가 코드 가까이에 남아야 다음 리뷰가 같은 질문을 다시 하지 않는다(가이드 39.2).
|
||||
|
||||
| 경우 | 이 repo에서 남기는 곳 | 예 |
|
||||
| --- | --- | --- |
|
||||
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc | notification `TenantId`의 차이와 이유(`1101` README 15절 01-03) |
|
||||
| 정적 분석 제외 | 제외 항목 옆 이유 | `src/config/spotbugs/exclude-test.xml`(`1103` README 14절), 메서드 하나로 좁힌 FindSecBugs 제외(`1103` README 6.1절) |
|
||||
| 규칙의 예외 경로 | 이유를 요구하는 표시 | `@SystemCaller(reason)` |
|
||||
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md` | `src/messaging/CLAUDE.md` 「공용 다이제스트 헬퍼를 복사해 두는 이유」 |
|
||||
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` | `docs/adr/ADR-JPA-003-completion-unknown.md` |
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 계층 규칙은 `AGENTS.md`와 leaf `CLAUDE.md`가 정본이다. 이 장은 반복해서 틀린 곳(P1~P11)을 기준으로 바꾼 것이다.
|
||||
- 고칠 때마다 "같은 원인의 다른 자리"와 "그 동작을 설명하는 문서"를 함께 찾는다(P1·P2·P4).
|
||||
- "하지 마라"는 주석이 아니라 장치로 막는다(P7).
|
||||
@@ -0,0 +1,143 @@
|
||||
# 05. 테스트 구조 기준
|
||||
|
||||
## 핵심
|
||||
|
||||
테스트는 **이름이 말한 것을 증명해야 한다.** 통과하는 테스트가 지키겠다고 한 동작을 실제로 지키지 못하면, 그 테스트는
|
||||
초록색 거짓말이다. 지난 리뷰에서 그런 테스트가 반복해서 나왔다(부록 A6).
|
||||
|
||||
정본은 셋이다. 이 장은 그 셋을 가리키고, 개선 작업에서 테스트를 평가·수정할 때의 기준을 더한다.
|
||||
|
||||
| 무엇 | 정본 |
|
||||
| --- | --- |
|
||||
| 테스트 작성 규칙 6개(이름·`@DisplayName`·GWT·`@Nested`·단언·fake) | `AGENTS.md` 「테스트 전략」 |
|
||||
| 테스트 분류 5개(TEST·INTEGRATION·SYSTEM·ARCHITECTURE·PERFORMANCE), 배치, source set, 공용 지원 코드 | `docs/testing/TESTING_STRATEGY.md`, 기계 기준 `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java` |
|
||||
| 새 기능의 테스트 배치(포트 → fake → 계약 → adapter 계약) | `docs/manual/08-testing.md` |
|
||||
|
||||
## 1. lane과 단계
|
||||
|
||||
**lane**은 테스트 묶음 하나다. 분류(category)·source set·태그를 선언하고, 그 분류에 따라 어느 **단계**(PR·main·integration·
|
||||
performance)에서 돌지가 정해진다. 선언은 leaf `build.gradle`의 `strictTestLanes { lane(...) { ... } }`이다.
|
||||
|
||||
```text
|
||||
lane 선언(leaf build.gradle)
|
||||
└─ category ── test() ── leaf check ────────────────────────> ci (PR)
|
||||
├─ architecture() ── architectureCheck ───────────> ci (PR)
|
||||
├─ mainStage()(document-contract 등) ─────────────> mainCheck (main)
|
||||
├─ integration() ─────────────────────────────────> integrationCheck
|
||||
├─ system() ──────────────────────────────────────> systemTestCheck(mainCheck 안)
|
||||
├─ performance() ─────────────────────────────────> performanceCheck
|
||||
└─ explicitOnly(reason) ── 어떤 집계에도 없음, 실행하면 이유를 출력
|
||||
```
|
||||
|
||||
예외 하나: `app-bootstrap`의 전체 기동 lane은 그 leaf의 `check`에 들어 있어 `ci`에서 돈다. 조립이 뜨지 않으면 병합을
|
||||
막아야 하기 때문이다(`src/build.gradle` `systemTestCheck` 위 주석).
|
||||
|
||||
단계 표의 정본은 `docs/manual/08-testing.md` 「lane과 단계」와 `src/build.gradle` 라이프사이클이다. 개선 작업에서 지킬 것:
|
||||
|
||||
- **새 lane은 반드시 어떤 단계에 속한다.** 어떤 workflow도 돌리지 않는 lane 14개가 있었다(`1101/08-01`). 이제
|
||||
`verifyStrictLaneStages --dry-run`(PR)이 단계 없는 lane에서 실패한다. workflow를 고치지 않고 집계 태스크로 붙인다.
|
||||
- **반드시 돌아야 하는 테스트는 이름을 박는다.** `requires(클래스)` + `rejectSkipped`. 이름이 바뀌거나 지워지면 lane이
|
||||
실패한다(`docs/manual/08-testing.md` 「판단: 새 테스트를 어느 lane에」).
|
||||
- **lane 정책 값은 캐시 입력이다.** `rejectSkipped`를 바꿨는데 옛 결과가 캐시에서 통과하던 것을 고쳤다(`1103/RR-06-02`).
|
||||
lane 정책을 새로 더하면 Test 입력으로 선언한다.
|
||||
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하면 `document-contract`(`mainStage()`), 빌드 스크립트·workflow·
|
||||
compose를 읽으면 `repository-contract`. 저장소 루트는 이 두 lane에만 준다. 태그 없이 저장소를 읽으면 `test`에서 실패한다
|
||||
(`AGENTS.md` 「Gradle 정책 권위」, `1101/08-03`).
|
||||
- **hermetic lane이 파일을 읽으면 그 파일을 입력으로 선언한다.** 그래야 캐시가 거짓 통과를 내지 않는다(`AGENTS.md`
|
||||
「Gradle 정책 권위」 strict lane 캐시).
|
||||
|
||||
## 2. 포트당 fake와 공유 계약
|
||||
|
||||
규칙의 정본은 `AGENTS.md` 테스트 작성 규칙 6이다: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고,
|
||||
adapter가 있는 포트는 fake와 adapter가 같은 추상 계약(`XxxContract`)을 통과한다.
|
||||
|
||||
```text
|
||||
포트 (소유 leaf)
|
||||
├─ testFixtures: InMemoryX (fake, 하나)
|
||||
├─ testFixtures: XContract (abstract — 약속 목록)
|
||||
├─ test: InMemoryXContractTest extends XContract → ci
|
||||
└─ adapter leaf: RealXContractTest extends XContract → integrationCheck (실 vendor)
|
||||
```
|
||||
|
||||
fake가 실제와 다르게 동작하면 그 fake 위의 유스케이스 테스트가 모두 거짓 초록이 된다(`docs/testing/TESTING_STRATEGY.md` 9절).
|
||||
개선 작업에서 지킬 것:
|
||||
|
||||
- **계약 밖 fake를 만들지 않는다.** 테스트 안 private fake는 실제와 갈라진다(`docs/manual/08-testing.md` 「판단: fake가
|
||||
어디 사나」, `1101/01-05`).
|
||||
- **소비자 없는 fake도 만들지 않는다.** 쓰는 유스케이스 테스트가 없는 fake는 두 번째 복사본이 된다(`1101` README 15절
|
||||
04-14 결정).
|
||||
- **fake의 동작을 바꾸면 계약 케이스를 같이 바꾼다.** 계약에 없는 동작을 fake에만 넣지 않는다. fake가 실제와 달랐던 예:
|
||||
쿼터 fake(`1103/RR-01-04`), in-memory fake가 fingerprint 검사 전에 기록을 넘겨줌(`1103` README 17절 r10-02).
|
||||
- **계약과 겹친 adapter 손 사본 테스트는 지운다.** 같은 약속을 두 번 쓰면 둘 중 하나만 고쳐진다(`1103` README 17절 r10-02,
|
||||
20건 삭제).
|
||||
- **skip 수를 본다.** 계약 케이스가 skip되면 그 약속은 검증되지 않았다. command fake 위 계약이 시계를 움직일 수 있는데도
|
||||
시간 케이스 17개를 skip했다(`1103/RR6-02-02` → 0). 남긴 skip은 설계 이유를 적는다(`1103` README 17.2절 "in-memory fake
|
||||
계약의 skip 19는 시간 케이스(설계)").
|
||||
- **현황표를 갱신한다.** 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md` 9절 표를 고친다(`1101` README
|
||||
16절 r3-h "TESTING_STRATEGY 9절 표를 오케스트레이터가 갱신").
|
||||
|
||||
## 3. 이름·GWT
|
||||
|
||||
규칙은 `AGENTS.md` 테스트 작성 규칙 1~5가 정본이다. 요약하지 않고 개선 작업의 적용 방법만 적는다.
|
||||
|
||||
- 테스트를 **고칠 때** 그 테스트에 규칙을 적용한다. 기존 영어 `@DisplayName`은 고칠 때 한국어로 바꾼다(결정 5,
|
||||
`AGENTS.md` 규칙 2).
|
||||
- 이름을 바꾸면 이름이 말한 성질을 단언하는지 다시 본다. 이름과 설명이 다른 계약 테스트가 남은 적이 있다
|
||||
(`1101` README 13절 05-01 "WorkerCrashRecoveryContractTest 이름/설명 불일치").
|
||||
- GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없고, 실질적인 강제 수단은 공유 계약 상속이다
|
||||
(`AGENTS.md` 「테스트 전략」).
|
||||
|
||||
## 4. RED 확인
|
||||
|
||||
**RED**는 고치기 전 코드에서 새 테스트가 실패하는 것을 실행으로 본 기록이다. 수정의 완료 기준이다(01장 2절).
|
||||
|
||||
**하는 법**
|
||||
|
||||
1. 테스트만 먼저 쓰고 지금 코드에서 돌린다. 실패 메시지를 기록한다.
|
||||
2. 이미 수정과 테스트를 함께 썼다면, 기준 커밋에 테스트만 얹은 임시 worktree에서 돌린다. 예: desktop 임시 worktree에
|
||||
`45d2a478` + 새 fixture 7개만 얹어 예상한 6건 실패를 확인했다(`1103` README 17.2절).
|
||||
3. 또는 수정 커밋에서 production 변경만 되돌려 돌린다. 예: TRANSITION 시작 revision 검사만 되돌리자 command fake 계약과
|
||||
실 Redis 계약이 같은 2건으로 실패했다(`1103` README 17.2절).
|
||||
4. 실험한 worktree와 되돌린 변경은 지운다.
|
||||
|
||||
**RED가 증거가 되려면**
|
||||
|
||||
- **실패 메시지가 그 결함을 말한다.** 예: `expected NOT_OWNER but was ALREADY_STARTED_SAME_OPERATION`(`1103` README 17.2절).
|
||||
컴파일 오류·준비 실패로 인한 실패는 RED가 아니다.
|
||||
- **환경에 따라 통과하지 않는다.** watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서는 옛 코드도 통과시켰다
|
||||
(`1103/RR4-03-01` → 병렬도와 무관하게 고침, `1103` README 16절 r9-b).
|
||||
- **실 vendor가 필요한 결함은 실 vendor에서 RED를 본다.** 단위 테스트 RED로 대신했으면 그렇게 적는다(`1101` README 14절
|
||||
r2-04 "새 실 PG 테스트 3개는 수정 전 실패를 실 PG로 확인 안 함").
|
||||
- 기록 형식: 테스트 이름 + 실패 수(예: "RED 실 PG 5·실 Redis 6·fake 2" — `1103` README 15절 r8-a).
|
||||
|
||||
## 5. 테스트가 증명해야 하는 것 — 리뷰 점검표
|
||||
|
||||
| 점검 | 결함 모양 | 지난 예 |
|
||||
| --- | --- | --- |
|
||||
| 이름이 말한 성질을 단언하나 | 이름은 "carrier를 남기지 않는다"인데 준비는 다른 예외 | `1103/RR6-01-08`(`aClientSideCarrierIsNotLogged`가 `IllegalArgumentException`을 넣음) |
|
||||
| 부재 단언이 null과 "키 없음"을 구분하나 | `doesNotExist`가 null 필드도 통과 | `1101/02-02` |
|
||||
| 지키려는 코드를 지우면 실패하나(변이) | 소유자 검사를 지워도 전부 통과 | `1101/05-08`, `1101` README 3절(변이 대부분은 잡음) |
|
||||
| 시간 제한 대기의 반환값을 단언하나 | `CountDownLatch.await(timeout)` 결과를 버려 시간 초과에도 다음 단계로 | `1103` README 14절(7건) |
|
||||
| skip이 0이거나 설계 이유가 있나 | 계약 케이스가 조용히 skip | `1103/RR6-02-02` |
|
||||
| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성(허용해야 할 것을 거부)을 못 봄 | `1103/RR6-01-03`, `1103` README 17절 r10-01(A1·A2 위반, A5 허용 fixture) |
|
||||
| 한 테스트에 `// when`이 하나인가 | 두 동작을 한 테스트가 봄 | `AGENTS.md` 규칙 3 |
|
||||
| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 53개 태스크가 실패한 채 방치 | `1103` README 14절 → `testQualityCheck` |
|
||||
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 | `1103` README 16.1절(`ClientRuntimeRegistryTest`) |
|
||||
|
||||
ArchUnit 규칙의 fixture는 `src/app-bootstrap/src/architectureTest/`의 `ArchitectureViolationFixtureTest`가 모은다. 규칙을
|
||||
더하거나 넓히면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 같은 변경에 넣는다.
|
||||
|
||||
## 6. 테스트를 옮기거나 나눌 때
|
||||
|
||||
- 옮기기 전과 뒤의 **테스트 수**를 lane별로 비교한다. 보고는 테스트 수로 한다(예: `jpaPlatformContractTest` 407 —
|
||||
`1103` README 17.2절).
|
||||
- lane을 바꾸면 그 lane이 단계에 속하는지 `verifyStrictLaneStages --dry-run`으로 본다.
|
||||
- 공유 테스트 코드는 `testFixtures`로 옮긴다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). 한
|
||||
source set에서만 쓰면 그 source set에 둔다(`docs/testing/TESTING_STRATEGY.md` 5절).
|
||||
- 아무도 쓰지 않는 테스트 helper는 지운다(`1103` README 14절 — web-fileserver helper 2개).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 테스트는 이름이 말한 것을 증명한다. 변이로 확인한다.
|
||||
- fake는 포트당 하나, 계약을 fake와 adapter가 함께 상속한다. skip 수를 본다.
|
||||
- 수정은 RED(그 결함을 말하는 실패 메시지)를 실행으로 본 뒤에 끝난다.
|
||||
@@ -0,0 +1,115 @@
|
||||
# 06. 성능·최적화 기준
|
||||
|
||||
## 핵심
|
||||
|
||||
**숫자 없이 최적화하지 않는다.** 같은 조건에서 전과 후를 잰다. 바꾼 것 외의 변수가 같아야 두 숫자를 비교할 수 있다.
|
||||
|
||||
이 템플릿에는 지연·처리량 목표가 없다. 그래서 "빠르다/느리다" 대신 **요청당 비용**(SQL 수, 지연, 처리량, CPU)과 그 비용이
|
||||
**데이터 수에 비례해 늘어나는지**로 판정한다(`1101/09-performance-measurement.md` 1절 「규모 목표」).
|
||||
|
||||
```text
|
||||
기준선 측정 ──> 원인 좁히기 ──> 변경 하나 ──> 같은 조건 재측정 ──> 회귀 테스트로 고정 ──> lane 단계 지정
|
||||
(2·3절) (3절) (7절) (5절) (6절) (07장)
|
||||
```
|
||||
|
||||
## 1. 무엇을 재나
|
||||
|
||||
| 지표 | 재는 법 | 결함 신호 | 지난 예 |
|
||||
| --- | --- | --- | --- |
|
||||
| 아티팩트 | bootJar 크기, `BOOT-INF/lib` jar 목록 | 운영 jar에 테스트용·중복 라이브러리 | `1101/09-09`(H2), `1101/09-11`(Jackson 2·3) |
|
||||
| 기동 | `Started … in` 시간, 기동 3초 뒤 RSS·heap, 빈 수, 스레드 수 | 빈 수에 비해 긴 공백 한 곳 | `1101/09-performance-measurement.md` 3.1절(공백이 한 곳에 몰리지 않아 결함 아님) |
|
||||
| 요청당 SQL 수 | PG `log_statement='all'`로 요청 하나 전후의 문장 수 | 페이지 크기에 비례(N+1) | `1101/09-01`(20건 46개, 100건 206개) |
|
||||
| 지연·처리량 | 닫힌 루프 부하, p50·p95·p99·rps | 단건 대비 목록 처리량이 SQL 수 비율만큼 떨어짐 | `1101/09-performance-measurement.md` 3.3절 |
|
||||
| 요청당 CPU | JFR `settings=profile`, 상위 프레임 소유자 | 한 라이브러리가 CPU의 큰 몫 | 같은 문서 3.5절(목록에서 Hibernate 31%) |
|
||||
| 데이터 증가에 따른 변화 | 같은 요청을 행 수를 늘려 반복 | 행 수에 비례해 느려짐(순차 스캔) | `1101/09-02` |
|
||||
| 게이트·테스트 시간 | 게이트별 rc·초, 테스트 결과 XML 합계 | 바뀐 것이 없는데 매번 다시 도는 lane | `1101/08-02` |
|
||||
|
||||
## 2. 측정 위치와 조건
|
||||
|
||||
측정은 무거운 실행이다. 위치는 07장 「소유자 환경」을 따른다. 조건은 `1101/09-performance-measurement.md` 「측정 조건」을
|
||||
기준으로 한다.
|
||||
|
||||
| 조건 | 기준 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| 머신 | 다른 빌드가 돌지 않는 머신. 측정 직전 load average(1분)를 회차마다 적는다. 15를 넘은 회차는 "부하 높음"으로 표시하고 비교에 쓰지 않는다 | 기동 시간이 머신 부하에 따라 ±20% 움직였다(같은 문서 3.1절) |
|
||||
| JVM | 옵션을 고정하고 적는다. 예: `-Xmx1g -XX:+ExitOnOutOfMemoryError`, G1 기본 | 호스트에서 `MaxRAMPercentage=75`는 22 GiB 힙이 된다. 1 GiB 컨테이너에 가까운 값을 골랐다 |
|
||||
| DB | 자원을 제한한 컨테이너(예: `postgres:16-alpine`, `--cpus 4 --memory 1g`), 튜닝 없음 | DB 자원이 달라지면 앱 변경 효과를 가린다 |
|
||||
| 데이터 | 행 수를 정해 적는다(예: `work_log` 10,000행). 측정 중 늘어나는 테이블은 행 수를 함께 적는다 | `poster`가 측정 중 23,071행까지 늘어 처리량이 회차마다 떨어졌다(같은 문서 3.3절) |
|
||||
| 부하 생성 | 닫힌 루프 N 스레드, 앞 20% 워밍업 버림, 생성기가 같은 호스트면 한계로 적는다 | `wrk`·`hey`가 없어 JDK `HttpClient`로 만든 생성기를 썼다 |
|
||||
| 반복 | 3회 반복, 중앙값. 튀는 회차는 이유와 함께 적고 비교에서 뺀다 | 같은 문서 3.3절(334 rps로 튄 회차를 비교에 쓰지 않음) |
|
||||
| 캐시 | 애플리케이션 캐시 상태, DB 버퍼 캐시 상태(워밍업 뒤)를 적는다 | |
|
||||
|
||||
## 3. 측정 방법
|
||||
|
||||
다시 재는 명령은 `1101/09-performance-measurement.md` 「측정 명령 (다시 돌리는 법)」에 있다. 요약:
|
||||
|
||||
- **SQL 수**: PG에서 `alter system set log_statement='all'` → 요청 하나 → 로그의 `statement`·`execute` 줄 수 → 측정 뒤
|
||||
`'none'`으로 되돌림. 앱 설정을 바꾸지 않는다.
|
||||
- **부하**: 같은 요청을 동시성 N으로 15초, 앞 3초 버림.
|
||||
- **CPU**: 부하 중 `jcmd <pid> JFR.start … duration=20s` → `jfr print --events jdk.ExecutionSample`로 상위 프레임 집계.
|
||||
- **설정만 바꾼 실험**: 코드는 그대로 두고 시스템 프로퍼티 하나만 바꾼다. 예:
|
||||
`-Dspring.jpa.properties.hibernate.default_batch_fetch_size=100`만으로 목록 처리량이 2.9배가 됐다(같은 문서 3.4절).
|
||||
코드를 바꾸기 전에 설정으로 원인을 확인한다.
|
||||
|
||||
측정 스크립트(`run-app.sh`, `Load.java`, `sqlcount.sh`)는 그때 scratchpad에 두었고 repo에는 없다. 다시 재려면 위 문서의 명령으로
|
||||
다시 만든다. **[제안]** 다음 성능 라운드에서 스크립트를 `scripts/perf/`로 넣을지 소유자가 정한다.
|
||||
|
||||
## 4. 기준선
|
||||
|
||||
기준선은 **잰 커밋과 함께만** 쓴다. 아래 숫자는 현재 HEAD에서 다시 잰 값이 아니다. 성능 작업을 시작하면 현재 커밋에서
|
||||
다시 재고 이 표와 비교한다.
|
||||
|
||||
| 측정 | 값 | 커밋·출처 |
|
||||
| --- | --- | --- |
|
||||
| 기본 조합 bootJar / 기동 중앙값 / 빈 수 | 41.4 MB / 3.44 s / 407 | `01a8a2a70`, `1101/09-performance-measurement.md` 3.1절 |
|
||||
| 샘플 bootJar / 기동 중앙값 / 빈 수 | 99.0 MB / 8.05 s / 603 | 같음 |
|
||||
| 필터 체인만 지나는 요청 | 27,130 rps, p50 0.51 ms | 같은 문서 3.4절 (d) |
|
||||
| 샘플 단건 조회 | 5,521 rps, p50 2.70 ms, SQL 7개 | 같은 문서 3.2·3.3절 |
|
||||
| 샘플 목록 20건 | 829 rps, p50 15.54 ms, SQL 46개 | 같음(수정 전) |
|
||||
| 샘플 목록 20건(09-01 수정 뒤) | SQL 46 → 6, 765 → 2,528 rps | `1101` README 14절 r2-09(묶음 보고 — E0, 다시 재지 않음) |
|
||||
| 관측 기능 비용 | 처리량 약 3% | 같은 문서 3.4절 (b) |
|
||||
| 가상 스레드 | 처리량 차이 없음(병목은 커넥션 10개와 DB 왕복) | 같은 문서 3.3절 |
|
||||
| 게이트 시간(desktop, 12코어·31GB) | `ci`+`verifyDependencyLocks` 5분 42초, `mainCheck` 8분 8초, `integrationCheck` 17분 10초 | `2c692554`, `1103` README 17.2절 |
|
||||
|
||||
## 5. 결과를 믿을 조건
|
||||
|
||||
- **커밋 외 변수가 하나다.** 전후 측정이 같은 머신·JVM 옵션·DB 자원·데이터·동시성에서 나왔다.
|
||||
- **반복과 중앙값이 있다.** 1회 측정은 비교 근거가 아니다.
|
||||
- **부하가 기록돼 있다.** 회차마다 직전 load average.
|
||||
- **측정은 E3다.** 실험실 결과이고 운영 증거가 아니다(02장 4절). "운영에서 N배 빨라진다"고 쓰지 않는다.
|
||||
- **성능 단언을 켠 상태로 돌렸다.** 일부 performance lane은 시간 단언을 `performance.assertions.enabled` 속성으로 켠다.
|
||||
workflow는 이 값을 `true`로 준다(`.github/workflows/integration-main.yml:198`). leaf마다 기본값이 다르다:
|
||||
httpclient lane은 `false`(`src/adapter/outbound/httpclient/build.gradle:196-197`), persistence-mongo lane은 `true`
|
||||
(`src/adapter/outbound/persistence-mongo/build.gradle:243-244`). desktop에서 `performanceCheck`를 돌릴 때는 workflow와 같게
|
||||
`-Pperformance.assertions.enabled=true`를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다.
|
||||
- **꼬리 지연의 원인을 확인하지 않았으면 그렇게 적는다.** 예: SQL을 46 → 8로 줄여도 p95가 그대로였고, TCP delayed ACK가
|
||||
의심되지만 확인하지 않았다(같은 문서 3.4절 — 미검증으로 기록).
|
||||
|
||||
## 6. 회귀를 막는 법
|
||||
|
||||
숫자는 다음 변경에서 다시 나빠진다. 고친 비용은 테스트로 고정한다.
|
||||
|
||||
| 장치 | 무엇을 고정하나 | 단계 |
|
||||
| --- | --- | --- |
|
||||
| 요청당 SQL 수 단언 | 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 — `src/sample-portfolio/src/systemTest/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/WorkLogStatementCostSystemTest.java` | sample `systemTest`(`mainCheck`) |
|
||||
| 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료(`adapter/inbound/web` `performanceTest`, `webJettyPerformanceTest`), HTTP client 풀·스트리밍·재시도(`httpClientPerformanceTest`), Hikari 풀(`jpaPlatformPoolContractTest`) | `performanceCheck`(main·nightly) |
|
||||
| 마이크로 벤치마크 | JMH source set(`src/messaging/messaging-kafka/src/jmh`, `src/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh`) | 명시 실행 |
|
||||
|
||||
- 시간 단언은 다른 빌드가 돌지 않는 머신에서만 의미가 있다. 그래서 performance lane은 PR·main 단계가 아니라
|
||||
`performanceCheck`에 있다(`src/build.gradle` `performanceCheck` 위 주석).
|
||||
- SQL 수·호출 수처럼 **머신과 무관한 숫자**를 먼저 고정한다. 시간보다 덜 흔들린다.
|
||||
|
||||
## 7. 최적화를 고르는 순서
|
||||
|
||||
비용이 작은 개선부터 비교한다(가이드 31절 「비용이 작은 개선부터 비교」).
|
||||
|
||||
1. **설정**: 이미 열린 설정 키로 해결되는지 본다(`default_batch_fetch_size`처럼).
|
||||
2. **DB**: 인덱스·유일 제약·쿼리 모양. 순차 스캔은 인덱스로(`1101/09-02`). 중복 규칙은 DB 유일 제약 하나로 느린 검사 쿼리와 동시 중복을 함께 없앤다.
|
||||
3. **매핑·쿼리 코드**: N+1, 불필요한 컬렉션 재작성(`1101/09-06`), 트랜잭션마다 생기는 왕복(`1101/09-05`).
|
||||
4. **구조**: 캐시·비동기·새 인프라는 마지막이다. 캐시를 넣으면 무효화·경합을 함께 검증해야 한다(`1101/05-04`).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 목표가 없는 템플릿이라 "요청당 비용"과 "데이터 수 비례"로 판정한다.
|
||||
- 기준선은 잰 커밋과 함께만 쓰고, 측정 조건(부하·JVM·DB·데이터·반복)을 같이 적는다.
|
||||
- 고친 비용은 SQL 수 같은 머신 무관 숫자로 먼저 고정한다. performance lane은 단언 속성을 켜고 돌린다.
|
||||
@@ -0,0 +1,172 @@
|
||||
# 07. 검증과 게이트
|
||||
|
||||
## 핵심
|
||||
|
||||
**작은 것부터 돌리고, 바꾼 것에 맞는 게이트를 돈다.** 작업 중에는 바꾼 leaf의 `check`, 묶음이 끝나면 경계에 맞는 저장소
|
||||
게이트, 라운드가 끝나면 합친 트리에서 전체 게이트다.
|
||||
|
||||
```text
|
||||
작업 중 <leaf>:check (+ 그 leaf의 관련 strict lane)
|
||||
묶음 끝 + architectureCheck · 표면별 검사(env 키·공개 경로·의존성 잠금) · 관련 lane
|
||||
라운드 끝 합친 트리에서 전체 묶음(3절) ── workflow가 PR·main에서 돌리는 것과 같은 명령
|
||||
```
|
||||
|
||||
게이트 구성의 정본은 `src/build.gradle` 라이프사이클과 `.github/workflows/`다. 이 장은 **언제 무엇을 어디서** 돌리는지 정한다.
|
||||
무거운 실행 위치는 6절 「소유자 환경」이다.
|
||||
|
||||
## 1. 게이트 목록
|
||||
|
||||
명령은 모두 `src/`에서 실행한다.
|
||||
|
||||
| 게이트 | 무엇 | 단계 | 정의 |
|
||||
| --- | --- | --- | --- |
|
||||
| `./gradlew <gradle-path>:check` | 그 leaf만: 컴파일·테스트·Spotless·Checkstyle·Error Prone·API surface | 작업 중 | leaf 컨벤션 플러그인, `CLAUDE.md` 「Testing」 |
|
||||
| `architectureCheck` | 의존 방향, domain-core·shared-contract·application-* 순수성, ArchUnit | PR(`ci` 안) | `src/build.gradle` `architectureCheck` |
|
||||
| `qualityCheck` | SpotBugs·FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` `qualityCheck` |
|
||||
| `ci` | 모든 production leaf `check` + `architectureCheck` + `qualityCheck` | PR | `src/build.gradle` `ci`; workflow는 `./gradlew :ci :verifyDependencyLocks --warning-mode=fail`(`.github/workflows/ci-quality-gates.yml:51`) |
|
||||
| `verifyStrictLaneStages --dry-run` | 모든 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml:57`, `:87`(`-p optional-platforms`) |
|
||||
| `:sample-portfolio:check :sample-portfolio:qualityCheck` | 샘플(production leaf가 아니라 `ci` 밖) | PR | `ci-quality-gates.yml:73` |
|
||||
| `-p optional-platforms ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml:82` |
|
||||
| `mainCheck` | env 계약, 전체 기동, 샘플 실서버 계약·전체 기동, 공개 경로 스냅숏, 전송·메시징 qualification, 생성 명령 왕복, 테스트 코드 정적 분석, leaf `mainCheck`(document-contract lane) | main | `src/build.gradle` `mainCheck`; workflow는 `--continue --warning-mode=fail`(`.github/workflows/integration-main.yml:85`) |
|
||||
| `integrationCheck` | 모든 INTEGRATION lane(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `src/build.gradle` `integrationCheck`; `integration-main.yml:176` |
|
||||
| `performanceCheck` | 모든 PERFORMANCE lane | main·nightly | `src/build.gradle` `performanceCheck`; `integration-main.yml:205`(단언 속성 `true`, `:198`), optional `:211` |
|
||||
| `releaseCheck -PgitRevision=<sha>` | 릴리스 provenance + 공개 경로 | 태그 | `src/build.gradle` `releaseCheck`(sha 없이 돌리면 설계대로 실패 — `1101` README 13.1절) |
|
||||
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가 | PR | `ci-quality-gates.yml`(같은 job) |
|
||||
| `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리 | `mainCheck` 안(`configContractCheck`) | 결정 4 |
|
||||
| `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` |
|
||||
| `verifyDependencyLocks` | lockfile | PR | `ci-quality-gates.yml:51` |
|
||||
|
||||
`./gradlew <gradle-path>:check`의 `<gradle-path>`는 `src/config/architecture/modules.json`에서 읽는다. leaf별 명령 목록을 문서에
|
||||
적지 않는다(`AGENTS.md` 「테스트 전략」 권장 절차 뒤 문단).
|
||||
|
||||
## 2. 바꾼 것에 맞춰 고르기
|
||||
|
||||
| 바꾼 것 | 추가로 돌릴 것 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 한 leaf 안의 코드 | 그 leaf `check` + 그 코드를 지키는 strict lane(실 DB 등) | `docs/manual/11-checklist.md` 「검사」 |
|
||||
| leaf 경계·의존·registry | `architectureCheck`, `verifyDependencyLocks` | 같음 |
|
||||
| env 키 | `:app-bootstrap:verifyEnvKeys` | 같음 |
|
||||
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` | 같음 |
|
||||
| 의존성 | `verifyDependencyLocks` | 같음 |
|
||||
| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) | `src/app-bootstrap/build.gradle` `documentContractTest` 위 주석 |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` | `1103` README 17.2절 |
|
||||
| 패키지 규칙·생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) | `src/build.gradle` `verifyFeatureScaffold` |
|
||||
| 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane | `1103` README 17.2절 |
|
||||
| 테스트 코드 | 그 leaf `testQualityCheck` | `1103` README 14절 |
|
||||
| compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`·기동 | `1101` README 16절 r3-f·r3-k |
|
||||
|
||||
- 문서 링크는 workflow `link-check.yml`(lychee)이 PR에서 검사한다. 대상은 `README.md`, `src/**/README.md`, `src/**/CLAUDE.md`,
|
||||
`docs/**/*.md`, `.github/**/*.md`다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(README 결정 M-5).
|
||||
- 전체 `test`·`check`·`ci`는 총괄의 지시가 있을 때 돌린다(`CLAUDE.md` 「Testing」 마지막 줄).
|
||||
|
||||
## 3. 라운드 끝 — 합친 트리의 전체 묶음
|
||||
|
||||
여러 묶음을 합친 트리는 workflow가 PR·main에서 돌리는 것과 같은 명령으로 검증한다. `1103` README 17.2절의 묶음이 기준이다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :ci :verifyDependencyLocks --warning-mode=fail
|
||||
./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck
|
||||
./gradlew :verifyStrictLaneStages --dry-run
|
||||
./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run
|
||||
./gradlew :mainCheck --warning-mode=fail
|
||||
./gradlew :integrationCheck
|
||||
./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true
|
||||
./gradlew :performanceCheck -Pperformance.assertions.enabled=true
|
||||
./gradlew :releaseCheck -PgitRevision=<HEAD sha>
|
||||
cd .. && bash scripts/verify-compose-profile-contracts.sh
|
||||
```
|
||||
|
||||
- 한 번에 하나씩 돌린다. 같은 머신에서 두 빌드를 겹치지 않는다(6절).
|
||||
- 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다(`1103` README 16.1·16.2절).
|
||||
- 합친 뒤에만 드러나는 결함이 있다. 두 묶음의 수정이 처음 한 트리에서 만나면 새 결함이 생긴다(`1101` README 16.1절
|
||||
`BC_IMPOSSIBLE_INSTANCEOF`). 그래서 묶음별 검증으로 이 단계를 대신하지 않는다.
|
||||
- `-Pperformance.assertions.enabled=true`는 workflow와 같은 단언으로 돌리기 위한 것이다(06장 5절).
|
||||
|
||||
## 4. 결과 기록
|
||||
|
||||
게이트 결과는 표로 적는다(`1103` README 17.2절 형식).
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||
| --- | --- | --- | --- |
|
||||
| `:ci :verifyDependencyLocks --warning-mode=fail` | rc=0 | 5분 42초 | 2.65 |
|
||||
|
||||
함께 적을 것:
|
||||
|
||||
- **대상 커밋 sha.** 작업 트리가 커밋되지 않았으면 그렇다고 적는다(`1101` README 13.1절 "작업 트리가 미커밋이라 실제 릴리스
|
||||
증거로는 쓸 수 없다").
|
||||
- **못 돌린 것과 이유.** 이유 없이 빠진 검증은 HARD-STOP 6 위반이다.
|
||||
- **캐시로 통과한 것.** 실행 시간이 짧으면 캐시 재사용인지 적는다. 캐시 없는 첫 실행 시간을 재지 않았으면 그렇게 적는다
|
||||
(`1101` README 16.2절).
|
||||
- **집계가 뺀 lane.** 입력이 없어 빠진 lane의 이름(`1103` README 10.2절: `redisTopologyTest` 3개, `objectStorageAwsQualificationTest`).
|
||||
- **고친 테스트의 lane을 따로 돌렸는지.** 큰 집계 안에서 몇 개가 돌았는지 테스트 수로(`1103` README 14.1절).
|
||||
- 묶음 보고서가 적은 태스크가 실제로 있는지 확인한다. 없는 태스크 이름이 보고에 들어간 적이 있다(`1103` README 17.2절).
|
||||
|
||||
## 5. 게이트를 믿을 조건 — 거짓 통과 막기
|
||||
|
||||
게이트가 초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다. 지난 라운드의 거짓 통과(부록 A7):
|
||||
|
||||
| 거짓 통과 모양 | 지난 예 | 지금의 장치 |
|
||||
| --- | --- | --- |
|
||||
| 어떤 workflow도 돌리지 않는 lane | `1101/08-01`(14개), `integration-main.yml`이 `integrationCheck --dry-run`만 함 | `verifyStrictLaneStages --dry-run`(PR) |
|
||||
| optional 빌드를 안 봄 | `1103/RR-06-03`(`grpcPerformanceTest` 미실행) | optional 빌드도 같은 검사 |
|
||||
| 실패를 막지 못하는 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 …) | `1103` README 15절 r8-b 남음, 16절 r9-d | `AGENTS.md` 「Gradle 정책 권위」의 세 이유 |
|
||||
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | `1103/RR-06-02` | 정책 값을 Test 입력으로 |
|
||||
| 게이트 밖에서 실패한 채 방치된 검사 | `1103` README 14절(테스트 SpotBugs 53개) | `testQualityCheck`(`mainCheck`) |
|
||||
| 실서버 계약이 어느 게이트에도 없음 | `1103/RR-04-05`(Redis 멱등성 계약) | lane 연결 |
|
||||
| 시간 단언을 끈 채 performance lane 실행 | 06장 5절 | `-Pperformance.assertions.enabled=true` |
|
||||
|
||||
게이트 장치 자체를 바꿨으면 **망가뜨린 입력으로 실패하는 것을 본다.** 예: compose 정적 검사가 일부러 망가뜨린 6가지를 모두
|
||||
잡았다(`1101` README 16절 r3-k). workflow 판독기는 바꾸기 전후로 실제 workflow의 판정이 같은지 비교했다(`1103` README 17절
|
||||
r10-04 "세는 명령 48개는 수정 전후 같다").
|
||||
|
||||
외부 이미지가 사라지면 lane이 다른 이유와 섞여 실패한다. 테스트 lane의 이미지는 한 곳(`src/config/testing/container-images.properties`,
|
||||
MinIO qualification 이미지만 objectstorage leaf 소유)에 digest로 고정하고, MinIO pull 실패는 따로 구분된 메시지
|
||||
(`PinnedImageUnavailableException`)로 실패한다(`1101/05-09`, `1101/08-04`). main 단계는 `--continue`로 돌아 한 lane의 실패가
|
||||
다른 lane 결과를 가리지 않는다(`.github/workflows/integration-main.yml:85`).
|
||||
|
||||
## 6. 소유자 환경 — 무거운 실행 위치
|
||||
|
||||
> 이 절은 이 repo 소유자의 작업 환경에 묶인 규칙이다. 파생 프로젝트는 이 절만 자기 환경으로 바꾼다(README 결정 M-6).
|
||||
|
||||
**규칙**: Gradle·Docker·테스트·게이트·성능 측정은 노트북에서 돌리지 않는다. 원격 desktop에서 브랜치를 받아 돌린다
|
||||
(`1103` README 17.1절, 2026-11-05 소유자 지시). 노트북에서는 git·grep·파일 읽기·문서 편집만 한다.
|
||||
|
||||
**왜**: 수정 묶음 여럿이 노트북에서 Gradle을 동시에 돌려 노트북 부하가 크게 올랐다. desktop은 12코어·31GB이고 Java 21·Docker가
|
||||
있다(`1103` README 17.2절).
|
||||
|
||||
**절차**
|
||||
|
||||
```bash
|
||||
# 1) 노트북: 검증할 변경을 내 브랜치에 커밋하고 push
|
||||
git push origin <내 브랜치>
|
||||
|
||||
# 2) desktop에 접속해 같은 checkout에서 브랜치를 받는다
|
||||
ssh desktop
|
||||
cd ~/workspace/clean-architecture-backend-template
|
||||
git status # 다른 세션의 변경·현재 브랜치 확인
|
||||
uptime # 다른 빌드가 돌고 있지 않은지 부하 확인
|
||||
git fetch
|
||||
git switch <내 브랜치> # 처음 받는 브랜치면 origin/<내 브랜치>를 추적하는 로컬 브랜치가 생긴다
|
||||
|
||||
# 3) 돌린다
|
||||
cd src
|
||||
./gradlew <게이트> --console=plain
|
||||
|
||||
# 4) 끝나면 원래 브랜치로 되돌린다
|
||||
git switch <원래 브랜치>
|
||||
```
|
||||
|
||||
- **checkout을 여러 세션이 함께 쓴다.** 시작 전에 현재 브랜치를 적어 두고, 끝나면 그 브랜치로 되돌린다. 남의 stash는 건드리지
|
||||
않는다(`git stash`·`git stash pop`을 쓰지 않는다).
|
||||
- **빌드를 겹치지 않는다.** 이전 라운드는 같은 머신의 빌드를 공유 잠금 파일(`flock <heavy.lock>`)로 줄 세웠다
|
||||
(`1101/09-performance-measurement.md` 「측정 명령」, `1103/round6/01-core-inbound.md` 「실행한 명령과 결과」). desktop에서도 한 번에
|
||||
하나만 돌리고, 결과 표에 직전 부하를 적는다.
|
||||
- **로그를 남긴다.** 게이트별 로그를 desktop에 파일로 남기고, 그 위치를 보고에 적는다. 결과 표는 리뷰 README에 옮긴다.
|
||||
- **임시 worktree는 지운다.** RED 확인용 worktree를 desktop에 만들었으면 끝나고 지운다(`1103` README 17.2절).
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 작업 중 leaf `check` → 묶음 끝 경계별 게이트 → 라운드 끝 합친 트리 전체 묶음.
|
||||
- 결과는 커밋 sha·rc·시간·부하로 적고, 못 돌린 것·캐시 통과·빠진 lane을 숨기지 않는다.
|
||||
- 무거운 실행은 desktop에서, 한 번에 하나, 끝나면 원래 브랜치로.
|
||||
@@ -0,0 +1,181 @@
|
||||
# 08. 결정과 기록
|
||||
|
||||
## 핵심
|
||||
|
||||
**소유자가 정한 것은 다시 묻지 않는다.** 결정의 원문은 각 리뷰 문서의 결정 절에 있고, 그 원문이 정본이다. 이 장의 표는
|
||||
흩어진 결정을 한곳에서 찾게 하는 **색인**이다. 표와 원문이 다르면 원문이 맞다(README 결정 M-4).
|
||||
|
||||
```text
|
||||
작업 시작 ──> 이 장 색인에서 주제를 찾는다 ──> 있으면: 원문을 읽고 그대로 따른다
|
||||
└─> 없으면: 결정이 필요한가? ──> 소유자 몫이면 묻는다(3절)
|
||||
└─> 아니면 정하고 기록한다(3절)
|
||||
```
|
||||
|
||||
## 1. 결정 색인
|
||||
|
||||
"누가" 칸의 뜻:
|
||||
|
||||
- **소유자** — 소유자가 직접 정했다.
|
||||
- **위임** — 소유자가 "결정이 필요한 것은 지금 정하고 진행하라"고 맡겨 총괄이 정했다(`1101` README 15절 머리말, `1103` README
|
||||
4절 제목). 소유자가 뒤집을 수 있다.
|
||||
- **기본값** — 수정 묶음이 정하고 처리 표 「결정」 칸에 남겼다. 소유자 확인 대상이다(`1103` README 8·13.1절).
|
||||
|
||||
| 분야 | 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 작업 규칙 | 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | `AGENTS.md` 「Gradle 정책 권위」 끝, `CLAUDE.md` 「Gradle policy authorities」 끝 |
|
||||
| 작업 규칙 | 커밋 예외 2026-09-25 | `refactor/review-followup`에 Wave마다 에이전트가 커밋. `main` 병합·push는 사용자 확인 뒤 | 소유자 | 결정 1 |
|
||||
| 작업 규칙 | 커밋 예외 2026-11-03 | 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push | 소유자 | `1101` README 17절 |
|
||||
| 작업 규칙 | 커밋 예외 2026-11-05 | 개선 매뉴얼 작업 브랜치에 커밋·push. PR·병합·다른 브랜치 push는 하지 않음 | 소유자 | 2026-11-05 총괄 세션 brief(이 매뉴얼 작업) |
|
||||
| 작업 규칙 | 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복 | 소유자 | `1103` README 16절, 09장 5절 |
|
||||
| 작업 규칙 | 옛 멈춤 기준 | "새 Important 0이면 멈춤"(9.1절), "Minor는 기록만"(11.1절) — **거둠** | 위임 → 소유자가 거둠 | `1103` README 9.1·11.1·16절 |
|
||||
| 작업 규칙 | 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 총괄 세션 brief, 실행 예 `1103` README 2절 |
|
||||
| 작업 규칙 | 무거운 실행 위치 | 노트북에서 Gradle·Docker를 돌리지 않는다. desktop에서 git pull 뒤 | 소유자 | `1103` README 17.1절, 07장 6절 |
|
||||
| 작업 규칙 | 세션 분업 | 총괄 세션은 지휘만, 실제 작업은 하위 세션 | 소유자 | 2026-11-05 총괄 세션 brief, 09장 |
|
||||
| 작업 규칙 | 개선 매뉴얼 | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 | 소유자 | 2026-11-05 총괄 세션 brief |
|
||||
| 작업 규칙 | `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 |
|
||||
| 작업 규칙 | 학습 문서 | 삭제된 코드를 설명하는 학습 문서(`docs/study/*.ko.md`, `docs/*-superpowers-package/`)는 현재 코드에 맞게 갱신 | 소유자 | 결정 6 |
|
||||
| 작업 규칙 | client 오류 문구 | 한국어. `Category`별 문구 표 하나를 shared-contract에 | 소유자 | 결정 11 |
|
||||
| 구조·조립 | outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 |
|
||||
| 구조·조립 | 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` README 15절 |
|
||||
| 구조·조립 | edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본 사용, vendored(`messaging:*`·`grpc:*`)는 복사본 유지 + family `CLAUDE.md`에 이유 | 위임 | `1101` README 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` README 15절(01-03) |
|
||||
| 구조·조립 | 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` README 15절(r2-10) |
|
||||
| 구조·조립 | `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` README 4절(RR-01-02) |
|
||||
| 구조·조립 | 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 명시 표시(`@SystemCaller(reason)`)로 허용 | 위임 | `1103` README 9.1절(RR-01-12), 10절 r5-b |
|
||||
| 계약·오류 | HTTP 오류 응답 | Envelope 하나. fileserver problem+json도 Envelope로, tus 프로토콜 헤더만 유지 | 소유자 | 결정 2 |
|
||||
| 계약·오류 | 처리 중 409 | `IDEMPOTENT_IN_FLIGHT`는 `retryable=true` + `Retry-After: 2`, 계약 문서에 고정 | 소유자 | `1101` README 5절(02-01), 15절 |
|
||||
| 계약·오류 | Envelope null 필드 | 백엔드가 생략(`NON_NULL`) | 소유자 | `1101` README 5절(02-02) |
|
||||
| 계약·오류 | `INTERNAL_ERROR` retryable | `false`. 일시적 실패는 전용 코드가 retryable을 가진다 | 소유자 | 결정 28 |
|
||||
| 계약·오류 | 새 오류 코드 소유 | 코드를 쓰는 leaf의 enum. 계약은 `docs/web/http-contract.md` §4 | 위임 | `1101` README 15절 |
|
||||
| 계약·오류 | correlation ID | 규칙 밖이면 서버가 새 값으로 교체 | 위임 | `1101` README 15절(02-11) |
|
||||
| 계약·오류 | JSON 아닌 본문 상한 | 전역 상한 없음 — 엔드포인트가 직접 둔다 | 위임 | `1101` README 15절(02-09) |
|
||||
| 계약·오류 | GraphQL 복잡도 | 크기 미선언 list = 20, `first`·`last` 둘 다면 큰 쪽, per-parent 경고 임계 10 | 위임 | `1101` README 15절(03-01·03-03) |
|
||||
| 계약·오류 | GraphQL DataLoader 키 실패 | 등록된 `ApiErrorCode`만 노출 | 소유자 | 결정 25 |
|
||||
| 계약·오류 | Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 |
|
||||
| 계약·오류 | 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 |
|
||||
| 멱등성 | complete 단계 연결 포화 | `UNAVAILABLE` 현재 동작 유지 + 문서화 | 소유자 | 결정 24 |
|
||||
| 멱등성 | complete 단계 저장소 실패 | "결과 불명"으로 따로 알린다(실행 전 503과 구분). 같은 키 재전송은 서버가 판정 | 위임 | `1103` README 4절(RR-02-03) |
|
||||
| 멱등성 | lease 지난 실행 중 기록 | 두 store(PostgreSQL·Redis)가 같은 계약: 작업을 다시 돌리지 않고 "회복 필요" | 위임 | `1103` README 9.1절(RR-01-11) |
|
||||
| 멱등성 | Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease), 설정 검사 | 위임 | `1103` README 9.1절(RR-03-11) |
|
||||
| 멱등성 | 늦은 완료 | 늦게 끝난 첫 시도의 완료는 **기록한다**(묶음 기본값 "버린다"를 뒤집음). 다시 실행은 여전히 하지 않음 | 소유자 | `1103` README 15절 ① |
|
||||
| 멱등성 | 보존 기간 관계 | `failure-retention < replay-ttl`이면 기동 실패 | 소유자 | `1103` README 15절 ③ |
|
||||
| 멱등성 | 같은 attempt 재claim | lease 지난 `CLAIMED`·`FAILED_RETRYABLE`을 넘겨받는다. 같은 attempt를 두 호출이 동시에 쓰는 것은 호출자 계약 | 기본값 | `1103` README 17절 r10-02 |
|
||||
| 멱등성 | Redis 연결 예산 | 캐시 조건부 쓰기는 멱등성·lease와 다른 연결 예산(SCRIPT lane) | 위임 | `1103` README 4절(RR-04-02) |
|
||||
| 영속성 | JPA 기본값 | 트랜잭션 제한 30초, JDBC batch 50, H2 운영 jar 제거, 격리 수준 Hikari 고정, upsert `DO NOTHING` 후 갱신 | 위임 | `1101` README 15절(04) |
|
||||
| 영속성 | 포트 시그니처 | claim에 lease·`claimFence`, fileserver `claimDue`·`markAbandoned`·`claimToken` | 위임 | `1101` README 15절 |
|
||||
| 영속성 | 마이그레이션 번호 | 스트림별 순번. 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 `V8_1`. notification은 `V13` | 위임 | `1101` README 15절 |
|
||||
| 영속성 | V21 유일 인덱스 | 기존 중복이 있으면 마이그레이션 실패. runbook에 확인 쿼리 | 위임 | `1101` README 15절 |
|
||||
| 영속성 | 순서 번호 seed | counter가 없으면 전역 floor부터 | 위임 | `1103` README 4절(RR-03-02) |
|
||||
| 영속성 | 마이그레이션 잠금 | 강한 잠금을 거는 마이그레이션은 `SET LOCAL lock_timeout`, 같은 모양의 lane 테스트 | 위임 | `1103` README 9.1절(RR-02-09) |
|
||||
| 영속성 | Flyway PostgreSQL 잠금 | 세션 수준(`transactional-lock: false`). 전제: Hikari 직접 연결 — transaction-mode PgBouncer 뒤에서는 깨진다 | 기본값 | `1103` README 17절 r10-03(RR6-03-01) |
|
||||
| 영속성 | persistence-jpa 설정 prefix | 플랫폼 자체는 `app.persistence-jpa.*`, 공유 기능은 기능 트리(`app.outbox`·`app.lock`·`app.realtime.replay`) | 소유자 | 결정 36 |
|
||||
| 영속성 | 분산 lock·lease | 둘 다 capability로 유지, 공통 계약 테스트 | 소유자 | 결정 8 |
|
||||
| 샘플 | 포스터 업로드 abort·reconcile 경합 | 먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409) | 소유자 | 결정 22 |
|
||||
| 샘플 | work log 권한·batch | 관리자도 남의 work log 수정 불가, `batchCreate` 상한 1000·한 트랜잭션 | 위임 | `1101` README 15절(09) |
|
||||
| 샘플 | 이벤트 tenant·오류 코드 | 이벤트 tenant 범위 `global`, `WORKLOG_INVALID`·`OPERATION_NOT_FOUND` | 위임 | `1101` README 15절(01) |
|
||||
| 메시징 | outbox append 모델 | canonical(`OutboxAppendPort`)로 통일, legacy 포트·legacy Kafka 발행 경로 삭제 | 소유자 | 결정 7 |
|
||||
| 메시징 | Kafka 소비 | 지원. `MessageHandler<T>` 하나 + starter-kafka가 consumer 조립 | 소유자 | 결정 10 |
|
||||
| 메시징 | decode 타입 등록 | handler bean이 선언한 타입으로 decode 목록을 만든다 | 위임 | `1101` README 15절(06-08 후속) |
|
||||
| 메시징 | relay 재시도 | 재시도 가능 거부는 무한 재시도(5분 간격), 예산 설정 키 없음, 인증 오류는 경보로 | 위임 | `1101` README 15절(06-01·06-03) |
|
||||
| 메시징 | 끝나지 않는 재시도 | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로, runbook에 park·재개 절차와 테스트된 SQL | 위임 | `1103` README 4절(RR-05-03) |
|
||||
| 메시징 | 카드 검증기 YAML | messaging leaf 테스트에서만 snakeyaml(main 금지) | 소유자 | 결정 29 |
|
||||
| 보안 | JWT audience·role | audience 필수, 자기 client role만(기존 배포는 env 하나를 채움) | 소유자 | `1101` README 5절(02-03), 15절 |
|
||||
| 보안 | 데모 계정 | `local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만(허용 목록). 각 프로필은 sample이 실제로 뜨는 프로필 | 위임 | `1103` README 4절(RR-07-02), 9.1절(RR2-04-02) |
|
||||
| 보안 | `fixture-` 값 거부 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사 | 위임 | `1103` README 9.1절(RR2-04-01) |
|
||||
| 보안 | 파일 서버 인가 | 소유자 검사(`ownerPrincipalId`), 역할 검사(`file:*` 권한)와 소유자·tenant 검사를 둘 다 | 소유자 | 결정 14, 결정 32 |
|
||||
| 보안 | cross-origin redirect | 호출자 헤더 전부 제거, 안전한 헤더만 유지 | 소유자 | 결정 23 |
|
||||
| 보안 | 개발 compose Redis | lane Redis에 ACL 계정, "기동 WARN 없음" 검사 유지 | 위임 | `1101` README 15절(r3-J) |
|
||||
| 보안 | 서블릿 오류 디스패치 | 보안 체인이 ERROR 디스패치만 허용 | 기본값 | `1103` README 6절 r4-b, 8절 |
|
||||
| 설정 | 설정 prefix | `app.*`로 통일, `APP_*` env 키 유지 | 소유자 | 결정 16 |
|
||||
| 설정 | Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` README 15절(05-18), `AGENTS.md` capability 기준 4 |
|
||||
| 설정 | 로그 설정 | logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated | 위임 | `1101` README 15절(07) |
|
||||
| 설정 | 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | `1101` README 15절 |
|
||||
| 설정 | `APP_FLYWAY_ENABLED` | dev·prod에도 적용 | 위임 | `1101` README 15절(r3-F) |
|
||||
| 설정 | 전송 상한 기본값 | gRPC 스레드 32·큐 256·동시 100·deadline 10s·drain 2s, ledger `claimTtl` 5m·보존 24h, WebSocket `max-connections` 1000(초과 시 1013) | 위임 | `1101` README 15절(03-06·03-09·03-10) |
|
||||
| 빌드·게이트 | 빌드 게이트 | `verifyEnvKeys`는 bootstrap 유지, JPA evidence manifest는 폐기하고 leaf 테스트로, redis topology lane 유지 | 소유자 | 결정 4 |
|
||||
| 빌드·게이트 | API surface 단계 | PR(`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` README 15절(08-07) |
|
||||
| 빌드·게이트 | 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` README 14절 |
|
||||
| 빌드·게이트 | lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` README 4절(RR-06-02) |
|
||||
| 빌드·게이트 | workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` README 15절 ② |
|
||||
| 빌드·게이트 | MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` README 15절(05-09) |
|
||||
| 빌드·게이트 | Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) — 닫음 | 위임 | `1101` README 15절(09-11) |
|
||||
| capability | httpclient reactive | 삭제 | 소유자 | 결정 9 |
|
||||
| capability | SES 연동 | AWS SDK(sesv2) | 소유자 | 결정 17 |
|
||||
| capability | durable operation | HTTP 어댑터 추가, 설계 4개(서버 생성 id, payload 지문으로 재제출 판정, 고정 event type, 1일 보존) 승인 | 소유자 | 결정 15, 결정 26 |
|
||||
| capability | 알림 provider profile 소실 | 일반 재시도 정책 후 FAILED | 소유자 | 결정 21 |
|
||||
| capability | notification INGEST_ONLY | runtime 없이도 accept 때 route 이름 기록 | 위임 | `1101` README 15절(r3-I) |
|
||||
| capability | 파일 서버 쿼터 | 상한 미설정 = 무제한, 동시 예약은 상한을 넘을 수 있음, 정리 worker 기본 켜짐 | 위임 | `1101` README 15절(r2-05a) |
|
||||
| capability | objectstorage | provider type 하나 추가 | 위임 | `1101` README 15절(05-16) |
|
||||
| 기타 | 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 끝 목록 |
|
||||
| 기타 | 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | `1101` README 13·14·16절, `1103` README 6·10·12·15·16·17절 표 |
|
||||
|
||||
## 2. 결정을 다시 묻지 않는 규칙
|
||||
|
||||
1. **작업 시작 전에 이 색인과 원문을 읽는다.** 표에 있는 주제면 그 결정대로 한다. brief에도 해당 결정을 링크한다(09장 3절).
|
||||
2. **다시 열 수 있는 경우는 셋뿐이다.**
|
||||
- 결정의 전제가 코드·측정으로 틀렸다고 확인됐다.
|
||||
- 두 결정이 서로 충돌한다.
|
||||
- 결정이 `AGENTS.md` HARD-STOP과 충돌한다.
|
||||
3. **다시 열 때는 근거와 권하는 안을 붙여 소유자에게 묻는다.** 예: 소유자가 묶음 기본값 세 가지를 다시 물었을 때, 총괄은
|
||||
각각 "다시 따져 본 것"을 적어 답했고 소유자가 다시 정했다(`1103` README 15절 표의 "다시 따져 본 것" 칸). ①은 "기존
|
||||
PostgreSQL이 그렇게 한다는 것 말고 근거가 없었다"가 다시 연 이유였다.
|
||||
4. **위임·기본값 결정은 보고에 따로 적는다.** 소유자가 뒤집을 수 있게, 무엇을 기본값으로 정했는지 보고의 "결정" 칸에 남긴다
|
||||
(`1103` README 8절 "소유자 확인이 필요한 결정").
|
||||
5. **뒤집힌 결정은 원문에서 지우지 않는다.** 취소선이나 "→ N절에서 바꿈"으로 새 위치를 가리킨다(`1103` README 13.1절의 취소선,
|
||||
11.1절 → 16절). 이력이 남아야 같은 논의를 다시 하지 않는다.
|
||||
6. **리뷰어는 정한 결정을 결함으로 다시 올리지 않는다**(02장 9절).
|
||||
|
||||
## 3. 새 결정을 기록하는 법
|
||||
|
||||
**누가 정하나**
|
||||
|
||||
| 소유자에게 묻는다 | 직접 정하고 기록한다 |
|
||||
| --- | --- |
|
||||
| 공개 계약·wire 형식 변경, 파생 서비스 동작을 바꾸는 기본값, 보안 정책, 새 leaf, commit 정책, 되돌리기 비싼 선택, 비용이 드는 외부 일 | 기존 원칙에서 바로 따라 나오는 것, 결함 수정의 구현 방법, 문서 위치 |
|
||||
|
||||
근거: 새 leaf는 승인을 받았다(`1101` README 15절). 파생 서비스 동작을 바꾸는 것은 "결정 필요"로 모았다(`1101` README 14.3절).
|
||||
에이전트가 원칙에서 바로 정한 것은 "소유자가 뒤집을 수 있음"으로 표시했다(`docs/reviews/2026-09-25-review-followup-status.md`
|
||||
「소유자 결정」 끝 목록).
|
||||
|
||||
**묻는 법**: 항목 · 선택지 · 권고 · 승인자를 한 표로(`1101` README 5절 형식). 권하는 안과 그 이유를 반드시 붙인다.
|
||||
|
||||
**어디에 쓰나**
|
||||
|
||||
| 결정의 종류 | 위치 |
|
||||
| --- | --- |
|
||||
| 리뷰 라운드에서 나온 결정 | 그 라운드 README의 「결정」 절. 형식: 항목 · 결정 · 이유(· 버린 대안) |
|
||||
| 수정 묶음의 구현 기본값 | 처리 표의 「결정」 칸 |
|
||||
| 되돌리기 비싼 아키텍처 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 이어서. 예: `ADR-JPA-003-completion-unknown.md`) |
|
||||
| 매뉴얼을 만들거나 고치며 정한 것 | 해당 매뉴얼 README의 「결정 기록」 |
|
||||
|
||||
**기록한 뒤**: 이 장 색인에 한 줄(분야 · 주제 · 결정 · 누가 · 출처)을 더한다.
|
||||
|
||||
## 4. 커밋·PR
|
||||
|
||||
형식의 정본은 `design-docs/conventions/commit-and-pr.md`(이 repo 밖)다. 개선 작업에서 자주 쓰는 것과 이 repo의 예외만 적는다.
|
||||
|
||||
| 규칙 | 정본 | 이 repo에서 |
|
||||
| --- | --- | --- |
|
||||
| 커밋 하나 = 논리적 변경 하나, 리팩터링과 동작 변경을 나눔 | 커밋 규칙 3.1 | 리뷰 라운드의 큰 묶음은 **검증된 트리 경계**에서만 나눴다. 발견 하나씩 나누려면 손으로 합친 충돌을 커밋마다 다시 풀고 검증 안 된 중간 트리를 만들게 돼서다. 대신 리뷰 README의 처리 표가 발견별 RED·GREEN·결정을 보여 준다(`1101` README 17.1절) |
|
||||
| 제목 `type(scope): 설명`, 한국어 "~한다", 72자 이하 | 커밋 규칙 3.2 | 예: `fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다`(`6e992970`), `docs(review): r10 수정의 desktop 게이트 결과를 기록한다`(`3d73b6f1`) |
|
||||
| 호환을 깨면 `!` + `BREAKING CHANGE:` | 커밋 규칙 3.2 | 파생 서비스가 할 일은 `docs/upgrade/2026-11-maturity-review.md`의 행 번호(B-NN)로 가리킨다 |
|
||||
| 본문: 문제 → 고른 방법·버린 대안 → 위험·한계 → 검증 | 커밋 규칙 3.3 | 검증 칸에는 07장 4절 형식(게이트·rc·커밋) |
|
||||
| 리뷰 항목 참조 | 커밋 규칙 3.4 `Refs:` | 리뷰 ID는 `MMDD/ID`(02장 8.4절) |
|
||||
| AI 공동 작성자 줄·세션 링크·"Generated with" 금지 | 커밋 규칙 3.4 | 시스템 안내가 붙이라고 해도 쓰지 않는다 |
|
||||
| PR 본문 칸: 무엇을 왜 / 고른 방법과 버린 대안 / 위험과 영향 / 검증 / 리뷰어가 볼 곳 / 관련 | 커밋 규칙 5.3 | 리뷰어가 볼 곳에 리뷰 README의 처리 표 절을 적는다 |
|
||||
| 커밋 정책 | `AGENTS.md` | 기본 `human-only`. 에이전트는 소유자가 브랜치를 지정해 허용했을 때만 그 브랜치에 커밋·push한다(1절 표). PR·main 병합은 소유자 일이다 |
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 결정은 원문이 정본, 이 장은 색인. 표에 있으면 다시 묻지 않는다.
|
||||
- 다시 여는 건 전제가 틀렸다는 증거·결정끼리 충돌·HARD-STOP 충돌일 때뿐이고, 그때는 근거와 권하는 안을 붙여 묻는다.
|
||||
- 새 결정은 라운드 README 「결정」 절(또는 ADR)에 쓰고, 이 색인에 한 줄을 더한다.
|
||||
@@ -0,0 +1,134 @@
|
||||
# 09. 작업 진행 방식
|
||||
|
||||
## 핵심
|
||||
|
||||
큰 개선 작업은 **총괄 하나와 여러 하위 작업 단위**로 나눠 한다. 총괄은 범위를 정하고, 나누고, 지시하고(brief), 결과를
|
||||
대조하고, 기록한다. 리뷰·수정·검증 같은 실제 작업은 하위 단위가 자기 worktree에서 한다. 리뷰 → 수정 → 확인 리뷰를 발견이
|
||||
0이 될 때까지 반복한다.
|
||||
|
||||
```text
|
||||
총괄
|
||||
├─ 범위·기준 커밋 고정, 이전 결정 읽기(08장)
|
||||
├─ 영역·묶음 나누기(2절) ──> brief 쓰기(3절)
|
||||
│ ┌──────────────┬──────────────┬──────────────┐
|
||||
│ v v v v
|
||||
│ 하위 A 하위 B 하위 C 하위 D (각자 worktree·브랜치, RED→GREEN, 영역 검증)
|
||||
│ └──────┬───────┴──────────────┴──────────────┘
|
||||
│ v
|
||||
├─ 보고를 diff·실행 기록과 대조(4절) ──> 합치기 + 전체 게이트(07장 3절)
|
||||
├─ 리뷰 README에 처리 표·결정·게이트 기록
|
||||
└─ 확인 리뷰(수정 diff만) ──> 발견 0? ── 아니면 다시 나누기
|
||||
└─ 0이면 보고(5절)
|
||||
```
|
||||
|
||||
하위 작업 단위를 무엇으로 띄우는지는 환경에 묶인 규칙이라 6절 「소유자 환경」에 따로 둔다.
|
||||
|
||||
## 1. 역할
|
||||
|
||||
| 총괄이 한다 | 하위 단위가 한다 |
|
||||
| --- | --- |
|
||||
| 범위·기준 커밋·영역 분할 | 맡은 영역의 리뷰, 또는 맡은 발견의 수정 |
|
||||
| brief 작성, 결정 색인 연결 | RED → GREEN, 같은 원인의 다른 자리 찾기, 문서 동기화 |
|
||||
| 소유자에게 결정 묻기(근거와 권하는 안을 붙여) | 영역 검증(leaf `check`, 관련 lane) |
|
||||
| 보고를 diff·실행 기록과 대조 | 처리 표 한 행 형식의 보고 |
|
||||
| 리뷰 README 기록, 소유자 보고 | 범위 밖 발견은 고치지 않고 보고 |
|
||||
|
||||
- 합치기와 전체 게이트도 하위 단위에 맡길 수 있다. r10 수정의 전체 게이트는 별도 작업 단위가 desktop에서 돌렸다
|
||||
(`1103` README 17.1·17.2절).
|
||||
- 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(`1101` README 2절).
|
||||
- 총괄은 보고를 믿지 않고 확인한다. 보고는 E0 증거다(02장 4절).
|
||||
|
||||
## 2. 나누는 법
|
||||
|
||||
- **영역 분할은 최근 리뷰의 영역 표를 다시 쓴다.** 전체 리뷰는 `1101` README 9절의 9영역, 재리뷰는 `1103` README 2절의 7영역,
|
||||
확인 리뷰는 4영역(`1103/round6/`).
|
||||
- **두 묶음이 같은 파일을 건드리지 않게 나눈다.** 겹치면 합칠 때 손으로 풀어야 한다. 2라운드는 묶음 사이 충돌이 많아 한 묶음을
|
||||
처음부터 다시 시켰다(`1101` README 14.1절 r2-06 "10개 파일 충돌로 baseline2 위에서 다시 작업").
|
||||
- **묶음마다 그 시점의 메인 상태에서 시작한다.** 3라운드가 2라운드보다 충돌이 적었던 이유다(`1101` README 16.1절).
|
||||
- **전 leaf의 import를 바꾸는 묶음은 마지막에 혼자 한다**(`1101` README 15.1절 r3-G).
|
||||
- **한 묶음을 너무 크게 만들지 않는다.** 알림·파일 서버를 한 묶음으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다
|
||||
(`1101` README 14.3절 r2-05a). 그 묶음은 다음 라운드에 다시 올려 합쳤다(`1101` README 16절 r3-a).
|
||||
- **같은 결함을 두 영역이 보면 한 묶음에만 배정한다.** 같은 문장을 두 리뷰가 적은 것은 한 번 고쳤다(`1103` README 17절
|
||||
"RR6-01-07과 RR6-02-03은 같은 runbook 문장이라 한 번 고쳤다").
|
||||
|
||||
## 3. brief에 넣을 것
|
||||
|
||||
brief는 하위 단위가 받는 유일한 맥락이다. 빠뜨린 것은 하위 단위가 모른다.
|
||||
|
||||
- [ ] **목표와 완료 기준.** 무엇이 끝나면 끝인가(01장의 해당 작업 완료 기준).
|
||||
- [ ] **기준 커밋·브랜치·worktree.** 어디서 시작하고 어디에 커밋하나.
|
||||
- [ ] **범위.** pathspec과 발견 ID 목록. 범위 밖 발견은 "고치지 말고 보고"(`1103` README 12절 "맡은 Minor 밖은 고치지 않고
|
||||
보고만 하게 했다").
|
||||
- [ ] **이미 정한 결정.** 08장 색인의 해당 행과 원문 위치. "다시 묻지 말 것".
|
||||
- [ ] **쓸 스킬.** 01장 표에서. 리뷰면 리뷰어 템플릿과 영역 스킬(`1103` README 머리말).
|
||||
- [ ] **심각도 기준**(리뷰면). 02장 3절 정의를 그대로 붙인다(`1103` README 11절 "심각도 기준을 지침에 적었다").
|
||||
- [ ] **검증 위치와 명령.** 07장 6절 「소유자 환경」, 돌릴 게이트.
|
||||
- [ ] **하지 말 것.** 리뷰는 코드 수정 금지, 다른 브랜치 push 금지, PR·병합 금지, 하위의 하위 위임 금지(환경에 따라).
|
||||
- [ ] **커밋 허용 여부와 규칙.** 08장 4절.
|
||||
- [ ] **보고 형식.** 4절.
|
||||
- [ ] **막혔을 때.** 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 묻는다.
|
||||
|
||||
## 4. 보고 형식
|
||||
|
||||
**하위 단위 → 총괄**: 리뷰 README 처리 표의 한 행으로 바로 옮길 수 있게 쓴다(`1101` README 13절, `1103` README 6·10·12·16·17절 표).
|
||||
|
||||
| 칸 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 묶음·발견 ID | `r10-02`, `RR6-02-01~05` |
|
||||
| 상태 | 완료 / 부분(무엇이 남았나) / 못 함(이유) |
|
||||
| 검증 | 명령과 테스트 수. 예: "`redisContainerContractTest` 78, PG 계약 31" |
|
||||
| RED | 수정 전 실패한 테스트 이름과 수 |
|
||||
| 처리 내용 | 무엇을 바꿨나, 고치다 새로 찾아 고친 것 |
|
||||
| 결정·남은 것 | 정한 기본값(소유자 확인 대상), 남은 것 |
|
||||
|
||||
함께 줄 것: 브랜치와 커밋 sha, 실행 로그 위치, 범위 밖에서 본 결함.
|
||||
|
||||
**총괄 → 소유자**: 바꾼 것 · 확인한 것(게이트·rc·커밋) · 남은 문제. 남은 문제를 숨기지 않는다(`AGENTS.md` 「작업 보고 규칙」).
|
||||
소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 「소유자 일」로 한 번만 적고 남은 문제와 섞지 않는다(`1103` README 13.1절
|
||||
"소유자 일").
|
||||
|
||||
## 5. 리뷰 → 수정 반복과 종료 조건
|
||||
|
||||
**왜 반복하나**: 수정이 새 결함을 만든다. 1차 재리뷰는 원래 리뷰의 수정에서 Important 27건을 찾았고(`1103` README 1절), 그
|
||||
수정을 다시 본 2차 재리뷰도 새 Important를 찾았다(`1103` README 9절 표 "이번 라운드가 새로 만든 Important"). round6은 r9
|
||||
수정의 회귀를 찾았다(`1103/RR6-01-01`).
|
||||
|
||||
**확인 리뷰의 범위**: 저장소 전체가 아니라 **그 수정 커밋만** 본다. 전 영역은 이미 봤고, 남은 위험은 "수정이 새 결함을
|
||||
만든다"이기 때문이다(`1103` README 9절). 수정 diff가 건드린 동작의 주변 코드는 함께 읽는다(02장 8.2절 「범위」).
|
||||
|
||||
**종료 조건** — 모두 만족해야 끝난다.
|
||||
|
||||
1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다.
|
||||
2. 열린 「Declined to judge」 항목이 없다. 판단하지 않은 항목은 총괄이 다음 묶음에 배정하거나 결정으로 닫았다.
|
||||
3. 합친 트리에서 07장 3절 전체 묶음이 통과했다.
|
||||
4. 리뷰 README의 "남음" 항목이 0이다. 결정으로 닫은 것은 결정 위치가 적혀 있다.
|
||||
|
||||
예전 멈춤 기준("새 Important 0이면 멈춤", "Minor는 기록만")은 소유자가 거뒀다(`1103` README 16절, 08장 1절).
|
||||
|
||||
**코드로 고칠 수 없는 것**: 소유자 결정이 필요한 것만 남을 수 있다. 그것은 근거와 권하는 안을 붙여 질문으로 보고한다. 질문이
|
||||
답을 받으면 다시 고치기로 돌아간다.
|
||||
|
||||
**종료 조건을 미리 정한다**: 라운드를 시작할 때 그 라운드의 멈춤 조건을 README에 적는다(`1103` README 9.1절 끝 문단처럼).
|
||||
이 매뉴얼의 종료 조건과 다르면 이 매뉴얼을 따른다.
|
||||
|
||||
## 6. 소유자 환경 — 세션 분업
|
||||
|
||||
> 이 절은 이 repo 소유자의 작업 도구에 묶인 규칙이다. 파생 프로젝트는 이 절만 자기 환경으로 바꾼다(README 결정 M-6).
|
||||
> 출처: 2026-11-05 총괄 세션 brief(README 결정 M-9).
|
||||
|
||||
- **총괄 세션은 지휘만 한다.** 하위 작업 단위는 Claude 데스크톱 앱의 **하위 세션**(별도 세션, 사용자가 열어 보고 멈출 수 있다)으로
|
||||
띄운다. 세션 안의 하위 에이전트(subagent)로 돌리지 않는다.
|
||||
- **하위 세션 안에서 다시 하위 에이전트를 띄우지 않는다.** 넓은 조사는 그 세션이 직접 나눠 읽는다. 지난 라운드도 사용량 한도
|
||||
때문에 하위 에이전트 없이 진행했다(`1101` README 16절 "하위 에이전트는 쓰지 않았다(지난 라운드 사용량 한도)",
|
||||
`1103` README 6절 "하위 에이전트 없음").
|
||||
- **세션마다 자기 worktree와 브랜치를 쓴다.** 같은 checkout을 두 세션이 동시에 쓰지 않는다. desktop checkout은 예외로 함께 쓰므로
|
||||
07장 6절 절차를 따른다.
|
||||
- **세션끼리는 공유 노트 폴더로 큰 결과를 넘긴다.** 탐침 코드와 실행 로그처럼 메시지에 넣기 큰 것은 노트 폴더에 두고 위치만
|
||||
보고한다(`1103/round6/01-core-inbound.md` "탐침 코드와 결과 파일은 공유 노트 폴더 `rr6-01-probes/`에").
|
||||
- **짝 프론트 repo의 일은 프론트 쪽 총괄 세션을 거친다.** 계약 변경은 인계 문서로 넘긴다(`1101` README 16.3절 "프론트 인계").
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 총괄은 나누고·지시하고·대조하고·기록한다. 일은 하위 단위가 자기 worktree에서 한다.
|
||||
- brief는 하위 단위의 유일한 맥락이다. 결정·범위·검증 위치·보고 형식을 빠뜨리지 않는다.
|
||||
- 확인 리뷰는 수정 diff만 보고, 발견 0 + Declined 0 + 전체 게이트 통과 + "남음" 0일 때 끝난다.
|
||||
@@ -0,0 +1,141 @@
|
||||
# 개선 작업 매뉴얼 — 이 repo를 리뷰·수정·리팩터링·최적화할 때의 기준
|
||||
|
||||
## 핵심
|
||||
|
||||
이 매뉴얼은 **이미 있는 코드를 평가하거나 고치는 사람**이 읽는다. 사람과 AI 에이전트가 같은 기준을 쓴다.
|
||||
새 업무 기능을 만드는 순서는 [`docs/manual/`](../manual/README.md)이 맡는다. 두 매뉴얼은 독자가 다르다.
|
||||
|
||||
개선 작업 하나는 다음 흐름을 탄다. 각 칸의 숫자는 이 매뉴얼의 장이다.
|
||||
|
||||
```text
|
||||
리뷰(02) ──> 결함 목록 ──> 수정 묶음(01·03·04·05·06) ──> 검증(07)
|
||||
^ |
|
||||
| v
|
||||
└──── 확인 리뷰: 수정 diff만 본다(02) <──── 발견이 남았나?(09)
|
||||
| 0이면
|
||||
v
|
||||
결정·결과 기록(08) ──> 보고
|
||||
```
|
||||
|
||||
- **리뷰**는 결함을 찾고 적는다. 코드를 고치지 않는다.
|
||||
- **수정 묶음**은 결함을 테스트로 먼저 재현하고(RED) 고친다(GREEN).
|
||||
- **확인 리뷰**는 수정이 만든 새 결함을 찾는다. 지난 라운드의 반복 결함 대부분이 여기서 나왔다(부록 A12).
|
||||
- 발견이 심각도와 상관없이 0이 될 때까지 반복한다(09장).
|
||||
|
||||
## 적용 범위
|
||||
|
||||
| 작업 | 이 매뉴얼 | 다른 문서 |
|
||||
| --- | --- | --- |
|
||||
| 리뷰(전체·영역·커밋 diff) | 01장 1절, 02장 | 공용 가이드(아래) |
|
||||
| 결함 수정 | 01장 2절, 04·05장 | 해당 leaf `src/**/CLAUDE.md` |
|
||||
| 리팩터링(동작을 바꾸지 않는 구조 변경) | 01장 3절, 04장 | |
|
||||
| 성능 최적화 | 01장 4절, 06장 | |
|
||||
| 폴더·모듈 구조 변경 | 01장 5절, 03장 | `src/config/architecture/modules.json` |
|
||||
| 테스트 구조 개선 | 01장 6절, 05장 | `docs/testing/TESTING_STRATEGY.md` |
|
||||
| 새 업무 기능 추가 | 아님 | [`docs/manual/`](../manual/README.md) |
|
||||
| 운영 장애 대응 | 아님 | [`docs/runbooks/`](../runbooks/template.md) |
|
||||
|
||||
## 정본 표
|
||||
|
||||
이 매뉴얼은 규칙을 다시 쓰지 않고 **정본을 가리킨다**. 매뉴얼과 정본이 다르면 정본이 맞고, 매뉴얼을 고친다.
|
||||
아래 「이 매뉴얼이 정본」 행만 이 매뉴얼이 처음이자 유일한 기록이다.
|
||||
|
||||
| 무엇 | 정본 | 이 매뉴얼에서 |
|
||||
| --- | --- | --- |
|
||||
| HARD-STOP 7개, 계층 책임, 금지된 지름길 | `AGENTS.md`(요약 `CLAUDE.md`) | 04장이 가리킴 |
|
||||
| 테스트 작성 규칙 6개(이름·`@DisplayName`·GWT·단언·fake) | `AGENTS.md` 「테스트 전략」 | 05장이 가리킴 |
|
||||
| capability 완료 기준 7개 | `AGENTS.md` 「부가 기능(capability) 모듈 규칙」 | 03·04장이 가리킴 |
|
||||
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` | 03장이 가리킴 |
|
||||
| 이름 규칙, 템플릿 패키지 목록 | `src/application-core/CLAUDE.md` 「Naming convention」「Package ownership」 | 03·04장이 가리킴 |
|
||||
| 테스트 분류 5개, 배치, source set | `docs/testing/TESTING_STRATEGY.md`, 기계 기준 `TestLaneCategory` | 05장이 가리킴 |
|
||||
| 게이트 구성(`ci`·`mainCheck`·`integrationCheck`…) | `src/build.gradle` 라이프사이클, `.github/workflows/` | 07장이 언제 무엇을 돌리는지 정함 |
|
||||
| strict lane 단계 검사 | `src/build-logic/`(`StrictLaneStagesPlugin`), `AGENTS.md` 「Gradle 정책 권위」 | 07장이 가리킴 |
|
||||
| HTTP wire 계약 | `docs/web/http-contract.md` | 04장이 가리킴 |
|
||||
| 새 기능 만드는 순서 | `docs/manual/` | 가리킴 |
|
||||
| 커밋·PR 형식 | `design-docs/conventions/commit-and-pr.md`(저장소 밖) | 08장이 이 repo 예외를 덧붙임 |
|
||||
| 28개 관점의 일반 설명, 판정 체계(심각도·통제·증거) | 공용 가이드(저장소 밖, 아래) | 02장이 이 repo에 맞춤 |
|
||||
| 소유자 결정 원문 | 각 리뷰 문서의 결정 절, `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 | 08장은 색인 |
|
||||
| **이 매뉴얼이 정본** | 작업 종류별 절차(01), 이 repo의 리뷰 점검 항목·결함 정의·리뷰 문서 형식(02), 반복 결함 패턴과 막는 기준(04·부록), 성능 측정 조건(06), 무거운 실행 위치(07 「소유자 환경」), 결정을 다시 묻지 않는 규칙·결정 기록법(08), 세션 분업·brief·리뷰 반복 종료 조건(09) | |
|
||||
|
||||
## 읽는 순서
|
||||
|
||||
처음이면 이 README → 01 → 09 → 08을 읽는다. 그다음은 맡은 작업의 장만 읽는다.
|
||||
|
||||
| 장 | 파일 | 언제 읽나 |
|
||||
| --- | --- | --- |
|
||||
| 01 작업 종류별 절차 | [01-procedures.md](01-procedures.md) | 어떤 작업이든 시작할 때. 시작 조건·단계·산출물·완료 기준 |
|
||||
| 02 리뷰 기준 | [02-review-criteria.md](02-review-criteria.md) | 리뷰하거나 리뷰 결과를 읽을 때 |
|
||||
| 03 폴더·모듈 구조 기준 | [03-folder-module-structure.md](03-folder-module-structure.md) | leaf·패키지·source set·문서 위치를 바꿀 때 |
|
||||
| 04 코드 구조 기준 | [04-code-structure.md](04-code-structure.md) | 결함을 고치거나 리팩터링할 때 |
|
||||
| 05 테스트 구조 기준 | [05-test-structure.md](05-test-structure.md) | 테스트를 쓰거나 옮기거나 RED를 확인할 때 |
|
||||
| 06 성능·최적화 기준 | [06-performance.md](06-performance.md) | 성능을 재거나 고칠 때 |
|
||||
| 07 검증과 게이트 | [07-verification-gates.md](07-verification-gates.md) | 무엇을 언제 어디서 돌릴지 정할 때 |
|
||||
| 08 결정과 기록 | [08-decisions-records.md](08-decisions-records.md) | 결정이 필요해 보일 때, 커밋·PR을 쓸 때 |
|
||||
| 09 작업 진행 방식 | [09-working-method.md](09-working-method.md) | 여러 세션으로 나눠 일할 때, 반복을 멈출지 정할 때 |
|
||||
| 부록 결함 패턴 카탈로그 | [appendix-defect-patterns.md](appendix-defect-patterns.md) | 리뷰 전 훑어볼 목록이 필요할 때 |
|
||||
|
||||
## 프론트 매뉴얼과 같은 뼈대
|
||||
|
||||
짝 프론트 템플릿(`clean-architecture-frontend-template`)도 같은 장 번호로 개선 매뉴얼을 만든다. 장 번호가 같으면
|
||||
"두 repo의 05장"처럼 같은 주제를 바로 비교할 수 있다. 이 repo는 장을 합치거나 더하지 않았다. 부록 파일 이름은
|
||||
`appendix-defect-patterns.md`다.
|
||||
|
||||
## 공용 리뷰 가이드와의 관계
|
||||
|
||||
지금까지 리뷰 기준으로 쓴 가이드는 프론트 repo의 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`다.
|
||||
Backend·Frontend·Platform 공용 일반론이고, 예시는 이 템플릿의 코드가 아니다. 2026-11-01 백엔드 성숙도 리뷰도
|
||||
이 가이드의 31절 Backend 시나리오를 기준으로 했다(`docs/reviews/2026-11-01-maturity-review/README.md` 머리말).
|
||||
|
||||
- 이 매뉴얼은 가이드를 **복사하지 않는다**. 가이드의 절 번호(예: 「가이드 35.5」)로 가리킨다.
|
||||
- 02장은 가이드의 28개 관점과 판정 체계를 **이 repo의 경로·명령·지난 결함**으로 바꿔 적는다. 일반 설명이 더 필요하면
|
||||
가이드를 읽는다.
|
||||
- 가이드는 저장소 밖에 있어 링크 검사(`.github/workflows/link-check.yml`, lychee)가 따라갈 수 없다. 그래서 경로를
|
||||
링크가 아니라 코드 표기로 쓴다.
|
||||
- 이 repo에서 파생한 서비스에는 프론트 repo가 없을 수 있다. 02장은 가이드 없이도 판정할 수 있게 썼다.
|
||||
|
||||
## 근거 표기
|
||||
|
||||
- 경로는 저장소 루트 기준이다. 코드 근거는 `file:line`, 문서 근거는 「문서 N절」로 적는다.
|
||||
- `file:line`은 링크로 쓰지 않는다. lychee가 `path:42`를 없는 파일로 본다.
|
||||
- 리뷰 ID는 가이드 36.3의 라운드 밖 표기 `MMDD/ID`를 쓴다. 같은 접두어를 그 폴더의 파일에도 쓴다.
|
||||
이 매뉴얼에서 쓰는 줄임말:
|
||||
|
||||
| 줄임말 | 뜻 |
|
||||
| --- | --- |
|
||||
| `1101/05-01` | `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01. `1101` README는 그 폴더의 `README.md`, `1101/09-performance-measurement.md`는 그 폴더의 파일 |
|
||||
| `1103/RR6-01-05` | `docs/reviews/2026-11-03-rereview/`의 발견. `RR-*`(1차 재리뷰), `RR2-*`~`RR6-*`(round2~round6). `1103` README, `1103/round6/01-core-inbound.md`도 같은 방식 |
|
||||
| 「결정 N」 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번 |
|
||||
| 「가이드 N절」 | 공용 리뷰 가이드(프론트 repo `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`)의 N절 |
|
||||
| 「커밋 규칙 N」 | `design-docs/conventions/commit-and-pr.md`(이 repo 옆 `design-docs` repo)의 N절 |
|
||||
|
||||
- 이 repo에서 근거를 찾지 못한 기준은 **[제안]**으로 표시했다. 제안은 소유자가 받기 전까지 규칙이 아니다.
|
||||
|
||||
## 결정 기록
|
||||
|
||||
이 매뉴얼을 만들며 정한 것이다. 소유자가 뒤집을 수 있다.
|
||||
|
||||
| # | 결정 | 이유 | 버린 대안 |
|
||||
| --- | --- | --- | --- |
|
||||
| M-1 | 위치는 `docs/improvement/` | 독자가 `docs/manual/`(새 기능 작성자)과 다르다. `docs/reviews/`는 리뷰 결과 보관소라, 기준서를 섞으면 어느 문서가 현재 기준인지 흐려진다 | `docs/reviews/` 안에 두기, `docs/manual/` 뒤에 장 추가 |
|
||||
| M-2 | 장 구성은 총괄 세션이 준 뼈대 그대로 | 프론트 매뉴얼과 장 번호를 맞추기 위해서다 | 07·09 합치기 |
|
||||
| M-3 | 심각도 체계를 용도로 나눈다. 전체 리뷰는 가이드 35.2(Critical~Low)+35.3(P0~P3), 확인 리뷰는 Critical/Important/Minor(02장 3절) | 두 체계 모두 이력에 있다(`1101` 전체 리뷰, `1103` 확인 리뷰). 전체 리뷰는 지난 결과·프론트와 비교해야 하고, 확인 리뷰는 `superpowers:requesting-code-review` 템플릿이 쓰는 체계다. 어느 쪽이든 모든 발견을 고치므로 심각도는 순서와 재확인 범위만 정한다 | 하나로 통일(지난 문서와 비교가 끊긴다) |
|
||||
| M-4 | 08장의 결정 표는 색인이다. 한 줄 요약과 출처만 둔다 | 결정 원문을 옮겨 쓰면 갈라진 복사본이 된다(부록 A1) | 결정 원문 이동 |
|
||||
| M-5 | 저장소 밖 문서(공용 가이드, 커밋 규칙)는 링크 대신 코드 표기 | lychee 링크 검사가 저장소 밖을 못 따라간다 | 상대 링크 |
|
||||
| M-6 | 소유자 환경에 묶인 규칙(desktop 실행, 세션 도구)은 07·09장의 「소유자 환경」 절에만 둔다 | 파생 프로젝트가 그 절만 바꾸면 되게 하려는 것이다 | `AGENTS.md`에 직접 쓰기 |
|
||||
| M-7 | `AGENTS.md`의 commit 정책 `human-only`는 바꾸지 않는다. 소유자가 브랜치를 지정해 허용한 예외를 08장에 적는다 | commit 정책은 소유자만 바꿀 수 있다 | 정책 문장 수정 |
|
||||
| M-8 | 결함이 아닌 "개선 제안"도 열린 채 두지 않는다. 받아서 고치거나, 받지 않는 이유를 결정으로 남긴다 | 소유자 규칙 "보고할 때 남은 문제가 없어야 한다"(`1103` README 16절)를 결함이 아닌 항목에도 적용한 것이다 | 제안은 기록만 |
|
||||
| M-9 | 총괄+하위 세션 분업과 "Minor도 고친다"는 2026-11-05 총괄 세션 brief로 받은 소유자 규칙이다. 이 매뉴얼(09장)이 그 규칙의 저장소 안 정본이 된다 | 규칙이 세션 기록에만 있었다 | |
|
||||
|
||||
## 이 매뉴얼을 고칠 때
|
||||
|
||||
- 정본이 바뀌면 이 매뉴얼의 해당 문장을 고친다. 이 매뉴얼을 정본과 대조하는 자동 검사는 없다. 이 repo는 문서를
|
||||
파싱해 대조하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 2·8절, `AGENTS.md` 「Gradle 정책 권위」).
|
||||
- 상대 링크는 lychee가 검사한다(`.github/workflows/link-check.yml`의 `docs/**/*.md`).
|
||||
- 리뷰 라운드에서 새 반복 패턴이 나오면 부록에 행을 더하고, 막는 기준이 생기면 04·05·07장에 넣는다.
|
||||
- 새 소유자 결정이 생기면 08장 색인에 한 줄을 더한다.
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 새 기능은 `docs/manual/`, 이미 있는 코드를 평가·수정하는 일은 이 매뉴얼.
|
||||
- 규칙의 정본은 `AGENTS.md`·registry·leaf `CLAUDE.md`다. 이 매뉴얼은 가리키고, 절차·점검 항목·패턴·기록법만 소유한다.
|
||||
- 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 돈다.
|
||||
@@ -0,0 +1,32 @@
|
||||
# 부록. 결함 패턴 카탈로그
|
||||
|
||||
2026-11-01 성숙도 리뷰부터 2026-11-05 round6까지 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고,
|
||||
리뷰 문서의 「반복되는 원인」에 이 번호를 붙인다. 근거 ID 표기는 README 「근거 표기」를 따른다.
|
||||
|
||||
출발점은 `1101` README 4절 「반복되는 원인」 다섯 가지다(A3·A4·A5·A11·A1). 그 뒤 재리뷰와 확인 리뷰에서 나온 모양을 더했다.
|
||||
|
||||
| # | 패턴 | 어떻게 보이나 | 근거 | 막는 기준 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| A1 | 갈라진 복사본 | 같은 규칙·표·정규식·이미지 참조가 여러 곳에 있고 이미 다르다 | `1101/01-03`, `1101/01-07`, `1101/04-06`, `1101/05-09`, `1101/07-06`, `1101/01-11`, `1103/RR-01-14`, `1101` README 16.3절(템플릿 패키지 목록 두 곳), `1103` README 16절 r9-c(버전 정규식 사본) | 04장 P1 |
|
||||
| A2 | 문서와 코드 불일치 | 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다 | `1101/02-01`, `1101/07-11`, `1101/03-04`, `1101/06-11`, `1103/RR-01-03`, `1103/RR-01-11`, `1103/RR5-01-01`, `1103/RR6-02-05`, `1103/RR6-03-05`, `1103/RR6-04-05` | 04장 P2 |
|
||||
| A3 | 선언과 실행이 떨어져 있다 | 설정 키는 바인딩되지만 동작하지 않는다. 선언한 설정 bean이 조용히 바인딩되지 않는다. 레지스트리 행·지표를 아무 코드도 쓰지 않는다 | `1101/05-15`, `1101/03-11`, `1101/02-03`, `1101/07-06`, `1103/RR-06-01`, `1103/RR2-04-03`, `1103` README 6.1절(`redis.capability.*` 6개) | 04장 P3 |
|
||||
| A4 | 결과 불명을 확실함으로 | 외부 효과의 결과를 모르는데 "시작 안 함"·"재시도 가능"·"확정 거부"로 기록한다(또는 반대로 부풀린다) | `1101/05-01`, `1101/04-01`, `1101/06-01`, `1101/05-17`, `1101/05-11`, `1103/RR-02-03`, `1103/RR-01-11` | 04장 P4 |
|
||||
| A5 | 중복·경쟁을 코드 순서로 | 조회 후 insert, 찾고 없으면 넣기, 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim | `1101/09-02`, `1101/04-08`, `1101/04-02`, `1101/03-10`, `1101/04-13`, `1103/RR-03-01`, `1103/RR-02-04` | 04장 P5 |
|
||||
| A6 | 주장하는 것을 보지 않는 테스트 | 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다 | `1101/05-08`, `1101/02-02`, `1101/01-05`, `1103` README 14절(`CountDownLatch` 7건), `1103/RR4-03-01`, `1103/RR6-01-08`, `1103/RR6-02-02` | 05장 4·5절 |
|
||||
| A7 | 거짓 통과 게이트 | 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈 | `1101/08-01`, `1101/04-04`, `1101/03-12`, `1103/RR-06-02`, `1103/RR-06-03`, `1103/RR-04-05`, `1103` README 14절(테스트 SpotBugs 53개), `1103/RR3-04-02`, `1103/RR6-04-01` | 07장 5절 |
|
||||
| A8 | 로그로 새는 입력값·원인 | 클라이언트 입력·SQL 원인이 로그 메시지에 실린다. 서버 실패를 남기지 않거나 클라이언트 실패를 ERROR로 남긴다 | `1103/RR6-01-05`, `1103/RR6-01-06`, `1103` README 16절 r9-a(STOMP SQL 원인, gRPC 무기록), `1101/02-11`, `1101/01-04` | 04장 P8 |
|
||||
| A9 | 이름만 보는 허용·거부 | 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다 | `1103/RR-07-02`, `1103/RR2-04-02`, `1103/RR2-04-01`, `1101/07-14` | 04장 P6 |
|
||||
| A10 | 글로만 있는 규칙 | "하지 마라"·"반드시"가 주석·문서에만 있고 막는 장치가 없다(통제 M0~M1) | `1103/RR-01-02`, `1101/04-03`, `1101/05-16` | 04장 P7 |
|
||||
| A11 | 샘플·fixture가 운영과 다르게 조립 | 샘플이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"이 기동하지 않는다 | `1101/07-03`, `1101/09-03`, `1101/09-08`, `1101/07-04`, `1101/01-02`, `1101/07-09` | 04장 P9 |
|
||||
| A12 | 수정이 새 결함을 만든다 | 고친 커밋에서 새 Important·회귀가 나온다. 두 수정이 한 트리에서 처음 만나 새 결함이 생긴다 | `1103` README 1절(Important 27), 9절(새 Important), `1103/RR6-01-01`(회귀), `1101` README 16.1절(`BC_IMPOSSIBLE_INSTANCEOF`), `1103` README 6.1절(최종 게이트에서 드러난 2건) | 09장 5절, 07장 3절 |
|
||||
| A13 | 합치는 과정의 누락 | 색인을 손으로 옮기다 발견이 빠진다. 손으로 푼 충돌이 한쪽 변경을 지운다 | `1101` README 12절 정정(06-10~14 다섯 건), `1101` README 14.1절(충돌 처리 목록) | 01장 1절 8단계, 09장 2절 |
|
||||
| A14 | 타이밍에 기댄 약속 | "스레드를 남기지 않는다"·"시간 안에 끊는다"가 공용 풀이나 "보통은 끝나 있음"에 기댄다 | `1103` README 16.1절(`ClientRuntimeRegistry.close`), `1103/RR3-03-01`, `1101/05-06` | 04장 P10 |
|
||||
| A15 | 사라지는 외부 공급원 | 고정한 컨테이너 이미지를 더는 받을 수 없어 다른 lane 결과까지 가린다 | `1101/05-09`, `1101/08-04` | 07장 5절 |
|
||||
| A16 | 상한 없는 자원 | 연결·구독·동시 호출·본문 크기·트랜잭션 시간에 상한이 없거나 코드에 드러나지 않는다 | `1101/03-06`, `1101/03-09`, `1101/04-10`, `1101/02-09`, `1101/04-12` | 04장 P11 |
|
||||
|
||||
## 패턴을 더하는 법
|
||||
|
||||
- 새 라운드에서 **두 건 이상**이 같은 모양이면 행을 더한다. 한 건이면 그 라운드 README에만 둔다.
|
||||
- 행에는 모양(코드에서 어떻게 보이나)과 근거 ID를 적는다. 원인 추측이 아니라 실제로 본 모양을 쓴다.
|
||||
- 막는 기준이 생기면 04·05·07장에 기준을 쓰고 이 표의 「막는 기준」 칸에서 가리킨다.
|
||||
- 번호는 다시 매기지 않는다. 지운 패턴은 행을 남기고 "합침 → A<n>"으로 적는다.
|
||||
@@ -12,6 +12,9 @@
|
||||
|
||||
근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.
|
||||
|
||||
이미 있는 코드를 리뷰·수정·리팩터링·최적화하는 일은 이 매뉴얼이 아니라
|
||||
[개선 작업 매뉴얼](../improvement/README.md)이 맡는다.
|
||||
|
||||
## 읽는 순서
|
||||
|
||||
처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다.
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# 개선 작업 매뉴얼 작성 계획
|
||||
|
||||
> 실행 방식: 한 세션이 직접 쓴다(하위 에이전트 없음 — 총괄 세션 지시). 문서 작업이라 TDD 대신 "근거 대조 → 링크 검사 → 문서 대조 lane"으로 검증한다.
|
||||
|
||||
**목표:** 이 repo를 리뷰·결함 수정·리팩터링·성능 최적화·구조 변경할 때 사람과 AI가 같이 쓰는 기준서 `docs/improvement/`를 만든다.
|
||||
|
||||
**방식:** 규칙의 정본은 이미 있는 곳(`AGENTS.md`, `modules.json`, `application-core/CLAUDE.md`, `docs/testing/TESTING_STRATEGY.md`, `src/build.gradle`, 리뷰 문서의 결정 절)을 가리키고, 정본이 없는 것(작업 종류별 절차, 이 repo용 리뷰 점검 항목, 반복 결함 패턴, 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업)만 이 매뉴얼이 정본이 된다.
|
||||
|
||||
**입력:** 총괄 세션 brief(2026-11-05). 프론트 repo도 같은 장 번호로 따로 만든다.
|
||||
|
||||
## 전체 제약
|
||||
|
||||
- 장 번호: README, 01 절차, 02 리뷰 기준, 03 폴더·모듈, 04 코드 구조, 05 테스트 구조, 06 성능, 07 검증·게이트, 08 결정·기록, 09 진행 방식, 부록 결함 패턴. 합치거나 더하면 README에 이유.
|
||||
- 모든 기준에 이 repo 경로(`file:line` 또는 문서 절) 근거. 근거가 없으면 쓰지 않거나 "제안"으로 표시.
|
||||
- 소유자 규칙 반영: (a) Minor도 고친다, 남은 문제 0까지 리뷰↔수정 반복 (b) 알맞은 스킬 (c) 무거운 실행은 desktop — 따로 떼어 쓴다 (d) 총괄 + 하위 세션.
|
||||
- `docs/**/*.md`는 lychee 링크 검사 대상(`.github/workflows/link-check.yml`). 저장소 밖 경로와 `file:line`은 링크가 아니라 코드 표기로 쓴다.
|
||||
- 이 노트북에서 Gradle·Docker를 돌리지 않는다. 문서 대조 lane은 push 뒤 desktop에서.
|
||||
- `CLAUDE.md`는 `./gradlew :app-bootstrap:architectureTest` 문자열을 유지해야 한다(`DeveloperExperienceContractTest.guidanceNamesTheArchitectureSourceSetTask`).
|
||||
|
||||
## 위험 지점
|
||||
|
||||
1. 결정 표가 원문과 갈라진 복사본이 된다 → 한 줄 요약 + 출처, "다르면 출처가 맞다"를 표 위에 적는다.
|
||||
2. 저장소 밖(프론트 repo, design-docs) 링크가 lychee를 깨뜨린다 → 코드 표기로만 쓴다.
|
||||
3. 심각도 체계가 두 벌(가이드 High/Medium/Low, 확인 리뷰 Important/Minor) → 02에서 언제 무엇을 쓰는지 정하고 README 결정 기록에 남긴다.
|
||||
4. `AGENTS.md`의 `human-only`와 소유자의 브랜치 커밋 허용이 어긋나 보인다 → 08에서 "기본은 human-only, 소유자가 작업마다 허용"으로 출처와 함께 적는다. AGENTS 규칙 자체는 바꾸지 않는다.
|
||||
5. 인용한 경로가 없는 파일이 된다 → 작성 뒤 인용 경로를 스크립트로 전수 확인한다.
|
||||
|
||||
## 작업
|
||||
|
||||
### 1. 근거 읽기 (완료)
|
||||
|
||||
리뷰 README 두 개, 후속 현황표 결정 절, `AGENTS.md`·`CLAUDE.md`, `docs/manual/`, `TESTING_STRATEGY.md`, `src/build.gradle` 라이프사이클, workflow, 공용 가이드 35·36절.
|
||||
|
||||
### 2. 매뉴얼 작성
|
||||
|
||||
- Create: `docs/improvement/README.md`, `01-procedures.md` … `09-working-method.md`, `appendix-defect-patterns.md`
|
||||
- 각 장은 「핵심」으로 시작하고 「지금 이해하면 되는 것」으로 닫는다(`docs/manual/` 형식).
|
||||
|
||||
### 3. 연결
|
||||
|
||||
- Modify: `AGENTS.md`(리뷰·개선 기준 절), `CLAUDE.md`(같은 내용 요약), `docs/README.md`(횡단 문서 표)
|
||||
|
||||
### 4. 검증
|
||||
|
||||
- 인용 경로 전수 확인(로컬 스크립트, 읽기만)
|
||||
- 상대 링크 확인(로컬 스크립트, lychee와 같은 규칙: 파일 존재)
|
||||
- push 뒤 desktop: `./gradlew :app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest --console=plain`
|
||||
|
||||
### 5. 커밋·push
|
||||
|
||||
- `docs(improvement): 개선 작업 매뉴얼을 만든다` 한 커밋(문서와 연결은 한 논리 변경). AI 꼬리말 없음.
|
||||
Reference in New Issue
Block a user