문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
31 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 | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자·개발자에게 틀린 조치를 시키는 문서(예: README·AGENTS.md가 지운 타입을 지금 것으로 설명, 지운 설정 키를 켜라고 함) |
| Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 |
확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다.
심각도가 정하지 않는 것
- 고칠지 말지. 이 repo는 모든 발견을 고치거나 결정으로 닫는다(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 |
갈라진 복사본, 현재 동작과 다른 주석·문서, 코드·테스트·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-docsrepo-structure/05-library-repos.md4.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 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분 부하. 탐침이면 무엇을 단언했나(결함 동작 / 약속, gates.md 2절 「탐침」) |
| 못 본 것 | 무엇과 이유 |
| 항목 재확인 | 고쳤다고 한 항목마다 닫힘 / 부분 / 안 닫힘 |
| 넘어온 항목 판정 | brief가 맡겼을 때만: 지난 라운드 Declined와 README 남은 항목마다 판정(결함 / 결함 아님 / 결정 필요)과 근거 |
| 결함 | ### <ID> · <심각도> · <한 줄 제목> 아래 발견 필드 |
| Declined to judge | 판단하지 않은 것, 위치, 이유 |
| 결론 | Critical·Important·회귀 수, 결함 수와 "이번 수정 / 이전부터" 구분 |
확인 리뷰 라운드의 README 절: 리뷰 폴더 README에 라운드마다 절 하나를 두고, 하위 절을 이 순서로 둔다. 앞의 다섯은 리뷰가 끝나면, 뒤의 셋은 수정과 합치기가 끝나면 쓴다. 누가 쓰는지는 improve.md 4.1절 7단계다.
- 결과 — 색인 표(ID, 심각도, 한 줄 내용, 이번 수정 / 이전부터, 증거, 결정이 필요한 질문)
- 리뷰어 B와의 대응 — 독립 리뷰어 둘일 때만.
B-NN-MM→ 정본 ID, 겹침 비율 - 실행 — 리뷰어별 명령·결과·로그 위치
- 결정이 필요한 것 — 항목 · 선택지 · 권하는 안과 이유 · 정할 사람
- 넘어온 항목 판정 — 지난 라운드 남은 항목마다 판정과 위치
- 멈춤 기준 상태 — improve.md 4.5절 넷
- 처리 — 처리 표: 발견 · 상태 · 고친 커밋 · RED · 검증 · 정한 기본값. improve.md 8절 보고에서 옮긴다. brief가 다른 칸을 정하면 brief를 따른다
- 합친 트리와 게이트 — 병합 순서, 충돌과 처리, 라운드 끝 게이트 표(gates.md 4절), 못 돌린 것
수정 세션 보고의 「정한 기본값」은 7의 처리 표와 decisions.md(기본값 행)로, 「범위 밖에서 본 것」은 README 남은 항목(6의 넷째)으로 옮긴다. 옮긴 남은 항목은 다음 확인 리뷰가 brief를 받아 5에서 판정한다.
발견 하나의 필드
- 전체 리뷰: 가이드 36.3절 표 필드 전체(성격, 관련 관점, 근거, 발생 조건, 영향, 심각도, 확실성, 결정의 근거, 이해 비용, 최소 개선 방향, 대안 비교, 단순화의 보존 조건, 비용, 재검토 조건, 완료 기준, 검증 방법). 선택 비교가 필요 없는 단순 결함은 설계 선택 필드를
적용 제외 — <이유 한 문장>으로 둔다. - 확인 리뷰: 위치(
file:line, 문서·설정·코드를 나눠서), 무엇이 틀렸나(한 문장에 사실 하나), 발생 조건·영향, 테스트가 못 본 이유, 고치는 법(권장안·대안·RED 테스트 모양), 이번 수정 / 이전부터, 증거(E 수준과 명령 번호).
ID
- 라운드 안에서는
NN-MM(영역-순번)이다. 확인 리뷰는 라운드 접두어를 붙여RR<n>-NN-MM으로 쓴다(첫 재리뷰만<n>없이). - 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다:
MMDD/<ID>(가이드 36.3절). - 영역 번호 자리에
NN같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다. - 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다.
- 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면(독립 리뷰어 둘, 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 1절).
- 범위 밖 결함을 버리지 않는다. 「Declined to judge」에 위치와 함께 적어 맡긴 쪽에 넘긴다.