Files

T

2026-07-25 12:53:13 +09:00

title, source_type, status, related_branches, related_projects, tags, created, status_label, target_audience, inspiration_url, archive_url

title

source_type

status

related_branches

related_projects

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으로 구현한 작업에서 파생.

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

사실 후보:
- 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를 문서화해야 한다.

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

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에서 시간 비용 측정.

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

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