Files
clean-architecture-backend-…/docs/work/reference/gates.md
T
DongHyeonka 5e204e6a43 refactor(platforms)!: gRPC 플랫폼을 별도 repo grpc-library로 옮기고 지운다
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼
(src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드
(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데,
registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘,
카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다.

소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절,
05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다.
gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13).
코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리
해시가 이 기준 커밋 22df3525와 같다).

지운 것:
- src/platforms/grpc, grpc-advanced, optional-build(343파일)
- registry의 "build": "optional-grpc" 9행
- ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs,
  integration-main.yml optional 성능 단계와 job
  grpc-optional-platform-integration, release.yml job
  grpc-stable-release-gate와 이미지 job의 needs 한 줄
- build-logic ca.grpc-platform-module·ca.optional-architecture-registry,
  MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의
  optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다
- 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14:
  채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄
- 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘,
  gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리
  블록 「현재 정본」만 새 자리를 말하게 했다
- DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험,
  adopter API 표면 검사의 optional-build 제외 경로

남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),
src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원
(ModuleRegistry, 일반 기능).

살아 있는 문서: README, docs 지도, capability-status, work/delegate·
gates·decisions(새 행 「라이브러리 repo」)·defect-patterns·
review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로),
manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석.
새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이
고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56.

위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다
(tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전
커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지
않았다.

검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck,
compose smoke, 빠른 시작). 문서 검사 셋 rc=0.

BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:*
프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin
protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로
받는다(docs/upgrade/2026-11-maturity-review.md 3.8절).
Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
2026-11-08 11:29:47 +09:00

25 KiB

게이트

무엇을, 언제, 어디서 돌리는지 정한다. 게이트 구성의 정본은 src/build.gradle의 라이프사이클과 .github/workflows/다. 이 문서와 그 둘이 다르면 그 둘이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 operate.md 「실행 위치」다.

작업 중      <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 안) 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
bash scripts/verify-compose-profile-contracts.sh compose lane이 선언대로 렌더링되는가(저장소 루트에서) PR ci-quality-gates.yml
python3 scripts/check-repo-layout.py 저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 PR ci-quality-gates.yml
python3 scripts/check-docs.py 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자(docs/README.md 「문서 검사」). 앞에 자기 시험 python3 -m unittest discover -s scripts/tests를 돈다 PR·main push docs-check.yml(경로 필터 없음)
mainCheck configContractCheck + qualificationCheck(testQualityCheck 포함) + 공개 경로 스냅숏 + 전송·메시징 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
performanceCheck 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 main·nightly integration-main.yml. 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/**, AGENTS.md·CLAUDE.md, README) 그 문서를 읽는 document-contract lane(예: :app-bootstrap:documentContractTest) + 링크 검사(아래) + python3 scripts/check-docs.py
파일·폴더·Gradle 프로젝트를 지우거나 옮김 python3 scripts/check-docs.py(문서가 가리키던 경로가 사라진다)
docs/work/, 루트 AGENTS.md·CLAUDE.md, src/**/AGENTS.md, .claude/ 아래 문서 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
테스트 코드(ArchUnit fixture 포함) 그 leaf testQualityCheck
compose·Dockerfile compose 검사 스크립트, 실제 docker build와 기동
  • ArchUnit 위반·허용 fixture도 testQualityCheck(SpotBugs)가 분석한다. 외부 라이브러리의 Lombok 클래스를 상속한 fixture는 SpotBugs가 lombok.Generated를 찾지 못해 실패한다(missing analysis class). 그런 상속 fixture는 두지 않는다.

