donghyeon.kang/clean-architecture-backend-template

Files

T

DongHyeonkaandClaude Opus 5 ef947e5bb0 refactor(build,ci): 현재 상태 검증을 걷어내고 불변조건만 남기는 검증 표면 축소

외부 리뷰("현재 상태를 유지하기 위한 검증이 너무 많고, 그 검증 자체를
다시 검증하는 구조까지 생겼다")를 설계 문서로 정리하고 코드로 반영한다.
설계·판단 근거는 docs/superpowers/specs/2026-09-16-verification-surface-reduction-design.md.

삭제
- .github/ci-gate-matrix.yml(1,025줄) + verify-gate-matrix.sh(568줄):
  Gradle task graph와 workflow graph에 이미 있는 정보의 3중 복제
- verify-gradle-wrapper.sh(799줄): workflow 바이트 해시 잠금.
  wrapper 검증은 gradle/actions/wrapper-validation(full SHA 핀)에 위임
- DeveloperExperienceContractTest 등의 CI YAML mutation 테스트:
  애플리케이션 test suite가 GitHub Actions YAML 파서를 검증하던 계층 역전
- 문서 drift 파서: verifyReadmeCommands, verifyRunbookReferences,
  verifyDocumentedLeafCount, verifyTestSourceSetRegistry
- 빈 레지스트리를 지키던 커스텀 YAML 파서: verifyTrivyignore,
  verifyQuarantineSunset, flaky-quarantine.yaml
- verifyConfigurationPropertiesProcessor, verifyOneTypePerFile:
  각각 ca.spring-config convention과 Checkstyle OneTopLevelClass가 대체
- 정상 입력으로도 성공할 수 없던 messaging always-fail task
- ModuleRegistry의 JSON 필드 집합 정확 일치, sample-portfolio negative guard

이동
- java/quality/spring 공통 설정을 configure(subprojects) 블록에서
  ca.java-conventions / ca.quality-conventions / ca.java-library /
  ca.spring-library convention plugin으로
- 아키텍처 검증을 ca.architecture로, JPA·messaging qualification을
  gradle/qualification/ 아래로, verifyEnvKeys를 :app-bootstrap 소유로

완화
- Git revision은 releaseCheck·아카이브 생성에서만 요구. 일반 빌드는 SNAPSHOT
- SpotBugs/FindSecBugs는 로컬 check에서 빼고 qualityCheck 레인으로

task 계층
- leaf check는 그 leaf만. architectureCheck / qualityCheck /
  configContractCheck / integrationCheck / ci / releaseCheck로 이름 분리

CI
- _reusable-gradle.yml 신규. checkout + wrapper validation + JDK/캐시 공통화
- fileserver-release.yml -> fileserver-certification.yml (CD가 아니라 certification)
- GitHub Actions = CI + artifact, Argo CD = CD 경계를 docs/ci-cd/boundary.md로 고정

순증감 +3,274 / -7,483.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-16 20:33:19 +09:00

2.8 KiB

Raw Blame History

Template maintainer와 Template consumer의 검증은 다르다

결론

이 저장소에는 성격이 다른 두 종류의 검증이 섞여 있다.

스켈레톤을 만드는 사람에게 필요한 검증 — sample 모듈이 정말 제거 가능한가, optional 모듈 조합이 모두 빌드되는가, 레지스트리가 확장 가능한가.
스켈레톤을 가져다 서비스를 만드는 사람에게 필요한 검증 — 내 애플리케이션의 테스트, 아키텍처 방향, 보안, 릴리스.

파생 프로젝트가 1번을 그대로 물려받으면, 자기 서비스와 아무 상관 없는 게이트를 평생 유지하게 된다. 이 문서는 어느 쪽이 어느 쪽인지 적어 둔다.

Template 전용 (파생 프로젝트는 삭제해도 된다)

대상	무엇을 지키는가
`:app-bootstrap:sampleOffTest`, `ci-quality-gates.yml`의 `sample-off` job	sample 픽스처를 지워도 애플리케이션이 빌드·부팅되는가
`sample-portfolio` leaf 전체	참조 구현
`Dockerfile.sample`, `docker-compose.*` 중 sample 관련	위와 동일
`docs/superpowers/**`	이 템플릿을 만든 과정의 설계/계획 기록
`gradle/qualification/**`	이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계
`-certification.yml`, `-qualification.yml`, `jpa-next-*.yml`	템플릿이 광고하는 지원 매트릭스의 근거

Consumer 필수 (파생 프로젝트가 유지해야 한다)

대상	무엇을 지키는가
`architectureCheck`	Clean Architecture 의존 방향. 이 템플릿의 존재 이유
각 leaf의 `check`	컴파일 · 단위 테스트 · 포맷 · 스타일 · Error Prone
`qualityCheck`	SpotBugs / FindSecBugs
`configContractCheck`	환경변수 계약
`verifyDependencyLocks`	재현 가능한 의존성 해석
`dependency-vulnerability.yml`	dependency-review + Trivy
`ci-quality-gates.yml`	PR 게이트
`release.yml`	이미지 · SBOM 생산
action의 full SHA 핀	공급망

파생 프로젝트가 할 일

Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + config/architecture/modules.json 에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다.
docs/ci-cd/boundary.md의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다.
.trivyignore.yaml과 CODEOWNERS는 그대로 쓴다.

아직 하지 않은 것

Template CI와 Generated Application CI를 물리적으로 분리하지는 않았다(생성기 없음). 지금은 이 문서가 그 경계다. 생성기를 만든다면, 위 표의 "Template 전용" 열이 생성기가 벗겨 내야 할 목록이다.

2.8 KiB Raw Blame History