문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
rc=0(3건)
16 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 안), 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 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | integration-main.yml, optional 빌드도. 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/**, CLAUDE.md, README) |
그 문서를 읽는 document-contract lane(예: :app-bootstrap:documentContractTest) + 링크 검사(아래) |
docs/work/, 루트 CLAUDE.md, AGENTS.md, src/**/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 -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java로 찾는다. 걸리는 테스트가 없으면(주석만 걸려도 없음이다) document-contract lane은 돌리지 않고 grep 명령과 결과를 보고에 적는다. 리뷰 기록(docs/reviews/**)도 같다.
링크 검사: 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가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):
python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/CLAUDE.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md')
--links docs만 돌리면 src/**/README.md·src/**/CLAUDE.md·.github/**/*.md를 빠뜨린다. 저장소 밖 경로와 file:line은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
3. 라운드 끝 — 합친 트리의 전체 묶음
여러 묶음을 합친 트리는 workflow가 PR과 main push에서 돌리는 것을 모두 돌린다. 정본은 .github/workflows/다. (가)는 늘 도는 것, (나)는 바뀐 파일로 켜지는 것, (다)는 로컬에 도구가 없는 것이다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다.
실제로 돌았음을 보이기. 새 detached worktree에서 시작하고 모든 Gradle 명령에 --no-build-cache를 붙인다. 로그마다 grep -c 'FROM-CACHE' <로그>가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다. --rerun은 바로 앞 태스크 하나에만 걸려 ci 같은 집계 태스크의 증거가 되지 않는다.
(가) 늘 도는 것:
cd src
# PR: ci-quality-gates.yml
./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain
./gradlew :verifyStrictLaneStages --dry-run --console=plain
./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --no-build-cache --console=plain
./gradlew -p optional-platforms ci --no-build-cache --console=plain
./gradlew -p optional-platforms :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 -p optional-platforms performanceCheck --continue --no-build-cache --console=plain
./gradlew -p optional-platforms integrationCheck --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
./gradlew -p optional-platforms releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
cd ..
bash scripts/verify-compose-profile-contracts.sh
bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
- 여러 명령으로 된 main job 둘은 그 job의
run줄을 차례로 그대로 돌린다:integration-main.yml의configuration-cache(로그에 "Reusing configuration cache."가 있어야 한다),notification-platform.yml의pr(main push마다 경로와 상관없이 돈다). - 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다.
- 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다.
(나) 바뀐 파일로 켜지는 것 — brief의 "바뀐 영역의 lane"은 이것이다:
- 바뀐 파일 목록을 만든다:
git diff --name-only <기준 커밋> <합친 커밋>. - 그 목록을 두 종류의 패턴과 맞춘다.
on.pull_request.paths가 있는 workflow(grep -l 'paths:' .github/workflows/*.yml). 패턴은 glob이다(**는 폴더 여러 단계).pr-adapters.yml의changesjob에 있는emit줄. lane(web·websocket·httpclient·jpa)마다 정규식이고,grep -E로 맞춘다.
- 걸린 workflow·job의
run줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의docker compose … up·down단계도 같이 한다. - 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다.
(다) 로컬에 도구가 없는 것:
| job | 로컬에서 | 대체가 못 보는 것 |
|---|---|---|
link-check.yml(lychee) |
2절 끝의 같은 범위 상대 링크 검사 | 외부 URL |
ci-quality-gates.yml grpc-proto-buf(buf lint·buf breaking) |
buf가 있으면 job의 run 줄 그대로. 없으면 못 돌림으로 적는다. diff에 .proto·buf*.yaml이 없으면 "해당 없음 — proto 변경 없음" |
전부 |
dependency-vulnerability.yml dependency-review·dependency-submission |
GitHub에서만 돈다. diff에 lockfile·src/gradle/libs.versions.toml 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 |
전부 |
dependency-vulnerability.yml trivy-fs |
trivy가 있으면 job의 run 줄 그대로, 없으면 못 돌림 |
— |
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, notificationpr)은 명령마다 한 줄을 쓰고 「게이트」 칸에<job> 1/7처럼 순번을 붙인다. Gradle의 태스크 집계 줄은 명령마다 하나씩 나오므로 로그도 명령마다 나눈다. - 「실제 실행」 칸은 로그의
> Task줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다.
함께 적는다:
- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
- 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다.
- 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다.
- 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름.
- 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로.
- 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다.
5. 성능 lane
- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은
AGENTS.md「Gradle 정책 권위」와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에 있다.
회귀를 막는 장치:
| 장치 | 고정하는 것 | 단계 |
|---|---|---|
요청당 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 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) |
| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. --rerun은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 --no-build-cache로 돌리고 FROM-CACHE 0을 보인다(3절) |
| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 src/config/testing/container-images.properties 한 곳에 digest로 고정, main 단계는 --continue |
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.