@choblue/claude-code-toolkit 1.1.4 → 1.2.0

package/.claude/skills/DDD/references/aggregate-repository.md

@@ -0,0 +1,234 @@
+# Aggregate & Repository 심화
+
+> 이 문서는 `../SKILL.md`의 참조 문서이다.
+
+---
+
+## 1. Aggregate 심화
+
+### 내부 Entity (OrderItem) 관리
+
+Aggregate Root는 내부 Entity의 생명주기를 완전히 관리한다. 외부에서 내부 Entity를 직접 생성하거나 조작할 수 없다.
+
+```typescript
+// Good - Aggregate 내부 Entity
+class OrderItem {
+  constructor(
+    private readonly _productId: string, // ID로만 참조
+    private readonly _price: Money,
+    private _quantity: number,
+  ) {
+    if (quantity <= 0) {
+      throw new Error('Quantity must be positive');
+    }
+  }
+
+  get productId(): string { return this._productId; }
+  get price(): Money { return this._price; }
+  get quantity(): number { return this._quantity; }
+
+  get subtotal(): Money {
+    return this._price.multiply(this._quantity);
+  }
+
+  increaseQuantity(amount: number): void {
+    if (amount <= 0) throw new Error('Amount must be positive');
+    this._quantity += amount;
+  }
+}
+```
+
+### Aggregate Root의 addItem / removeItem 패턴
+
+Aggregate Root가 불변식을 보호하면서 내부 Entity를 조작하는 전체 패턴이다.
+
+```typescript
+// Good - Aggregate Root가 내부 Entity의 추가/제거를 관리
+class Order {
+  private readonly _id: string;
+  private readonly _customerId: string;
+  private readonly _items: OrderItem[];
+  private _status: OrderStatus;
+
+  constructor(id: string, customerId: string, items: OrderItem[]) {
+    if (items.length === 0) {
+      throw new Error('Order must have at least one item');
+    }
+    this._id = id;
+    this._customerId = customerId;
+    this._items = items;
+    this._status = OrderStatus.PENDING;
+  }
+
+  get id(): string { return this._id; }
+  get customerId(): string { return this._customerId; }
+  get items(): ReadonlyArray<OrderItem> { return [...this._items]; }
+  get status(): OrderStatus { return this._status; }
+
+  addItem(productId: string, price: Money, quantity: number): void {
+    if (this._status !== OrderStatus.PENDING) {
+      throw new Error('Cannot modify confirmed order');
+    }
+    const existing = this._items.find(i => i.productId === productId);
+    if (existing) {
+      existing.increaseQuantity(quantity);
+    } else {
+      this._items.push(new OrderItem(productId, price, quantity));
+    }
+  }
+
+  removeItem(productId: string): void {
+    if (this._status !== OrderStatus.PENDING) {
+      throw new Error('Cannot modify confirmed order');
+    }
+    const index = this._items.findIndex(i => i.productId === productId);
+    if (index === -1) {
+      throw new Error(`Item not found: ${productId}`);
+    }
+    this._items.splice(index, 1);
+    if (this._items.length === 0) {
+      throw new Error('Order must have at least one item');
+    }
+  }
+
+  get totalAmount(): Money {
+    return this._items.reduce(
+      (sum, item) => sum.add(item.subtotal),
+      Money.create(0, 'KRW'),
+    );
+  }
+}
+```
+
+### Aggregate 간 ID 참조 패턴
+
+```typescript
+// Bad - Aggregate 간 직접 객체 참조
+class Order {
+  customer: Customer;      // 다른 Aggregate를 직접 참조
+  items: OrderItem[];
+}
+
+class OrderItem {
+  product: Product;        // 다른 Aggregate를 직접 참조
+}
+
+// Good - ID로만 참조
+class Order {
+  private readonly _customerId: string;   // ID 참조
+  private readonly _items: OrderItem[];
+}
+
+class OrderItem {
+  private readonly _productId: string;    // ID 참조
+}
+```
+
+### Aggregate 설계 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| 작게 유지 | 꼭 필요한 Entity만 포함. 크기가 커지면 분리 검토 |
+| ID 참조 | Aggregate 간 객체 참조 대신 ID 참조 사용 |
+| 하나의 트랜잭션 | 하나의 트랜잭션에서 하나의 Aggregate만 변경 |
+| 불변식 보호 | 모든 상태 변경 시 비즈니스 규칙(불변식) 검증 |
+| Root를 통한 접근 | 외부에서 내부 Entity에 직접 접근 불가 |
+
+---
+
+## 2. Repository 심화
+
+### Repository 인터페이스와 구현 분리
+
+```typescript
+// domain/order/order.repository.ts (도메인 레이어 - 인터페이스만)
+interface OrderRepository {
+  findById(id: string): Promise<Order | null>;
+  findByCustomerId(customerId: string): Promise<Order[]>;
+  save(order: Order): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+```
+
+### TypeORM 기반 구현체
+
+```typescript
+// infrastructure/persistence/typeorm-order.repository.ts (인프라 레이어 - 구현)
+@Injectable()
+class TypeOrmOrderRepository implements OrderRepository {
+  constructor(
+    @InjectRepository(OrderEntity)
+    private readonly ormRepo: Repository<OrderEntity>,
+  ) {}
+
+  async findById(id: string): Promise<Order | null> {
+    const entity = await this.ormRepo.findOne({
+      where: { id },
+      relations: ['items'],
+    });
+    if (!entity) return null;
+    return OrderMapper.toDomain(entity);
+  }
+
+  async save(order: Order): Promise<void> {
+    const entity = OrderMapper.toEntity(order);
+    await this.ormRepo.save(entity);
+  }
+
+  async findByCustomerId(customerId: string): Promise<Order[]> {
+    const entities = await this.ormRepo.find({
+      where: { customerId },
+      relations: ['items'],
+    });
+    return entities.map(OrderMapper.toDomain);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.ormRepo.delete(id);
+  }
+}
+```
+
+### Mapper 패턴
+
+도메인 모델과 ORM Entity 간 변환을 담당한다.
+
+```typescript
+// infrastructure/persistence/order.mapper.ts
+class OrderMapper {
+  static toDomain(entity: OrderOrmEntity): Order {
+    return new Order(entity.id, entity.status as OrderStatus);
+  }
+
+  static toEntity(domain: Order): OrderOrmEntity {
+    const entity = new OrderOrmEntity();
+    entity.id = domain.id;
+    entity.status = domain.status;
+    return entity;
+  }
+}
+```
+
+### NestJS Module에서 DI 바인딩
+
+```typescript
+// Module에서 DI 바인딩
+@Module({
+  providers: [
+    {
+      provide: 'OrderRepository', // 또는 Symbol/abstract class 토큰
+      useClass: TypeOrmOrderRepository,
+    },
+  ],
+})
+class OrderModule {}
+```
+
+### Repository 설계 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| Aggregate Root 단위 | OrderItem용 Repository는 만들지 않는다 |
+| 인터페이스 분리 | 도메인 레이어에 인터페이스, 인프라 레이어에 구현 |
+| Mapper 사용 | 도메인 모델과 ORM Entity를 반드시 분리한다 |
+| 의존성 역전 | Service는 인터페이스에 의존, 구현체는 DI로 주입 |

