---
title: blog-topic / executable-clean-architecture-onboarding-2026-06-25
source_type: blog-topic
status: raw
related_branches: [feature-domain-feature-onboarding-contract]
related_projects: [ca-tmpl]
tags: [blog-topic, ca-tmpl, architecture, testing, archunit, clean-architecture, multi-module]
created: 2026-06-25
status_label: ready-for-canonical
target_audience: backend-engineer
inspiration_url:
archive_url:
---

# blog-topic: executable-clean-architecture-onboarding-2026-06-25

> Layer: `raw/blog-topics/` — multi-module Clean Architecture onboarding checklist 를 실행 가능한 테스트로 만든 경험 글감.

## Parent / 부모

- [[raw/branch-notes/feature-domain-feature-onboarding-contract]] — 문서 중심 onboarding contract를 ArchUnit/JUnit dry-run으로 구현한 작업에서 파생.

## 트리거 / Trigger

- 트리거 유형: `branch-work`
- 트리거 날짜: 2026-06-25
- 트리거 연결 노트: [[raw/branch-notes/feature-domain-feature-onboarding-contract]]

## 글감 / Topic seed

- 한 문장 요지: Clean Architecture 체크리스트는 README에만 있으면 약하고, test-only dry-run slice와 negative fixture로 만들면 새 도메인 추가 경계가 CI에서 반복 검증된다.
- 예상 제목 후보:
  - Clean Architecture 온보딩 체크리스트를 테스트로 바꾸기
  - 새 도메인 추가가 아키텍처를 깨지 않는다는 걸 어떻게 증명할까

## 핵심 주장 후보 / Claim candidates

- 사실 후보:
  - ca-tmpl은 read-only/write onboarding slice를 분리해 정의한다 — 근거 후보: [[raw/branch-notes/feature-domain-feature-onboarding-contract]] D3, D4.
  - 이번 구현은 `DomainFeatureOnboardingContractTest`와 `CleanArchitectureTest` rule로 해당 계약을 검증한다 — 근거 후보: [[raw/branch-notes/feature-domain-feature-onboarding-contract]] §구현 결과.
- 경험 후보:
  - `./gradlew verifyCleanArchitectureDependencies`, ArchUnit focused test, focused onboarding suite, 전체 `./gradlew test`까지 통과시켰다 — 근거 후보: [[raw/branch-notes/feature-domain-feature-onboarding-contract]] §Verification commands.
- 의견/해석 후보:
  - “문서로 합의한 아키텍처”와 “실제로 실패하는 guardrail” 사이에는 큰 차이가 있다. 단, 모든 것을 정적 분석으로 잡을 수는 없으므로 Open Risk를 문서화해야 한다.

## Outline seed

1. 문제: 새 도메인 추가는 controller-only shortcut으로 무너지기 쉽다 — 체크리스트만으로는 반복 검증이 어렵다.
2. 접근: read-only/write 최소 slice를 test-only Ticket fixture로 만든다 — 실제 production domain을 추가하지 않고도 계약을 검증한다.
3. 실패도 데이터로 만든다 — missing transaction boundary와 shared-contract domain pollution을 negative fixture로 잡는다.
4. 한계: ArchUnit direct-call 분석은 helper 뒤를 못 본다 — guardrail과 review의 경계를 같이 적어야 한다.

## Canonical 전환 후보 / Canonical extraction candidates

- `wiki/projects/ca-tmpl/domain-feature-onboarding-guardrails.md` 후보:
  - ca-tmpl에서 새 도메인 기능을 추가할 때 통과해야 하는 read/write dry-run guardrail.
- `wiki/concepts/executable-architecture-guardrails.md` 후보:
  - 아키텍처 문서 계약을 JUnit/ArchUnit positive/negative fixture로 전환하는 일반 패턴.
- 필요한 추가 검증:
  - 실제 downstream 새 도메인 branch에서 false positive/negative 관찰.
  - `sampleOffTest`까지 포함한 check matrix에서 시간 비용 측정.

## Sources / 근거 후보

- [[raw/branch-notes/feature-domain-feature-onboarding-contract]] — 구현 결정과 local verification evidence.
- [[raw/errors/gradle-wrapper-sandbox-lock-2026-06-25]] — sandboxed Gradle 검증 문제.
- [[raw/interviews/clean-architecture-domain-onboarding-guardrails]] — 예상 면접 질문 원석.

## 미해결 / Unknown

- 아직 확인해야 할 사실: downstream fork에서 fixture 없이 실제 production domain slice를 추가했을 때 rule coverage가 충분한지.
- 과장하면 안 되는 부분: 이 작업은 local verification이며 운영 검증이나 보편 표준 증명은 아니다.
- 블로그로 쓰기 전에 필요한 canonical 정제: `wiki/projects/ca-tmpl/`에 project fact로 승격 후 blog derive.

## Decision / 처리 결정

- 액션: `promote-to-canonical`
- 이유: `wiki/projects/ca-tmpl/clean-architecture-package-layout.md` 에 executable onboarding guardrails 글감으로 반영했다.
- 다음 단계: source canonical이 `verified` 상태이므로 이후 `blogify` 대상으로 삼을 수 있다. 단 운영 검증이나 보편 표준 증명처럼 쓰지 않는다.

## Related / 관련

- 관련 branch: [[raw/branch-notes/feature-domain-feature-onboarding-contract]]
- 관련 error: [[raw/errors/gradle-wrapper-sandbox-lock-2026-06-25]]
- 관련 interview prep: [[raw/interviews/clean-architecture-domain-onboarding-guardrails]]
- derived blog: 생성 전