문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
13 KiB
07. 검증과 게이트
핵심
작은 것부터 돌리고, 바꾼 것에 맞는 게이트를 돈다. 작업 중에는 바꾼 leaf의 check, 묶음이 끝나면 경계에 맞는 저장소
게이트, 라운드가 끝나면 합친 트리에서 전체 게이트다.
작업 중 <leaf>:check (+ 그 leaf의 관련 strict lane)
묶음 끝 + architectureCheck · 표면별 검사(env 키·공개 경로·의존성 잠금) · 관련 lane
라운드 끝 합친 트리에서 전체 묶음(3절) ── workflow가 PR·main에서 돌리는 것과 같은 명령
게이트 구성의 정본은 src/build.gradle 라이프사이클과 .github/workflows/다. 이 장은 언제 무엇을 어디서 돌리는지 정한다.
무거운 실행 위치는 6절 「소유자 환경」이다.
1. 게이트 목록
명령은 모두 src/에서 실행한다.
| 게이트 | 무엇 | 단계 | 정의 |
|---|---|---|---|
./gradlew <gradle-path>:check |
그 leaf만: 컴파일·테스트·Spotless·Checkstyle·Error Prone·API surface | 작업 중 | leaf 컨벤션 플러그인, CLAUDE.md 「Testing」 |
architectureCheck |
의존 방향, domain-core·shared-contract·application-* 순수성, ArchUnit | PR(ci 안) |
src/build.gradle architectureCheck |
qualityCheck |
SpotBugs·FindSecBugs(운영 코드) | PR(ci 안) |
src/build.gradle qualityCheck |
ci |
모든 production leaf check + architectureCheck + qualityCheck |
PR | src/build.gradle ci; workflow는 ./gradlew :ci :verifyDependencyLocks --warning-mode=fail(.github/workflows/ci-quality-gates.yml:51) |
verifyStrictLaneStages --dry-run |
모든 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | ci-quality-gates.yml:57, :87(-p optional-platforms) |
:sample-portfolio:check :sample-portfolio:qualityCheck |
샘플(production leaf가 아니라 ci 밖) |
PR | ci-quality-gates.yml:73 |
-p optional-platforms ci |
gRPC 플랫폼 빌드 | PR | ci-quality-gates.yml:82 |
mainCheck |
env 계약, 전체 기동, 샘플 실서버 계약·전체 기동, 공개 경로 스냅숏, 전송·메시징 qualification, 생성 명령 왕복, 테스트 코드 정적 분석, leaf mainCheck(document-contract lane) |
main | src/build.gradle mainCheck; workflow는 --continue --warning-mode=fail(.github/workflows/integration-main.yml:85) |
integrationCheck |
모든 INTEGRATION lane(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | src/build.gradle integrationCheck; integration-main.yml:176 |
performanceCheck |
모든 PERFORMANCE lane | main·nightly | src/build.gradle performanceCheck; integration-main.yml:205(단언 속성 true, :198), optional :211 |
releaseCheck -PgitRevision=<sha> |
릴리스 provenance + 공개 경로 | 태그 | src/build.gradle releaseCheck(sha 없이 돌리면 설계대로 실패 — 1101 README 13.1절) |
bash scripts/verify-compose-profile-contracts.sh |
compose lane이 선언대로 렌더링되는가 | PR | ci-quality-gates.yml(같은 job) |
:app-bootstrap:verifyEnvKeys |
env 키 레지스트리 | mainCheck 안(configContractCheck) |
결정 4 |
verifyPublicPathSnapshot |
기본 공개 경로가 docs/security/public-paths-snapshot.txt와 같은가 |
mainCheck·releaseCheck 안 |
src/build.gradle |
verifyDependencyLocks |
lockfile | PR | ci-quality-gates.yml:51 |
./gradlew <gradle-path>:check의 <gradle-path>는 src/config/architecture/modules.json에서 읽는다. leaf별 명령 목록을 문서에
적지 않는다(AGENTS.md 「테스트 전략」 권장 절차 뒤 문단).
2. 바꾼 것에 맞춰 고르기
| 바꾼 것 | 추가로 돌릴 것 | 근거 |
|---|---|---|
| 한 leaf 안의 코드 | 그 leaf check + 그 코드를 지키는 strict lane(실 DB 등) |
docs/manual/11-checklist.md 「검사」 |
| leaf 경계·의존·registry | architectureCheck, verifyDependencyLocks |
같음 |
| env 키 | :app-bootstrap:verifyEnvKeys |
같음 |
| 공개 경로·보안 체인 | verifyPublicPathSnapshot |
같음 |
| 의존성 | verifyDependencyLocks |
같음 |
문서(docs/**, CLAUDE.md, README) |
그 문서를 읽는 document-contract lane(예: :app-bootstrap:documentContractTest) + 링크 검사(아래) |
src/app-bootstrap/build.gradle documentContractTest 위 주석 |
| build-logic·workflow | -p build-logic check javadoc, 두 빌드의 verifyStrictLaneStages --dry-run |
1103 README 17.2절 |
| 패키지 규칙·생성 명령 템플릿 | verifyFeatureScaffold(mainCheck 안) |
src/build.gradle verifyFeatureScaffold |
| 마이그레이션 | persistence-jpa check, 잠금 대기 lane(postgresqlMigrationLockWaitIntegrationTest), 마이그레이션 lane |
1103 README 17.2절 |
| 테스트 코드 | 그 leaf testQualityCheck |
1103 README 14절 |
| compose·Dockerfile | compose 검사 스크립트, 실제 docker build·기동 |
1101 README 16절 r3-f·r3-k |
- 문서 링크는 workflow
link-check.yml(lychee)이 PR에서 검사한다. 대상은README.md,src/**/README.md,src/**/CLAUDE.md,docs/**/*.md,.github/**/*.md다. 저장소 밖 경로와file:line은 링크로 쓰지 않는다(README 결정 M-5). - 전체
test·check·ci는 총괄의 지시가 있을 때 돌린다(CLAUDE.md「Testing」 마지막 줄).
3. 라운드 끝 — 합친 트리의 전체 묶음
여러 묶음을 합친 트리는 workflow가 PR·main에서 돌리는 것과 같은 명령으로 검증한다. 1103 README 17.2절의 묶음이 기준이다.
cd src
./gradlew :ci :verifyDependencyLocks --warning-mode=fail
./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck
./gradlew :verifyStrictLaneStages --dry-run
./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run
./gradlew :mainCheck --warning-mode=fail
./gradlew :integrationCheck
./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true
./gradlew :performanceCheck -Pperformance.assertions.enabled=true
./gradlew :releaseCheck -PgitRevision=<HEAD sha>
cd .. && bash scripts/verify-compose-profile-contracts.sh
- 한 번에 하나씩 돌린다. 같은 머신에서 두 빌드를 겹치지 않는다(6절).
- 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다(
1103README 16.1·16.2절). - 합친 뒤에만 드러나는 결함이 있다. 두 묶음의 수정이 처음 한 트리에서 만나면 새 결함이 생긴다(
1101README 16.1절BC_IMPOSSIBLE_INSTANCEOF). 그래서 묶음별 검증으로 이 단계를 대신하지 않는다. -Pperformance.assertions.enabled=true는 workflow와 같은 단언으로 돌리기 위한 것이다(06장 5절).
4. 결과 기록
게이트 결과는 표로 적는다(1103 README 17.2절 형식).
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|---|---|---|---|
:ci :verifyDependencyLocks --warning-mode=fail |
rc=0 | 5분 42초 | 2.65 |
함께 적을 것:
- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다(
1101README 13.1절 "작업 트리가 미커밋이라 실제 릴리스 증거로는 쓸 수 없다"). - 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다.
- 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다. 캐시 없는 첫 실행 시간을 재지 않았으면 그렇게 적는다
(
1101README 16.2절). - 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름(
1103README 10.2절:redisTopologyTest3개,objectStorageAwsQualificationTest). - 고친 테스트의 lane을 따로 돌렸는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로(
1103README 14.1절). - 묶음 보고서가 적은 태스크가 실제로 있는지 확인한다. 없는 태스크 이름이 보고에 들어간 적이 있다(
1103README 17.2절).
5. 게이트를 믿을 조건 — 거짓 통과 막기
게이트가 초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다. 지난 라운드의 거짓 통과(부록 A7):
| 거짓 통과 모양 | 지난 예 | 지금의 장치 |
|---|---|---|
| 어떤 workflow도 돌리지 않는 lane | 1101/08-01(14개), integration-main.yml이 integrationCheck --dry-run만 함 |
verifyStrictLaneStages --dry-run(PR) |
| optional 빌드를 안 봄 | 1103/RR-06-03(grpcPerformanceTest 미실행) |
optional 빌드도 같은 검사 |
실패를 막지 못하는 명령을 실행으로 셈(|| true, pipefail 없는 파이프, if 조건 …) |
1103 README 15절 r8-b 남음, 16절 r9-d |
AGENTS.md 「Gradle 정책 권위」의 세 이유 |
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | 1103/RR-06-02 |
정책 값을 Test 입력으로 |
| 게이트 밖에서 실패한 채 방치된 검사 | 1103 README 14절(테스트 SpotBugs 53개) |
testQualityCheck(mainCheck) |
| 실서버 계약이 어느 게이트에도 없음 | 1103/RR-04-05(Redis 멱등성 계약) |
lane 연결 |
| 시간 단언을 끈 채 performance lane 실행 | 06장 5절 | -Pperformance.assertions.enabled=true |
게이트 장치 자체를 바꿨으면 망가뜨린 입력으로 실패하는 것을 본다. 예: compose 정적 검사가 일부러 망가뜨린 6가지를 모두
잡았다(1101 README 16절 r3-k). workflow 판독기는 바꾸기 전후로 실제 workflow의 판정이 같은지 비교했다(1103 README 17절
r10-04 "세는 명령 48개는 수정 전후 같다").
외부 이미지가 사라지면 lane이 다른 이유와 섞여 실패한다. 테스트 lane의 이미지는 한 곳(src/config/testing/container-images.properties,
MinIO qualification 이미지만 objectstorage leaf 소유)에 digest로 고정하고, MinIO pull 실패는 따로 구분된 메시지
(PinnedImageUnavailableException)로 실패한다(1101/05-09, 1101/08-04). main 단계는 --continue로 돌아 한 lane의 실패가
다른 lane 결과를 가리지 않는다(.github/workflows/integration-main.yml:85).
6. 소유자 환경 — 무거운 실행 위치
이 절은 이 repo 소유자의 작업 환경에 묶인 규칙이다. 파생 프로젝트는 이 절만 자기 환경으로 바꾼다(README 결정 M-6).
규칙: Gradle·Docker·테스트·게이트·성능 측정은 노트북에서 돌리지 않는다. 원격 desktop에서 브랜치를 받아 돌린다
(1103 README 17.1절, 2026-11-05 소유자 지시). 노트북에서는 git·grep·파일 읽기·문서 편집만 한다.
왜: 수정 묶음 여럿이 노트북에서 Gradle을 동시에 돌려 노트북 부하가 크게 올랐다. desktop은 12코어·31GB이고 Java 21·Docker가
있다(1103 README 17.2절).
절차
# 1) 노트북: 검증할 변경을 내 브랜치에 커밋하고 push
git push origin <내 브랜치>
# 2) desktop에 접속해 같은 checkout에서 브랜치를 받는다
ssh desktop
cd ~/workspace/clean-architecture-backend-template
git status # 다른 세션의 변경·현재 브랜치 확인
uptime # 다른 빌드가 돌고 있지 않은지 부하 확인
git fetch
git switch <내 브랜치> # 처음 받는 브랜치면 origin/<내 브랜치>를 추적하는 로컬 브랜치가 생긴다
# 3) 돌린다
cd src
./gradlew <게이트> --console=plain
# 4) 끝나면 원래 브랜치로 되돌린다
git switch <원래 브랜치>
- checkout을 여러 세션이 함께 쓴다. 시작 전에 현재 브랜치를 적어 두고, 끝나면 그 브랜치로 되돌린다. 남의 stash는 건드리지
않는다(
git stash·git stash pop을 쓰지 않는다). - 빌드를 겹치지 않는다. 이전 라운드는 같은 머신의 빌드를 공유 잠금 파일(
flock <heavy.lock>)로 줄 세웠다 (1101/09-performance-measurement.md「측정 명령」,1103/round6/01-core-inbound.md「실행한 명령과 결과」). desktop에서도 한 번에 하나만 돌리고, 결과 표에 직전 부하를 적는다. - 로그를 남긴다. 게이트별 로그를 desktop에 파일로 남기고, 그 위치를 보고에 적는다. 결과 표는 리뷰 README에 옮긴다.
- 임시 worktree는 지운다. RED 확인용 worktree를 desktop에 만들었으면 끝나고 지운다(
1103README 17.2절).
지금 이해하면 되는 것
- 작업 중 leaf
check→ 묶음 끝 경계별 게이트 → 라운드 끝 합친 트리 전체 묶음. - 결과는 커밋 sha·rc·시간·부하로 적고, 못 돌린 것·캐시 통과·빠진 lane을 숨기지 않는다.
- 무거운 실행은 desktop에서, 한 번에 하나, 끝나면 원래 브랜치로.