package/.claude/skills/DDD/references/domain-events.md

@@ -0,0 +1,202 @@
+# Domain Service & Domain Event 심화
+
+> 이 문서는 `../SKILL.md`의 참조 문서이다.
+
+---
+
+## 1. Domain Service 심화
+
+### 여러 Aggregate 간 계산 로직
+
+Domain Service는 단일 Entity에 속하지 않는, 여러 Aggregate를 조율하는 도메인 로직을 담당한다.
+
+```typescript
+// Bad - 특정 Entity에 속하는 로직을 Domain Service에 두기
+class OrderDomainService {
+  // 이 로직은 Order Entity에 속해야 한다
+  cancelOrder(order: Order): void {
+    if (order.status !== OrderStatus.PENDING) {
+      throw new Error('Cannot cancel');
+    }
+    order.status = OrderStatus.CANCELLED;
+  }
+
+  // 이 로직도 Order Entity에 속해야 한다
+  calculateTotal(order: Order): number {
+    return order.items.reduce(
+      (sum, item) => sum + item.price * item.quantity,
+      0,
+    );
+  }
+}
+```
+
+### 할인 계산 Domain Service
+
+```typescript
+// Good - 여러 Aggregate(Order, Customer, Promotion)의 정보가 필요한 할인 계산
+class PricingService {
+  calculateDiscount(
+    order: Order,
+    customerTier: CustomerTier,
+    promotions: Promotion[],
+  ): Money {
+    let discount = Money.create(0, 'KRW');
+
+    // 고객 등급별 할인
+    if (customerTier === CustomerTier.VIP) {
+      discount = discount.add(order.totalAmount.multiply(0.1));
+    }
+
+    // 프로모션 할인
+    for (const promo of promotions) {
+      if (promo.isApplicableTo(order)) {
+        discount = discount.add(promo.calculateDiscount(order.totalAmount));
+      }
+    }
+
+    return discount;
+  }
+}
+```
+
+### 이체 Domain Service
+
+```typescript
+// Good - 두 Aggregate(Account) 간 이체 - 어느 한쪽에 속하지 않는 로직
+class TransferService {
+  transfer(from: Account, to: Account, amount: Money): void {
+    if (!from.canWithdraw(amount)) {
+      throw new Error('Insufficient balance');
+    }
+    from.withdraw(amount);
+    to.deposit(amount);
+  }
+}
+```
+
+### Domain Service vs Application Service 구분
+
+| 구분 | Domain Service | Application Service |
+|------|---------------|-------------------|
+| 역할 | 순수 도메인 로직 | 유스케이스 흐름 조율 |
+| 예시 | 할인 계산, 이체 규칙 | 트랜잭션, 이벤트 발행 |
+| 상태 | stateless | stateless |
+| 의존성 | 도메인 객체만 | Repository, EventPublisher 등 |
+| 위치 | Domain 레이어 | Application 레이어 |
+
+---
+
+## 2. Domain Event 심화
+
+### AggregateRoot 기반 이벤트 수집
+
+Aggregate에서 이벤트를 수집하는 기반 클래스를 정의한다.
+
+```typescript
+// Good - AggregateRoot 기반 클래스
+abstract class AggregateRoot {
+  private _domainEvents: DomainEvent[] = [];
+
+  get domainEvents(): ReadonlyArray<DomainEvent> {
+    return [...this._domainEvents];
+  }
+
+  protected addDomainEvent(event: DomainEvent): void {
+    this._domainEvents.push(event);
+  }
+
+  clearDomainEvents(): void {
+    this._domainEvents = [];
+  }
+}
+```
+
+### Aggregate에서 이벤트 발생
+
+```typescript
+// Good - Order Aggregate가 생성 시 이벤트를 수집
+class Order extends AggregateRoot {
+  // ... 기존 필드 생략
+
+  static place(id: string, customerId: string, items: OrderItem[]): Order {
+    const order = new Order(id, customerId, items);
+    order.addDomainEvent(
+      new OrderPlacedEvent(
+        order.id,
+        order.customerId,
+        order.items.map(i => ({ productId: i.productId, quantity: i.quantity })),
+        order.totalAmount.amount,
+      ),
+    );
+    return order;
+  }
+}
+```
+
+### 이벤트 핸들러 독립 구현
+
+각 핸들러는 독립적으로 이벤트를 처리하며, 핸들러 간 순서 의존성이 없다.
+
+```typescript
+// Good - 각 핸들러가 독립적으로 처리
+class SendOrderConfirmationHandler {
+  constructor(private readonly emailService: EmailService) {}
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    await this.emailService.sendOrderConfirmation(event.orderId);
+  }
+}
+
+class DecreaseStockHandler {
+  constructor(private readonly inventoryService: InventoryService) {}
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    for (const item of event.items) {
+      await this.inventoryService.decrease(item.productId, item.quantity);
+    }
+  }
+}
+
+class AccumulatePointsHandler {
+  constructor(private readonly pointService: PointService) {}
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    await this.pointService.accumulate(event.customerId, event.totalAmount);
+  }
+}
+```
+
+### Application Service에서의 조합
+
+Application Service가 Repository 저장과 이벤트 발행을 조율한다.
+
+```typescript
+// Good - Application Service가 유스케이스 흐름을 조율
+class PlaceOrderUseCase {
+  constructor(
+    private readonly orderRepo: OrderRepository,
+    private readonly eventPublisher: DomainEventPublisher,
+  ) {}
+
+  async execute(command: PlaceOrderCommand): Promise<void> {
+    const order = Order.place(command.id, command.customerId, command.items);
+    await this.orderRepo.save(order);
+
+    // Aggregate에서 수집한 이벤트를 발행
+    await this.eventPublisher.publishAll(order.domainEvents);
+    order.clearDomainEvents();
+  }
+}
+```
+
+### 이벤트 설계 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| 과거형 이름 | `OrderPlaced`, `PaymentCompleted` (not `PlaceOrder`) |
+| 불변 객체 | 생성 후 변경하지 않는다 |
+| 필요한 데이터만 | 이벤트에 Aggregate 전체를 넣지 않고, 핸들러가 필요한 최소 데이터만 포함 |
+| 발생 시각 포함 | `occurredAt` 필드로 이벤트 발생 시각을 기록 |
+| 순서 비의존 | 핸들러 간 실행 순서에 의존하지 않는다 |
+| Aggregate에서 수집 | `addDomainEvent`로 수집, Application 레이어에서 `publishAll`로 발행 |

