147 lines
11 KiB
Markdown
147 lines
11 KiB
Markdown
---
|
||
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 / 묶음
|
||
|
||
<!-- GENERATED: derived-blogs:start -->
|
||
- [[wiki/blog/ca-tmpl-skeleton-governance-registry-verification-test-scorecard-2026-07-02]]
|
||
<!-- GENERATED: derived-blogs:end -->
|