donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
cfd84875bf9799a0d2d11d78d2a6201ea7e255f1
llm-wiki/wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard.md
T

11 KiB
Raw Blame History

title, source_type, status, confidence, tags, related_projects, last_reviewed
title source_type status confidence tags related_projects last_reviewed
ca-tmpl - Skeleton Governance 결정 (Registry + Verification + Test + Scorecard) project verified high
ca-tmpl
governance
archunit
testcontainers
scorecard
actually-implemented
locally-verified
ca-tmpl
2026-07-02

ca-tmpl - Skeleton Governance 결정 (Registry + Verification + Test + Scorecard)

Layer: wiki/projects/ — 내 프로젝트 사실. 일반 개념은 wiki/concepts/skeleton-governance-registry-verification-test-scorecard 참고.

프로젝트 컨텍스트

ca-tmpl skeleton — Clean Architecture 기반의 재사용 가능한 Spring Boot 템플릿 프로젝트. 이 문서는 그 중 governance 4축(Registry / Verification / Test taxonomy / Scorecard)의 설계 결정을 기록한다.

  • 현재 단계: C2 부분 구현 + 로컬 검증 완료.
  • scope: markdown SSOT + YAML registry + 11 release-blocking gate + 6 test level + binary pass/fail scorecard (15 area).
  • registry yaml 위치: /home/donghyeon/workspace/ca-tmpl/docs/registries/ (LLM Wiki 외부, ca-tmpl 저장소 내부).
  • 목적: skeleton을 "남에게 줘도 망가지지 않는 상태"로 굳히기 위한 governance 계약을 명문화. 검증·테스트·도입 준비도가 branch-note ≈ mini-ADR 한 장과 1:1로 묶이도록 설계.

자세한 운영 계약은 raw/project-notes/ca-skeleton-operational-contract (§12 / §21 / §27 / §29 G-G) 참고.

실제 구현 내용 (actually-implemented)

  • docs/registries/ 아래 error-codes.yaml, env-keys.yaml, secrets-classification.yaml, headers.yaml, mdc-keys.yaml, metrics.yaml, capabilities.yaml가 존재한다.
  • .github/ci-gate-matrix.yml가 gate ↔ owner ↔ mechanism matrix를 코드화한다.
  • ContractRegistrySchemaGovernanceTest, OutboxStatusRegistryContractTest, EnvProfileMatrixContractTest 등 registry/gate contract tests가 존재한다.
  • CleanArchitectureTest, DisabledAdapterArchitectureTest, NamingConventionTest, ProductionClassImportOption, sample-off test source set이 architecture/test taxonomy 일부를 강제한다.
  • scorecard 자체는 아직 별도 CI badge/자동 산출물까지 구현되지 않았다.

로컬/dev 검증 (locally-verified)

  • ./gradlew check 통과(2026-07-02, BUILD SUCCESSFUL, 114 tasks).
  • 실행 중 verifyCleanArchitectureDependencies, verifyEnvKeys, verifyQuarantineSunset, verifyReadmeCommands, verifyTrivyignore가 OK로 통과했다.
  • outbox/idempotency integration tests가 PostgreSQL Testcontainers 기반으로 실행되어 contract 일부를 검증한다.

운영 검증 (prod-verified)

없음. ca-tmpl은 운영 배포 대상 자체가 아닌 skeleton/template.

문서/계획만 존재 (documented-only / planned)

아래 항목은 구현된 registry/gate/test taxonomy slice와 아직 자동화되지 않은 scorecard/coverage slice를 분리한다.

Registry (canonical §21)

  • 결정: markdown SSOT (사람이 읽는 정의) + YAML generated constants (코드가 읽는 사본). 두 곳을 둬도 SSOT는 markdown 한 곳.
  • 7-column schema 정의: key / kind / description / since / status / owner / notes.
  • 7개 yaml: error.yaml, env.yaml, secrets.yaml, headers.yaml, mdc.yaml, metrics.yaml, capabilities.yaml.
  • 구현됨: YAML registry files + schema governance test. 남음: generated constants/code generator 전체와 markdown ↔ yaml 완전 drift gate.
  • ArchUnit annotation-as-registry 대안 평가 (2026-05-22) — markdown SSOT 유지. framework-neutral + git diff review + 외부 도구 호환 근거. ArchUnit은 verifier 역할 한정. 상세: raw/official-docs/archunit-annotation-as-registry-evaluation.
  • 근거: raw/branch-notes/feature-contract-registry-governance.

Verification (canonical §12)

  • 결정: 11개 release-blocking gate + JSON snapshot 기반 contract 검증. Pact CDC는 out-of-scope — single-team / 단일 release train에는 over-engineering.
  • gate 예시: ArchUnit / dependency / API snapshot / error envelope / observability / OpenAPI / Testcontainers 강제 / 등.
  • 구현됨: 다수 Gradle verification task와 .github/ci-gate-matrix.yml. 남음: 11 gate 전체의 hosted release-blocking 이력과 gate별 실패 메시지 표준 완전성 확인.
  • 근거: raw/branch-notes/feature-contract-verification-test-suite.

Test taxonomy (canonical §29 G-G)

  • 결정: 6 level test taxonomy. Testcontainers는 integration level부터 강제 (unit/slice에서 금지).
  • src/testFixtures 사용: fixture 코드가 main classpath에 새는 것 방지.
  • 5min budget: skeleton local fast feedback loop 목표.
  • 구현됨: sample-off source set, sampleFixture, Testcontainers integration tests, ArchUnit fixture pattern. 남음: 6 level 전체 budget 측정/강제 mechanism.
  • 근거: raw/branch-notes/feature-test-taxonomy-fixture-contract.

