Pattern Selection Guide

A decision guide for selecting optimal patterns based on the situation.

Reference location: .claude/references/DECISION_MATRIX.md

A decision guide for selecting optimal patterns based on the situation.

UseCase Patterns#

✅ Standard: Optional Constructor Injection (Pure DI)

UseCase 사용? ─Yes→ Optional Constructor Injection
             └No→ Repository 직접 접근 금지 (UseCase 통해서만!)

Pattern#

Criteria	Optional Constructor Injection
Recommended	✅ Standard pattern
DI Setup	getIt/injectable not needed
Testing	`Bloc(useCase: mockUseCase)` direct injection

Key Points:

UseCase: const UseCase([IRepo? repo]) : _repo = repo ?? ConcreteRepo()
BLoC: Bloc({UseCase? useCase}) : _useCase = useCase ?? const UseCase()
Test: Bloc(useCase: mockUseCase) - getIt.reset() Not needed

-> Details: patterns/usecase-patterns.md

BLoC State Pattern Selection#

Clear state separation? ─Yes─► Freezed Union (권장)
               │
               └No─► Avoid code generation? ─Yes─► Sealed Class
                                   │
                                   └No─► Single State

Detailed Comparison#

Criteria	Freezed Union	Sealed Class	Single State
Code Generation	Required	Not needed	Required
State Separation	✅ Clear	✅ Clear	⚠️ Less clear
copyWith	✅ Auto	⚠️ Manual	✅ Auto
Pattern Matching	✅ when/map	✅ switch	⚠️ Conditionals
Recommended For	General use	Dart 3.0+, avoiding codegen	Pagination, filtering

Selection Criteria:

✅ Freezed Union: Clear Initial/Loading/Loaded/Error separation
✅ Sealed Class: Type-safe without code generation
✅ Single State: Multiple state combinations (isLoading + items + hasMore)

-> Details: patterns/bloc-patterns.md

Repository Implementation Pattern Selection#

Need network logic reuse? ─Yes─► Mixin 패턴 (권장)
                         │
                         └No─► Multiple data source combination? ─Yes─► Mixin 패턴
                                                     │
                                                     └No─► Direct implementation

Detailed Comparison#

Criteria	Mixin Pattern	Direct implementation
Logic Reuse	✅ Easy	⚠️ Difficult
Structural Complexity	⚠️ Increased	✅ Simple
Testing	✅ Independent Mixin tests	⚠️ Full tests
Recommended For	Complex APIs, multiple data sources	Simple CRUD

Selection Criteria:

✅ Mixin Pattern: API logic reuse, caching layer separation, complex data processing
✅ Direct Implementation: Simple CRUD, quick implementation, no reuse needed

-> Details: patterns/repository-patterns.md

Caching Strategy Selection#

Data changes frequently? ─Yes─► SWR (Stale-While-Revalidate)
                 │
                 └No─► Need offline? ─Yes─► Cache-First
                                      │
                                      └No─► SWR

Detailed Comparison#

Criteria	SWR	Cache-First
Response Speed	✅ Instant (cache) + refresh	✅ Instant (cache)
Network Usage	⚠️ Called every time	✅ Skipped when cached
Data Freshness	✅ Latest	⚠️ Until cache expires
Offline Support	⚠️ Only when cached	✅ Cache first

Suitable cases:

SWR	Cache-First
Feed, timeline	User profile
Chat messages	App settings
Notification List	Category List
Real-time status	Static content

-> Details: patterns/caching-patterns.md

Entity Definition Pattern Selection#

Code generation available? ─Yes─► Freezed (권장)
              │
              └No─► Dart 3.0+? ─Yes─► Final Class
                              │
                              └No─► 일반 Class

Detailed Comparison#

Criteria	Freezed	Final Class	일반 Class
copyWith	✅ Auto	⚠️ Manual	⚠️ Manual
equality	✅ Auto	⚠️ Manual	⚠️ Manual
Immutability	✅ Enforced	✅ final Enforced	⚠️ Selection
JSON serialization	✅ Auto	⚠️ Manual	⚠️ Manual

UI Component Selection#

Existing component available? ─Yes─► /coui:improve (Improvement)
                   │
                   └No─► Form component? ─Yes─► /coui:form
                                      │
                                      └No─► Full screen? ─Yes─► /coui:screen
                                                        │
                                                        └No─► /coui:component

Test Strategy Selection#

E2E test? ─Yes─► /bdd:generate (BDD 시나리오)
           │
           └No─► BLoC test? ─Yes─► bloc_test 패키지
                              │
                              └No─► Unit test? ─Yes─► mocktail + flutter_test

Agent Selection Guide#

Feature Development#

Scenario	Invocation	Description
Full Feature creation	`/feature:create`	Domain + Data + Presentation
Domain only	`/feature:domain`	Entity, UseCase, Repository Interface
Data only	`/feature:data`	Repository impl, Cache, DAO
Presentation only	`/feature:presentation`	BLoC, Page, Widget
BLoC only	`/feature:bloc`	State management only

Backend Development#

Scenario	Invocation	Description
New model definition	`/serverpod:model`	.spy.yaml file creation
Endpoint creation	`/serverpod:endpoint`	API endpoints

UI Development#

Scenario	Invocation	Description
Single component	`/coui:component`	Buttons, cards, etc.
Form creation	`/coui:form`	Complete input form
Full screen	`/coui:screen`	Page composition
Existing UI improvement	`/coui:improve`	Refactoring, style improvement

Quick Reference Checklist#

When Starting a New Feature#

/serverpod:model - Backend model definition
/serverpod:endpoint - API endpoints
/feature:domain - Entity, UseCase Definition
/feature:data - Repository Implementation
/feature:presentation - BLoC, UI Implementation
/bdd:generate - Test scenarios

When Selecting Patterns#

UseCase → patterns/usecase-patterns.md
BLoC State → patterns/bloc-patterns.md
Repository → patterns/repository-patterns.md
Caching → patterns/caching-patterns.md

When Checking Workflow#

Feature Generation → DEPENDENCY_GRAPH.md
Parallel Execution → DEPENDENCY_GRAPH.md#parallel-execution-available-work

Referencing Agents#

All /feature:* Agents
/serverpod:* Agents
/coui:* Agents