154 lines
12 KiB
Markdown
154 lines
12 KiB
Markdown
---
|
|
title: Skeleton Governance (Registry + Verification + Test taxonomy + Scorecard)
|
|
source_type: llm-generated
|
|
status: draft
|
|
confidence: medium
|
|
tags: [skeleton, governance, archunit, testcontainers, scorecard]
|
|
related_projects: [ca-skeleton]
|
|
last_reviewed: 2026-05-22
|
|
---
|
|
|
|
# Skeleton Governance (Registry + Verification + Test taxonomy + Scorecard)
|
|
|
|
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 `project-template` 사용.
|
|
|
|
## Summary
|
|
|
|
스켈레톤 거버넌스는 네 축으로 구성된다. (1) **Contract registry** — markdown SSOT(canonical 운영 계약) + YAML 파생을 단일 진실 원천으로 두고 ADR/스키마 레지스트리 같은 외부 대안을 트레이드오프 관점에서 선택, (2) **Verification suite** — Pact CDC · Spring Cloud Contract · Spring REST Docs · WireMock/Hoverfly 등으로 계약-구현 일치를 자동 검증, (3) **Test taxonomy** — 단위/얇은 슬라이스/통합/E2E/계약/성능의 6 레벨로 피라미드와 트로피의 절충을 명시, (4) **Readiness scorecard** — 11개 릴리즈 차단 게이트의 binary pass/fail로 채택 가능 여부를 판정. 네 축은 서로 참조 관계이며 어느 하나가 빠지면 거버넌스가 깨진다.
|
|
|
|
## Standard (공식 정의)
|
|
|
|
### Contract registry
|
|
|
|
- **Architecture Decision Records (ADR)**: Michael Nygard이 제안한 결정 단위 markdown 문서. 컨텍스트·결정·결과를 명시하며 한번 채택된 ADR은 변경 대신 새 ADR로 교체. branch-note의 "결정/근거/측정값" 패턴과 구조가 유사하다.
|
|
- **Schema/Protobuf/Smithy registry**: 데이터/인터페이스 계약을 IDL로 선언하고 빌드 산출물(jar, 코드)로 분배. 멀티 언어·멀티 팀에서 단일 출처를 강제하는 방식.
|
|
- **Markdown SSOT + YAML 파생**: 운영 계약을 사람이 읽는 markdown 한 곳에만 두고, machine-readable 형식은 빌드 시점에 파생. drift는 빌드 스크립트가 검사.
|
|
- **Code-only registry (enum/annotation)**: ArchUnit·custom annotation에 메타정보를 박는 방식. verifier 가깝지만 사람이 읽기 어려움.
|
|
|
|
### Verification suite
|
|
|
|
- **Pact (Consumer-Driven Contract)**: consumer가 기대를 pact 파일로 선언 → provider가 pact broker에서 받아 검증. 외부 consumer가 많을 때 효과.
|
|
- **Spring Cloud Contract**: provider 쪽 DSL/YAML로 계약 정의 → consumer stub 자동 생성. JVM 단일 생태계에 최적.
|
|
- **Spring REST Docs**: 테스트 통과 시점에 asciidoc 스니펫을 자동 추출. 문서-구현 일치 보장 강하지만 "계약 위반 시 빌드 실패" 강제력은 약함.
|
|
- **ApprovalTests / JSON snapshot**: 출력 스냅샷을 파일로 저장, diff로 회귀 감지. 단일 팀에서 가장 가볍다.
|
|
- **WireMock / Hoverfly**: 외부 의존성 mock/record-replay. 통합 테스트에서 외부 시스템을 격리.
|
|
- **ArchUnit**: 패키지 의존 방향·네이밍·어노테이션 규칙을 JUnit 테스트로 표현해 빌드 차단.
|
|
|
|
### Test taxonomy
|
|
|
|
- **Test pyramid (Mike Cohn, *Succeeding with Agile*)**: 단위 다수 → 서비스 일부 → UI 소수. 비용/속도 기반.
|
|
- **Test trophy (Kent C. Dodds)**: 정적 분석 + 단위 + 통합(가장 두꺼움) + E2E. 통합이 ROI가 높다는 주장.
|
|
- **Honeycomb (Spotify)**: 마이크로서비스에서는 통합 중심이 현실적이라는 변형.
|
|
- **Fitness functions (*Building Evolutionary Architectures*, Ford et al.)**: 아키텍처 특성(레이어 의존성, 성능 SLO, 보안 룰)을 실행 가능한 테스트로 표현.
|
|
- **Testcontainers**: real DB/Kafka/Redis를 Docker로 띄워 통합 테스트. mock의 false confidence를 줄인다는 입장.
|
|
|
|
### Readiness scorecard
|
|
|
|
- **AWS Well-Architected Framework**: 6 pillar(운영·보안·신뢰성·성능·비용·지속가능성)에 대한 review 질문. 점진적 maturity.
|
|
- **CIS Benchmark**: 구성 항목별 pass/fail. 보안 baseline에 가까움.
|
|
- **SLSA (Supply-chain Levels for Software Artifacts)**: build 단계의 무결성을 1~4 레벨로 나눔.
|
|
- **CMMI**: 조직 프로세스 성숙도 1~5.
|
|
- **OpenTelemetry Maturity Model**: observability 도입 단계.
|
|
|
|
스켈레톤은 이 중 **CIS/Well-Architected의 binary pass/fail** 접근에 가깝다. "릴리즈 가능한가"만 판정.
|
|
|
|
## 한계 / 주의점
|
|
|
|
### Registry 축
|
|
|
|
- **Markdown SSOT + YAML 파생**: drift 검증 도구를 **자체 작성**해야 함. CI에 통합되지 않으면 SSOT가 깨져도 모름.
|
|
- **Code-only enum/annotation**: SSOT가 코드 곳곳에 분산. 사람이 한눈에 보기 어렵고 외부 리뷰어가 접근 못 함.
|
|
- **Protobuf/Smithy registry**: IDL 학습·빌드 파이프라인 추가·breaking change 정책까지 필요. 단일 팀 스켈레톤에는 도입 비용이 효익을 초과할 수 있음.
|
|
- **ArchUnit annotations as registry**: verifier 한정. "왜 이 규칙인지"를 표현하지 못함 — registry라기보다 enforcement. (2026-05-22 후속 평가: framework-neutral 부재 / git diff review 약함 / 외부 도구 호환 불가로 ca-tmpl에서 채택 보류, markdown SSOT 유지. [[raw/official-docs/archunit-annotation-as-registry-evaluation]])
|
|
- **DB-stored registry (config service)**: 런타임 의존성·운영 부담. 빌드 타임 결정에는 부적합.
|
|
|
|
### Verification 축
|
|
|
|
- **Pact CDC**: 외부 consumer가 다수일 때 강점. **single-team / single-repo 환경에선 JSON snapshot이 우위** — broker 운영 비용, consumer-provider 협업 오버헤드가 효익을 초과.
|
|
- **Spring Cloud Contract**: JVM 외 consumer가 있으면 stub 활용도 떨어짐.
|
|
- **Spring REST Docs**: 문서 자동 생성에는 좋지만 "계약을 깨면 빌드가 실패"하는 강제력은 약함 — 문서가 코드와 같이 갱신될 뿐, 변경 자체는 막지 않음.
|
|
- **WireMock/Hoverfly**: real system과 mock의 차이로 false green 가능. Testcontainers와 병행 필요.
|
|
- **ArchUnit**: 규칙이 많아지면 테스트 시간·유지보수 부담. annotation 기반 규칙은 어노테이션 누락 시 silently pass.
|
|
|
|
### Test taxonomy 축
|
|
|
|
- **6 level (unit / slice / integration / e2e / contract / performance)**: 전체 budget 5분 등 시간 제약을 두면 레벨이 늘수록 budget 준수가 어려움. **레벨 분리 + 병렬화 + nightly 분리**가 필요.
|
|
- **Testcontainers integration**: real DB/Redis로 mock보다 정확하지만 CI 시간 증가. cache layer warm-up 비용 큼.
|
|
- **Trophy/Honeycomb 모델**: "통합이 ROI 높다"는 주장은 도메인 의존적. 순수 라이브러리·CLI에는 과한 권고.
|
|
- **Fitness functions**: 빌드 차단력은 강하지만 룰을 잘못 짜면 false positive로 개발 흐름을 막음.
|
|
|
|
### Scorecard 축
|
|
|
|
- **Binary pass/fail**: **adoption gate 판단에 적합**. "이 스켈레톤으로 신규 프로젝트를 시작해도 되는가" 같은 컷오프 결정에 단순·명확.
|
|
- 그러나 **점진적 개선이 필요한 기존 시스템 평가**에는 부적합 — "50% 만족"을 표현 못 함. 한 게이트를 못 넘으면 전체가 not-ready로 표시되어, 개선 우선순위를 가리기 어려움.
|
|
- **AWS Well-Architected / CIS**: 운영 중 시스템의 점진적 개선·우선순위 매기기에 적합. 새 스켈레톤 평가엔 항목이 너무 많아 noise.
|
|
- **SLSA**: 공급망에 한정. registry/test 영역은 다루지 않음.
|
|
- **CMMI / OpenTelemetry maturity**: 조직·도메인 단위 평가. 단일 skeleton repo 단위에는 과대.
|
|
|
|
### 4축의 결합 한계
|
|
|
|
- 네 축이 서로 참조되도록 강제하지 않으면 거버넌스가 깨짐. 예: scorecard가 verification suite를 "통과" 표시했는데 실제로는 일부 contract만 검증된 경우. **메타 검증(scorecard ↔ verification ↔ registry 교차 확인)이 별도로 필요**.
|
|
- branch-note ≈ mini-ADR로 운용하면 결정 이력은 보존되나, 시간이 지나며 ADR이 누락된 결정이 코드에 생길 수 있음 — registry 정기 audit 필요.
|
|
|
|
## Project Application
|
|
|
|
- [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — §12 Test Contract, §21 Contract Registry, §27 Readiness Scorecard, §29 Group G-G
|
|
- [[raw/branch-notes/feature-contract-registry-governance]]
|
|
- [[raw/branch-notes/feature-contract-verification-test-suite]]
|
|
- [[raw/branch-notes/feature-test-taxonomy-fixture-contract]]
|
|
- [[raw/branch-notes/feature-implementation-readiness-scorecard]]
|
|
|
|
(실제 구현 여부·검증 등급은 위 project / branch 문서에서 판정. 본 concept 문서는 등급을 직접 매기지 않음.)
|
|
|
|
## Interview Questions
|
|
|
|
- Contract registry의 SSOT 위치를 markdown SSOT vs code-only(enum/annotation) vs IDL(Protobuf/Smithy) 중 어떻게 선택했고, 각 선택의 트레이드오프는 무엇인가?
|
|
- Consumer-Driven Contract(Pact)와 단순 JSON snapshot(ApprovalTests) 중 single-team skeleton에 어느 쪽을 택해야 하고 이유는?
|
|
- Testcontainers를 통합 테스트에 강제하는 이유와, 대신 mock으로 갈 때 잃는 보장은 무엇인가?
|
|
- 단위/슬라이스/통합/E2E/계약/성능의 6 test level이 각각 무엇을 보장하며, budget 5분을 어떻게 지키는가?
|
|
- Readiness scorecard에서 binary pass/fail vs maturity score(AWS WAF·CMMI 류) 중 binary를 택하는 상황은 언제인가?
|
|
- branch-note를 mini-ADR처럼 사용한다는 것은 구체적으로 무엇을 의미하며, ADR과 어떤 부분이 같고 어떤 부분이 다른가?
|
|
|
|
## Do Not Overclaim
|
|
|
|
- "Pact CDC가 항상 우월하다"고 말하지 말 것. **외부 consumer가 다수일 때만 효익이 비용을 넘는다**. single-team 환경에서는 over-engineering이 되며, JSON snapshot이 더 적합할 수 있다.
|
|
- "Binary pass/fail이 절대적 기준"이라고 말하지 말 것. **adoption gate(채택 가능 여부) 한정**이다. 운영 중 시스템의 점진적 개선 평가에는 AWS Well-Architected / CIS 형태가 적합하다.
|
|
- "ArchUnit으로 모든 거버넌스를 강제할 수 있다"고 말하지 말 것. 어노테이션 누락 시 silently pass하는 등 enforcement 한계가 있다.
|
|
- "Spring REST Docs가 계약을 강제한다"고 말하지 말 것. 문서-구현 일치를 자동화할 뿐, 계약 위반 자체를 막는 강제력은 약하다.
|
|
- "Markdown SSOT + YAML 파생이 다른 registry보다 우월하다"고 말하지 말 것. **drift 검증 도구를 자체 작성·CI 통합**해야 비로소 신뢰 가능하다.
|
|
- "Test taxonomy 6 level이면 항상 5분 budget을 지킬 수 있다"고 말하지 말 것. 병렬화·nightly 분리·캐시 전략이 같이 가야 한다.
|
|
|
|
## Sources
|
|
|
|
### Canonical (내 프로젝트 운영 계약)
|
|
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — §12 Test Contract, §21 Contract Registry, §27 Readiness Scorecard, §29 Group G-G
|
|
|
|
### Registry
|
|
|
|
- [[raw/official-docs/registry-adr-official]] — Architecture Decision Records
|
|
- [[raw/official-docs/schema-protobuf-vs-json-evolution]] — IDL registry / 호환성
|
|
- [[raw/official-docs/governance-archunit-official]] — code-only enforcement registry
|
|
- [[raw/official-docs/archunit-annotation-as-registry-evaluation]] — annotation-as-registry 대안 평가 (2026-05-22, ca-tmpl 채택 보류)
|
|
|
|
### Verification
|
|
|
|
- [[raw/official-docs/verification-pact-cdc-official]] — Consumer-Driven Contract
|
|
- [[raw/official-docs/verification-spring-cloud-contract-official]] — provider-side contract
|
|
- [[raw/official-docs/verification-spring-restdocs-official]] — 문서-구현 일치
|
|
- [[raw/official-docs/verification-approvaltests-snapshot-official]] — JSON snapshot 대안
|
|
|
|
### Test taxonomy
|
|
|
|
- [[raw/official-docs/test-taxonomy-practical-pyramid-fowler]] — Practical Test Pyramid
|
|
- [[raw/official-docs/test-taxonomy-testcontainers-official]] — Testcontainers
|
|
- [[raw/official-docs/dx-testcontainers-java-best-practices]] — Testcontainers Java DX
|
|
- [[raw/company-tech-blogs/test-pyramid-vs-trophy-kent-dodds]] — Trophy 모델 (회사 블로그 — 공식 기준 아님)
|
|
|
|
### Scorecard
|
|
|
|
- [[raw/official-docs/scorecard-aws-well-architected]] — Well-Architected Framework
|
|
- [[raw/official-docs/scorecard-cis-benchmarks-slsa]] — CIS / SLSA
|
|
- [[raw/official-docs/scorecard-opentelemetry-maturity]] — OTel Maturity Model
|