package/.claude/skills/DDD/references/entity-vo.md

@@ -0,0 +1,225 @@
+# Entity & Value Object 심화
+
+> 이 문서는 `../SKILL.md`의 참조 문서이다.
+
+---
+
+## 1. Entity 심화
+
+### Value Object를 활용한 Entity 강화
+
+Entity 내부에서 Value Object를 사용하여 도메인 개념을 명확히 표현한다.
+
+```typescript
+// Good - Entity가 Value Object를 내부적으로 활용
+class Order {
+  private readonly _id: string;
+  private _status: OrderStatus;
+  private readonly _items: OrderItem[];
+
+  constructor(id: string, items: OrderItem[]) {
+    if (items.length === 0) {
+      throw new Error('Order must have at least one item');
+    }
+    this._id = id;
+    this._status = OrderStatus.PENDING;
+    this._items = items;
+  }
+
+  get id(): string { return this._id; }
+  get status(): OrderStatus { return this._status; }
+  get items(): ReadonlyArray<OrderItem> { return [...this._items]; }
+
+  get totalAmount(): Money {
+    return this._items.reduce(
+      (sum, item) => sum.add(item.subtotal),
+      Money.create(0, 'KRW'),
+    );
+  }
+
+  cancel(): void {
+    if (this._status !== OrderStatus.PENDING) {
+      throw new Error('Only pending orders can be cancelled');
+    }
+    this._status = OrderStatus.CANCELLED;
+  }
+
+  confirm(): void {
+    if (this._status !== OrderStatus.PENDING) {
+      throw new Error('Only pending orders can be confirmed');
+    }
+    this._status = OrderStatus.CONFIRMED;
+  }
+
+  equals(other: Order): boolean {
+    return this._id === other._id;
+  }
+}
+```
+
+### equals 메서드 패턴
+
+Entity의 동등성 비교는 반드시 id 기반으로 한다.
+
+```typescript
+// Bad - 모든 속성 비교
+class User {
+  equals(other: User): boolean {
+    return this.name === other.name && this.email === other.email;
+  }
+}
+
+// Good - id 기반 비교
+class User {
+  private readonly _id: string;
+
+  equals(other: User): boolean {
+    return this._id === other._id;
+  }
+}
+```
+
+### 상태 전이(State Transition) 패턴
+
+Entity의 상태 변경은 명시적인 메서드로 표현하고, 허용되지 않는 전이를 방어한다.
+
+```typescript
+// Good - 상태 전이를 명시적으로 관리
+class Order {
+  private _status: OrderStatus;
+
+  // 허용 전이: PENDING -> CONFIRMED -> SHIPPED -> DELIVERED
+  //           PENDING -> CANCELLED
+
+  confirm(): void {
+    this.assertStatus(OrderStatus.PENDING, 'confirm');
+    this._status = OrderStatus.CONFIRMED;
+  }
+
+  ship(): void {
+    this.assertStatus(OrderStatus.CONFIRMED, 'ship');
+    this._status = OrderStatus.SHIPPED;
+  }
+
+  deliver(): void {
+    this.assertStatus(OrderStatus.SHIPPED, 'deliver');
+    this._status = OrderStatus.DELIVERED;
+  }
+
+  cancel(): void {
+    if (this._status !== OrderStatus.PENDING) {
+      throw new Error('Only pending orders can be cancelled');
+    }
+    this._status = OrderStatus.CANCELLED;
+  }
+
+  private assertStatus(expected: OrderStatus, action: string): void {
+    if (this._status !== expected) {
+      throw new Error(
+        `Cannot ${action} order in ${this._status} status (expected: ${expected})`,
+      );
+    }
+  }
+}
+```
+
+---
+
+## 2. Value Object 심화
+
+### Money 패턴 전체 구현
+
+Money는 대표적인 Value Object로, 금액과 통화를 함께 관리한다.
+
+```typescript
+// Good - Money Value Object 전체 구현
+class Money {
+  private constructor(
+    private readonly _amount: number,
+    private readonly _currency: string,
+  ) {}
+
+  static create(amount: number, currency: string): Money {
+    if (amount < 0) {
+      throw new Error('Amount cannot be negative');
+    }
+    if (!['KRW', 'USD', 'EUR'].includes(currency)) {
+      throw new Error(`Unsupported currency: ${currency}`);
+    }
+    return new Money(amount, currency);
+  }
+
+  get amount(): number { return this._amount; }
+  get currency(): string { return this._currency; }
+
+  add(other: Money): Money {
+    if (this._currency !== other._currency) {
+      throw new Error('Cannot add different currencies');
+    }
+    return Money.create(this._amount + other._amount, this._currency);
+  }
+
+  multiply(factor: number): Money {
+    return Money.create(this._amount * factor, this._currency);
+  }
+
+  equals(other: Money): boolean {
+    return this._amount === other._amount && this._currency === other._currency;
+  }
+}
+```
+
+### 복합 Value Object
+
+여러 속성을 가진 Value Object도 동일한 패턴을 따른다.
+
+```typescript
+// Good - 복합 Value Object (주소)
+class Address {
+  private constructor(
+    private readonly _street: string,
+    private readonly _city: string,
+    private readonly _zipCode: string,
+    private readonly _country: string,
+  ) {}
+
+  static create(street: string, city: string, zipCode: string, country: string): Address {
+    if (!street || !city || !zipCode || !country) {
+      throw new Error('All address fields are required');
+    }
+    if (!/^\d{5}$/.test(zipCode)) {
+      throw new Error(`Invalid zip code: ${zipCode}`);
+    }
+    return new Address(street, city, zipCode, country);
+  }
+
+  get street(): string { return this._street; }
+  get city(): string { return this._city; }
+  get zipCode(): string { return this._zipCode; }
+  get country(): string { return this._country; }
+
+  equals(other: Address): boolean {
+    return (
+      this._street === other._street &&
+      this._city === other._city &&
+      this._zipCode === other._zipCode &&
+      this._country === other._country
+    );
+  }
+
+  // 상태 변경 시 새 인스턴스 반환 (불변 유지)
+  changeStreet(newStreet: string): Address {
+    return Address.create(newStreet, this._city, this._zipCode, this._country);
+  }
+}
+```
+
+### Value Object vs 원시값 판단 기준
+
+| 기준 | 원시값 사용 | Value Object 사용 |
+|------|------------|-------------------|
+| 유효성 검증 | 필요 없음 | 생성 시 검증 필요 |
+| 도메인 연산 | 없음 | add, multiply 등 존재 |
+| 포맷/정규화 | 불필요 | trim, lowercase 등 필요 |
+| 여러 속성 조합 | 단일 값 | 복합 값 (Money = amount + currency) |
+| 비즈니스 의미 | 범용적 | 도메인 특화 의미 |

