--- title: ca-tmpl - Skeleton Governance 결정 (Registry + Verification + Test + Scorecard) source_type: project status: verified confidence: high tags: [ca-tmpl, governance, archunit, testcontainers, scorecard, actually-implemented, locally-verified] related_projects: [ca-tmpl] last_reviewed: 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 참조 패턴에 일반화하지 않는다. ## 관련 개념 - [[wiki/concepts/skeleton-governance-registry-verification-test-scorecard]] ## Sources - [[raw/project-notes/ca-skeleton-operational-contract]] — §12 (Verification), §21 (Registry), §27 (Scorecard), §29 G-G (Test taxonomy) - [[raw/branch-notes/feature-contract-registry-governance]] - [[raw/branch-notes/feature-contract-verification-test-suite]] - [[raw/blog-topics/contract-verification-suite-release-gates-2026-07-02]] — contract verification suite/release gate 블로그 글감 raw seed - [[raw/branch-notes/feature-implementation-readiness-scorecard]] - [[raw/blog-topics/binary-readiness-scorecard-clean-architecture-skeleton-2026-07-02]] — binary readiness scorecard 블로그 글감 raw seed - [[raw/blog-topics/contract-registry-schema-owner-vs-row-owner-gate-2026-06-20]] — registry schema owner vs row owner gate 블로그 글감 raw seed - [[raw/blog-topics/test-taxonomy-archunit-enforcement-2026-06-19]] — test taxonomy ArchUnit enforcement 블로그 글감 raw seed - [[raw/blog-topics/archunit-violations-as-data-pattern-2026-05-28]] — violations-as-data ArchUnit fixture 블로그 글감 raw seed - [[raw/blog-topics/archunit-testcompileonly-fixture-annotation-pattern-2026-06-02]] — ArchUnit `testCompileOnly` fixture annotation-only 패턴 블로그 글감 raw seed - [[raw/branch-notes/feature-test-taxonomy-fixture-contract]] - [[raw/branch-notes/feature-implementation-readiness-scorecard]] ## Cluster / 묶음 - [[wiki/blog/ca-tmpl-skeleton-governance-registry-verification-test-scorecard-2026-07-02]]