Scorecard (canonical §27)

  • 결정: binary pass/fail (maturity 점수 X) × 15 area × 1:1 branch evidence (각 area는 branch-note 1개를 evidence로 지목).
  • 도입 gate 한정 — "이 skeleton을 도입해도 되는가" 여부 판단용. 운영 SLO나 코드 품질 점수 도구가 아님.
  • 남음: scorecard CI step, badge, branch-note ↔ area 매핑 자동 검증.
  • 근거: raw/branch-notes/feature-implementation-readiness-scorecard.

면접에서 말할 수 있는 범위

자신 있게 답할 수 있는 질문

  • "registry의 SSOT를 markdown에 두는 이유와 code-generated YAML의 역할 분리"
  • "Pact CDC를 도입하지 않고 JSON snapshot으로 contract를 잡은 trade-off (단일 팀 / 단일 release train 한정)"
  • "Testcontainers를 integration level부터 강제하고 unit/slice에서 금지하는 이유"
  • "6 level test taxonomy의 각 level이 무엇을 책임지는지"
  • "binary pass/fail vs maturity score를 선택한 이유 — 도입 gate 용도 한정"
  • "branch-note를 mini-ADR로 보고 scorecard area와 1:1로 묶는 설계 의도"

적당히 답할 수 있는 질문

  • "정식 ADR vs branch-note의 관계 — branch-note가 ADR의 경량 대체로 어디까지 커버되는가"
  • "fitness function 도입 검토 — ArchUnit 외 어떤 측정 지표를 자동화 후보로 보고 있는가"

답하면 안 되는 질문 (모른다고 해야 함)

  • "verifier task를 직접 구현해 봤는가" → 일부 구현. verifyCleanArchitectureDependencies, verifyEnvKeys, verifyQuarantineSunset, verifyTrivyignore 등은 로컬 check에 포함됨.
  • "scorecard 자동화를 CI에서 운영해 봤는가" → ❌. 미작성.
  • "5min test budget을 실제로 측정해 봤는가" → ❌. 정책 선언이며 budget gate는 별도 구현 필요.
  • "11 gate가 실제로 release를 차단한 사례" → ❌. 없음.

과장 금지 지점

  • "Pact가 항상 우월하다" → ❌. ca-tmpl 같은 single-team / 단일 release train 환경에는 over-engineering. JSON snapshot이 비용 대비 충분.
  • "binary pass/fail이 모든 품질 측정의 절대 기준" → ❌. skeleton 도입 gate 한정. 운영 SLO나 코드 품질 maturity 측정에 그대로 쓰면 안 됨.
  • "11 gate 검증 자동화를 완성했다" → ❌. 일부 gate는 구현됐지만 전체 완성으로 쓰지 않는다.
  • "Testcontainers 5min budget을 보장한다" → ❌. 정책 선언, 실측 / 강제 mechanism 없음.
  • "registry YAML이 SSOT다" → ❌. markdown이 SSOT, YAML은 generated constants.

Blog-topic ingest: verification/scorecard 묶음 (2026-07-02)

raw/blog-topics/contract-verification-suite-release-gates-2026-07-02 는 skeleton 운영 계약을 문서로만 두지 않고 release-blocking test suite로 묶는 이유를 블로그로 풀기 위한 raw seed다.

  • canonical 반영 범위: verification suite/release gate 글감을 governance/registry/scorecard canonical에 연결했다.
  • blogify 전 조건: 충족. 이 문서는 2026-07-02 기준 코드와 ./gradlew check로 검증됨. 단 hosted CI/prod evidence는 분리한다.
  • 블로그 전 과장 방지: verifier 자동화나 release 차단 운영 사례가 이미 있다고 쓰지 않는다. 정의/정책/로컬 검증 범위를 구분한다.
  • raw/blog-topics/binary-readiness-scorecard-clean-architecture-skeleton-2026-07-02: 좋아 보이는 skeleton과 도입 가능한 skeleton을 15개 영역의 binary gate로 분리하는 글감. local readiness를 production readiness나 외부 채택 가능성으로 확대하지 않는다.
  • raw/blog-topics/contract-registry-schema-owner-vs-row-owner-gate-2026-06-20: contract registry에서 schema owner와 row owner를 분리하고 schema gate가 reference row 면제를 명시적으로 검증해야 하는 이유를 다루는 글감. schema 정합을 token 사용 강제나 runtime verification으로 확대하지 않는다.
  • raw/blog-topics/test-taxonomy-archunit-enforcement-2026-06-19: test taxonomy를 README 컨벤션이 아니라 ArchUnit import graph rule로 강제하는 글감. 테스트 품질 전체 보장이 아니라 level misplacement와 dependency boundary 방지로 제한한다.
  • raw/blog-topics/archunit-violations-as-data-pattern-2026-05-28: fitness function 자체를 negative fixture로 검증하는 글감. governance/test scorecard 관점에서는 non-vacuity proof pattern으로 연결한다.
  • raw/blog-topics/archunit-testcompileonly-fixture-annotation-pattern-2026-06-02: testCompileOnly 타입을 ArchUnit fixture에서 annotation-only로 안전하게 참조하는 글감. 모든 fixture 참조 패턴에 일반화하지 않는다.

관련 개념

Sources

Cluster / 묶음

Reference in New Issue View Git Blame Copy Permalink