docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와 리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이 "이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는 없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지), 커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음). 고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs delegation-loop/02-design.md 4~6·10절): - CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본 AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는 곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던 내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은 reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절. - docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개 (new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns, decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고 review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에 나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고, improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다. - improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과 수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난 수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25, +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다. - 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를 README 4절과 AGENTS.md에 같은 말로 적었다. - 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인 (reference/decisions.md, reference/defect-patterns.md)에만 둔다. - 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md, docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운 CLAUDE.md 「Layer workflow」를 가리키던 줄). 위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라 초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어 docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/ 본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의 성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다. 검증 - python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80, playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄 - python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0 - CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest .guidanceNamesTheArchitectureSourceSetTask가 기대하는 "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는 이 커밋을 push한 뒤 desktop에서 돌린다
This commit is contained in:
@@ -0,0 +1,188 @@
|
||||
# 결정 색인
|
||||
|
||||
이미 정한 것을 한곳에서 찾는 색인이다. 결정의 원문은 「출처」 칸의 문서에 있고, 원문이 정본이다. 이 표와 원문이 다르면 원문이 맞고 이 표를 고친다. 이 문서는 지난 리뷰 ID와 결정 번호를 출처로 쓴다(매뉴얼 본문에는 쓰지 않는다).
|
||||
|
||||
```text
|
||||
작업 시작 ─> 이 색인에서 주제를 찾는다 ─> 있으면: 원문을 읽고 그대로 따른다
|
||||
└> 없으면: 소유자 몫인가? ─> 그렇다: 묻는다(3절)
|
||||
└> 아니다: 정하고 기록한다(3절)
|
||||
```
|
||||
|
||||
## 1. 결정을 다시 묻지 않는 규칙
|
||||
|
||||
1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다.
|
||||
2. 다시 열 수 있는 경우는 셋뿐이다.
|
||||
- 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다.
|
||||
- 두 결정이 서로 충돌한다.
|
||||
- 결정이 `AGENTS.md` HARD-STOP과 충돌한다.
|
||||
3. 다시 열 때는 "다시 따져 본 것"과 권하는 안을 붙여 소유자에게 묻는다. 예: 2026-11-04 소유자가 수정 묶음의 기본값 셋을 다시 물었을 때, 총괄은 각각 근거를 다시 따져 적었고 소유자가 다시 정했다(`docs/reviews/2026-11-03-rereview/README.md` 15절).
|
||||
4. 위임·기본값으로 정한 것은 보고에 따로 적는다. 소유자가 뒤집을 수 있게 한다.
|
||||
5. 뒤집힌 결정은 원문에서 지우지 않는다. 취소선이나 "→ N절에서 바꿈"으로 새 위치를 가리킨다.
|
||||
6. 리뷰어는 정한 결정을 결함으로 다시 올리지 않는다.
|
||||
|
||||
## 2. 색인
|
||||
|
||||
「누가」 칸: **소유자**는 소유자가 직접 정했다. **위임**은 소유자가 "지금 정하고 진행하라"고 맡겨 총괄이 정했다(소유자가 뒤집을 수 있다). **기본값**은 수정 묶음이 정하고 처리 표에 남겼다(소유자 확인 대상). **총괄 지시**는 소유자 환경을 운영하려고 총괄 세션이 정한 작업 규칙이다. **정책**은 `AGENTS.md`에 적힌 규칙이다.
|
||||
|
||||
「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번, `1101`은 `docs/reviews/2026-11-01-maturity-review/README.md`, `1103`은 `docs/reviews/2026-11-03-rereview/README.md`다.
|
||||
|
||||
### 2.1 작업 방식
|
||||
|
||||
| 주제 | 결정 | 누가 | 날짜 | 출처 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 |
|
||||
| 커밋 예외 | brief가 허용하면 그 작업의 자기 브랜치에만 커밋·push한다. main 병합·다른 브랜치 push·force push는 하지 않는다 | 소유자 | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절, `docs/work/README.md` 4절 |
|
||||
| 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 |
|
||||
| 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | `1103` 16절 |
|
||||
| 옛 멈춤 기준 | "새 Important 0이면 멈춤", "Minor는 기록만" — 거둠 | 위임 → 소유자가 거둠 | 2026-11-05 | `1103` 9.1·11.1·16절 |
|
||||
| 두 repo의 종료 조건 | 각자 유지한다. 백엔드는 발견이 0이 될 때까지, 짝 프론트는 자기 매뉴얼의 조건 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 전달(소유자 원문 "각자 유지") |
|
||||
| 무거운 실행 위치 | 노트북에서 Gradle·Docker를 돌리지 않는다. desktop에서 브랜치를 받아 돌린다 | 소유자 | 2026-11-05 | `1103` 17.1절 |
|
||||
| desktop 공유 잠금 | desktop의 Gradle·Docker 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 프론트와 부하·포트(4173·4174)가 겹치지 않게 | 총괄 지시 | 2026-11-05 | 2026-11-05 총괄 세션 brief, design-docs `conventions/delegation-loop.md` 11절 |
|
||||
| 세션 분업 | 총괄 세션은 지휘만, 실제 작업은 하위 세션 | 소유자 | 2026-11-05 | design-docs `conventions/delegation-loop.md` 2절 |
|
||||
| 하위 에이전트 | Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`) | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 |
|
||||
| 매뉴얼 체계 | 짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작 | 소유자 | 2026-11-06 | 같은 문서 D1, D4 |
|
||||
| 크기별 생략 | 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 | 소유자 | 2026-11-06 | 같은 문서 D2, design-docs `conventions/work-thinking-order.md` |
|
||||
| 매뉴얼 검사 장치 | 이력 ID·분량 검사와 리뷰 색인 검사는 Gradle 밖 `scripts/`(`check-work-docs.py`, `check-review-index.py`) | 소유자 | 2026-11-06 | 같은 문서 D6 |
|
||||
| 규칙 ID | 규칙마다 ID(`R-…`)는 아직 붙이지 않는다. 원장이 생길 때 붙인다 | 소유자 | 2026-11-06 | 같은 문서 D7 |
|
||||
| 옛 개선 매뉴얼 | 브랜치 `claude/improvement-manual-6ae516`은 병합하지 않고 재료로만 쓴다 | 소유자 | 2026-11-06 | 같은 문서 D12 |
|
||||
| 개선 매뉴얼을 먼저(지난 것) | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 brief |
|
||||
| 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 | `1103` 2절 |
|
||||
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 |
|
||||
| 학습 문서 | 삭제된 코드를 설명하는 학습 문서(`docs/study/*.ko.md`, `docs/*-superpowers-package/`)는 현재 코드에 맞게 갱신 | 소유자 | 2026-09-25 | 결정 6 |
|
||||
| client 오류 문구 | 한국어. `Category`별 문구 표 하나를 shared-contract에 | 소유자 | 2026-09-25 | 결정 11 |
|
||||
|
||||
### 2.2 구조·조립
|
||||
|
||||
| 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 |
|
||||
| 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `CLAUDE.md`에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 |
|
||||
| id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 |
|
||||
| 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 |
|
||||
| notification `TenantId` | 통합하지 않음. 차이와 이유는 그 타입 Javadoc | 위임 | `1101` 15절(01-03) |
|
||||
| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) |
|
||||
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
|
||||
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
|
||||
|
||||
### 2.3 계약·오류
|
||||
|
||||
| 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| HTTP 오류 응답 | Envelope 하나. fileserver problem+json도 Envelope로, tus 프로토콜 헤더만 유지 | 소유자 | 결정 2 |
|
||||
| 처리 중 409 | `IDEMPOTENT_IN_FLIGHT`는 `retryable=true` + `Retry-After: 2`, 계약 문서에 고정 | 소유자 | `1101` 5절(02-01), 15절 |
|
||||
| Envelope null 필드 | 백엔드가 생략(`NON_NULL`) | 소유자 | `1101` 5절(02-02) |
|
||||
| `INTERNAL_ERROR` retryable | `false`. 일시적 실패는 전용 코드가 retryable을 가진다 | 소유자 | 결정 28 |
|
||||
| 새 오류 코드 소유 | 코드를 쓰는 leaf의 enum. 계약은 `docs/web/http-contract.md` §4 | 위임 | `1101` 15절 |
|
||||
| correlation ID | 규칙 밖이면 서버가 새 값으로 교체 | 위임 | `1101` 15절(02-11) |
|
||||
| JSON 아닌 본문 상한 | 전역 상한 없음. 엔드포인트가 직접 둔다 | 위임 | `1101` 15절(02-09) |
|
||||
| GraphQL 복잡도 | 크기 미선언 list = 20, `first`·`last` 둘 다면 큰 쪽, per-parent 경고 임계 10 | 위임 | `1101` 15절(03-01·03-03) |
|
||||
| GraphQL DataLoader 키 실패 | 등록된 `ApiErrorCode`만 노출 | 소유자 | 결정 25 |
|
||||
| Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 |
|
||||
| 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 |
|
||||
|
||||
### 2.4 멱등성
|
||||
|
||||
| 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| complete 단계 연결 포화 | `UNAVAILABLE` 현재 동작 유지 + 문서화 | 소유자 | 결정 24 |
|
||||
| complete 단계 저장소 실패 | "결과 불명"으로 따로 알린다(실행 전 503과 구분). 같은 키 재전송은 서버가 판정 | 위임 | `1103` 4절(RR-02-03) |
|
||||
| lease 지난 실행 중 기록 | PostgreSQL·Redis store가 같은 계약: 작업을 다시 돌리지 않고 "회복 필요" | 위임 | `1103` 9.1절(RR-01-11) |
|
||||
| Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease), 설정 검사 | 위임 | `1103` 9.1절(RR-03-11) |
|
||||
| 늦은 완료 | 늦게 끝난 첫 시도의 완료는 **기록한다**(묶음 기본값 "버린다"를 뒤집음). 다시 실행은 여전히 하지 않음 | 소유자 | `1103` 15절 ① |
|
||||
| 보존 기간 관계 | `failure-retention < replay-ttl`이면 기동 실패 | 소유자 | `1103` 15절 ③ |
|
||||
| 같은 attempt 재claim | lease 지난 `CLAIMED`·`FAILED_RETRYABLE`을 넘겨받는다. 같은 attempt를 두 호출이 동시에 쓰는 것은 호출자 계약 | 기본값 | `1103` 17절 r10-02 |
|
||||
| 다른 핸들의 시작 답 | PostgreSQL도 Redis와 같게 `NOT_OWNER`/`NOT_CLAIMED`로 답한다 | 기본값 | `1103` 17절 r10-02 |
|
||||
| Redis 연결 예산 | 캐시 조건부 쓰기는 멱등성·lease와 다른 연결 예산(SCRIPT lane) | 위임 | `1103` 4절(RR-04-02) |
|
||||
|
||||
### 2.5 영속성
|
||||
|
||||
| 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| JPA 기본값 | 트랜잭션 제한 30초, JDBC batch 50, H2 운영 jar 제거, 격리 수준 Hikari 고정, upsert `DO NOTHING` 후 갱신 | 위임 | `1101` 15절(04) |
|
||||
| 포트 시그니처 | claim에 lease·`claimFence`, fileserver `claimDue`·`markAbandoned`·`claimToken` | 위임 | `1101` 15절 |
|
||||
| 마이그레이션 번호 | 스트림별 순번. 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 `V8_1`. notification은 `V13` | 위임 | `1101` 15절 |
|
||||
| V21 유일 인덱스 | 기존 중복이 있으면 마이그레이션 실패. runbook에 확인 쿼리 | 위임 | `1101` 15절 |
|
||||
| 순서 번호 seed | counter가 없으면 전역 floor부터 | 위임 | `1103` 4절(RR-03-02) |
|
||||
| 마이그레이션 잠금 | 강한 잠금을 거는 마이그레이션은 `SET LOCAL lock_timeout`, 같은 모양의 lane 테스트 | 위임 | `1103` 9.1절(RR-02-09) |
|
||||
| Flyway PostgreSQL 잠금 | 세션 수준(`transactional-lock: false`). 전제: Hikari 직접 연결. transaction-mode PgBouncer 뒤에서는 깨진다 | 기본값 | `1103` 17절 r10-03(RR6-03-01) |
|
||||
| persistence-jpa 설정 prefix | 플랫폼 자체는 `app.persistence-jpa.*`, 공유 기능은 기능 트리(`app.outbox`·`app.lock`·`app.realtime.replay`) | 소유자 | 결정 36 |
|
||||
| 분산 lock·lease | 둘 다 capability로 유지, 공통 계약 테스트 | 소유자 | 결정 8 |
|
||||
|
||||
### 2.6 샘플·메시징·보안·설정
|
||||
|
||||
| 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| 포스터 업로드 abort·reconcile 경합 | 먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409) | 소유자 | 결정 22 |
|
||||
| work log 권한·batch | 관리자도 남의 work log 수정 불가, `batchCreate` 상한 1000·한 트랜잭션 | 위임 | `1101` 15절(09) |
|
||||
| 이벤트 tenant·오류 코드 | 이벤트 tenant 범위 `global`, `WORKLOG_INVALID`·`OPERATION_NOT_FOUND` | 위임 | `1101` 15절(01) |
|
||||
| outbox append 모델 | canonical(`OutboxAppendPort`)로 통일, legacy 포트·legacy Kafka 발행 경로 삭제 | 소유자 | 결정 7 |
|
||||
| Kafka 소비 | 지원. `MessageHandler<T>` 하나 + starter-kafka가 consumer 조립 | 소유자 | 결정 10 |
|
||||
| decode 타입 등록 | handler bean이 선언한 타입으로 decode 목록을 만든다 | 위임 | `1101` 15절(06-08 후속) |
|
||||
| relay 재시도 | 재시도 가능 거부는 무한 재시도(5분 간격), 예산 설정 키 없음, 인증 오류는 경보로 | 위임 | `1101` 15절(06-01·06-03) |
|
||||
| 끝나지 않는 재시도 | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로, runbook에 park·재개 절차와 테스트된 SQL | 위임 | `1103` 4절(RR-05-03) |
|
||||
| 카드 검증기 YAML | messaging leaf 테스트에서만 snakeyaml(main 금지) | 소유자 | 결정 29 |
|
||||
| JWT audience·role | audience 필수, 자기 client role만(기존 배포는 env 하나를 채움) | 소유자 | `1101` 5절(02-03), 15절 |
|
||||
| 데모 계정 | `local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만(허용 목록). 각 프로필은 sample이 실제로 뜨는 프로필 | 위임 | `1103` 4절(RR-07-02), 9.1절(RR2-04-02) |
|
||||
| `fixture-` 값 거부 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사 | 위임 | `1103` 9.1절(RR2-04-01) |
|
||||
| 파일 서버 인가 | 역할 검사(`file:*` 권한)와 소유자·tenant 검사(`ownerPrincipalId`)를 둘 다 | 소유자 | 결정 14, 결정 32 |
|
||||
| cross-origin redirect | 호출자 헤더 전부 제거, 안전한 헤더만 유지 | 소유자 | 결정 23 |
|
||||
| 개발 compose Redis | lane Redis에 ACL 계정, "기동 WARN 없음" 검사 유지 | 위임 | `1101` 15절(r3-J) |
|
||||
| 서블릿 오류 디스패치 | 보안 체인이 ERROR 디스패치만 허용 | 기본값 | `1103` 6절 r4-b, 8절 |
|
||||
| 설정 prefix | `app.*`로 통일, `APP_*` env 키 유지 | 소유자 | 결정 16 |
|
||||
| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `AGENTS.md` capability 기준 4 |
|
||||
| 로그 설정 | logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated | 위임 | `1101` 15절(07) |
|
||||
| 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | `1101` 15절 |
|
||||
| `APP_FLYWAY_ENABLED` | dev·prod에도 적용 | 위임 | `1101` 15절(r3-F) |
|
||||
| 전송 상한 기본값 | gRPC 스레드 32·큐 256·동시 100·deadline 10s·drain 2s, ledger `claimTtl` 5m·보존 24h, WebSocket `max-connections` 1000(초과 시 1013) | 위임 | `1101` 15절(03-06·03-09·03-10) |
|
||||
|
||||
### 2.7 빌드·게이트·capability
|
||||
|
||||
| 주제 | 결정 | 누가 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| 빌드 게이트 | `verifyEnvKeys`는 app-bootstrap 태스크로 유지(구현은 build-logic `ca.config-contract`), JPA evidence manifest는 폐기하고 leaf 테스트로, redis topology lane 유지 | 소유자 | 결정 4 |
|
||||
| API surface 단계 | PR(leaf `check` 안) | 소유자 | 결정 20 |
|
||||
| PR `ci` 범위 | 변경 모듈만 돌리지 않음. 전체 실행 + Gradle 캐시(보류) | 소유자 | 결정 30 |
|
||||
| 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 |
|
||||
| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 |
|
||||
| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 |
|
||||
| gRPC `.proto` | protobuf Gradle 플러그인 + Buf(CI) | 소유자 | 결정 18 |
|
||||
| SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | `1101` 15절(08-07) |
|
||||
| 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 |
|
||||
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
|
||||
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② |
|
||||
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 |
|
||||
| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |
|
||||
| Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) |
|
||||
| httpclient reactive | 삭제 | 소유자 | 결정 9 |
|
||||
| SES 연동 | AWS SDK(sesv2) | 소유자 | 결정 17 |
|
||||
| durable operation | HTTP 어댑터 추가, 설계 4개(서버 생성 id, payload 지문으로 재제출 판정, 고정 event type, 1일 보존) 승인 | 소유자 | 결정 15, 결정 26 |
|
||||
| 알림 provider profile 소실 | 일반 재시도 정책 후 FAILED | 소유자 | 결정 21 |
|
||||
| notification INGEST_ONLY | runtime 없이도 accept 때 route 이름 기록 | 위임 | `1101` 15절(r3-I) |
|
||||
| 파일 서버 쿼터 | 상한 미설정 = 무제한, 동시 예약은 상한을 넘을 수 있음, 정리 worker 기본 켜짐 | 위임 | `1101` 15절(r2-05a) |
|
||||
| objectstorage | provider type 하나 추가 | 위임 | `1101` 15절(05-16) |
|
||||
| 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 끝 목록 |
|
||||
| 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | `1101` 13·14·16절, `1103` 6·10·12·15·16·17절 표 |
|
||||
|
||||
## 3. 새 결정을 기록하는 법
|
||||
|
||||
**누가 정하나**
|
||||
|
||||
| 소유자에게 묻는다 | 직접 정하고 기록한다 |
|
||||
| --- | --- |
|
||||
| 공개 계약·wire 형식 변경, 파생 서비스 동작을 바꾸는 기본값, 보안 정책, 새 leaf, 커밋 정책, 되돌리기 비싼 선택, 비용이 드는 외부 일 | 기존 원칙에서 바로 따라 나오는 것, 결함 수정의 구현 방법, 문서 위치 |
|
||||
|
||||
**묻는 법**: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람을 한 표로 쓴다.
|
||||
|
||||
**어디에 쓰나**
|
||||
|
||||
| 결정의 종류 | 위치 |
|
||||
| --- | --- |
|
||||
| 리뷰 라운드에서 나온 결정 | 그 라운드 README의 「결정」 절. 항목 · 결정 · 이유 · 버린 대안 |
|
||||
| 수정 묶음의 구현 기본값 | 처리 표의 「결정」 칸 |
|
||||
| 되돌리기 비싼 아키텍처 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 잇는다) |
|
||||
| 매뉴얼을 만들거나 고치며 정한 것 | 이 색인 + 근거는 `docs/work/evidence.md` |
|
||||
| 여러 repo와 소유자 운영에 걸친 결정 | design-docs |
|
||||
|
||||
**기록한 뒤**: 이 색인에 한 줄(주제 · 결정 · 누가 · 날짜 · 출처)을 더한다.
|
||||
@@ -0,0 +1,131 @@
|
||||
# 결함 패턴
|
||||
|
||||
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
|
||||
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
|
||||
## 패턴
|
||||
|
||||
### A1. 갈라진 복사본
|
||||
|
||||
- **모양**: 같은 규칙·표·정규식·상수·이미지 참조가 여러 곳에 있고 이미 다르다.
|
||||
- **막는 기준**: 규칙·표·정규식·상수·이미지 참조는 한 곳에 둔다. 두 곳이 꼭 필요하면 하나를 정본으로 명시하고, 다른 하나가 정본과 같은지 보는 대조 테스트를 둔다.
|
||||
- **볼 것**: 새로 쓴 상수·정규식·표가 이미 어딘가에 있는지 grep. 같은 판정을 두 클래스가 하는지.
|
||||
- **장치**: 정본을 가져다 쓰기(예: 마이그레이션 버전 판정 정본 `VersionedMigrationFiles`를 grpc 빌드가 Sync 태스크로 가져온다), 대조 테스트(`TemplatePackageOwnershipDocumentTest`). 테스트 lane의 컨테이너 이미지는 `src/config/testing/container-images.properties` 한 곳이다(MinIO qualification 이미지만 objectstorage leaf 소유).
|
||||
|
||||
### A2. 문서와 코드 불일치
|
||||
|
||||
- **모양**: 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다.
|
||||
- **막는 기준**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: `docs/web/http-contract.md`, `docs/registries/`, runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다.
|
||||
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/CLAUDE.md`를 grep.
|
||||
- **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane, runbook SQL을 실 PostgreSQL에서 그대로 실행하는 lane. 나머지는 리뷰가 본다. 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절).
|
||||
|
||||
### A3. 선언과 실행이 떨어져 있다
|
||||
|
||||
- **모양**: 설정 키는 바인딩되지만 동작하지 않는다. 선언한 설정 bean이 조용히 바인딩되지 않는다. 레지스트리 행·지표를 아무 코드도 쓰지 않는다.
|
||||
- **막는 기준**: 선언(설정 키, 레지스트리 행, 지표 이름, 옵션)마다 그것을 실행하는 코드가 있어야 한다. 실행 코드가 없으면 선언을 지운다. 동작하지 않는 옵션은 설정 키 자체를 두지 않는다(`AGENTS.md` capability 기준 3).
|
||||
- **볼 것**: 새 설정 키를 읽는 곳, 새 레지스트리 행을 내보내는 곳, 문서가 말한 옵션의 분기. 기동 rule이 `static @Bean`이고 필드 주입이 없는지.
|
||||
- **장치**: `StrictSettingsBinder`(모르는 키·오타 거부), `verifyEnvKeys`, 레지스트리와 코드를 대조하는 테스트(`ErrorCodeRegistryMappingTest`, `HeaderRegistryRuntimeAlignmentTest` 등).
|
||||
|
||||
### A4. 결과 불명을 "확실함"으로 기록한다
|
||||
|
||||
- **모양**: 외부 효과의 결과를 모르는데 "시작 안 함", "재시도 가능", "확정 거부"로 기록한다. 또는 반대로 확실한 실패를 결과 불명으로 부풀린다.
|
||||
- **막는 기준**: 외부 효과(DB 커밋, 알림 발송, broker 전송)의 결과를 모르면 "결과 불명"으로 기록·응답한다. 결과 불명을 자동으로 다시 실행하지 않는다. 확실히 실패한 것을 결과 불명으로 부풀리지 않는다.
|
||||
- **볼 것**: 외부 호출 전후의 상태 기록 순서, 예외를 retryable·terminal·unknown으로 나누는 분기, 응답의 `retryable`.
|
||||
- **장치**: 멱등성 공유 계약(`IdempotencyStoreContract` — PostgreSQL·Redis store가 같은 판정), `PersistenceExceptionTranslator`의 커밋 단계 분류, `docs/adr/ADR-JPA-003-completion-unknown.md`.
|
||||
|
||||
### A5. 중복·경쟁을 코드 순서로 막는다
|
||||
|
||||
- **모양**: 조회 후 insert, 찾고 없으면 넣기, 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim, 프로세스 메모리에 둔 소유권.
|
||||
- **막는 기준**: 유일성은 DB 유일 제약이 막고, adapter는 그 제약 위반만 기능 예외로 바꾼다. 여러 인스턴스가 집는 작업은 트랜잭션 안의 claim + lease로 소유권을 정한다.
|
||||
- **볼 것**: 존재 확인 뒤 쓰기, 트랜잭션 밖 잠금, 메모리 안 소유권.
|
||||
- **장치**: `CallerTransaction`(store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(`CreatePosterConcurrencyIntegrationTest`). 정본: `docs/manual/04-persistence.md`.
|
||||
|
||||
### A6. 주장하는 것을 보지 않는 테스트
|
||||
|
||||
- **모양**: 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다.
|
||||
- **막는 기준**: [review-criteria.md](review-criteria.md) 7절 점검표. 변이로 확인한다. skip은 0이거나 설계 이유를 적는다.
|
||||
- **장치**: 포트당 fake와 공유 계약 상속(`AGENTS.md` 테스트 작성 규칙 6), `rejectSkipped`.
|
||||
|
||||
### A7. 거짓 통과 게이트
|
||||
|
||||
- **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane.
|
||||
- **막는 기준**: [gates.md](gates.md) 6절. 게이트 장치를 바꾸면 일부러 망가뜨린 입력으로 실패하는 것을 본다.
|
||||
- **장치**: `verifyStrictLaneStages --dry-run`(두 빌드), lane 정책 값의 캐시 입력 선언, `testQualityCheck`.
|
||||
|
||||
### A8. 로그로 새는 입력값·원인
|
||||
|
||||
- **모양**: 클라이언트 입력이나 SQL 원인이 로그 메시지에 실린다. 서버 실패를 남기지 않거나 클라이언트 실패를 ERROR로 남긴다.
|
||||
- **막는 기준**: 클라이언트 탓 실패(입력 오류)는 WARN 한 줄로 남기고 입력값을 싣지 않는다. 서버 실패는 전송마다 같은 실패 로그 줄(`ServerFailureLog`)을 쓰고, 원인 체인의 SQL·입력값을 메시지에 붙이지 않는다. 클라이언트가 보낸 식별자가 규칙 밖이면 서버가 새 값으로 바꾼다.
|
||||
- **볼 것**: 새 `log.warn`·`log.error`의 인자, 예외 메시지에 사용자 입력을 넣는 곳, 전송별 예외 처리기.
|
||||
- **장치**: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java`(`refusedArgument` 포함), 비밀 분류 `docs/registries/secrets-classification.yaml`.
|
||||
|
||||
### A9. 이름만 보는 허용·거부
|
||||
|
||||
- **모양**: 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다.
|
||||
- **막는 기준**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 허용 목록으로 연다. 허용 목록의 값마다 실제로 그 값으로 동작해야 한다.
|
||||
- **볼 것**: 프로필·환경 이름 문자열 비교, 허용 값마다 실제로 기동하는 테스트가 있는지.
|
||||
- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동).
|
||||
|
||||
### A10. 글로만 있는 규칙
|
||||
|
||||
- **모양**: "하지 마라", "반드시"가 주석·Javadoc·문서에만 있고 막는 장치가 없다(통제 M0~M1).
|
||||
- **막는 기준**: 위반하면 데이터·권한이 깨지는 규칙은 기동 실패, ArchUnit, 타입으로 막는다.
|
||||
- **볼 것**: "must not", "하지 않는다", "금지", "반드시"가 붙은 문장마다 막는 장치가 있는지.
|
||||
- **장치**: 이유를 요구하는 표시(`@SystemCaller(reason)`), 기동 rule, ArchUnit.
|
||||
|
||||
### A11. 샘플·fixture가 운영과 다르게 조립된다
|
||||
|
||||
- **모양**: 샘플이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"으로 둔 fixture가 기동하지 않는다.
|
||||
- **막는 기준**: 샘플은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다. 새 기능의 모양으로 둔 fixture는 실제로 기동되는 모양이어야 한다.
|
||||
- **볼 것**: 샘플 `@SpringBootApplication(exclude=…)`, 샘플 `application.yml`과 기본 조합의 차이.
|
||||
- **장치**: 샘플 전체 기동 lane(`:sample-portfolio:systemTest`, `mainCheck`), 샘플 실서버 계약(`sampleWebContractCheck`).
|
||||
|
||||
### A12. 수정이 새 결함을 만든다
|
||||
|
||||
- **모양**: 고친 커밋에서 새 Important·회귀가 나온다. 두 수정이 한 트리에서 처음 만나 새 결함이 생긴다.
|
||||
- **막는 기준**: 수정 보고에 「새로 가정하는 것」을 쓰고 확인 리뷰가 그 칸부터 본다. 수정 묶음 크기 상한을 지킨다([improve.md](../improve.md) 4.4절). 합친 트리를 라운드 끝 게이트로 따로 검증한다.
|
||||
- **장치**: 확인 리뷰(수정 diff만), [gates.md](gates.md) 3절.
|
||||
|
||||
### A13. 합치는 과정의 누락
|
||||
|
||||
- **모양**: 색인을 손으로 옮기다 발견이 빠진다. 손으로 푼 충돌이 한쪽 변경을 지운다.
|
||||
- **막는 기준**: 색인은 영역 문서에서 기계로 대조한다. 두 묶음이 같은 파일을 건드리지 않게 나눈다([delegate.md](../delegate.md) 「나누는 법」).
|
||||
- **장치**: `python3 scripts/check-review-index.py docs/reviews/<폴더>`.
|
||||
|
||||
### A14. 타이밍에 기댄 약속
|
||||
|
||||
- **모양**: "스레드를 남기지 않는다", "시간 안에 끊는다"가 공용 풀이나 "보통은 끝나 있다"에 기댄다.
|
||||
- **막는 기준**: 그런 약속은 join·종료 대기·전용 스레드로 보장한다.
|
||||
- **볼 것**: `awaitTermination` 뒤 스레드 생존 확인, 시간 제한을 거는 실행기가 공용인지.
|
||||
- **장치**: 부하·자원 한계 lane(`httpClientPerformanceTest` 등, `performanceCheck`).
|
||||
|
||||
### A15. 사라지는 외부 공급원
|
||||
|
||||
- **모양**: 고정한 컨테이너 이미지를 더는 받을 수 없어 다른 lane 결과까지 가린다.
|
||||
- **막는 기준**: 테스트 이미지는 한 곳에 digest로 고정하고, pull 실패는 따로 구분되는 메시지로 실패하게 한다.
|
||||
- **장치**: `src/config/testing/container-images.properties`, `PinnedImageUnavailableException`, main 단계 `--continue`.
|
||||
|
||||
### A16. 상한 없는 자원
|
||||
|
||||
- **모양**: 연결·구독·동시 호출·본문 크기·트랜잭션 시간·큐 길이에 상한이 없거나 코드에 드러나지 않는다.
|
||||
- **막는 기준**: 상한이 있고 그 값이 코드나 설정에 드러난다. 상한을 넘으면 정해진 응답(예: WebSocket 1013, gRPC 즉시 닫기)을 준다.
|
||||
- **정한 값**: [decisions.md](decisions.md) 「전송 상한 기본값」, JPA 기본 트랜잭션 제한 30초. JSON 아닌 본문 상한은 엔드포인트가 직접 둔다.
|
||||
|
||||
## 코드에 결정을 드러내는 곳
|
||||
|
||||
고칠 때 "왜 이 모양인가"를 코드 가까이에 남긴다. 다음 리뷰가 같은 질문을 다시 하지 않게 하려는 것이다.
|
||||
|
||||
| 경우 | 남기는 곳 |
|
||||
| --- | --- |
|
||||
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
|
||||
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
|
||||
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
|
||||
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/messaging/CLAUDE.md`) |
|
||||
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
|
||||
|
||||
## 패턴을 더하는 법
|
||||
|
||||
- 새 라운드에서 **두 건 이상**이 같은 모양이면 행을 더한다. 한 건이면 그 라운드 README에만 둔다.
|
||||
- 모양은 원인 추측이 아니라 코드에서 실제로 본 모양을 쓴다. 근거 ID는 [evidence.md](../evidence.md)에 쓴다.
|
||||
- 번호는 다시 매기지 않는다. 지운 패턴은 행을 남기고 "합침 → A<n>"으로 적는다.
|
||||
@@ -0,0 +1,129 @@
|
||||
# 게이트
|
||||
|
||||
무엇을, 언제, 어디서 돌리는지 정한다. 게이트 구성의 정본은 `src/build.gradle`의 라이프사이클과 `.github/workflows/`다. 이 문서와 그 둘이 다르면 그 둘이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다.
|
||||
|
||||
```text
|
||||
작업 중 <leaf>:check (+ 그 leaf의 관련 strict lane)
|
||||
묶음 끝 + architectureCheck · 바뀐 표면의 검사(env 키·공개 경로·의존성 잠금) · 관련 lane
|
||||
라운드 끝 합친 트리에서 3절 묶음 전체 — workflow가 PR·main에서 돌리는 것과 같은 명령
|
||||
```
|
||||
|
||||
## 1. 게이트 목록
|
||||
|
||||
명령은 모두 `src/`에서 실행한다. leaf의 Gradle path는 `src/config/architecture/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다.
|
||||
|
||||
| 게이트 | 무엇 | 단계 | 정의·workflow |
|
||||
| --- | --- | --- | --- |
|
||||
| `./gradlew <gradle-path>:check` | 그 leaf만: 컴파일, 테스트, Spotless, Checkstyle, Error Prone, API surface | 작업 중 | leaf 컨벤션 플러그인 |
|
||||
| `architectureCheck` | 의존 방향, domain-core·shared-contract·application-* 순수성, Git이 옮길 수 있는 소스, ArchUnit | PR(`ci` 안) | `src/build.gradle` |
|
||||
| `./gradlew :app-bootstrap:architectureTest` | 저장소 전체 ArchUnit suite만 | 작업 중 | app-bootstrap `architectureTest` source set |
|
||||
| `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` |
|
||||
| `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안), optional 빌드는 `ci` | `src/build.gradle` |
|
||||
| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR | `ci-quality-gates.yml`: `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` |
|
||||
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p optional-platforms` |
|
||||
| `:sample-portfolio:check :sample-portfolio:qualityCheck` | 샘플(`ci` 밖) | PR | `ci-quality-gates.yml` |
|
||||
| `-p optional-platforms ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` |
|
||||
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` |
|
||||
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 샘플 실서버 계약 + 샘플 전체 기동(`:sample-portfolio:systemTest`) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` |
|
||||
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 |
|
||||
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). main·nightly에서 돈다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 |
|
||||
| `releaseCheck -PgitRevision=<sha>` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` |
|
||||
| `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` |
|
||||
| `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` |
|
||||
| `verifyDependencyLocks` | lockfile | PR | `ci-quality-gates.yml` |
|
||||
| `:app-bootstrap:documentContractTest` | 문서와 코드를 대조하는 lane(태그 `document-contract`) | main(`mainCheck` 안) | `src/app-bootstrap/build.gradle` |
|
||||
| `:app-bootstrap:repositoryContractTest` | 빌드 스크립트·workflow·compose를 읽는 계약(태그 `repository-contract`) | PR | `src/app-bootstrap/build.gradle` |
|
||||
|
||||
- leaf의 `check`는 그 leaf만 본다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다.
|
||||
- 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
|
||||
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다.
|
||||
|
||||
## 2. 바꾼 것에 맞춰 고르기
|
||||
|
||||
| 바꾼 것 | 추가로 돌릴 것 |
|
||||
| --- | --- |
|
||||
| 한 leaf 안의 코드 | 그 leaf `check` + 그 코드를 지키는 strict lane(실 DB 등) |
|
||||
| leaf 경계·의존·registry | `architectureCheck`, `verifyDependencyLocks` |
|
||||
| env 키 | `:app-bootstrap:verifyEnvKeys` |
|
||||
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
|
||||
| 의존성 | `verifyDependencyLocks` |
|
||||
| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) |
|
||||
| `docs/work/`, 루트 `CLAUDE.md` | `python3 scripts/check-work-docs.py` |
|
||||
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` |
|
||||
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
|
||||
| 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane |
|
||||
| 테스트 코드 | 그 leaf `testQualityCheck` |
|
||||
| compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 |
|
||||
|
||||
어떤 테스트가 그 문서를 읽는지는 `grep -rn '<파일 이름>' src --include=*.java`로 찾는다.
|
||||
|
||||
**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 `python3 scripts/check-work-docs.py --links docs`로 상대 링크만 확인한다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
|
||||
|
||||
## 3. 라운드 끝 — 합친 트리의 전체 묶음
|
||||
|
||||
여러 묶음을 합친 트리는 workflow와 같은 명령으로 검증한다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :ci :verifyDependencyLocks --warning-mode=fail --console=plain
|
||||
./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --console=plain
|
||||
./gradlew :verifyStrictLaneStages --dry-run --console=plain
|
||||
./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain
|
||||
./gradlew :mainCheck --continue --warning-mode=fail --console=plain
|
||||
./gradlew :integrationCheck --continue --console=plain
|
||||
./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true --console=plain
|
||||
./gradlew :performanceCheck --continue -Pperformance.assertions.enabled=true --console=plain
|
||||
./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain
|
||||
cd .. && bash scripts/verify-compose-profile-contracts.sh
|
||||
```
|
||||
|
||||
- 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다.
|
||||
- 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다.
|
||||
|
||||
## 4. 결과 기록
|
||||
|
||||
| 게이트 | 결과 | 시간 | 실행 직전 1분 부하 | 로그 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `:ci :verifyDependencyLocks --warning-mode=fail` | rc=0 | 5분 42초 | 2.65 | desktop `~/<작업 이름>-logs/ci.log` |
|
||||
|
||||
함께 적는다:
|
||||
|
||||
- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
|
||||
- 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다.
|
||||
- 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다.
|
||||
- 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름.
|
||||
- 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로.
|
||||
- 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다.
|
||||
|
||||
## 5. 성능 lane
|
||||
|
||||
- 일부 performance lane은 시간 단언을 `performance.assertions.enabled` 속성으로 켠다. workflow는 이 값을 `true`로 준다(`integration-main.yml`의 `GRADLE_OPTS`).
|
||||
- leaf마다 기본값이 다르다: httpclient lane은 `false`(`src/adapter/outbound/httpclient/build.gradle`), persistence-mongo lane은 `true`(`src/adapter/outbound/persistence-mongo/build.gradle`).
|
||||
- 그래서 desktop에서 `performanceCheck`를 돌릴 때는 workflow와 같게 `-Pperformance.assertions.enabled=true`를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다.
|
||||
- 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다.
|
||||
|
||||
회귀를 막는 장치:
|
||||
|
||||
| 장치 | 고정하는 것 | 단계 |
|
||||
| --- | --- | --- |
|
||||
| 요청당 SQL 수 단언(`WorkLogStatementCostSystemTest`) | 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 | sample `systemTest`(`mainCheck`) |
|
||||
| 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` |
|
||||
| JMH 벤치마크 | `src/messaging/messaging-kafka/src/jmh`, `src/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 |
|
||||
|
||||
## 6. 게이트를 믿을 조건 — 거짓 통과 막기
|
||||
|
||||
초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다.
|
||||
|
||||
| 거짓 통과 모양 | 지금의 장치 |
|
||||
| --- | --- |
|
||||
| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) |
|
||||
| optional 빌드를 보지 않음 | optional 빌드도 같은 검사 |
|
||||
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `AGENTS.md` 「Gradle 정책 권위」의 세는 규칙 |
|
||||
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 |
|
||||
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
|
||||
| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 |
|
||||
| 시간 단언을 끈 채 performance lane 실행 | 5절 속성 |
|
||||
| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` |
|
||||
|
||||
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.
|
||||
@@ -0,0 +1,283 @@
|
||||
# 리뷰 기준
|
||||
|
||||
리뷰와 수정에서 무엇을 결함으로 보고, 어떻게 판정하고, 어떤 형식으로 적는지 정한다. [improve.md](../improve.md)가 필요할 때 이 문서의 절을 가리킨다. 지난 리뷰에서 실제로 나온 예는 [evidence.md](../evidence.md) 「리뷰 기준의 예」에 있다.
|
||||
|
||||
공용 리뷰 가이드는 이 repo 밖에 있다: design-docs `conventions/template-maturity-review-guide.md`. 아래 「가이드 N절」은 그 문서의 절이다. 이 문서는 가이드 없이도 판정할 수 있게 썼다. 일반 설명이 더 필요할 때만 가이드를 읽는다.
|
||||
|
||||
## 1. 결함이란
|
||||
|
||||
리뷰는 **약속과 실제 동작이 다른 곳**을 찾는다. 약속은 코드 이름, Javadoc, 문서, 레지스트리, 테스트 이름, 게이트가 한 것이다. 약속을 어긴 증거가 있으면 결함이고, 없으면 개선 제안이다.
|
||||
|
||||
| 결함의 모양 | 증거 |
|
||||
| --- | --- |
|
||||
| 이름·Javadoc·문서가 말한 동작과 실제 동작이 다르다 | 코드 경로 또는 실행 결과 |
|
||||
| `AGENTS.md` HARD-STOP을 어긴다 | 의존 방향 게이트, ArchUnit, 코드 |
|
||||
| 같은 규칙·값·표가 두 곳 이상에 있고, 서로 다르거나 같게 지키는 장치가 없다 | 두 위치와 차이 |
|
||||
| 테스트나 게이트가 통과하지만 막겠다고 한 것을 막지 못한다 | 변이 실험, 실행 그래프 대조 |
|
||||
| 운영자·개발자에게 틀린 조치를 시키는 문서 | 문서대로 실행한 결과 |
|
||||
| 위험한 동작이 기본값·설정 뒤에 숨어 있다 | 기본값과 그 효과 |
|
||||
|
||||
**개선 제안**은 계약 위반 없이 이해나 비용을 줄일 여지다. 현재 선택과 대안을 비교해 적는다(가이드 41절). 받으면 고치고, 받지 않으면 이유를 결정으로 남긴다. 기록만 하고 열어 두지 않는다.
|
||||
|
||||
다음 말은 결함 근거가 아니다.
|
||||
|
||||
| 근거가 아닌 말 | 결함으로 적으려면 |
|
||||
| --- | --- |
|
||||
| "추상화가 많다" | 어느 wrapper가 무엇을 보호하지 않는지, 지우면 무엇이 유지되는지 |
|
||||
| "운영 준비가 안 됐다" | 어떤 절차를 어떤 버전에서 실행한 증거가 없는지 |
|
||||
| "업계 표준이 아니다" | 이 repo의 어느 계약을 어기는지 |
|
||||
|
||||
## 2. 발견의 성격
|
||||
|
||||
| 성격 | 뜻 |
|
||||
| --- | --- |
|
||||
| 확인된 결함 | 현재 커밋의 코드·실행으로 계약 위반을 보였다. 정적 증거만으로도 확정할 수 있다 |
|
||||
| 구조적 위험 | 인과 경로는 있으나 영향 확인이 남았다. 예: 다중 인스턴스 경쟁을 코드 경로로만 봤다 |
|
||||
| 미검증 | 이 환경에서 확인할 수 없다. 예: 실제 CI runner 실행 |
|
||||
| 개선 제안 | 1절 |
|
||||
|
||||
## 3. 심각도
|
||||
|
||||
심각도 체계는 둘이다. 리뷰 종류로 고른다.
|
||||
|
||||
**전체 리뷰 — Critical / High / Medium / Low, 우선순위 P0~P3** (가이드 35.2·35.3절)
|
||||
|
||||
| 등급 | 이 repo에서 |
|
||||
| --- | --- |
|
||||
| Critical | 인증 없이 민감정보 접근, 실제 데이터의 비가역 대량 손상 |
|
||||
| High | 지원 조건에서 업무 중복 실행, 결과 불명 작업의 재실행, 기본 조합에서 보안 검사가 꺼짐 |
|
||||
| Medium | 피해가 제한되거나 변경 비용을 반복해서 올림 |
|
||||
| Low | 가독성·편의, 제한된 문서 불일치 |
|
||||
|
||||
우선순위는 고치는 순서다. P1은 해당 용도 도입 전 해결, P2는 계획적 개선, P3는 선택이다.
|
||||
|
||||
**확인 리뷰 — Critical / Important / Minor** (`superpowers:requesting-code-review` 리뷰어 지침의 체계)
|
||||
|
||||
| 등급 | 정의 |
|
||||
| --- | --- |
|
||||
| Critical | 전체 리뷰의 Critical과 같다 |
|
||||
| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서 |
|
||||
| Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 |
|
||||
|
||||
확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다.
|
||||
|
||||
**심각도가 정하지 않는 것**
|
||||
|
||||
- 고칠지 말지. 이 repo는 모든 발견을 고치거나 결정으로 닫는다([improve.md](../improve.md) 4.5절). 심각도는 고치는 순서와, 맡긴 쪽이 코드에서 다시 확인할 범위(High·Important 이상)만 정한다.
|
||||
- 건수. 한 결함이 여러 관점에 걸치면 항목 하나에 관점 번호를 모두 붙인다. 두 영역이 같은 결함을 적으면 색인에서 합친다.
|
||||
|
||||
## 4. 증거 수준 E0~E4 (가이드 35.5절)
|
||||
|
||||
| 수준 | 이 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, `java -jar`·compose 실제 기동, 부하·장애 주입·동시 요청 실험 | 운영 환경, 운영 기간 |
|
||||
| E4 운영 관찰 | 이 템플릿에는 없다 | — |
|
||||
|
||||
- 이전 라운드의 실행 결과는 현재 증거가 아니다. 바뀐 커밋에서 다시 돌린다.
|
||||
- 묶음 보고의 "통과"는 E0다. 맡긴 쪽은 보고를 diff와 실행 로그에 대조한다.
|
||||
- build cache로 통과한 실행은 그렇다고 적는다. 실행 시간이 짧으면 캐시 재사용인지 확인한다.
|
||||
- 발견마다 증거 수준을 적는다. 섞이면 나눠 적는다. 예: "E3 — 명령 9·10, 잠금 동작은 E1".
|
||||
|
||||
## 5. 통제 수준 M0~M4 (가이드 35.4절)
|
||||
|
||||
| 수준 | 뜻 | 이 repo의 예 |
|
||||
| --- | --- | --- |
|
||||
| M0 | 지킬 수단이 없다 | — |
|
||||
| M1 | 적혀만 있다 | "하지 마라"가 주석·문서에만 있다 |
|
||||
| M2 | 구현되어 있다 | 코드 경로에 규칙이 있고 검사는 없다 |
|
||||
| M3 | 자동 검증이 위반을 잡는다 | ArchUnit(`src/app-bootstrap/src/architectureTest/`), 공유 계약 테스트, `verifyStrictLaneStages` |
|
||||
| M4 | 경계에서 강제한다 | Gradle 의존 방향 게이트(`verifyCleanArchitectureDependencies`), DB 유일 제약, 기동 실패 rule |
|
||||
|
||||
- 확인하지 못한 것은 M0가 아니라 "미확인"이다.
|
||||
- 위반하면 데이터·권한이 깨지는 규칙이 M1이면 결함으로 적는다.
|
||||
|
||||
## 6. 28개 관점 — 이 repo에서 볼 곳
|
||||
|
||||
관점의 일반 설명은 가이드 1~28절이다. 판정 기호: O 충족 · P 부분 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 종합은 평균하지 않는다. 한 영역이라도 X면 X다.
|
||||
|
||||
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
|
||||
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
|
||||
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
|
||||
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 |
|
||||
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
|
||||
| 6 | 실패 성숙도 | 예외 분류, `retryable`, 결과 불명 | 결과 불명을 확실함으로, 재시도 가능을 확정 실패로 기록 |
|
||||
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 |
|
||||
| 8 | 디버깅 가능성 | `ServerFailureLog`, correlation id, 오류 코드 | 서버 실패를 남기지 않음, 원인이 다른 실패를 같은 코드로 |
|
||||
| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석 | 갈라진 복사본, 현재 동작과 다른 주석·문서 |
|
||||
| 10 | 테스트 성숙도 | 7절 | 이름의 성질을 단언하지 않음, 변이 생존, 계약 밖 fake |
|
||||
| 11 | 데이터 성숙도 | 마이그레이션 스트림, 유일 제약, `@Version`, 잠금 시간 제한 | 중복 규칙에 DB 제약 없음, 적용된 마이그레이션 수정, `lock_timeout` 없는 강한 잠금 |
|
||||
| 12 | 동시성 성숙도 | claim·lease, `SKIP LOCKED`, 트랜잭션 경계 | 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim |
|
||||
| 13 | 확장성 | 연결·구독·동시 호출·본문 크기 상한 | 상한이 없거나 코드에 드러나지 않음 |
|
||||
| 14 | 성능 성숙도 | 8절 | 데이터 수에 비례하는 SQL 수(N+1), 순차 스캔 |
|
||||
| 15 | 보안 성숙도 | 인증·인가 체인, `docs/security/public-paths-snapshot.txt`, `docs/registries/secrets-classification.yaml`, 로그 | 기본으로 꺼진 검증, 권한 검사 없는 경로, 로그로 새는 입력값 |
|
||||
| 16 | 의존성 성숙도 | `src/gradle/libs.versions.toml`, lockfile, `src/config/testing/container-images.properties` | 사라진 외부 이미지, 운영 jar의 테스트용 드라이버 |
|
||||
| 17 | API·계약 성숙도 | `docs/web/http-contract.md`, `docs/registries/error-codes.yaml`, `docs/architecture/*-api-surface.txt`, 짝 프론트 계약 | 코드·문서·짝 계약이 서로 다름 |
|
||||
| 18 | 배포 성숙도 | `src/Dockerfile`, `src/Dockerfile.sample`, compose, `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서 |
|
||||
| 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 |
|
||||
| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함 |
|
||||
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 |
|
||||
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 |
|
||||
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 |
|
||||
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
|
||||
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
|
||||
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
|
||||
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, sample 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
|
||||
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
|
||||
|
||||
**따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다.
|
||||
|
||||
| 시나리오 | 따라갈 경로 |
|
||||
| --- | --- |
|
||||
| 정상 쓰기 요청 | sample `POST /api/worklogs`, 생성 명령으로 만든 기능 |
|
||||
| 중복·동시 요청 | 같은 제목 동시 `POST /api/posters`, 멱등 키(`docs/manual/05-idempotency.md`) |
|
||||
| 외부 응답 지연·유실 | httpclient 시간 예산·breaker, 알림 발송 attempt |
|
||||
| DB 오류·경쟁 | `PersistenceExceptionTranslator`, `@Version`, 트랜잭션 마감 |
|
||||
| 메시지 중복·역순 | outbox relay, inbox 재전달, aggregate 순서 번호 |
|
||||
| 신·구 버전 공존 | 마이그레이션 잠금, 배포 중 섞인 인스턴스 |
|
||||
| 여러 서버의 작업 실행 | 알림 정산 job claim, gRPC ledger claim |
|
||||
| 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, sample 소유자 검사 |
|
||||
| 큰 입력·목록 조회 | `GET /api/worklogs?size=100`, GraphQL 복잡도, JSON 아닌 본문 |
|
||||
| 종료·재시작 | relay·platform 종료 순서, 종료 시간 예산 |
|
||||
| 선택 어댑터 제거 | `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄 제거 |
|
||||
|
||||
## 7. 테스트가 증명해야 하는 것
|
||||
|
||||
정본: 테스트 작성 규칙은 `AGENTS.md` 「테스트 전략」, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다.
|
||||
|
||||
| 점검 | 결함 모양 |
|
||||
| --- | --- |
|
||||
| 이름이 말한 성질을 단언하나 | 이름은 "X를 남기지 않는다"인데 준비가 다른 예외를 넣는다 |
|
||||
| 부재 단언이 null과 "키 없음"을 구분하나 | `doesNotExist`가 null 필드도 통과 |
|
||||
| 지키려는 코드를 지우면 실패하나(변이) | 검사를 지워도 전부 통과 |
|
||||
| 시간 제한 대기의 반환값을 단언하나 | `CountDownLatch.await(timeout)` 결과를 버려 시간 초과에도 다음 단계로 감 |
|
||||
| skip이 0이거나 설계 이유가 있나 | 계약 케이스가 조용히 skip |
|
||||
| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성을 못 봄 |
|
||||
| `// when`이 하나인가 | 두 동작을 한 테스트가 봄 |
|
||||
| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 실패한 채 방치 |
|
||||
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 |
|
||||
|
||||
fake와 공유 계약: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 실제 adapter가 같은 추상 계약(`XxxContract`)을 상속한다. 계약 밖 fake, 소비자 없는 fake, 계약과 겹친 adapter 손 사본 테스트는 만들지 않는다. fake 동작을 바꾸면 계약 케이스를 같이 바꾼다. 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md`의 현황표를 고친다.
|
||||
|
||||
lane: 새 lane은 반드시 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run`). 반드시 돌아야 하는 테스트는 `requires(클래스)` + `rejectSkipped`로 이름을 박는다. lane 정책 값은 Test 입력으로 선언한다. 저장소 파일을 읽는 테스트는 태그를 단다(문서와 대조하면 `document-contract`, 빌드 스크립트·workflow·compose를 읽으면 `repository-contract`).
|
||||
|
||||
RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신에 따라 통과하지 않는다. 실 vendor가 필요한 결함은 실 vendor에서 본다(단위 테스트로 대신했으면 그렇게 적는다). 기록은 테스트 이름과 실패 수로 쓴다.
|
||||
|
||||
## 8. 성능 측정
|
||||
|
||||
이 템플릿에는 지연·처리량 목표가 없다. 그래서 요청당 비용(SQL 수, 지연, 처리량, CPU)과 그 비용이 데이터 수에 비례해 늘어나는지로 판정한다.
|
||||
|
||||
| 지표 | 재는 법 | 결함 신호 |
|
||||
| --- | --- | --- |
|
||||
| 아티팩트 | bootJar 크기, `BOOT-INF/lib` 목록 | 운영 jar에 테스트용·중복 라이브러리 |
|
||||
| 기동 | `Started … in`, 기동 3초 뒤 RSS·heap, 빈 수, 스레드 수 | 빈 수에 비해 긴 공백 한 곳 |
|
||||
| 요청당 SQL 수 | PostgreSQL `log_statement='all'`로 요청 하나 전후의 문장 수 | 페이지 크기에 비례(N+1) |
|
||||
| 지연·처리량 | 닫힌 루프 부하, p50·p95·p99·rps | 목록 처리량이 SQL 수 비율만큼 떨어짐 |
|
||||
| 요청당 CPU | JFR `settings=profile`, 상위 프레임 | 한 라이브러리가 CPU의 큰 몫 |
|
||||
| 데이터 증가 | 같은 요청을 행 수를 늘려 반복 | 행 수에 비례해 느려짐 |
|
||||
| 게이트 시간 | 게이트별 rc·초, 테스트 결과 XML 합계 | 바뀐 것이 없는데 매번 다시 도는 lane |
|
||||
|
||||
측정 조건(전후가 같아야 비교할 수 있다):
|
||||
|
||||
- 머신: 다른 빌드가 돌지 않는다. 측정 직전 1분 load average를 회차마다 적는다. 15를 넘은 회차는 비교에 쓰지 않는다.
|
||||
- JVM: 옵션을 고정하고 적는다(예: `-Xmx1g -XX:+ExitOnOutOfMemoryError`).
|
||||
- DB: 자원을 제한한 컨테이너(예: `--cpus 4 --memory 1g`), 튜닝 없음.
|
||||
- 데이터: 행 수를 정해 적는다. 측정 중 늘어나는 테이블은 행 수를 함께 적는다.
|
||||
- 부하: 닫힌 루프 N 스레드, 앞 20%는 워밍업으로 버린다. 생성기가 같은 호스트면 한계로 적는다.
|
||||
- 반복: 3회, 중앙값. 튀는 회차는 이유와 함께 빼고 적는다.
|
||||
- 설정만 바꾼 실험으로 원인을 먼저 확인한다(코드는 그대로, 시스템 프로퍼티 하나만).
|
||||
- 측정은 E3다. "운영에서 N배 빨라진다"고 쓰지 않는다. 꼬리 지연의 원인을 확인하지 않았으면 미검증으로 적는다.
|
||||
|
||||
최적화를 고르는 순서는 비용이 작은 것부터다: 설정 → DB(인덱스, 유일 제약, 쿼리 모양) → 매핑·쿼리 코드(N+1, 불필요한 컬렉션 재작성) → 구조(캐시, 비동기, 새 인프라). 캐시를 넣으면 무효화와 경합을 함께 검증한다. 고친 비용은 SQL 수처럼 머신과 무관한 숫자로 먼저 고정한다.
|
||||
|
||||
## 9. 구조 기준과 leaf 변경 체크리스트
|
||||
|
||||
- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다.
|
||||
- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다.
|
||||
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
|
||||
- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
|
||||
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
|
||||
- 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다).
|
||||
- 문서 위치 규칙은 `docs/README.md`가 정본이다.
|
||||
|
||||
leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼다:
|
||||
|
||||
- [ ] `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면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
|
||||
- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
|
||||
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
|
||||
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
|
||||
- [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행
|
||||
|
||||
검증은 [gates.md](gates.md) 2절의 "leaf 경계·의존·registry" 행이다.
|
||||
|
||||
## 10. 리뷰 문서 양식
|
||||
|
||||
**위치**: 전체 리뷰는 `docs/reviews/<YYYY-MM-DD>-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/`. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다.
|
||||
|
||||
**전체 리뷰 README의 절** (가이드 36.5절 양식에 처리 현황·결정 기록을 더한 것):
|
||||
|
||||
1. 사용 결정 — 용도별 사용 가능·조건부·보류와 막는 항목
|
||||
2. 차단 항목(High·P1) — 맡긴 쪽의 재확인 방법을 칸으로
|
||||
3. 확인된 강점
|
||||
4. 반복되는 원인 — [defect-patterns.md](defect-patterns.md) 번호를 붙인다
|
||||
5. 결정이 필요한 것 — 선택지, 권고, 승인자
|
||||
6. 미검증 — 무엇, 왜, 확인하려면
|
||||
7. 개선 순서 — 순서, 대상, 이유, 완료 기준
|
||||
8. 재검토 조건
|
||||
9. 리뷰 범위 — 기준 커밋, 게이트 결과 표, 영역 표
|
||||
10. 28개 관점 판정
|
||||
11. 발견 색인 — ID, 심각도, 우선순위, 한 줄 내용. 모든 ID를 이름으로 적는다
|
||||
12. 이후 라운드 — 처리 표, 합칠 때 생긴 충돌과 처리, 합친 뒤 게이트, 결정, 남은 것
|
||||
|
||||
**영역 문서**: 범위 → 지난 발견 재확인 → 새 발견 → 시나리오 추적 → 설계 선택 검토(가이드 41절) → 리팩터링 후보 → 28개 관점 판정표.
|
||||
|
||||
**확인 리뷰 문서**:
|
||||
|
||||
| 절 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 범위 | pathspec, `git diff --stat` 결과, 함께 읽은 주변 코드, 수정 보고의 「새로 가정하는 것」 |
|
||||
| 불러온 스킬과 적용한 기준 | 스킬, 그 스킬의 기준, 그 기준으로 본 것 |
|
||||
| 실행한 명령과 결과 | 명령, rc, 직전 1분 부하 |
|
||||
| 못 본 것 | 무엇과 이유 |
|
||||
| 항목 재확인 | 고쳤다고 한 항목마다 닫힘 / 부분 / 안 닫힘 |
|
||||
| 결함 | `### <ID> · <심각도> · <한 줄 제목>` 아래 발견 필드 |
|
||||
| Declined to judge | 판단하지 않은 것, 위치, 이유 |
|
||||
| 결론 | Critical·Important·회귀 수, 결함 수와 "이번 수정 / 이전부터" 구분 |
|
||||
|
||||
**발견 하나의 필드**
|
||||
|
||||
- 전체 리뷰: 가이드 36.3절 표 필드 전체(성격, 관련 관점, 근거, 발생 조건, 영향, 심각도, 확실성, 결정의 근거, 이해 비용, 최소 개선 방향, 대안 비교, 단순화의 보존 조건, 비용, 재검토 조건, 완료 기준, 검증 방법). 선택 비교가 필요 없는 단순 결함은 설계 선택 필드를 `적용 제외 — <이유 한 문장>`으로 둔다.
|
||||
- 확인 리뷰: 위치(`file:line`, 문서·설정·코드를 나눠서), 무엇이 틀렸나(한 문장에 사실 하나), 발생 조건·영향, 테스트가 못 본 이유, 고치는 법(권장안·대안·RED 테스트 모양), 이번 수정 / 이전부터, 증거(E 수준과 명령 번호).
|
||||
|
||||
**ID**
|
||||
|
||||
- 라운드 안에서는 `NN-MM`(영역-순번)이다. 확인 리뷰는 라운드 접두어를 붙여 `RR<n>-NN-MM`으로 쓴다(첫 재리뷰만 `<n>` 없이).
|
||||
- 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `MMDD/<ID>`(가이드 36.3절).
|
||||
- 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다.
|
||||
- ID는 리뷰 문서·brief·커밋에서 쓴다. 매뉴얼(`docs/work/`) 본문에는 쓰지 않는다.
|
||||
|
||||
## 11. 판단을 적는 법
|
||||
|
||||
- 판단 발견(설계·구조·비용)은 반증할 수 있는 가정과 반론을 함께 적는다. "이 판단이 틀렸다면 어디서 드러나나"를 쓴다.
|
||||
- 결정적 발견(컴파일 오류, 의존 위반, 비밀 노출, 실패한 테스트)은 규칙 → 증거 → 고치는 법 세 줄로 쓴다. 억지 반론을 만들지 않는다.
|
||||
- 대안이 3~5개 있으면 그만큼 비교한다. 실제로 더 적으면 적게 쓴다. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다.
|
||||
- 인용 확인은 리뷰 수준에 따른다: `review-lite`는 확인하지 않는다, `review-standard`는 차단 발견의 인용을 확인한다, `audit-deep`·`regulated`는 결론에 쓰인 인용을 모두 확인한다.
|
||||
- 리뷰 결과를 문서 파일로 남기는 경우: 위험이 높다, 차단 발견이 3건 이상이다, 아키텍처 결정이 있다, 요청자가 원한다, `regulated` 수준이다. 그 밖에는 짧은 결과 보고로 충분하다.
|
||||
|
||||
## 12. 리뷰어가 하지 않는 것
|
||||
|
||||
- 코드를 고치지 않는다. 실험은 별도 worktree에서 하고 지운다.
|
||||
- 이전 실행 결과를 현재 증거로 쓰지 않는다(4절).
|
||||
- 같은 결함을 여러 번 세지 않는다(3절).
|
||||
- 정한 결정을 결함으로 다시 올리지 않는다. 결정의 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다([decisions.md](decisions.md) 1절).
|
||||
- 범위 밖 결함을 버리지 않는다. 「Declined to judge」에 위치와 함께 적어 맡긴 쪽에 넘긴다.
|
||||
Reference in New Issue
Block a user