---

name: software-architecture description: Clean Architecture and SOLID principles guide. Use this when designing systems, reviewing architecture, or making structural decisions. allowed-tools: Read, Glob, Grep, Edit, Write license: MIT metadata: author: NeoLabHQ version: "1.0"

Software Architecture

Clean Architecture와 DDD 원칙 기반 소프트웨어 설계 가이드입니다.

Core Principles

SOLID

Clean Architecture Layers

Copy┌─────────────────────────────────────────┐
│           Frameworks & Drivers          │  ← DB, Web, UI
├─────────────────────────────────────────┤
│         Interface Adapters              │  ← Controllers, Gateways
├─────────────────────────────────────────┤
│         Application Business Rules      │  ← Use Cases
├─────────────────────────────────────────┤
│         Enterprise Business Rules       │  ← Entities
└─────────────────────────────────────────┘

의존성 규칙: 바깥 → 안쪽 방향으로만 의존

Code Style Rules

Early Return Pattern

Copy// ❌ 중첩된 조건문
function process(user) {
  if (user) {
    if (user.isActive) {
      if (user.hasPermission) {
        // do something
      }
    }
  }
}

// ✅ Early Return
function process(user) {
  if (!user) return;
  if (!user.isActive) return;
  if (!user.hasPermission) return;
  // do something
}

Function/File Size Limits

Domain-Specific Naming

Copy// ❌ 제네릭 네이밍
utils/helpers.ts
common/index.ts

// ✅ 도메인 네이밍
services/OrderCalculator.ts
auth/UserAuthenticator.ts

Library-First Approach

"모든 커스텀 코드는 유지보수, 테스트, 문서화가 필요한 부채다"

코드 작성 전 확인:

1. npm/yarn 패키지 검색
2. 기존 서비스/API 확인
3. 오픈소스 솔루션 검토

Anti-Patterns to Avoid

Separation of Concerns

Copy✅ 올바른 분리
├── domain/          # 비즈니스 로직
├── application/     # Use Cases
├── infrastructure/  # DB, API
└── presentation/    # UI, Controllers

❌ 잘못된 분리
├── components/
│   └── UserCard.tsx  # UI + API 호출 + 비즈니스 로직 혼합

Decision Checklist

새로운 코드 작성 시:

• 기존 라이브러리/서비스로 해결 가능?
• 단일 책임 원칙 준수?
• 의존성 방향 올바름?
• 테스트 가능한 구조?
• 도메인 네이밍 사용?