Files
clean-architecture-backend-…/docs/work/reference/gates.md
T
DongHyeonka 63c63413d1 docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).

고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
  AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
  곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
  내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
  reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
  (new-feature, improve, research-design, docs-writing, operate, delegate, 모두
  같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
  decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
  review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
  나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
  improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
  수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
  수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
  +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
  README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
  (reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
  docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
  CLAUDE.md 「Layer workflow」를 가리키던 줄).

위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.

검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
  playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
  .guidanceNamesTheArchitectureSourceSetTask가 기대하는
  "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
  이 커밋을 push한 뒤 desktop에서 돌린다
2026-11-06 19:58:44 +09:00

11 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 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). main·nightly에서 돈다 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 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와 같은 명령으로 검증한다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다.

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의 판정이 같은지 비교한다.