# 게이트 무엇을, 언제, 어디서 돌리는지 정한다. 무엇이 한 단계인지는 `build.gradle`의 단계 태스크(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`)가 정한다. workflow(`.gitea/workflows/`의 `pr.yml`·`main.yml`·`release.yml`)와 `scripts/verify.sh`는 그 태스크를 부르기만 한다. 이 문서와 그 셋이 다르면 그 셋이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다. ```text 작업 중 scripts/verify.sh leaf (+ 그 leaf의 관련 strict lane) 묶음 끝 + architectureCheck · 바뀐 표면의 검사(env 키·공개 경로·의존성 잠금) · 관련 lane 라운드 끝 합친 트리에서 scripts/verify.sh round — workflow가 PR·main·nightly·태그에서 돌리는 것과 같은 명령 ``` ## 1. 게이트 목록 Gradle 명령과 `scripts/verify.sh`는 모두 저장소 루트(Gradle 루트)에서 실행한다. `verify.sh`는 Gradle·Docker가 드는 단계를 desktop으로 옮겨 잠금 아래에서 돌린다([operate.md](../operate.md) 4.1절). leaf의 Gradle path는 `gradle/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다. | `scripts/verify.sh` 단계 | 무엇을 돌리나 | workflow | | --- | --- | --- | | `docs` | `check-work-docs.py`, `check-docs.py`, `scripts/tests` 자기 시험, `check-repo-layout.py`(Gradle 없음, 노트북 가능) | `pr.yml`의 `prCheck` 안 | | `leaf ` | 그 leaf의 `check` | — | | `pr` | `./gradlew :prCheck`, `./gradlew :verifyStrictLaneStages --dry-run` | `pr.yml` `done` | | `main` | `:mainCheck --continue`, `:integrationCheck --continue`, `-p build-logic test`, `scripts/ci/verify-configuration-cache.sh` | `main.yml`(push) | | `nightly` | compose smoke 전부, 마지막에 `:performanceCheck --continue` | `main.yml`(schedule·수동) | | `release` | `:releaseCheck`(지금 커밋을 provenance로) | `release.yml` `release` | | `app` | `scripts/bootstrap-local.sh`(앱을 띄워 health와 기본 endpoint 확인) | — | | `round` | `pr` → `main` → `nightly` → `release`, 첫 실패에서 멈춘다 | — | workflow에만 있는 job: `pr.yml` `done`의 마지막 step과 `main.yml`의 `vulnerabilities`(trivy, `scripts/ci/trivy-scan.sh`), `main.yml`의 `links`(lychee), nightly 행렬(`jpa-postgresql`·`httpclient-transport`·`redis-topology`·`fileserver-nfs-ambiguity`·`notification-chaos`·`jpa-next`), `release.yml`의 release lane과 이미지 job. 도구를 내려받거나 runner 환경이 필요해 `verify.sh`에 넣지 않았다. 손으로 돌리는 법은 3절 (다)다. 게이트 하나씩: | 게이트 | 무엇 | 단계 | 정의·workflow | | --- | --- | --- | --- | | `./gradlew :check` | 그 leaf만: 컴파일, 테스트, Spotless, Checkstyle, Error Prone, API surface | 작업 중 | leaf 컨벤션 플러그인 | | `architectureCheck` | 의존 방향, domain-core·shared-contract·application-* 순수성, Git이 옮길 수 있는 소스, ArchUnit | PR(`ci` 안) | `build.gradle` | | `./gradlew :app-bootstrap:architectureTest` | 저장소 전체 ArchUnit suite만 | 작업 중 | app-bootstrap `architectureTest` source set | | `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `build.gradle` | | `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안) | `build.gradle` | | `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR(`prCheck` 안) | `build.gradle` | | `prCheck` | `ci` + `verifyDependencyLocks` + `verifyComposeProfiles`(compose lane이 선언대로 렌더링되는가) + `verifyRepositoryLayout`(`check-repo-layout.py`) + `documentCheck`(`check-docs.py`, 앞에 `scripts/tests` 자기 시험) | PR | `pr.yml` `done`: `./gradlew :prCheck` | | `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 단계 태스크 하나의 계획에 들어 있는가(그래프 검사), 단계마다 선언한 workflow job이 `./gradlew <단계>` 한 줄을 정해진 조건으로 돌리는가(형식 검사) | PR | `pr.yml` `done` 둘째 줄. 형식은 `build-logic/AGENTS.md` | | `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR(`prCheck` 안) | `verifyRepositoryLayout` | | `python3 scripts/check-docs.py` | 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자, 상대 링크(`docs/README.md` 「문서 검사」) | PR(`prCheck` 안) | `documentCheck` | | `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `main.yml` `main`: `./gradlew :mainCheck --continue` | | `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `main.yml` `integration` | | `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | nightly(다른 무거운 job 뒤) | `main.yml` `performance`. 5절 | | `releaseCheck` | 릴리스 provenance + 공개 경로 스냅숏. 커밋을 `GITHUB_SHA`·`GIT_SHA`·`-PgitRevision=`로 받고, 없으면 설계대로 실패한다 | 태그 | `release.yml` `release` | | `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` | | `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `build.gradle` | | `verifyDependencyLocks` | lockfile | PR(`prCheck` 안) | `build.gradle` | | `:app-bootstrap:documentContractTest` | 문서와 코드를 대조하는 lane(태그 `document-contract`) | main(`mainCheck` 안) | `src/bootstrap/app/build.gradle` | | `:app-bootstrap:repositoryContractTest` | 빌드 스크립트·workflow·compose를 읽는 계약(태그 `repository-contract`) | PR | `src/bootstrap/app/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(`.gitea/`) | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` | | 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) | | 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane | | 테스트 코드(ArchUnit fixture 포함) | 그 leaf `testQualityCheck` | | compose·Dockerfile | `verifyComposeProfiles`(compose 렌더링), 실제 `docker build`와 기동(`scripts/verify.sh nightly`의 smoke) | - 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 :resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다. - 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다. **링크 검사**: 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL까지 보는 lychee는 문서 검사라 main 단계다(`main.yml` `links`, 범위 `README.md`, `docs/build.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`). 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). ## 3. 라운드 끝 — 합친 트리의 전체 묶음 여러 묶음을 합친 트리는 workflow가 PR·main·nightly·태그에서 돌리는 단계를 모두 돌린다. 경로 필터로 켜지는 job은 없다(2026-11-08부터, 단계 workflow의 경로 필터는 `verifyStrictLaneStages`가 거절한다). (가)는 `scripts/verify.sh` 단계, (나)는 workflow에만 있는 job이다. 한 번에 하나씩, 공유 잠금 아래에서 돈다(`verify.sh`가 잠근다). **단계별 묶음.** brief가 단계 이름으로 게이트를 시키면 같은 이름의 `verify.sh` 단계를 돈다. | brief의 말 | 돌릴 것 | | --- | --- | | pull request 단계 게이트 | `scripts/verify.sh pr --no-cache` + `scripts/verify.sh docs` | | main 단계 | `scripts/verify.sh main --no-cache` | | nightly, compose smoke, 성능 | `scripts/verify.sh nightly --no-cache` | | 라운드 끝 | `scripts/verify.sh round --no-cache` + `scripts/verify.sh docs`, 그리고 (나)에서 바뀐 영역에 걸리는 job | - `release` 단계(`releaseCheck`)는 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다. - `verify.sh`는 단계 하나를 로그 하나(`~/<로그 이름>-logs/<단계>.log`)로 남긴다. 4절 표에는 그 안의 Gradle 명령마다 한 줄을 쓴다. **실제로 돌았음을 보이기.** `--on desktop`(기본)은 새 detached worktree에서 시작한다. `--no-cache`가 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `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(태스크 이름)"으로 적는다. - `verify.sh`를 쓸 수 없는 환경이면 단계 함수의 명령을 저장소 루트에서 그대로 차례로 돈다. 단계 함수가 명령의 정본이다. - 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다. - 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다. (나) workflow에만 있는 job — brief의 "바뀐 영역의 lane"은 이것이다: 1. 바뀐 파일 목록을 만든다: `git diff --name-only <기준 커밋> <합친 커밋>`. 2. 바뀐 영역의 job을 고른다: PostgreSQL major(`jpa-postgresql`, persistence-jpa), HTTP transport(`httpclient-transport`, httpclient), Redis topology(`redis-topology`, redis leaf 셋), NFS(`fileserver-nfs-ambiguity`, fileserver), 알림 chaos(`notification-chaos`), 릴리스 lane(`release.yml`의 같은 영역 job). 3. 그 job의 `run` 줄을 저장소 루트에서 그대로 돌린다. 행렬은 값마다 한 번이다. 스크립트 job(`scripts/ci/redis-topology.sh `)은 desktop에서도 같은 줄로 돈다. 4. 고르지 않은 job은 이름과 "바뀐 영역 아님"을 결과 표에 적는다. 5. 처음 켠 job이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 job을 돌림), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다. (다) 로컬에 도구가 없는 것: | job | 로컬에서 | 대체가 못 보는 것 | | --- | --- | --- | | `main.yml` `links`(lychee) | `scripts/verify.sh docs`의 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL | | `vulnerabilities`(trivy) | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 `scripts/ci/trivy-scan.sh`의 검사 줄 그대로. 그 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. 스크립트가 trivy를 내려받아 설치하는 부분은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) | ## 4. 결과 기록 | 단계 | 게이트(명령) | 결과 | 시간 | 실행 직전 1분 부하 | 실제 실행 | 로그 | | --- | --- | --- | --- | --- | --- | --- | | PR | `:prCheck --no-build-cache` | rc=0 | 6분 32초 | 0.39 | 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 | desktop `~/<작업 이름>-logs/pr.log` | - 한 줄은 명령 하나다. `verify.sh` 단계 하나는 Gradle 명령 여럿이다. 명령마다 한 줄을 쓰고 「게이트」 칸에 `main 2/4`처럼 순번을 붙인다. Gradle의 태스크 집계 줄(`BUILD SUCCESSFUL in …`, `N actionable tasks`)은 명령마다 하나씩 나오므로 단계 로그에서 명령별로 나눠 읽는다. - 「실제 실행」 칸은 로그의 `> Task` 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다. **테스트 수 세기.** 성공한 Gradle 로그(`--console=plain`)에는 테스트 수가 찍히지 않는다. 같은 worktree의 다음 실행(특히 `--tests` 필터 실행)은 같은 leaf의 XML을 덮어쓴다. 그래서 명령이 끝날 때마다 XML을 로그 폴더로 복사하고 사본에서 센다. ```bash cp -r /build/test-results/<태스크> ~/<작업 이름>-logs/<명령 이름>-xml x=~/<작업 이름>-logs/<명령 이름>-xml for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | grep -o ']*' | 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](../operate.md) 7절). 함께 적는다: - 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다. - 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다. - 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다. - 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름. - 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로. - 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다. ## 5. 성능 lane - performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `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 ::jmh`를 쓴다. 게이트가 아니다. - 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다. 회귀를 막는 장치: | 장치 | 고정하는 것 | 단계 | | --- | --- | --- | | 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` | | JMH 벤치마크 | `src/adapter/outbound/httpclient/src/jmh`(메시징 벤치마크는 messaging-library repo로 옮겼다) | 명시 실행 | ## 6. 게이트를 믿을 조건 — 거짓 통과 막기 초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다. | 거짓 통과 모양 | 지금의 장치 | | --- | --- | | 어떤 단계도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR)의 그래프 검사 | | 단계 job이 단계를 조용히 돌리지 않음(바뀐 명령 줄, `if:`, `continue-on-error`, 경로 필터) | `verifyStrictLaneStages --dry-run`의 형식 검사(`build-logic/AGENTS.md` 「단계 job의 모양」) | | lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | | 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) | | 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 `--no-build-cache`로 돌리고 FROM-CACHE 0을 보인다(3절) | | 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `gradle/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`·`&&`·`||` 조건 밖에 두거나 rc를 직접 본다(`<명령>; rc=$?; [ "$rc" -eq 0 ] \|\| exit "$rc"`) | 게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. workflow를 바꿨으면 바꾸기 전후로 이벤트마다 계획되는 태스크 집합(`--dry-run`)을 비교한다. ## 7. workflow·검사 스크립트를 더할 때 리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다. 1. 어느 단계인가(PR·main·nightly·release). workflow 파일은 셋(`pr.yml`·`main.yml`·`release.yml`)뿐이다. 먼저 단계 태스크(`prCheck` 등)의 의존으로 넣을 수 있는지 보고, 안 되면 그 단계 파일의 job으로 넣는다. 새 workflow 파일과 모듈 이름의 workflow는 만들지 않는다. 2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 `--dry-run` 태스크 목록으로 보인다. 3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 `run:`은 한 줄이다. 4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다. 5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다. 6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 [operate.md](../operate.md) 4.1절의 값으로 판단한다. 7. 실행 환경(Gitea)에서 돌지 않는 action·권한(`id-token`, ghcr, GitHub 의존성 그래프, `upload-artifact@v4` 이상)을 쓰지 않는다. 써야 하면 `github.server_url` 조건을 단다. 8. Gradle 밖 검사 스크립트는 `scripts/`(workflow만 부르면 `scripts/ci/`)에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `prCheck`의 `testDocumentChecks`가 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다. 9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다([improve.md](../improve.md) 7절).