# 리뷰 기준 리뷰와 수정에서 무엇을 결함으로 보고, 어떻게 판정하고, 어떤 형식으로 적는지 정한다. [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 | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자·개발자에게 틀린 조치를 시키는 문서(예: README·`AGENTS.md`가 지운 타입을 지금 것으로 설명, 지운 설정 키를 켜라고 함) | | Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 | 확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다. **심각도가 정하지 않는 것** - 고칠지 말지. 이 repo는 모든 발견을 고치거나 결정으로 닫는다([improve.md](../improve.md) 4.5절). 심각도는 고치는 순서와, 맡긴 쪽이 코드에서 다시 확인할 범위(High·Important 이상)만 정한다. - 건수. 한 결함이 여러 관점에 걸치면 항목 하나에 관점 번호를 모두 붙인다. 두 영역이 같은 결함을 적으면 색인에서 합친다. ## 4. 증거 수준 E0~E4 (가이드 35.5절) | 수준 | 이 repo의 증거 | 주장할 수 없는 것 | | --- | --- | --- | | E0 설명·주장 | README, `AGENTS.md`·`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/bootstrap/app/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 `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(`src/`는 계층 폴더만, 저장소 루트는 Gradle 루트 표준 `build-logic`·`gradle`·`config`와 빌드 파일, 저장소 운영 `docs`·`scripts`·`.gitea`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 | | 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | | 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수, 루트 README만 읽고 구조·매뉴얼·첫 실행을 5분 안에 찾는가(cold-read 결과), 이벤트별 workflow job 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음, 같은 Gradle 태스크를 두 단계 이상이 돎(의도한 행렬 제외) | | 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | | 6 | 실패 성숙도 | 예외 분류, `retryable`, 결과 불명 | 결과 불명을 확실함으로, 재시도 가능을 확정 실패로 기록 | | 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 | | 8 | 디버깅 가능성 | `ServerFailureLog`, correlation id, 오류 코드 | 서버 실패를 남기지 않음, 원인이 다른 실패를 같은 코드로 | | 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석, 살아 있는 문서의 표본 주장(문서 종류마다 1~2개 파일, 파일마다 주장 2~5개를 코드와 대조하고 틀린 비율을 README에 적는다), 기록 문서의 상태 칸 | 갈라진 복사본, 현재 동작과 다른 주석·문서, 코드·테스트·workflow·스크립트 어디서도 읽지 않는 비소스 파일(compose, 셸 스크립트, 설정, README. 파일마다 `git grep -l -F <경로> -- ':!docs/history' ':!docs/reviews'`가 0건. 경로를 변수로 조립하는 workflow `matrix`는 따로 본다) | | 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 | 의존성 성숙도 | `gradle/libs.versions.toml`, lockfile, `gradle/container-images.properties` | 사라진 외부 이미지, 운영 jar의 테스트용 드라이버 | | 17 | API·계약 성숙도 | `docs/web/http-contract.md`, `docs/registries/error-codes.yaml`, `docs/architecture/*-api-surface.txt`, 짝 프론트 계약 | 코드·문서·짝 계약이 서로 다름 | | 18 | 배포 성숙도 | 저장소 루트 `compose.yaml`, `Dockerfile`, 테스트 lane 계약(`compose-profile-contracts.json`), `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서, README의 개발 환경 기동 명령이 실제로 뜨지 않음, 개발 환경을 띄우는 길이 둘 이상, 개발 환경 compose와 테스트 fixture가 한 파일에 섞임, Kubernetes 매니페스트·프록시 설정·IaC가 이 repo에 있음(배포 경계 `docs/ci-cd/boundary.md`) | | 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 | | 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간, 빈 clone에서 README 명령만으로 개발 환경을 띄우고 내리기(compose 파일 하나), 문서 지도가 모든 문서 폴더를 덮는가(`check-docs.py` `map`), 템플릿 CI 변경이 파생 서비스 동기화에서 건드리는 파일 수 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함, 개발 환경에 compose 파일이 둘 이상 필요함 | | 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계, 편집 훅(`scripts/hooks/`), CI 실행 기록(URL) | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사, CI 최근 실행 기록이 없음(확인 못 하면 「미검증」이 아니라 결함 후보), 검사 장치가 지키는 대상보다 큼, 같은 장치에서 두 라운드 연속 결함, 개수·문서·배선 검사가 PR 단계에 있음, 실행 환경(Gitea)에서 돌지 않는 action·권한 | | 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 | | 23 | 일관성 | 같은 역할의 이름·모양·규칙, 문서의 언어·문체·상태 어휘(`check-docs.py` `language`·`style`·`head`) | 같은 개념이 여러 벌, 한 문서 안에서 문체가 섞임 | | 24 | 네이밍·의미 | `src/application/core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | | 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 | | 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README(자기 것이나 family 것) | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | | 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, 샘플·예시 모듈 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎, 매뉴얼·생성 명령이 같은 역할을 하는데 남은 샘플(그 샘플이 어떤 게이트의 유일한 검증 대상이면 그 역할과 옮길 곳이 적혀 있는지) | | 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 | **따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다. | 시나리오 | 따라갈 경로 | | --- | --- | | 정상 쓰기 요청 | 생성 명령으로 만든 기능, durable operation `POST /operations` | | 중복·동시 요청 | 같은 호출자가 같은 작업을 동시에 `POST /operations`(payload fingerprint로 하나만 받는다), 멱등 키(`docs/manual/05-idempotency.md`) | | 외부 응답 지연·유실 | httpclient 시간 예산·breaker, 알림 발송 attempt | | DB 오류·경쟁 | `PersistenceExceptionTranslator`, `@Version`, 트랜잭션 마감 | | 메시지 중복·역순 | outbox relay, inbox 재전달, aggregate 순서 번호 | | 신·구 버전 공존 | 마이그레이션 잠금, 배포 중 섞인 인스턴스 | | 여러 서버의 작업 실행 | 알림 정산 job claim, 멱등성 실행 lease | | 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, durable operation 소유자·tenant 검사 | | 큰 입력·목록 조회 | 파일 서버 업로드 크기 한도, GraphQL 복잡도, JSON 아닌 본문 | | 종료·재시작 | relay·platform 종료 순서, 종료 시간 예산 | | 선택 어댑터 제거 | `src/bootstrap/app/build.gradle`의 `runtimeOnly` 한 줄 제거 | ## 7. 테스트가 증명해야 하는 것 정본: 테스트 작성 규칙은 `.claude/rules/java-tests.md`, 계층별 검증 기준은 그 계층의 `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/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. - 다른 경계(다른 leaf, 다른 빌드, 다른 repo가 될 수 있는 폴더)의 파일을 경로(`../../../`)로 읽는 빌드 스크립트·테스트는 결함 후보다. 그 경계가 옮겨 가면 조용히 깨진다. gRPC·메시징 라이브러리를 옮길 때 이런 결합이 다섯 곳 나왔다(design-docs `repo-structure/05-library-repos.md` 4.6절). 다른 repo의 파일이 필요하면 그 repo가 배포한 artifact에서 읽는다(예: persistence-jpa의 migration 시험이 메시징 라이브러리 jar의 `db/migration/messaging`을 푼다). - 별도 repo 라이브러리(`dev.cakit.*`)는 템플릿 타입에 의존하지 않는다. 그래서 남는 복사본은 이유를 그 라이브러리 repo의 모듈 지침에 적는다. 템플릿 leaf가 라이브러리 모듈을 쓰면 registry 행의 `allowed_libraries`에 좌표를 적는다. 적지 않은 소유 group 모듈을 선언하거나 컴파일에서 보면 방향 검사가 실패한다. - 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를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼다: - [ ] `gradle/modules.json`: ID, `source_path`, `gradle_path`, `allowed_dependencies`, 라이브러리를 쓰면 `allowed_libraries` - [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/bootstrap/app/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` - [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키 - [ ] 템플릿 패키지를 더하거나 지우면 `src/application/core/README.md` 「패키지 소유 (Package ownership)」 표와 `TemplatePackageOwnership` - [ ] ArchUnit 규칙과 그 위반·허용 fixture - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) - [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행 - [ ] 문서를 바꿨으면 `python3 scripts/check-docs.py`와 `python3 scripts/check-work-docs.py` 검증은 [gates.md](gates.md) 2절의 "leaf 경계·의존·registry" 행이다. ## 10. 리뷰 문서 양식 **위치**: 전체 리뷰는 `docs/reviews/-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/NN-<영역>.md`, 영역마다 하나다. 한 리뷰어가 모든 영역을 봐도 영역마다 나눈다. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 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분 부하. 탐침이면 무엇을 단언했나(결함 동작 / 약속, [gates.md](gates.md) 2절 「탐침」) | | 못 본 것 | 무엇과 이유 | | 항목 재확인 | 고쳤다고 한 항목마다 닫힘 / 부분 / 안 닫힘 | | 넘어온 항목 판정 | brief가 맡겼을 때만: 지난 라운드 Declined와 README 남은 항목마다 판정(결함 / 결함 아님 / 결정 필요)과 근거 | | 결함 | `### · <심각도> · <한 줄 제목>` 아래 발견 필드 | | Declined to judge | 판단하지 않은 것, 위치, 이유 | | 결론 | Critical·Important·회귀 수, 결함 수와 "이번 수정 / 이전부터" 구분 | **확인 리뷰 라운드의 README 절**: 리뷰 폴더 README에 라운드마다 절 하나를 두고, 하위 절을 이 순서로 둔다. 앞의 다섯은 리뷰가 끝나면, 뒤의 셋은 수정과 합치기가 끝나면 쓴다. 누가 쓰는지는 [improve.md](../improve.md) 4.1절 7단계다. 1. 결과 — 색인 표(ID, 심각도, 한 줄 내용, 이번 수정 / 이전부터, 증거, 결정이 필요한 질문) 2. 리뷰어 B와의 대응 — 독립 리뷰어 둘일 때만. `B-NN-MM` → 정본 ID, 겹침 비율 3. 실행 — 리뷰어별 명령·결과·로그 위치 4. 결정이 필요한 것 — 항목 · 선택지 · 권하는 안과 이유 · 정할 사람 5. 넘어온 항목 판정 — 지난 라운드 남은 항목마다 판정과 위치 6. 멈춤 기준 상태 — [improve.md](../improve.md) 4.5절 넷 7. 처리 — 처리 표: 발견 · 상태 · 고친 커밋 · RED · 검증 · 정한 기본값. [improve.md](../improve.md) 8절 보고에서 옮긴다. brief가 다른 칸을 정하면 brief를 따른다 8. 합친 트리와 게이트 — 병합 순서, 충돌과 처리, 라운드 끝 게이트 표([gates.md](gates.md) 4절), 못 돌린 것 수정 세션 보고의 「정한 기본값」은 7의 처리 표와 [decisions.md](decisions.md)(기본값 행)로, 「범위 밖에서 본 것」은 README 남은 항목(6의 넷째)으로 옮긴다. 옮긴 남은 항목은 다음 확인 리뷰가 brief를 받아 5에서 판정한다. **발견 하나의 필드** - 전체 리뷰: 가이드 36.3절 표 필드 전체(성격, 관련 관점, 근거, 발생 조건, 영향, 심각도, 확실성, 결정의 근거, 이해 비용, 최소 개선 방향, 대안 비교, 단순화의 보존 조건, 비용, 재검토 조건, 완료 기준, 검증 방법). 선택 비교가 필요 없는 단순 결함은 설계 선택 필드를 `적용 제외 — <이유 한 문장>`으로 둔다. - 확인 리뷰: 위치(`file:line`, 문서·설정·코드를 나눠서), 무엇이 틀렸나(한 문장에 사실 하나), 발생 조건·영향, 테스트가 못 본 이유, 고치는 법(권장안·대안·RED 테스트 모양), 이번 수정 / 이전부터, 증거(E 수준과 명령 번호). **ID** - 라운드 안에서는 `NN-MM`(영역-순번)이다. 확인 리뷰는 라운드 접두어를 붙여 `RR-NN-MM`으로 쓴다(첫 재리뷰만 `` 없이). - 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `MMDD/`(가이드 36.3절). - 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다. - 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다. - 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면(독립 리뷰어 둘, [improve.md](../improve.md) 4.1절) brief가 정한 쪽이 정본이다. 다른 쪽은 임시 번호 `B-NN-MM`을 쓰고, 그 발견은 합칠 때 정본의 다음 번호로 새 ID를 받는다. 두 ID의 대응표를 README의 그 라운드 색인 절에 둔다. 다른 쪽 문서를 그대로 합치지 않는다(같은 ID가 다른 결함을 가리킨다). - 두 리뷰가 같은 결함을 다르게 분류하면(심각도, 이번 수정 / 이전부터) 정본 리뷰어가 근거를 붙여 하나로 정하고, 다른 쪽 분류와 이유를 대응표에 적는다. - 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」에 위치와 함께 적어 맡긴 쪽에 넘긴다.