Files
clean-architecture-backend-…/docs/ci-cd/template-vs-consumer.md
T
DongHyeonka 3272faeb38
pr / done (pull_request) Successful in 11m34s
docs(ci): 단계·job 설명을 지금 workflow와 빌드에 맞춘다
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 「넘길 것」)
2026-11-12 21:36:05 +09:00

54 lines
4.1 KiB
Markdown

# Template maintainer와 Template consumer의 검증은 다르다
## 결론
이 저장소에는 성격이 다른 두 종류의 검증이 섞여 있다.
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — optional 모듈 조합이 모두 빌드되는가, 레지스트리가
확장 가능한가.
2. **스켈레톤을 가져다 서비스를 만드는 사람**에게 필요한 검증 — 내 애플리케이션의 테스트,
아키텍처 방향, 보안, 릴리스.
파생 프로젝트가 1번을 그대로 물려받으면, 자기 서비스와 아무 상관 없는 게이트를 평생 유지하게 된다.
이 문서는 어느 쪽이 어느 쪽인지 적어 둔다.
## Template 전용 (파생 프로젝트는 삭제해도 된다)
| 대상 | 무엇을 지키는가 |
| --- | --- |
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
| `main.yml`의 nightly job(`jpa-postgresql`, `httpclient-transport`, `redis-topology`, `fileserver-nfs-ambiguity`, `notification-chaos`, `jpa-next`), 손으로 실행할 때 입력 `run_protected_aws`를 켜야만 도는 `object-storage-aws`, `release.yml`의 영역별 release lane | 템플릿이 광고하는 지원 매트릭스의 근거. 서비스가 그 capability를 쓰면 남기고, 지운 capability의 job은 같이 지운다 |
## Consumer 필수 (파생 프로젝트가 유지해야 한다)
| 대상 | 무엇을 지키는가 |
| --- | --- |
| `architectureCheck` | Clean Architecture 의존 방향. 이 템플릿의 존재 이유 |
| 각 leaf의 `check` | 컴파일 · 단위 테스트 · 포맷 · 스타일 · Error Prone |
| `qualityCheck` | SpotBugs / FindSecBugs |
| `configContractCheck` | 환경변수 계약 |
| `verifyDependencyLocks` | 재현 가능한 의존성 해석 |
| `pr.yml`(`./gradlew :prCheck`, 필수 검사 `pr / done`) | PR 단계. 무엇을 돌리는지는 Gradle 태스크 `prCheck`가 정한다 |
| `main.yml`의 `main`(두 단계를 한 줄로)·`build-logic`·`configuration-cache` job | main 단계(`mainCheck`, `integrationCheck`) |
| `main.yml`의 `performance` job | nightly 성능 단계(`performanceCheck`) |
| `pr.yml` `done`의 Trivy step과 `main.yml`의 `vulnerabilities` job(`scripts/ci/trivy-scan.sh`) | Trivy와 CISA KEV |
| `release.yml` | `releaseCheck`, 이미지 · SBOM · 서명 |
| `scripts/verify.sh` | 사람·세션이 workflow와 같은 단계를 돌리는 진입점 |
| `prCheck`의 `verifyWorkDocs` | 작업 지침의 분량 상한·본문 이력 ID 0·playbook 뼈대(`scripts/check-work-docs.py`). 파생 서비스도 `docs/work/`와 `AGENTS.md`를 받으니 같은 상한을 지킨다 |
| `prCheck`의 `documentCheck`·`testDocumentChecks` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) |
| `main.yml`의 `links` job | 문서의 외부 URL과 상대 링크(lychee) |
| `scripts/check-repo-layout.py`(`prCheck`의 `verifyRepositoryLayout`) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 이 스크립트의 허용 목록을 고친다. `src/` 최상위 폴더면 `AGENTS.md` 지도의 `src/` 줄도 같은 변경에서 고친다(루트 항목은 지도에 목록이 없고 이 스크립트를 가리킨다) |
| action의 전체 URL·full SHA 핀 | 공급망 |
## 파생 프로젝트가 할 일
1. Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + `gradle/modules.json`
에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다.
2. `docs/ci-cd/boundary.md`의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다.
3. `.trivyignore.yaml`과 CODEOWNERS는 그대로 쓴다.
## 아직 하지 않은 것
Template CI와 Generated Application CI를 **물리적으로** 분리하지는 않았다(생성기 없음). 지금은 이
문서가 그 경계다. 생성기를 만든다면, 위 표의 "Template 전용" 열이 생성기가 벗겨 내야 할 목록이다.