Files
clean-architecture-backend-…/docs/ci-cd/template-vs-consumer.md
DongHyeonka 630f9b860a docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.

고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
  → docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
  원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.

옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.

위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.

검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
2026-11-07 12:15:45 +09:00

2.8 KiB

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

결론

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

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

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

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

대상 무엇을 지키는가
:app-bootstrap:sampleOffTest, ci-quality-gates.yml의 sample-off job sample 픽스처를 지워도 애플리케이션이 빌드·부팅되는가
sample-portfolio leaf 전체 참조 구현
Dockerfile.sample, docker-compose.* 중 sample 관련 위와 동일
docs/design/**, docs/history/** 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록
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 핀 공급망

파생 프로젝트가 할 일

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

아직 하지 않은 것

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