# 게이트 무엇을, 언제, 어디서 돌리는지 정한다. 게이트 구성의 정본은 `src/build.gradle`의 라이프사이클과 `.github/workflows/`다. 이 문서와 그 둘이 다르면 그 둘이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다. ```text 작업 중 :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 :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` 안), optional 빌드는 `ci` | `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`, optional 빌드는 `-p optional-platforms` | | `:sample-portfolio:check :sample-portfolio:qualityCheck` | 샘플(`ci` 밖) | PR | `ci-quality-gates.yml` | | `-p optional-platforms ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` | | `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` | | `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 샘플 실서버 계약 + 샘플 전체 기동(`:sample-portfolio:systemTest`) + 공개 경로 스냅숏 + 전송·메시징 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`, optional 빌드도 | | `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). main·nightly에서 돈다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 | | `releaseCheck -PgitRevision=` | 릴리스 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/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) | | `docs/work/`, 루트 `CLAUDE.md` | `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 | | 테스트 코드 | 그 leaf `testQualityCheck` | | compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 | 어떤 테스트가 그 문서를 읽는지는 `grep -rn '<파일 이름>' src --include=*.java`로 찾는다. **링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 `python3 scripts/check-work-docs.py --links docs`로 상대 링크만 확인한다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). ## 3. 라운드 끝 — 합친 트리의 전체 묶음 여러 묶음을 합친 트리는 workflow와 같은 명령으로 검증한다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다. ```bash cd src ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --console=plain ./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --console=plain ./gradlew :verifyStrictLaneStages --dry-run --console=plain ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain ./gradlew :mainCheck --continue --warning-mode=fail --console=plain ./gradlew :integrationCheck --continue --console=plain ./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true --console=plain ./gradlew :performanceCheck --continue -Pperformance.assertions.enabled=true --console=plain ./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain cd .. && bash scripts/verify-compose-profile-contracts.sh ``` - 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다. - 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다. ## 4. 결과 기록 | 게이트 | 결과 | 시간 | 실행 직전 1분 부하 | 로그 | | --- | --- | --- | --- | --- | | `:ci :verifyDependencyLocks --warning-mode=fail` | rc=0 | 5분 42초 | 2.65 | desktop `~/<작업 이름>-logs/ci.log` | 함께 적는다: - 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다. - 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다. - 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다. - 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름. - 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로. - 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다. ## 5. 성능 lane - 일부 performance lane은 시간 단언을 `performance.assertions.enabled` 속성으로 켠다. workflow는 이 값을 `true`로 준다(`integration-main.yml`의 `GRADLE_OPTS`). - leaf마다 기본값이 다르다: httpclient lane은 `false`(`src/adapter/outbound/httpclient/build.gradle`), persistence-mongo lane은 `true`(`src/adapter/outbound/persistence-mongo/build.gradle`). - 그래서 desktop에서 `performanceCheck`를 돌릴 때는 workflow와 같게 `-Pperformance.assertions.enabled=true`를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다. - 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다. 회귀를 막는 장치: | 장치 | 고정하는 것 | 단계 | | --- | --- | --- | | 요청당 SQL 수 단언(`WorkLogStatementCostSystemTest`) | 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 | sample `systemTest`(`mainCheck`) | | 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` | | JMH 벤치마크 | `src/messaging/messaging-kafka/src/jmh`, `src/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 | ## 6. 게이트를 믿을 조건 — 거짓 통과 막기 초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다. | 거짓 통과 모양 | 지금의 장치 | | --- | --- | | 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) | | optional 빌드를 보지 않음 | optional 빌드도 같은 검사 | | 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `AGENTS.md` 「Gradle 정책 권위」의 세는 규칙 | | lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | | 시간 단언을 끈 채 performance lane 실행 | 5절 속성 | | 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` | 게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.