문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다
고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
(operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
(고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.
위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다
검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
트리 3d0e5900을 만들고 flock 아래
:app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
건너뜀 0, 13초, 직전 1분 부하 3.13
(desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
25 KiB
리뷰 기준
리뷰와 수정에서 무엇을 결함으로 보고, 어떻게 판정하고, 어떤 형식으로 적는지 정한다. improve.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 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에 의존하지 않는다. 그래서 남는 복사본은 이유를 familyCLAUDE.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 2절의 "leaf 경계·의존·registry" 행이다.
10. 리뷰 문서 양식
위치: 전체 리뷰는 docs/reviews/<YYYY-MM-DD>-<종류>/README.md + 영역 문서 NN-<영역>.md. 확인 리뷰는 그 폴더 아래 roundN/NN-<영역>.md, 영역마다 하나다. 한 리뷰어가 모든 영역을 봐도 영역마다 나눈다. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다.
전체 리뷰 README의 절 (가이드 36.5절 양식에 처리 현황·결정 기록을 더한 것):
- 사용 결정 — 용도별 사용 가능·조건부·보류와 막는 항목
- 차단 항목(High·P1) — 맡긴 쪽의 재확인 방법을 칸으로
- 확인된 강점
- 반복되는 원인 — defect-patterns.md 번호를 붙인다
- 결정이 필요한 것 — 선택지, 권고, 승인자
- 미검증 — 무엇, 왜, 확인하려면
- 개선 순서 — 순서, 대상, 이유, 완료 기준
- 재검토 조건
- 리뷰 범위 — 기준 커밋, 게이트 결과 표, 영역 표
- 28개 관점 판정
- 발견 색인 — ID, 심각도, 우선순위, 한 줄 내용. 모든 ID를 이름으로 적는다
- 이후 라운드 — 처리 표, 합칠 때 생긴 충돌과 처리, 합친 뒤 게이트, 결정, 남은 것
영역 문서: 범위 → 지난 발견 재확인 → 새 발견 → 시나리오 추적 → 설계 선택 검토(가이드 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같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다. - 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다.
- 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면 brief가 정한 쪽이 정본이다. 다른 쪽 발견은 정본의 다음 번호로 새 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 1절).
- 범위 밖 결함을 버리지 않는다. 「Declined to judge」에 위치와 함께 적어 맡긴 쪽에 넘긴다.