donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
6c53ded9cb70f2d7cf3e66ff50d42f2d151c98b1
llm-wiki/vault/30-knowledge/concepts/skeleton-governance-registry-verification-test-scorecard.md
T

12 KiB
Raw Blame History

title, source_type, status, confidence, tags, related_projects, last_reviewed
title source_type status confidence tags related_projects last_reviewed
Skeleton Governance (Registry + Verification + Test taxonomy + Scorecard) llm-generated draft medium
skeleton
governance
archunit
testcontainers
scorecard
ca-skeleton
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

(실제 구현 여부·검증 등급은 위 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 (내 프로젝트 운영 계약)

Registry

Verification

Test taxonomy

Scorecard

Reference in New Issue View Git Blame Copy Permalink