package/.claude/skills/Planning/SKILL.md

@@ -0,0 +1,44 @@
+# Planning Skill
+
+작업 계획 수립 시 참조하는 체크리스트와 템플릿.
+
+---
+
+## 1. 티어 판단
+
+다음 질문에 순서대로 답하라:
+
+1. **변경 영향도**: 핵심 도메인 로직이 바뀌는가? → Yes면 L
+2. **레이어 횡단**: FE + BE 동시 변경인가? → 영향도에 따라 M 또는 L
+3. **설계 결정**: 새로운 아키텍처/패턴 도입이 필요한가? → Yes면 L
+4. **위 모두 No**: 파일 수와 변경 단순성으로 S/M 판단
+
+## 2. 작업 분해 템플릿
+
+### 요구사항 정리
+- [ ] 사용자가 원하는 최종 결과물은?
+- [ ] 변경되는 레이어는? (UI / API / Domain / DB)
+- [ ] 기존 코드에 영향을 주는 범위는?
+
+### 작업 단위 분해
+각 작업 단위는 **독립적으로 테스트 가능한 단위**로 나눈다:
+```
+1. [작업명] - [대상 파일/모듈] - [티어]
+2. [작업명] - [대상 파일/모듈] - [티어]
+```
+
+### 의존성 확인
+- [ ] 작업 간 순서 의존성이 있는가? (예: BE API 먼저 → FE 연동)
+- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)
+
+## 3. 계획 출력 형식
+
+사용자에게 계획을 제시할 때 다음 형식을 따른다:
+
+```
+**티어**: S / M / L
+**변경 범위**: [레이어 목록]
+**작업 목록**:
+1. [작업] → [담당 에이전트]
+2. [작업] → [담당 에이전트]
+```