어떤 테스트가 그 문서를 읽는지는 grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java로 찾는다. 걸리는 테스트가 없으면(주석만 걸려도 없음이다) document-contract lane은 돌리지 않고 grep 명령과 결과를 보고에 적는다. 리뷰 기록(docs/reviews/**)도 같다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(brief가 먼저다).

탐침: 의심 결함이나 RED를 보려고 별도 worktree에서 잠깐 돌리는 테스트다. 버릴 worktree에서만 돌리고 커밋하지 않는다.

  • 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다.
  • strict lane에 --tests를 붙여 탐침만 돌려도 된다. 단 requires(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(StrictTestLanePlugin의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다.
  • 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 ./gradlew <gradle-path>:resolveAndLockAll --write-locks로 다시 만들어 가져오고 verifyDependencyLocks로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다.
  • 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 build.gradle 한 줄을 더하고 --write-locks로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.

링크 검사: workflow link-check.yml(lychee)이 PR에서 README.md, src/README.md, src/**/README.md, src/**/CLAUDE.md, docs/**/*.md, .github/**/*.md를 검사한다. 그 범위 밖의 지침 문서(루트 AGENTS.md·CLAUDE.md, 지역 규칙 src/**/AGENTS.md, .claude/ 아래 문서)의 상대 링크는 PR마다 scripts/check-docs.py의 link가 본다. src/**/CLAUDE.md는 @AGENTS.md 한 줄이라 링크가 없다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):

python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/AGENTS.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md')

--links docs만 돌리면 src/**/README.md·src/**/AGENTS.md·.github/**/*.md를 빠뜨린다. 저장소 밖 경로와 file:line은 링크로 쓰지 않는다(lychee가 따라가지 못한다).

3. 라운드 끝 — 합친 트리의 전체 묶음

여러 묶음을 합친 트리는 workflow가 PR과 main push에서 돌리는 것을 모두 돌린다. 정본은 .github/workflows/다. (가)는 늘 도는 것, (나)는 바뀐 파일로 켜지는 것, (다)는 로컬에 도구가 없는 것이다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다.

단계별 묶음. brief가 단계 이름으로 게이트를 시키면 아래 줄을 돈다.

brief의 말 돌릴 것
pull request 단계 게이트 (가)의 # PR 줄과 verify-compose-profile-contracts.sh·check-repo-layout.py·check-docs.py(자기 시험 포함), (나)에서 pull_request로 켜지는 것, (다)
main 단계 (가)의 # main push 줄과 run-compose-runtime-smoke.sh·check-docs.py(자기 시험 포함), (나)에서 main push로 켜지는 것
라운드 끝 위 둘 전부와 (가)의 # 태그 두 줄
  • 태그 두 줄(releaseCheck)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. release.yml의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다(operate.md 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.

실제로 돌았음을 보이기. 새 detached worktree에서 시작하고 모든 Gradle 명령에 --no-build-cache를 붙인다. workflow 명령에 그 옵션이 없어도(예: tasks --group verification) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 grep -c 'FROM-CACHE' <로그>가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). --rerun은 바로 앞 태스크 하나에만 걸려 ci 같은 집계 태스크의 증거가 되지 않는다.

  • mainCheck 안의 verifyFeatureScaffold는 생성한 복사본에서 Gradle을 따로 띄워(scripts/verify-feature-scaffold.sh) 바깥의 --no-build-cache를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다.

(가) 늘 도는 것:

cd src
# PR: ci-quality-gates.yml
./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain
./gradlew :verifyStrictLaneStages --dry-run --console=plain
# main push: integration-main.yml
./gradlew :mainCheck --continue --warning-mode=fail --no-build-cache --console=plain
./gradlew :integrationCheck --continue --no-build-cache --console=plain
./gradlew :performanceCheck --continue --no-build-cache --console=plain
./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --no-build-cache --console=plain   # 실험 job, 실패해도 workflow는 통과
# 태그: release.yml (CI는 GITHUB_SHA로 커밋을 받는다. 손으로 돌릴 때는 -PgitRevision)
./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
cd ..
bash scripts/verify-compose-profile-contracts.sh
python3 scripts/check-repo-layout.py
python3 -m unittest discover -s scripts/tests     # docs-check.yml(PR·main push): 문서 검사의 자기 시험
python3 scripts/check-docs.py
bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
  • 여러 명령으로 된 main job 둘은 그 job의 run 줄을 차례로 그대로 돌린다: integration-main.yml의 configuration-cache(로그에 "Reusing configuration cache."가 있어야 한다), notification-platform.yml의 pr(main push마다 경로와 상관없이 돈다).
  • 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다.
  • 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다.

