source-command-align

name	source-command-align
description	Dallyrun 멀티모듈 MVI 아키텍처 정렬 점검

source-command-align

Use this skill when the user asks to run the migrated source command align.

Command Template

Architecture Alignment

새 파일을 만들거나 기존 파일을 리팩터링하기 전에 아래 체크리스트로 모듈 경계·계층 책임·의존 방향을 검증한다. 어긋나면 작업을 멈추고 사용자에게 어디에 두는 게 맞는지 먼저 합의한다.

1. 모듈 경계 (Domain Isolation)

이 로직이 어떤 모듈에 속하는지 먼저 결정한다.

Feature 모듈 (feature:<name>)

화면 단위 기능. UI · ViewModel · Navigation 만 들어간다.

• 기존 feature 의 확장인가? → feature/<name>/ 안에 둔다.
• 새 화면인가? → /new-feature <name> 으로 스캐폴딩 후 시작.
• 두 feature 가 서로 직접 import 하면 안 된다. 공유가 필요하면 core:* 로 끌어올린다.

Core 모듈 (core:<name>)

여러 feature 에서 공유되는 기반.

모듈	들어가는 것	들어가면 안 되는 것
core:model	순수 도메인 모델 (data class, sealed, value class)	Android 의존, 어노테이션 (@Serializable 등 네트워크 전용도 금지)
core:domain	UseCase, Repository 인터페이스	Repository 구현, Retrofit/Room
core:data	Repository 구현, DataStore, 토큰 저장소	Compose UI, ViewModel
core:network	Retrofit API, DTO, toDomain() 매퍼, Auth 인터셉터/인증기	UseCase, Repository 구현
core:database	Room DAO/Entity, PagingSource DAO, 로컬 캐시, schema 관리	네트워크, UI
core:designsystem	Material3 theme, 색상/타이포 토큰	비즈니스 도메인 모델
core:ui	feature 간 재사용되는 Compose 컴포넌트	feature 특화 화면, ViewModel
core:common	DallyrunViewModel, UiState, UiEvent, SideEffect MVI base	도메인 로직, Repository
core:testing	MainDispatcherRule, TestData, MockK/Turbine re-export	프로덕션 코드

새 core 모듈이 필요한지부터 의심하라 — 대부분은 기존 모듈 안에 자리가 있다. 새 모듈 추가는 별도 PR 로 분리.

2. 계층 책임 (Layered Responsibility)

MVI · Clean Architecture 기준 계층별 책임.

파일	책임	금지
*Screen.kt	stateless Composable. state 를 파라미터로 받고 이벤트는 (Event) -> Unit 으로 위임	ViewModel 직접 호출, 비즈니스 로직, suspend 호출
*Route.kt	viewModel() 주입, collectAsStateWithLifecycle(), SideEffect 수집	UI 그리기 (Screen 에 위임)
*ViewModel.kt	UI state 관리, onEvent() 핸들링, UseCase 호출	Retrofit/Room 직접 호출, Compose 의존, Dispatchers.IO 직접 사용 (UseCase 가 main-safe)
*Contract.kt	UiState, UiEvent, SideEffect 정의	로직
*Navigation.kt	type-safe Navigation route + navGraphBuilder.<feature>() 확장	라우트 외 로직
*UseCase.kt (core:domain)	단일 비즈니스 동작, Repository 조합	UI/Compose, DTO
*Repository.kt 인터페이스 (core:domain)	도메인 모델만 노출	DTO, Retrofit 타입
*RepositoryImpl.kt (core:data)	DTO ↔ Domain 매핑, 네트워크/DB 조합, suspend main-safe	UI
*Api.kt (core:network)	Retrofit suspend 함수	매핑, 비즈니스 로직
Network*.kt DTO (core:network)	@Serializable DTO + toDomain()	비즈니스 동작

3. 의존 방향 (Dependency Rule)

feature:* ──► core:domain ──► core:model
    │            ▲
    ├──► core:common, core:designsystem, core:ui
    └──► (테스트) core:testing

core:data ──► core:domain, core:model, core:network, core:database
core:database ──► core:model
core:network ──► core:model
core:ui ──► core:designsystem, core:model

금지:

• core:model 이 다른 무언가에 의존 (Android, 어노테이션 라이브러리 포함)
• core:domain 이 core:data / core:network 에 의존 (인터페이스만 정의, 구현은 data 가 책임)
• feature:* 간 직접 의존
• core:* 모듈 간 순환 의존
• core:designsystem 이 도메인 모듈에 의존

새 모듈 의존이 추가되면 core/AGENTS.md 의 의존성 다이어그램과 core 모듈 표도 같이 업데이트.

4. MVI 컨벤션

• ViewModel 은 DallyrunViewModel<UiState, UiEvent, SideEffect> 를 상속.
• 상태 변경은 MutableStateFlow.update { it.copy(...) }. value = 직접 대입 금지.
• Side effect (네비게이션, 토스트, 토큰 만료 알림 등) 는 Channel / SharedFlow 로 emit, Route 에서 수집.
• _uiState (private MutableStateFlow) ↔ uiState (public StateFlow) backing property 패턴.
• viewModelScope 외 스코프 사용 금지. UseCase 가 withContext(Dispatchers.IO) 로 main-safe 보장.

5. 참고 문서

문서	무엇이 있나
AGENTS.md (루트)	Module Structure, Convention Plugins, Coding Conventions
core/AGENTS.md	core 모듈 의존 규칙, Auth/Network 패턴, testing 사용법
feature/AGENTS.md	feature 모듈 작성 규칙 (있다면)
.codex/docs/VALIDATION.md	변경 유형별 Validation gate
.codex/docs/TROUBLESHOOTING.md	과거 트러블슈팅·트레이드오프·성능 결정

실행 절차

1. 변경하려는 코드가 위 체크리스트 중 어느 항목과 맞닿는지 먼저 식별.
2. 어긋남이 있으면 사용자에게 옮겨야 할 위치를 제안하고 합의 후 진행.
3. 새 모듈/계층/의존이 생기면 관련 AGENTS.md 동기 업데이트를 같은 PR 에 포함.
4. 작업 종료 시 scripts/verify-change.sh 또는 /check 로 Validation gate 통과 확인.