87 lines
4.9 KiB
Markdown
87 lines
4.9 KiB
Markdown
---
|
|
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: 생성 전
|