main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
문제: 모듈 README·AGENTS·매뉴얼·Javadoc이 옮기거나 이름을 바꾼 타입,
지운 샘플, 다른 repo로 옮긴 플랫폼을 그대로 가리켰다.
- 옮기거나 바꾼 타입: OutboxConfig(지금 :composition:outbox-relay의
OutboxRelayAutoConfiguration), IdempotencyProviderSelectionConfig(지금
:composition:idempotency의 IdempotencyAutoConfiguration),
TracingProperties·GraphQlPlatformProperties(지금 *Settings), SecretSource
(지금 application-core SecretSourcePort), JsonNullableModule(지금
JsonNullableJackson3Module), PeriodTest·OutboxEventIdFactory(샘플과 함께
지움).
- 지운 샘플: SampleDemoProfilesStartupSystemTest, 「sample 테스트」,
IdempotencyAutoConfiguration·ManagementSecurityConfig Javadoc의 샘플.
- 옮긴 플랫폼: graphql AGENTS·README가 messaging 플랫폼과 「두 패턴 공존」을
적었지만 그 플랫폼은 2026-11-08 messaging-library로 옮겼다. gRPC 문서는
grpc-library로 옮긴 플랫폼을 「vendored」·「벤더 starter」로 불렀다.
- leaf CLAUDE.md를 가리키던 곳(지금 AGENTS.md), 복사한 숫자(httpclient
java 파일 수, graphql systemTest 수), manual 06의 registry 머리말 옛 영어 인용.
고른 방법: 문장이 가리키는 대상만 지금 이름으로 바꾼다. 동작 설명은 그대로
둔다. 숫자는 지운다(레지스트리·빌드가 정한다).
검증:
- 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄
때문에만 rc=1.
- desktop(--no-build-cache, 트리 310eb524): 이 문서들을 읽는 시험
(:app-bootstrap:documentContractTest, repositoryContractTest —
DeveloperExperienceContractTest 포함, MongoNamespaceContractTest,
AwsQualificationClaimHonestyTest)과 Javadoc을 고친 두 leaf의
compileJava·spotlessCheck. 134건 실패 0, skip 1.
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
이 브랜치의 c0d7ad8f("operate.md를 150줄 안으로 줄이고 묶음 ID를
뺀다")를 되돌린다. 백엔드 CI 세션이 같은 줄을 PR #15(caa71d32)에서
다르게 고쳤고(4.4절 두 줄을 합쳐 150줄, ID 삭제), check-work-docs.py를
prCheck에 넣었다(13ed3a1d). 두 PR이 같은 줄을 고치면 병합 충돌이
난다.
위험·한계: PR #15가 병합되기 전에는 main의 operate.md가 151줄이고
"(W4 BE-OBS-A)"가 남아, 이 브랜치가 더한 ID 꼴 검사와 줄 수 검사로
check-work-docs.py가 rc=1이다. 지금 prCheck는 그 검사를 돌리지 않으므로
PR 단계는 막히지 않는다. #15가 병합되면 둘 다 풀린다.
검증: git diff origin/main -- docs/work/operate.md가 57·87줄의 /src
절차만 남는다. scripts/tests 158건 통과.
문제: be-api-contract·be-domain·be-persistence·be-security의 「검증」 절이
"명령은 `src/`에서다"라고 한다. 분야 스킬은 Gradle 루트를 저장소 루트로
옮긴 뒤에 들어왔는데 옛 위치를 적었다. 그대로 따르면 gradlew가 없는
폴더에서 명령을 돌린다. operate.md 4.1절의 같은 꼴은 앞 커밋이 고쳤다.
고른 방법: 네 줄을 "저장소 루트에서다"로 고치고, 진입 문서(AGENTS.md·
CLAUDE.md·docs/work/·.claude/)에 "명령은 `src/`에서"나 `cd …/src`가 남으면
실패하는 시험을 둔다.
검증: 새 시험 test_no_instruction_runs_gradle_from_the_old_src_root —
기준 스킬 넷에서 4건, 기준 operate.md에서 2건(57·87줄)을 잡고, 이
커밋에서 통과. scripts/tests 158건 통과, check-work-docs.py rc=0.
문제: 결정 색인의 네 행이 지금 코드와 다른데 바뀌었다는 표시가 없다.
색인 1절 6번은 리뷰어가 정한 결정을 결함으로 올리지 않게 하므로, 낡은
행대로 읽은 리뷰어는 맞는 코드를 결함으로 올린다.
- 「문서 검사」: workflow `docs-check`는 2026-11-08 workflow를 셋으로 접으며
없어졌다. 지금은 pr.yml done → :prCheck → documentCheck다.
- 「build-logic 의존성 잠금」: "잠그지 않음(보류)"인데 build-logic/build.gradle은
2026-09-25 커밋부터 STRICT로 잠근다.
- 「릴리스 이미지 서명」: "cosign keyless"인데 2026-11-07 소유자가 키 쌍으로
바꿨다(Gitea Actions가 OIDC 토큰을 주지 않음, operate.md 4.3절).
- 「workflow 명령의 빌드 판정」: "cd도 따라간다"인데 2026-11-08 셸을 해석하지
않는 고정 형식 검사로 바꿨다(소유자가 고른 B안, StrictLaneStagesPlugin).
docs/README.md 「문서 검사」도 같은 `docs-check`를 가리켜 함께 고친다.
고른 방법: 1절 5번대로 원문을 지우지 않고 취소선과 "→ 바꿈"으로 새 위치를
가리키고, 서명 키와 job 모양은 새 행을 더한다.
위험·한계: build-logic 잠금을 언제 누가 바꾸기로 했는지 기록이 없다. 행에
"바꾼 결정의 기록은 없다"고 적었다. 소유자 확인이 필요하다.
검증: check-work-docs.py rc=0, check-docs.py rc=0.
문제: verify-api 서브에이전트는 desktop worktree에서
`flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh`를 직접 돌린다.
bootstrap-local.sh의 ./gradlew에는 --no-daemon이 없어 desktop에 Gradle
daemon이 남는다(여러 worktree를 받은 daemon이 compiler worker를 쌓아
메모리를 채운 일이 있다). 5단계가 따르라는 "4.1절의 정리법"은 operate.md에
없다.
고른 방법: `scripts/verify.sh app --on here`로 부른다. verify.sh가 공유
잠금을 잡고 GRADLE_OPTS로 daemon을 끈 채 같은 스크립트를 부른다. 앱은
compose로 떠 있으니 4단계 호출은 그대로다. 정리는 compose down과
git worktree remove만 적고, 못 지우면 보고에 남기게 한다.
버린 대안: bootstrap-local.sh의 ./gradlew에 --no-daemon을 붙이기 — 사람이
노트북에서 처음 돌릴 때는 daemon이 이득이라 스크립트 기본값은 두고,
desktop 쪽 진입점(verify.sh)이 끈다.
검증: test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock을
새 절차로 바꿨다(verify.sh app --on here와 git worktree remove를 요구하고,
잠금만 두른 직접 호출과 "정리법"을 거절). 기준 verify-api.md에서 실패,
고친 파일에서 통과. test_claude_setup 16건 통과.
문제: experts.md 3절 「경로 → 전문가」는 리드가 바뀐 경로로 렌즈를
고르는 표이고 "지식 스킬의 paths와 맞춘다"고 적는다. 그런데 손으로 옮긴
표가 열 스킬 중 아홉에서 이미 갈라졌다. 예: be-build-ci의 settings.gradle·
gradle.properties·Dockerfile·renovate.json, be-api-contract의 .env.example·
docs/upgrade/**, be-observability의 docs/runbooks/**, be-docs의
**/CLAUDE.md가 표에 없다. 표로 렌즈를 고르면 그 파일을 바꾼 변경에서
렌즈가 빠진다. 이름만 보는 시험(test_the_experts_manual_names_every_expert)은
이 차이를 못 잡는다.
고른 방법: 표 1열을 1차 렌즈 스킬의 paths와 똑같이 고치고, 시험이
표를 읽어(중괄호 펼침) 스킬마다 "1차 렌즈로 이름 댄 행의 glob 합집합 ==
그 스킬의 paths"를 본다. 표 위 문장에 대조 시험이 있다고 적는다.
버린 대안: 표를 지우고 각 스킬 paths를 읽으라고만 쓰기 — 리드가 렌즈
하나를 고르려고 스킬 열 개의 머리를 읽어야 하고, 「이럴 때 더한다」 칸이
갈 곳이 없다.
위험·한계: 「이럴 때 더한다」 칸은 기계로 대조하지 않는다.
검증: 새 시험 test_the_experts_path_table_lists_exactly_each_skill_paths —
기준 표에서 9개 스킬 실패(be-domain만 통과), 고친 표에서 통과.
test_claude_setup 16건 통과, check-work-docs.py·check-docs.py rc=0.
문제: Gradle 루트를 저장소 루트로 옮긴 뒤(refactor(layout)!) src/에는
gradlew가 없다. 그런데 operate.md 4.1절 손 절차 두 곳은 아직
`cd ~/workspace/<작업 이름>/src` 다음 ./gradlew를 돌리라고 한다.
desktop-gates 스킬 6단계가 단계 밖 명령(lane 하나, spotlessApply, 탐침)을
이 절차로 보내므로 그대로 따르면 명령이 없다고 실패한다.
related-repos.md도 "Gradle 루트가 src/라 경로는 두 단계 위"라며
--include-build ../../messaging-library를 적는다. 지금은 workspace 밖을
가리킨다.
고른 방법: /src를 지우고, 라이브러리 경로를 한 단계 위(../messaging-library)로
고친다. 다른 살아 있는 문서에 같은 꼴(cd src, src/gradlew)이 남았는지
git grep으로 봤다. 시험 fixture(broken-readme.md)만 걸린다.
검증: python3 scripts/check-work-docs.py rc=0, check-docs.py rc=0.
문제: 진입 문서의 이력 ID 검사(HISTORY_PATTERNS)는 리뷰 라운드·묶음
이름의 아는 꼴만 잡는다. 2026-11 프로그램의 작업 흐름 이름(W1~W6)과 red
team 발견 ID(BE-OBS-A, BE-CONFIG-001)는 꼴이 없어, operate.md에 들어간
"(W4 BE-OBS-A)"를 --history도 기본 검사도 잡지 못했다.
고른 방법: 두 꼴을 패턴에 더한다. W 뒤 숫자 하나가 단어로 서 있을 때
(W3C, HTTP-W1-x는 아님), BE·FE 뒤 대문자 분야와 세 자리 번호나 글자
하나. 지금 검사 대상 문서에는 걸리는 줄이 없다.
위험·한계: 새 이름 꼴(다른 프로그램의 흐름 이름 등)은 또 패턴을 더해야
잡힌다. 검사는 아는 꼴만 본다는 한계는 그대로다(be-docs 함정 2).
검증: 새 시험 둘(걸리는 세 줄, 걸리면 안 되는 W3C) — 기준
check-work-docs.py에 얹으면 세 줄 모두 통과해 3건 실패, 이 커밋에서
test_check_work_docs 17건 통과. check-work-docs.py rc=0.
문제: red team 수정이 operate.md 4.3절에 요청률 제한 한 줄을 더해
151줄이 됐다(playbook 상한 150). main에서 check-work-docs.py가 rc=1이라
scripts/verify.sh docs와 라운드 끝 묶음이 실패한다. 같은 줄 끝의
"(W4 BE-OBS-A)"는 그 주 노트를 읽은 사람만 따라갈 수 있는 묶음 ID다.
진입 문서에는 ID를 쓰지 않는다(.claude/rules/docs.md).
고른 방법: 바로 위 「파생 서비스가 유지할 게이트」 줄에 한 문장으로
합치고 ID를 뺀다. 자세와 켜는 법의 정본은 docs/security/rate-limiting.md
「파생 서비스가 정할 것」이라 operate.md에는 가리키는 말만 남긴다.
버린 대안: 다른 줄을 지워 자리를 만드는 것 — 지울 만큼 낡은 줄이 없다.
위험·한계: check-work-docs.py가 PR 단계에서 돌지 않아 이 초과가 병합됐다.
그 검사를 PR 단계에 넣는 일은 workflow·build.gradle을 맡은 CI 세션에 넘겼다.
검증: python3 scripts/check-work-docs.py rc=0(operate.md 150/150).
기준 a7e38c10에서는 rc=1(151 lines, limit 150).
round9 확인 리뷰가 CI 파일의 설명이 실제와 다른 곳을 짚었다.
- verify.sh 머리 표: PR 단계 job 이름이 `gradle`이다. 실제는 `done`.
- build.gradle: JMH가 「세 leaf」에 있다고 하지만 지금은 플러그인을
쓰는 leaf가 정한다. verifyFeatureScaffold는 「leaf 다섯 중첩
빌드」라고 하지만 그 안의 architectureCheck가 모든 leaf의
architecture lane을 부른다.
- release.yml: `release` job 주석은 「ci를 다시 돌리지 않는다」인데
뒤의 job들은 ci가 이미 돈 시험 일부를 다시 돈다. 그 이유(문서가
job id로 부르는 릴리스 증거이고, 이미지 job이 모두를 needs로 받아
같은 run·같은 커밋에서 통과한 뒤 publish한다)를 적었다. job은 그대로다.
- gates.md 2절: redis-topology 줄을 desktop에서 그대로 돌리라고 하지만
스크립트 안 ./gradlew는 daemon을 남긴다. desktop에서는
GRADLE_OPTS=-Dorg.gradle.daemon=false를 붙이라고 적었다. 스크립트에
--no-daemon을 넣지 않은 이유: CI는 한 job의 step 11개가 daemon을
다시 쓴다.
- redis-sdk compose README: cache-redis 칸에 필수 클래스가 둘뿐이다.
build.gradle의 standalone·cluster 목록 다섯으로 맞췄다.
- template-vs-consumer.md: object-storage-aws를 nightly job으로 적었다.
실제는 손으로 실행하고 입력 run_protected_aws를 켤 때만 돈다. 최상위
항목을 더하면 「AGENTS.md 지도를 함께 고친다」고 했지만 지도는 루트
목록을 두지 않고 check-repo-layout.py를 가리킨다. src/ 최상위 폴더일
때만 지도의 src/ 줄을 고친다고 적었다.
동작 변경 없음: workflow는 주석만, 스크립트는 머리 주석만 바꿨다.
검증: scripts/verify.sh docs(노트북) rc=0.
Refs: round9 확인 리뷰(r9-be wave1-r4 「넘길 것」)
main.yml `links`의 lychee 범위에 `src/**/CLAUDE.md`가 있다. 폴더
지역 규칙이 같은 폴더 AGENTS.md로 옮겨 간 뒤 CLAUDE.md는
`@AGENTS.md` 한 줄이라 링크가 하나도 없다. 외부 URL이 있는
`src/**/AGENTS.md`는 범위 밖이라 그 링크가 죽어도 아무 단계도
모른다(상대 링크는 PR의 check-docs.py가 본다).
범위의 그 한 칸을 `src/**/AGENTS.md`로 바꾼다. 범위를 고정하는
DeveloperExperienceContractTest와 gates.md 2절 링크 검사 문장도 함께
바꾼다. 버린 안: 두 패턴을 다 두기 — 링크 없는 파일을 매번 읽을 뿐이다.
위험: 새로 보는 외부 링크는 messaging-kafka AGENTS.md의 Gitea 링크
하나다(코드 span 밖 URL 기준). 익명 GET이 200이라 runner에서도
통과할 것으로 본다. main push의 links job에서 확인한다.
검증: scripts/verify.sh docs(노트북) rc=0. Gradle 쪽
(DeveloperExperienceContractTest)은 PR 실행과 desktop verify.sh pr로 본다.
scripts/verify.sh docs와 docs/work/reference/gates.md는 docs 단계
(check-work-docs.py 포함)가 pr.yml의 prCheck 안에서 돈다고 적는다.
실제 prCheck는 check-docs.py·scripts/tests·check-repo-layout.py만
돌리고 check-work-docs.py는 빠져 있었다. 그래서 operate.md가 줄
상한을 넘은 PR(#12)이 PR 단계 초록으로 main에 들어갔다.
check-repo-layout.py·check-docs.py와 같은 모양의 Exec 태스크
verifyWorkDocs를 만들어 prCheck에 붙였다. 검사 본문은 Gradle 밖
스크립트 그대로다(소유자 결정: 매뉴얼 검사 장치는 scripts/).
버린 안: pr.yml에 python step을 따로 두기 — 단계 job은 Gradle 한 줄
이라는 verifyStrictLaneStages 형식과 어긋나고, verify.sh pr와
workflow가 다른 것을 돌리게 된다.
위험: 파생 서비스도 같은 상한을 PR에서 지켜야 한다
(template-vs-consumer.md에 행을 더했다). 검사는 1초 안쪽이다.
검증: scripts/verify.sh docs(노트북) rc=0. desktop prCheck는 이 커밋
메시지 뒤 PR 실행과 desktop verify.sh pr로 본다.
main(a7e38c10)에 들어온 요청률 제한 한 줄로 docs/work/operate.md가
151줄이 됐다. check-work-docs.py의 상한은 150줄이라
scripts/verify.sh docs가 main에서 실패한다. 같은 줄 끝의
「(W4 BE-OBS-A)」는 새 세션이 따라갈 수 없는 작업 이력 ID다.
같은 절에서 템플릿 전용 게이트 문서를 가리키는 줄과 파생 서비스 쪽
병합·게이트는 그 repo의 일이라는 줄을 한 항목으로 합쳤다. 둘 다
「파생 서비스의 게이트는 누구 몫인가」를 말한다. 요청률 제한 줄은
내용을 그대로 두고 이력 ID만 뺐다.
검증: scripts/verify.sh docs(노트북) rc=0, operate.md 150/150.
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
문제: `JpaPlatformContractSupport`의 Javadoc은 「서버를 JVM에서 공유한다」고
하지만, `start`는 부를 때마다 컨테이너를 새로 띄웠다. 클래스 42개가 저마다 띄워
desktop main 단계에서 platform 계약 lane이 컨테이너 75개(기동 181초), migration
lane이 36개(71초)를 썼다. 이 lane들은 build의 실서버 슬롯 하나 위에서 돌기 때문에,
이 기동 시간이 main job 시간에 그대로 더해졌다. release gate 셋과 nightly
행렬 셋에서도 같은 lane이 major마다 돈다.
고친 방법: Stable major마다 서버 하나를 JVM에서 처음 쓸 때 띄우고, JVM이 끝날 때
멈춘다(shutdown hook, reaper에 기대지 않는다). support마다 그 서버에 database를
하나 만들고(`create database contract_<n>`), close에서 pool을 다 닫은 뒤
지운다(`drop database ... with (force)`). 표·스키마·Flyway 이력은 database에
있어 클래스끼리 섞이지 않는다. 서버 전체에 걸리는 role은 섞이므로 Javadoc에
적었다. role을 만드는 계약은 `PostgreSqlSecurityContractTest` 하나이고, lane마다
JVM이 따로라 이름이 겹치지 않는다.
시험: 소유권 시험에 둘을 더한다. 두 번째 support가 같은 서버, 다른 database를
받는지, close가 database를 지우는지 본다. 공유를 되돌리면 앞의 것이, drop을
빼면 뒤의 것이 실패한다. close 시험의 이름은 「database를 지우기 전에 pool을
닫는다」로 고친다.
버린 대안: 컨테이너 tmpfs·fsync 끄기로 기동만 빠르게. 재시작·장애 복구 계약의
조건이 바뀐다. Testcontainers reuse: CI에서 일부러 끈 설정이다.
위험·한계: 한 클래스가 서버 설정(`ALTER SYSTEM`)을 바꾸면 같은 lane의 다음
클래스가 본다. 지금 그런 계약은 없다(검색으로 확인).
문제: main job은 `./gradlew :mainCheck :integrationCheck --continue` 한 번이다.
integration lane은 build 전체에서 실서버 슬롯 하나를 나눠 쓴다
(ExclusiveRealServerLaneService, maxParallelUsages 1). desktop 측정에서
이 lane들은 시작 약 10분 동안 슬롯을 거의 쓰지 못했다. main 단계 분석이 CPU를
다 쓰는 동안 lane의 컴파일이 뒤로 밀렸기 때문이다. 그 뒤 19분은 lane이 한 번에
하나씩, 한가한 기계에서 돌았다. runner run 132에서도 jpa 계약 lane이 1,134초에야
시작했다.
고른 방법: 줄을 `./gradlew :integrationCheck :mainCheck --continue`로 바꾼다.
Gradle은 준비된 일을 요청한 태스크 순서대로 시작하므로, integration lane의
컴파일이 먼저 돌고 슬롯이 첫 분부터 찬다. 같은 단계, 같은 태스크 집합이다.
build.gradle 단계 선언의 `line`, main.yml, scripts/verify.sh, gates.md,
build-logic/AGENTS.md의 예시 줄을 함께 바꾼다.
측정(desktop, e7be517e, --no-build-cache, 같은 init script):
- 순서 바꾸기 전 1,760초(aeb60339, 거의 같은 트리), 바꾼 뒤 1,484초(−16%), rc=0, 실패 0
- jpa 계약 lane 시작 777초 → 329초. 슬롯이 60초부터 끝까지 찬다.
버린 대안: 슬롯을 둘로 늘리기. 시간에 민감한 web·WebSocket lane이 함께 돌 때
실패해서 하나로 둔 것이다(2026-11-01 리뷰). lane을 두 Gradle 실행으로 나누기:
컴파일을 두 번 한다.
위험·한계: lane이 main 단계 분석과 같은 시간에 돌아 CPU를 나눠 쓴다. 지금도 앞
10분에는 전송 qualification lane이 그렇게 돌았다. desktop 한 번은 실패 0이고,
runner 결과는 PR 본문에 적는다. 이제 main job 시간은 슬롯 lane 시간의 합이
정한다(가장 큰 것은 PostgreSQL 컨테이너 기동, 후속).
문제: nightly의 httpclient-transport는 transport마다 job 하나였다. 행마다 1분이
안 되고, 그 대부분이 job 시작이다(run 100: apache 0.8분, jdk 0.9분).
고른 방법: job 하나에 transport마다 step 하나를 둔다. 줄은 지금과 같다
(`-Phttpclient.contract.transports=<transport>`). `if: always()`라서 앞
transport가 실패해도 뒤가 돌고, 실패한 step 이름이 transport를 말한다.
속성 값이 다르므로 두 번째 실행도 lane을 다시 돈다.
버린 대안: 그대로 두기. 매일 job 시작 한 번을 더 치른다.
검증: YAML을 읽어 step 넷(checkout, setup, apache, jdk)을 확인했다.
문제: nightly의 redis-topology가 행렬 job 11개였다. 행마다 job을 새로 시작해
컨테이너·checkout·JDK·Gradle 시작과 구성을 다시 치렀다. 수동 실행 run 100에서
이 11개가 runner 135분 가운데 26분이었고, 그중 약 3분의 1이 시작 비용이었다.
고른 방법: job 하나에 행마다 step 하나를 둔다. 각 step은 지금과 같은
`bash scripts/ci/redis-topology.sh <topology> <version>` 한 줄이다.
- `if: always()`로 한 행이 실패해도 나머지가 돈다. job이 빨갛게 되고, 실패한
step 이름이 행을 말한다.
- 스크립트가 끝날 때 자기 topology를 내리므로 행끼리 서버를 나누지 않는다.
- 같은 job 안에서 Gradle daemon과 구성 결과를 다시 쓴다.
- timeout은 행 11개를 합친 시간에 맞춰 90분으로 둔다.
문서: 행렬이라고 적던 곳(gates.md, template-vs-consumer.md, redis-sdk compose
README, 스크립트 머리 주석)을 step으로 고친다.
버린 대안: 버전마다 job 하나(3개). 시작 비용을 셋 더 치른다. 한 step에서
셸 반복문으로 돌기: 어느 행이 실패했는지 로그를 뒤져야 하고, 단계 job 규칙과
같은 이유로 셸 문법을 늘리지 않는다.
위험·한계: UI에서 행마다 따로 보이던 초록·빨강이 step 단위가 된다. job 하나가
시간 제한에 걸리면 남은 행이 함께 멈춘다.
검증: YAML을 읽어 step 13개(checkout, setup, 행 11)를 확인했다. runner nightly
측정은 PR 본문에 적는다.
문제: scripts/ci/trivy-scan.sh가 job마다 취약점 DB(133 MB, 약 30초)를
내려받는다. release 이미지 job은 Java 색인(952 MB, 약 2분)도 받는다. run 125의
이미지 job 7.0분 가운데 약 2.8분이 이 두 내려받기였다.
고른 방법: 새 composite action `.gitea/actions/trivy-db-cache`가 Trivy 기본
캐시 디렉터리(~/.cache/trivy)의 db와 java-db를 actions/cache로 복원한다.
pr.yml `done`, main.yml `vulnerabilities`, release.yml 이미지 job의 scan 앞에
둔다. Java 색인은 이미지 job만 받는다(`java-db: "true"`).
- Trivy는 DB 자체의 metadata로 최신인지 판단하고, 아니면 새로 받는다. 복원은
시간을 줄일 뿐이고 아는 권고 목록을 바꾸지 않는다.
- 항목은 덮어쓰지 않으므로 key에 기간을 넣는다. 취약점 DB는 하루, Java 색인은
Trivy가 스스로 3일마다 갱신하므로 3일 단위다. 952 MB가 매일 캐시에 쌓이지 않는다.
- 저장은 main ref만 한다. JDK·Gradle 캐시와 같은 규칙이다. 브랜치가 main이 쓸
DB를 정하지 못한다.
버린 대안: `--skip-db-update`로 캐시만 쓰기. DB가 오래될 수 있어 게이트가 약해진다.
key 하나 고정. 첫 사본이 영원히 남는다.
위험·한계: Java 색인 항목이 runner 캐시(5 GB 상한)의 약 1 GB를 쓴다. 효과는
main이 한 번 저장한 뒤부터 보인다.
검증: 네 YAML을 읽었다. runner 측정은 PR 본문에 적는다.
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
문제: runner 한 대를 모든 repo가 같이 쓴다. main.yml은 cancel-in-progress가
false라서, 새 push가 와도 이전 push run이 끝까지 돌아 runner를 잡는다.
고른 방법: group을 트리거와 ref로 나누고(main-<event>-<ref>) cancel-in-progress를
켠다. push는 같은 브랜치의 이전 push run을, nightly는 이전 nightly를, 수동 실행은
같은 브랜치의 이전 수동 실행을 대기 중이든 실행 중이든 취소한다. 새 run이 이전
run이 볼 것을 다 본다.
Gitea 1.27의 규칙(release/v1.27 models/actions/run.go
CancelPreviousJobsByRunConcurrency): 새 run이 생기면 같은 group의 대기·Blocked
job은 언제나 취소하고, cancel-in-progress가 true일 때만 실행 중인 job도 취소한다.
이 저장소 기록이 그대로다. run 79와 93의 Blocked performance job은 다음 run이
생긴 그 초에 취소됐고, PR run 97의 실행 중 job은 새 head가 들어오고 11초 뒤 runner
로그에 "Job cancelled"를 남기고 멈췄다.
pr.yml은 이미 PR마다 group 하나다(pull_request run의 ref가
refs/pull/<번호>/head). 그 사실을 주석으로만 남긴다.
버린 대안: group을 브랜치 하나로 두기(main-<ref>). push가 돌고 있는 nightly를
취소한다. nightly에는 push run에 없는 job이 있다. pr.yml group 문자열을
github.event.pull_request.number로 바꾸기: 지금 대기 중인 run(124, PR 12·14의
107·115)이 다른 group에 남아 다음 push에 취소되지 않는다.
위험·한계: main에 연달아 병합하면 앞 병합만의 main 단계 결과는 남지 않는다.
뒤 run이 둘을 함께 본다. release.yml은 그대로 취소하지 않는다.
검증: 세 workflow를 YAML로 읽어 concurrency 값을 확인했다. 실제 취소 증거는 이
PR 본문에 run 번호로 적는다.
문제: noble로 올린 release 수동 실행(run 101)의 이미지 검사가 HIGH 2건으로
실패한다. apt와 libapt-pkg6.0t64의 CVE-2026-109518이고, 고친 버전
2.8.4ubuntu0.1이 이미 나왔다. 가장 새로운 eclipse-temurin:21-jre-noble
digest(2026-10-29)에는 아직 들어오지 않았다. 정책은 고칠 수 있는
High/Critical을 실패로 둔다(2026-11-11 소유자 결정).
고른 방법: 실행 단계에서 `apt-get update && apt-get upgrade`로 이미 나온 보안
수정을 받고 패키지 목록을 지운다. desktop에서 같은 digest에 그대로 해 보니
apt가 2.8.4ubuntu0.1이 되었다. 정책 문서에 같은 내용을 적는다.
버린 대안: 예외로 두기. 정책은 아직 고친 버전이 없는 것만 예외로 둔다.
기본 이미지가 따라올 때까지 기다리기. 그동안 release가 막힌다.
위험·한계: 같은 커밋이라도 빌드한 날에 따라 OS 패키지 버전이 달라질 수 있다.
digest 고정은 시작점만 고정한다. SBOM이 그 빌드의 실제 버전을 남긴다.
검증: desktop 이미지 빌드, runner release 수동 실행(이 PR 본문에 적는다).
문제: compose smoke는 lane의 오래 도는 서비스를 `up --wait` 한 번에 함께 띄운다.
앱과 Kafka가 동시에 뜨면 앱의 producer가 아직 연결을 받지 않는 broker에 붙어
재시도 WARN을 남기고, 「기동 로그가 조용하다」 검사가 실패한다. main 수동 run 59
(2026-11-11)의 local-messaging lane이 이것으로 실패했다. 같은 lane이 바로 앞
run과 desktop에서는 통과했다(시간 경쟁).
고른 방법: smoke 스크립트가 app이 아닌 서비스를 먼저 `up --wait`로 healthy까지
띄우고, 그다음 app까지 `up --wait`한다. 모든 lane이 app을 가진다. 개발용
compose.yaml은 바꾸지 않는다.
버린 대안: compose.yaml의 app에 kafka `depends_on`(service_healthy)을 거는 것.
app은 profile이 다른 여러 lane과 개발 환경이 함께 쓰고, 꺼진 profile의 서비스를
기다리게 되면 그 구성이 시작하지 못한다(`required: false`는 Compose 2.20부터).
위험·한계: lane마다 기반 서비스가 healthy가 될 때까지 기다리는 만큼 lane이 조금
길어진다. 그전에도 `up --wait`가 그만큼 기다렸으므로 차이는 작다.
검증: desktop에서 local-messaging lane, runner nightly 수동 실행(이 PR 본문에 적는다).
ContractRegistrySchemaGovernanceTest(모든 레지스트리 행에 legal
compatibility_impact + non-blank required_test 강제)는 @Tag(document-contract)
라 main 스테이지에서만 돈다. PR 레인은 repository-contract이고 그 입력에
docs/**가 빠져 있어, 잘못된 env-keys가 prCheck를 통과하고 병합 뒤 mainCheck
에서야 깨졌다(BE-CONFIG-001이 그렇게 새어 나갔다). 또 필드가 아예 빠지면
Set.of(...).contains(null)이 NPE를 던져 어느 행이 문제인지 알 수 없었다.
- RegistrySchemaPullRequestGateTest(@Tag repository-contract): 같은
RegistryGovernanceCatalog.validate를 PR 레인에서 돌려 위반이 병합 전에
막히게 한다.
- app build.gradle repositoryContractInputs에 docs/registries/**를 더해
레지스트리가 바뀌면 PR 레인이 재실행된다.
- RegistryGovernanceCatalog: compatibility_impact가 null이면 "... must be one
of [...], but was null"로 또렷이 실패한다(NPE 대신). 누락-필드 음성 사례를
ContractRegistrySchemaGovernanceTest에 더했다.
- ManagementActuatorSecurityContractTest javadoc에
actuator-contract:management-address-loopback 항목을 더해 열거를 맞춘다.
버린 대안: required_test가 실제 시험을 가리키는지 범용 강제는 안 넣었다 —
env-keys의 distinct required_test 193개 중 테스트 소스에 literal로 있는 건
7개뿐이라(나머지는 문서적 식별자), 범용 강제는 기존 186행을 깨뜨린다.
위험·한계: PR 레인이 docs/registries 변경에도 재실행된다(의도).
검증(desktop, 고친 env-keys): spotlessCheck·verifyEnvKeys·build-logic test·
documentContractTest·repositoryContractTest(새 게이트)·
ManagementActuatorSecurityContractTest·web-fileserver·web-advanced 모두 rc=0.
RED 재현: 고치기 전 새 게이트가 "env-keys.yaml row MANAGEMENT_SERVER_PORT
compatibility_impact must be one of [...], but was null"로 실패.
env-keys.yaml에서 MANAGEMENT_SERVER_ADDRESS를 MANAGEMENT_SERVER_PORT 항목
중간에 끼워 넣어, PORT의 compatibility_impact와 required_test
(actuator-contract:management-port-separated) 두 줄이 ADDRESS로 넘어갔다.
PORT는 두 칸을 잃어 스키마상 불완전해졌고, ADDRESS의 required_test는 제
시험이 아니라 포트 분리 시험을 가리켰다.
PORT에 두 줄을 되돌리고, ADDRESS의 required_test를
actuator-contract:management-address-loopback로 바꾼다. 이 id는
ManagementActuatorSecurityContractTest의 loopback 기본값 시험 마커로 이미
존재한다(실제 시험을 가리킨다). validation: host_or_ip_address는 env-keys의
자유 서술 규약에 맞는 신규 서술자다(닫힌 집합 강제 없음).
위험·한계: 데이터 수정만. 동작 변화 없음.
검증(desktop): :app-bootstrap:verifyEnvKeys rc=0,
documentContractTest(ContractRegistrySchemaGovernanceTest) rc=0.
문제: 실제 세션 평가(구현 과제 3번)에서 `be-persistence`는 세 번 모두 스킬 목록에
떴지만 부른 세션은 한 번뿐이었다. 나머지 둘은 관련 문서를 직접 읽고 스킬을 건너뛰었다.
규칙은 "어느 스킬인지는 experts.md 3절 표"라고만 해서 한 번 더 읽어야 짝을 알았다.
고른 방법: 규칙에 고칠 것 → 스킬 짝을 한 줄로 적고, 처음 Edit·Write하기 전에 Skill
도구로 부르며 문서를 읽었어도 부른다고 적었다. 버린 대안: 모듈마다 leaf AGENTS.md에
한 줄 더하기(파일 수십 개, 배치 검사와 겹침), 강조어(MUST 등, 과다 호출을 부른다).
위험: 규칙이 붙는 세션마다 약 300토큰이 는다. 여러 분야를 부르면 호출이 는다.
검증: python3 -m unittest discover -s scripts/tests 154건 통과, scripts/verify.sh docs rc=0.
PR #12의 액추에이터·fileserver·web-advanced 수정 커밋이 긴 주석과
assertion 메시지에 포맷 드리프트를 남겨, runner pr / gradle의
:app-bootstrap:spotlessJavaCheck가 깨졌다. 모듈 시험만 돌리고 포맷
게이트(spotlessCheck)를 건너뛴 탓이다.
./gradlew spotlessApply로 바뀐 3개 파일만 재포맷했다. 이미 push된
커밋이라 force push 금지 → squash 대신 새 커밋으로 올린다.
위험·한계: 포맷만 바뀐다(긴 줄의 줄바꿈). 동작·의미 변화 없음.
검증: spotlessCheck rc=0. 바뀐 3개 모듈 시험 재실행 —
ManagementActuatorSecurityContractTest·FileserverAdminControllerRequestBodyValidationTest·WebCodecMapperTest
BUILD SUCCESSFUL (1m8s).
문제: PR 단계를 job 하나로 접자 Trivy filesystem 검사가 Gradle 빌드 뒤에 돌게
됐고, 처음으로 lockfile의 라이선스를 읽었다(run 95). Trivy는 같은 기계의 Gradle
캐시에서만 lockfile의 라이선스를 읽는데, 예전의 따로 된 검사 job에는 캐시가 없어
「High/Critical 라이선스는 막는다」는 검사가 라이선스를 한 번도 본 적이 없었다.
보이게 되자 lockfile마다 SpotBugs·Checkstyle(LGPL), Error Prone dataflow(GPL+CPE),
Jakarta API(EPL/GPL 이중), org.reflections(WTFPL, Trivy 분류 forbidden) 등이 걸렸다.
대부분 배포하지 않는 빌드 도구·시험 구성이다. 한편 릴리스 이미지 검사는 jar의
라이선스를 읽지 못한다(run 62의 Licenses 칸이 모든 jar에서 비어 있다). 그래서 앞
커밋의 「앱 의존성 금지 라이선스는 이미지에서 막는다」도 빈 검사였다.
고른 방법(2026-11-11 소유자 결정 「배포하는 의존성의 금지 라이선스만 실패」):
- filesystem 검사가 `src/bootstrap/app/gradle.lockfile`의 runtimeClasspath 항목
(기본 조립 jar에 실리는 것)만 골라 forbidden(CRITICAL)이면 실패한다.
- Gradle 캐시가 없으면 건너뛴다고 적는다. 캐시가 있는데 라이선스를 하나도 읽지
못하면 빈 검사이므로 실패한다.
- 나머지 라이선스 결과(OS, 도구, 시험, restricted)는 보고만 한다. 이미지 검사의
빈 라이선스 gate는 지우고 보고만 남긴다. 정책 문서를 실제 동작에 맞춘다.
버린 대안: lockfile 전체에 High/Critical을 그대로 막고 예외를 다는 것. Trivy의
라이선스 예외는 라이선스 이름 단위라 도구용 LGPL을 빼면 배포 의존성의 LGPL도 빠진다.
위험·한계: main.yml의 vulnerabilities job은 빌드하지 않아 라이선스 판정을 건너뛴다.
판정은 병합을 막는 PR 단계에 있다. runtimeClasspath 밖에서 jar에 실리는 것(다른
조립)이 생기면 grep 조건을 넓혀야 한다.
검증: runner PR `pr / done`(이 PR 본문에 적는다).
문제: main push는 `main`(17.1분)과 `integration`(17.4분) 두 job을 차례로 돈다
(run 79, runner capacity 1). 두 job이 같은 모듈을 각자 설정·컴파일하고,
integration의 컨테이너 lane은 실서버 슬롯(ExclusiveRealServerLaneService)
하나를 차례로 쓰는 동안 나머지 worker가 놀고, main의 분석(testQualityCheck,
생성 명령 왕복의 안쪽 빌드)은 다른 job이라 그 시간에 겹치지 못한다.
고른 방법: `./gradlew :mainCheck :integrationCheck --continue` 한 줄을 `main` job이
돈다. strict lane 단계 선언에 `line`을 더해, 같은 job을 쓰는 단계가 선언한 한
줄을 나눠 쓸 수 있게 한다. 「단계마다 정해진 한 줄」 규칙은 그대로다: 두 단계
모두 그 정확한 줄을 요구하고, line에는 태스크 경로만 쓸 수 있고 자기 단계를
빼면 설정 단계에서 거절한다(TestKit 시험 셋). scripts/verify.sh의 main 단계도
같은 줄을 쓴다.
버린 대안: 한 job에 두 줄을 차례로 두기. mainCheck가 실패하면 integration이
돌지 않는다. 실서버 슬롯을 둘로 늘리기. 시간에 민감한 lane이 서로 겹쳐 불안정해진다
(그 서비스가 생긴 이유).
위험·한계: 컨테이너 lane이 main 단계의 CPU 작업과 겹친다. 시간에 민감한 system
lane은 지금도 main 단계 안에서 같은 겹침을 견디고, integration lane은 대부분
컨테이너 계약이다. 한 job이 길어져(예상 22~25분) timeout을 240분으로 둔다.
검증: build-logic 시험(desktop), verifyStrictLaneStages --dry-run, runner main 수동
실행의 main job 시간(이 PR 본문에 적는다).
문제: release 수동 실행(run 62)은 gate job 12개를 하나씩 돈다(runner capacity 1).
web·websocket·httpclient 세 gate는 각각 2.4~3.2분인데 그중 약 2분이 checkout,
JDK, Gradle 시작, 세 lane이 함께 쓰는 모듈의 컴파일이다.
고른 방법: `stable-release-gates` job 하나가 세 job의 태스크를 Gradle 한 번에
`--continue`로 돈다. 한 lane이 실패해도 나머지 lane의 결과가 나온다.
app-image-release의 needs와 capability-status 문서의 job 이름을 맞춘다.
버린 대안: JPA·fileserver job까지 합치기. JpaReleaseRenderingTest가 PostgreSQL
major마다 job 하나인 행렬을, FileserverDocumentationCoverageTest와 지원 문서가
fileserver job 이름을 근거로 읽는다. `--tests` 필터를 쓰는 jpa-registry-and-docs는
같은 Gradle 실행에 넣으면 필터가 다른 시험 태스크에도 걸린다.
위험·한계: 세 영역의 로그가 한 job에 섞인다. 실패한 lane 이름은 Gradle이 끝에
모아 적는다.
검증: runner release 수동 실행(이 PR 본문에 적는다).
문제: NegotiatedProtocolContractTest의 JDK transport 시험 둘은 공용 시험 프로필
(연결 500ms, TLS 핸드셰이크 1s)을 그대로 쓴다. 부하가 높을 때 TLS 핸드셰이크와
ALPN이 그 안에 끝나지 않아 HttpConnectTimeoutException으로 실패한다.
main push run 93(2026-11-11, spring70CompatibilityTest lane)과 desktop(부하
18~24, 2026-11-08)에서 봤다. 이 시험이 보는 것은 협상된 프로토콜이지 시간
예산이 아니다.
고른 방법: 두 시험만 넉넉한 TimeoutSettings(연결·핸드셰이크·헤더·유휴 10s,
전체 30s)를 쓴다. DNS 값은 플랫폼이 받는 유일한 값인 기본값으로 둔다. 시간
제한을 보는 다른 시험은 공용 프로필 그대로다.
위험·한계: 공용 프로필을 쓰는 다른 실서버 시험도 같은 부하에서 걸릴 수 있다.
관측된 것은 이 시험뿐이라 이것만 고쳤다.
검증: desktop mainCheck, runner main 수동 실행.
문제: PR 단계는 한 줄만 바꾼 PR도 526개 태스크를 모두 처음부터 돈다(run 64·85,
FROM-CACHE 0). PR은 캐시를 읽기만 하는데, main push는 PR 단계 태스크
(spotbugsMain, test, checkstyle 등)를 돌리지 않아 읽을 항목이 없다. desktop PR
단계 태스크 시간 1,919초 가운데 컴파일 30%, SpotBugs 26%, 시험 35%다.
고른 방법: main.yml에 nightly·수동 전용 job `done`을 둔다. `:prCheck`를 main에서
한 번 더 돌리고, setup-gradle이 job 끝에 그 결과를 캐시에 저장한다. setup-gradle은
캐시 키에 job 이름을 넣고 같은 이름의 항목부터 찾으므로, pr.yml의 job과 같은
이름이어야 PR이 이 항목을 복원한다. 게이트가 아니라 문서(gates.md)에 그렇게 적는다.
버린 대안: main push마다 돌리기. 모든 push가 약 8분 늦어진다. PR이 캐시를 쓰게
하기. 검토 전 코드가 main이 복원할 캐시를 바꿀 수 있다.
위험·한계: 효과는 이 job이 main에서 한 번 돈 뒤부터다(브랜치 수동 실행은 캐시를
저장하지 않는다). 그날 병합으로 바뀐 모듈은 다음 nightly까지 PR에서 다시 돈다.
enhanced 캐시 제공자의 키 규칙은 공개되지 않아, 같은 이름으로 복원되는지는 첫
nightly 뒤 PR 로그의 FROM-CACHE 수로 확인한다. nightly에 약 8분이 더해진다.
검증: 병합 뒤 첫 nightly와 그 뒤 PR의 setup-gradle 복원 줄·FROM-CACHE 수(이 PR
본문에 적는다). desktop에서 캐시가 찬 PR 단계 시간(pr-bc2)으로 효과의 상한을 잰다.