(나) 바뀐 파일로 켜지는 것 — brief의 "바뀐 영역의 lane"은 이것이다:

  1. 바뀐 파일 목록을 만든다: git diff --name-only <기준 커밋> <합친 커밋>.
  2. 그 목록을 두 종류의 패턴과 맞춘다.
    • on.pull_request.paths가 있는 workflow(grep -l 'paths:' .github/workflows/*.yml). 패턴은 glob이다(**는 폴더 여러 단계).
    • pr-adapters.yml의 changes job에 있는 emit 줄. lane(web·websocket·httpclient·jpa)마다 정규식이고, grep -E로 맞춘다.
  3. 걸린 workflow·job의 run 줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의 docker compose … up·down 단계도 같이 한다.
  4. 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다.
  5. 경로로 처음 켜진 lane이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 lane이 켜짐), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 lane 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.

(다) 로컬에 도구가 없는 것:

job 로컬에서 대체가 못 보는 것
link-check.yml(lychee) 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 외부 URL
dependency-vulnerability.yml dependency-review·dependency-submission GitHub에서만 돈다. diff에 lockfile·src/gradle/libs.versions.toml 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 전부
dependency-vulnerability.yml trivy-fs 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다(operate.md 4.1절). 없으면 못 돌림 전부(못 돌렸을 때)

4. 결과 기록

단계 게이트(명령) 결과 시간 실행 직전 1분 부하 실제 실행 로그
PR :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache rc=0 6분 32초 0.39 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 desktop ~/<작업 이름>-logs/ci.log
  • 한 줄은 명령 하나다. 여러 명령으로 된 job(configuration-cache, notification pr)은 명령마다 한 줄을 쓰고 「게이트」 칸에 <job> 1/7처럼 순번을 붙인다. Gradle의 태스크 집계 줄은 명령마다 하나씩 나오므로 로그도 명령마다 나눈다.
  • 「실제 실행」 칸은 로그의 > Task 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다.

테스트 수 세기. 성공한 Gradle 로그(--console=plain)에는 테스트 수가 찍히지 않는다. 같은 worktree의 다음 실행(특히 --tests 필터 실행)은 같은 leaf의 XML을 덮어쓴다. 그래서 명령이 끝날 때마다 XML을 로그 폴더로 복사하고 사본에서 센다.

cp -r <leaf 경로>/build/test-results/<태스크> ~/<작업 이름>-logs/<명령 이름>-xml
x=~/<작업 이름>-logs/<명령 이름>-xml
for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | grep -o '<testsuite [^>]*' | grep -o " $k=\"[0-9]*\"" | tr -dc '0-9\n' | awk -v k=$k '{s+=$1} END {print k"="s+0}'; done

앞 실행을 증거로 쓰기. 다시 돌리지 않고 앞 실행을 증거로 쓸 수 있는 것은 둘이다.

  • 같은 worktree에서 앞 명령이 만든 출력이라 이번 명령의 태스크가 UP-TO-DATE로 끝났다. 앞 명령의 로그와 XML 사본을 함께 적는다.
  • 같은 트리 해시에서 돈 자기 실행 로그가 있다(맡은 발견이 이미 커밋된 수정에 들어 있을 때 등). 로그에 적힌 트리 해시와 지금 트리 해시를 함께 적는다.
  • 트리가 다르거나 다른 세션 보고의 「통과」는 증거가 아니다(E0). 다시 돌린다.

smoke 이미지가 이 트리에서 만들어졌음을 보이기. smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 CACHED가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다.

원래 있던 실패 가리기. 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 --tests <클래스> --rerun으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 nproc개의 yes > /dev/null &를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다.

공유 잠금 기다리기. 순서는 flock이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 ps -o pid,etime,args -C flock으로 쥔 쪽을 보고 맡긴 쪽에 알린다(operate.md 7절).

함께 적는다:

  • 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
  • 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다.
  • 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다.
  • 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름.
  • 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로.
  • 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다.

5. 성능 lane

  • performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 src/build-logic/AGENTS.md 「lane 캐시와 성능 lane」과 docs/testing/TESTING_STRATEGY.md의 PERFORMANCE 문단이다.
  • strict lane convention이 테스트 JVM에 performance.assertions.enabled=true를 넣는다. leaf나 lane은 이 값을 선언하지 않는다.
  • 빌드(-P, GRADLE_OPTS)나 lane이 true 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. -Pperformance.assertions.enabled=true는 받지만 줄 필요가 없다.
  • 그래서 desktop에서 손으로 돌리는 ./gradlew performanceCheck와 workflow가 같은 상한을 단언한다.
  • 판정 없이 숫자만 보려면 JMH가 있는 leaf의 ./gradlew :<leaf>:jmh를 쓴다. 게이트가 아니다.
  • 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 performanceCheck에 있다.

회귀를 막는 장치:

장치 고정하는 것 단계
자원 한계 lane Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 performanceCheck
JMH 벤치마크 src/platforms/messaging/messaging-kafka/src/jmh, src/platforms/messaging/messaging-testkit/src/jmh, src/adapter/outbound/httpclient/src/jmh 명시 실행

6. 게이트를 믿을 조건 — 거짓 통과 막기

초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다.

거짓 통과 모양 지금의 장치
어떤 workflow도 돌리지 않는 lane verifyStrictLaneStages --dry-run(PR)
실패를 막지 못하는 workflow 명령을 실행으로 셈(|| true, pipefail 없는 파이프, if 조건 등) src/build-logic/AGENTS.md 「verifyStrictLaneStages가 세는 명령」
lane 정책을 바꿨는데 캐시가 옛 결과로 통과 lane 정책 값을 Test 입력으로
게이트 밖에서 실패한 채 방치된 검사 testQualityCheck(mainCheck)
실서버 계약이 어느 게이트에도 없음 lane을 단계에 연결
시간 단언을 끈 채 performance lane 실행 convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절)
캐시에서 가져온 결과를 지금 통과한 것으로 셈 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. --rerun은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 --no-build-cache로 돌리고 FROM-CACHE 0을 보인다(3절)
외부 이미지가 사라져 다른 lane 결과까지 가림 테스트 이미지를 src/config/testing/container-images.properties 한 곳에 digest로 고정, main 단계는 --continue
smoke rc=0인데 앱이 OOM으로 재시작함 scripts/run-compose-runtime-smoke.sh가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 restarts.txt·app-memory-peak-bytes.txt를 남긴다. 그 밖의 compose 실행은 docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>로 본다
셸 함수·if 조건 안에서 set -e가 꺼져 중간 실패가 지나감 실패를 받아야 하는 명령은 if·&&·`

게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.

7. workflow·검사 스크립트를 더할 때

리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다.

  1. 어느 단계인가(PR·main·nightly·release), 그리고 그 단계의 기존 workflow에 job으로 넣을 수 없는 이유를 한 줄로 쓴다. 모듈 이름의 workflow 파일은 만들지 않는다.
  2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 --dry-run 태스크 목록으로 보인다.
  3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 run:은 한 줄이다.
  4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다.
  5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다.
  6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 operate.md 4.1절의 값으로 판단한다.
  7. 실행 환경(Gitea)에서 돌지 않는 action·권한(id-token, ghcr, GitHub 의존성 그래프, upload-artifact@v4 이상)을 쓰지 않는다. 써야 하면 github.server_url 조건을 단다.
  8. Gradle 밖 검사 스크립트는 scripts/에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 scripts/tests/에 unittest로 둔다. docs-check.yml이 PR마다 python3 -m unittest discover -s scripts/tests로 돌린다.
  9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다(improve.md 7절).