@choblue/claude-code-toolkit 1.1.1 → 1.1.4

package/.claude/skills/TDD/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tdd
+description: TDD(테스트 주도 개발) 공통 원칙. 테스트 작성 시 Red-Green-Refactor 사이클, FIRST 원칙, AAA 패턴, Mock/Stub/Spy 사용법을 참조한다.
+---
+
 # TDD Skill - 핵심 원칙
 
 이 문서는 모든 테스트 코드 작성 시 적용되는 공통 원칙을 정의한다.

package/.claude/skills/TailwindCSS/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tailwindcss
+description: Tailwind CSS 유틸리티 패턴 가이드. 스타일링, 반응형 디자인, 다크 모드, CVA 패턴, cn() 유틸리티 등 Tailwind 기반 스타일 작업 시 참조한다.
+---
+
 # TailwindCSS Skill - Tailwind CSS 규칙
 
 Tailwind CSS를 사용하는 프로젝트에 적용되는 스타일링 규칙이다.
@@ -21,11 +26,23 @@ React 규칙은 `../React/SKILL.md`, 공통 원칙은 `../Coding/SKILL.md`를
 
 ### 클래스 조합
 - 관련 있는 클래스를 논리적 그룹으로 정렬한다
-- 권장 순서: 레이아웃 -> 크기 -> 간격 -> 타이포그래피 -> 색상 -> 효과
+- 권장 순서: 레이아웃 → 크기 → 간격 → 타이포그래피 → 색상 → 효과
+- **클래스가 길어지면 관심사별로 줄바꿈하여 가독성을 높인다**
 
 ```typescript
-// Good - 논리적 순서로 정렬
+// Bad - 한 줄로 길게 나열 (화면 벗어남, 어떤 CSS가 있는지 파악 어려움)
 <button className="flex items-center justify-center w-full h-10 px-4 text-sm font-medium text-white bg-blue-600 rounded-lg hover:bg-blue-700">
+
+// Good - 관심사별 줄바꿈
+<button
+  className={cn(
+    'flex items-center justify-center', // 레이아웃
+    'w-full h-10 px-4',                 // 크기/간격
+    'text-sm font-medium text-white',   // 타이포그래피
+    'bg-blue-600 rounded-lg',           // 배경/모양
+    'hover:bg-blue-700',                // 상태
+  )}
+>
   버튼
 </button>
 ```
@@ -222,7 +239,8 @@ export function Button({ variant = 'primary', size = 'md', className, children }
     <button
       className={cn(
         // 기본 스타일
-        'inline-flex items-center justify-center rounded-lg font-medium transition-colors',
+        'inline-flex items-center justify-center',
+        'rounded-lg font-medium transition-colors',
         // variant
         {
           'bg-blue-600 text-white hover:bg-blue-700': variant === 'primary',
@@ -256,7 +274,12 @@ import { cn } from '@/lib/utils';
 
 const buttonVariants = cva(
   // 기본 스타일
-  'inline-flex items-center justify-center rounded-lg font-medium transition-colors disabled:pointer-events-none disabled:opacity-50',
+  [
+    'inline-flex items-center justify-center', // 레이아웃
+    'rounded-lg font-medium',                  // 모양/타이포
+    'transition-colors',                       // 효과
+    'disabled:pointer-events-none disabled:opacity-50', // 상태
+  ],
   {
     variants: {
       variant: {
@@ -365,4 +388,4 @@ const colorClasses = {
 } as const;
 
 <div className={colorClasses[color]}>
-```
+```

package/.claude/skills/TanStackQuery/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tanstack-query
+description: TanStack Query 서버 상태 관리 가이드. useQuery, useMutation, queryKey 팩토리, Optimistic Update, Prefetching 등 서버 상태 관리 시 참조한다.
+---
+
 # TanStack Query Skill - 서버 상태 관리 규칙
 
 TanStack Query (React Query)를 사용한 서버 상태 관리 규칙을 정의한다.

package/.claude/skills/TypeORM/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: typeorm
+description: TypeORM Entity, Repository, QueryBuilder 가이드. NestJS에서 TypeORM을 사용한 Entity 정의, Relations, Repository 패턴, 마이그레이션, 트랜잭션 등 데이터베이스 작업 시 참조한다.
+---
+
 # TypeORM Skill - TypeORM 규칙
 
 NestJS와 함께 사용하는 TypeORM 패턴과 규칙을 정의한다.
@@ -279,307 +284,7 @@ const count = await this.userRepository.count({ where: { isActive: true } });
 
 ---
 
-## 4. QueryBuilder
-
-### 기본 사용법
-
-```typescript
-const users = await this.userRepository
-  .createQueryBuilder('user')
-  .select(['user.id', 'user.name', 'user.email'])
-  .where('user.isActive = :isActive', { isActive: true })
-  .andWhere('user.role = :role', { role: UserRole.ADMIN })
-  .orderBy('user.createdAt', 'DESC')
-  .take(20)
-  .skip(0)
-  .getMany();
-```
-
-### JOIN
-
-```typescript
-// leftJoinAndSelect - 관계가 없어도 결과에 포함 (LEFT JOIN)
-const users = await this.userRepository
-  .createQueryBuilder('user')
-  .leftJoinAndSelect('user.posts', 'post')
-  .where('user.id = :id', { id: userId })
-  .getOne();
-
-// innerJoinAndSelect - 관계가 있는 경우만 포함 (INNER JOIN)
-const usersWithPosts = await this.userRepository
-  .createQueryBuilder('user')
-  .innerJoinAndSelect('user.posts', 'post')
-  .getMany();
-```
-
-### 서브쿼리
-
-```typescript
-// 서브쿼리로 특정 조건의 사용자 조회
-const users = await this.userRepository
-  .createQueryBuilder('user')
-  .where((qb) => {
-    const subQuery = qb
-      .subQuery()
-      .select('post.authorId')
-      .from(Post, 'post')
-      .where('post.createdAt > :date', { date: startDate })
-      .getQuery();
-    return `user.id IN ${subQuery}`;
-  })
-  .getMany();
-```
-
-### getOne vs getMany vs getRawOne vs getRawMany
-
-| 메서드 | 반환 타입 | 용도 |
-|--------|----------|------|
-| `getOne()` | `Entity \| null` | Entity 단건 조회 |
-| `getMany()` | `Entity[]` | Entity 목록 조회 |
-| `getRawOne()` | `object \| undefined` | 가공된 데이터 단건 (집계 등) |
-| `getRawMany()` | `object[]` | 가공된 데이터 목록 |
-
-```typescript
-// 집계 쿼리 - getRawOne 사용
-const result = await this.postRepository
-  .createQueryBuilder('post')
-  .select('COUNT(post.id)', 'totalCount')
-  .addSelect('AVG(post.viewCount)', 'avgViews')
-  .where('post.authorId = :authorId', { authorId })
-  .getRawOne();
-// result: { totalCount: '42', avgViews: '128.5' }
-```
-
-### find vs QueryBuilder 가이드
-
-| 상황 | 권장 방법 |
-|------|----------|
-| 단순 CRUD (조건 1~2개) | `find`, `findOne`, `findOneBy` |
-| 단순 관계 로딩 | `find` + `relations` 옵션 |
-| 복잡한 WHERE 조건 (OR, 중첩) | `QueryBuilder` |
-| JOIN 조건이 복잡한 경우 | `QueryBuilder` |
-| 집계 함수 (COUNT, SUM, AVG) | `QueryBuilder` + `getRawOne/getRawMany` |
-| 서브쿼리가 필요한 경우 | `QueryBuilder` |
-| 동적 조건 조합 | `QueryBuilder` |
-
----
-
-## 5. 마이그레이션
-
-### CLI 명령어
-
-```bash
-# 마이그레이션 자동 생성 (Entity 변경 감지)
-npx typeorm migration:generate src/migrations/AddUserRole -d src/data-source.ts
-
-# 마이그레이션 수동 생성 (빈 파일)
-npx typeorm migration:create src/migrations/SeedInitialData
-
-# 마이그레이션 실행
-npx typeorm migration:run -d src/data-source.ts
-
-# 마이그레이션 되돌리기 (가장 최근 1개)
-npx typeorm migration:revert -d src/data-source.ts
-```
-
-### 마이그레이션 파일 작성 패턴
-
-```typescript
-export class AddUserRole1700000000000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.addColumn(
-      'user',
-      new TableColumn({
-        name: 'role',
-        type: 'enum',
-        enum: ['user', 'admin', 'moderator'],
-        default: `'user'`,
-      }),
-    );
-
-    await queryRunner.createIndex(
-      'user',
-      new TableIndex({
-        name: 'IDX_USER_ROLE',
-        columnNames: ['role'],
-      }),
-    );
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.dropIndex('user', 'IDX_USER_ROLE');
-    await queryRunner.dropColumn('user', 'role');
-  }
-}
-```
-
-### 마이그레이션 원칙
-- `up`과 `down`을 반드시 쌍으로 작성한다 (되돌릴 수 있어야 한다)
-- `down`은 `up`의 역순으로 실행한다
-- `synchronize: true`는 개발 환경에서만 사용한다 - 프로덕션에서는 마이그레이션만 사용한다
-
----
-
-## 6. 트랜잭션
-
-### DataSource.transaction() 패턴
-
-가장 간결한 트랜잭션 패턴이다. 콜백 내에서 제공되는 `EntityManager`를 사용한다.
-
-```typescript
-@Injectable()
-export class OrderService {
-  constructor(private readonly dataSource: DataSource) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    return this.dataSource.transaction(async (manager) => {
-      const order = manager.create(Order, {
-        userId: dto.userId,
-        totalAmount: dto.totalAmount,
-      });
-      await manager.save(order);
-
-      const orderItems = dto.items.map((item) =>
-        manager.create(OrderItem, { ...item, orderId: order.id }),
-      );
-      await manager.save(orderItems);
-
-      await manager.decrement(
-        Product,
-        { id: In(dto.items.map((i) => i.productId)) },
-        'stock',
-        1,
-      );
-
-      return order;
-    });
-  }
-}
-```
-
-### QueryRunner를 사용한 수동 트랜잭션
-
-세밀한 제어가 필요한 경우 사용한다.
-
-```typescript
-async transferPoints(fromId: string, toId: string, amount: number): Promise<void> {
-  const queryRunner = this.dataSource.createQueryRunner();
-  await queryRunner.connect();
-  await queryRunner.startTransaction();
-
-  try {
-    await queryRunner.manager.decrement(User, { id: fromId }, 'points', amount);
-    await queryRunner.manager.increment(User, { id: toId }, 'points', amount);
-
-    await queryRunner.commitTransaction();
-  } catch (error) {
-    await queryRunner.rollbackTransaction();
-    throw error;
-  } finally {
-    await queryRunner.release(); // 반드시 release
-  }
-}
-```
-
-### 트랜잭션 선택 가이드
-
-| 상황 | 권장 패턴 |
-|------|----------|
-| 단순 다중 저장 | `DataSource.transaction()` |
-| 조건부 커밋/롤백 | `QueryRunner` 수동 트랜잭션 |
-| 중간에 외부 API 호출 필요 | `QueryRunner` (커밋 시점 제어) |
-
----
-
-## 7. 성능 최적화
-
-### N+1 문제 방지
-
-```typescript
-// Bad - N+1 문제 발생 (users를 조회 후 각 user마다 posts를 개별 조회)
-const users = await this.userRepository.find();
-for (const user of users) {
-  const posts = await this.postRepository.find({ where: { authorId: user.id } });
-}
-
-// Good - relations으로 한 번에 조회
-const users = await this.userRepository.find({
-  relations: ['posts'],
-});
-
-// Good - QueryBuilder로 한 번에 조회
-const users = await this.userRepository
-  .createQueryBuilder('user')
-  .leftJoinAndSelect('user.posts', 'post')
-  .getMany();
-```
-
-### select로 필요한 컬럼만 조회
-
-```typescript
-// Bad - 모든 컬럼 조회
-const users = await this.userRepository.find();
-
-// Good - 필요한 컬럼만 조회
-const users = await this.userRepository.find({
-  select: { id: true, name: true, email: true },
-});
-
-// Good - QueryBuilder에서 select
-const users = await this.userRepository
-  .createQueryBuilder('user')
-  .select(['user.id', 'user.name', 'user.email'])
-  .getMany();
-```
-
-### 인덱스 설정
-
-```typescript
-@Entity()
-@Index(['email'], { unique: true })
-@Index(['isActive', 'role']) // 복합 인덱스 - 자주 함께 조회하는 컬럼
-@Index(['createdAt'])         // 정렬에 자주 사용되는 컬럼
-export class User {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column({ type: 'varchar' })
-  email: string;
-
-  @Column({ type: 'boolean', default: true })
-  isActive: boolean;
-
-  @Column({ type: 'enum', enum: UserRole })
-  role: UserRole;
-
-  @CreateDateColumn()
-  createdAt: Date;
-}
-```
-
-### 인덱스 설정 원칙
-- WHERE 조건에 자주 사용되는 컬럼에 인덱스를 설정한다
-- ORDER BY에 자주 사용되는 컬럼에 인덱스를 설정한다
-- 복합 인덱스는 카디널리티가 높은 컬럼을 앞에 배치한다
-- 불필요한 인덱스는 쓰기 성능을 저하시키므로 남용하지 않는다
-
-### Pagination
-
-```typescript
-async findUsers(page: number, limit: number): Promise<{ data: User[]; total: number }> {
-  const [data, total] = await this.userRepository.findAndCount({
-    order: { createdAt: 'DESC' },
-    take: limit,
-    skip: (page - 1) * limit,
-  });
-
-  return { data, total };
-}
-```
-
----
-
-## 8. 네이밍 컨벤션
+## 4. 네이밍 컨벤션
 
 | 대상 | 규칙 | 예시 |
 |------|------|------|
@@ -608,7 +313,15 @@ export const dataSource = new DataSource({
 
 ---
 
-## 9. 금지 사항
+## 참조 문서
+
+- **[Advanced Queries](./references/advanced-queries.md)** - QueryBuilder 고급 사용법, 서브쿼리, 성능 최적화, N+1 문제 해결
+- **[Migrations](./references/migrations.md)** - 마이그레이션 생성, 실행, 롤백 및 작성 패턴
+- **[Transactions](./references/transactions.md)** - 트랜잭션 패턴 및 사용 가이드
+
+---
+
+## 5. 금지 사항
 
 - `synchronize: true` 프로덕션 사용 금지 - 마이그레이션을 사용한다
 - Raw SQL 직접 실행 금지 (`query()` 메서드 사용 금지) - QueryBuilder를 사용한다
@@ -618,4 +331,4 @@ export const dataSource = new DataSource({
 - `eager: true` 남용 금지 - 필요할 때 `relations` 옵션으로 로딩한다
 - `find` 시 `where` 조건 없이 전체 조회 금지 (대량 데이터 위험) - 반드시 조건 또는 pagination을 사용한다
 - Repository 외 레이어에서 직접 쿼리 실행 금지 - `../Coding/backend.md` 레이어 규칙을 따른다
-- 마이그레이션 `down` 메서드 누락 금지 - 항상 롤백 가능해야 한다
+- 마이그레이션 `down` 메서드 누락 금지 - 항상 롤백 가능해야 한다

package/.claude/skills/TypeORM/references/advanced-queries.md

@@ -0,0 +1,176 @@
+# TypeORM Advanced Queries - QueryBuilder 고급 사용법 및 성능 최적화
+
+> 이 문서는 `../SKILL.md`의 참조 문서이다.
+
+---
+
+## 1. QueryBuilder
+
+### 기본 사용법
+
+```typescript
+const users = await this.userRepository
+  .createQueryBuilder('user')
+  .select(['user.id', 'user.name', 'user.email'])
+  .where('user.isActive = :isActive', { isActive: true })
+  .andWhere('user.role = :role', { role: UserRole.ADMIN })
+  .orderBy('user.createdAt', 'DESC')
+  .take(20)
+  .skip(0)
+  .getMany();
+```
+
+### JOIN
+
+```typescript
+// leftJoinAndSelect - 관계가 없어도 결과에 포함 (LEFT JOIN)
+const users = await this.userRepository
+  .createQueryBuilder('user')
+  .leftJoinAndSelect('user.posts', 'post')
+  .where('user.id = :id', { id: userId })
+  .getOne();
+
+// innerJoinAndSelect - 관계가 있는 경우만 포함 (INNER JOIN)
+const usersWithPosts = await this.userRepository
+  .createQueryBuilder('user')
+  .innerJoinAndSelect('user.posts', 'post')
+  .getMany();
+```
+
+### 서브쿼리
+
+```typescript
+// 서브쿼리로 특정 조건의 사용자 조회
+const users = await this.userRepository
+  .createQueryBuilder('user')
+  .where((qb) => {
+    const subQuery = qb
+      .subQuery()
+      .select('post.authorId')
+      .from(Post, 'post')
+      .where('post.createdAt > :date', { date: startDate })
+      .getQuery();
+    return `user.id IN ${subQuery}`;
+  })
+  .getMany();
+```
+
+### getOne vs getMany vs getRawOne vs getRawMany
+
+| 메서드 | 반환 타입 | 용도 |
+|--------|----------|------|
+| `getOne()` | `Entity \| null` | Entity 단건 조회 |
+| `getMany()` | `Entity[]` | Entity 목록 조회 |
+| `getRawOne()` | `object \| undefined` | 가공된 데이터 단건 (집계 등) |
+| `getRawMany()` | `object[]` | 가공된 데이터 목록 |
+
+```typescript
+// 집계 쿼리 - getRawOne 사용
+const result = await this.postRepository
+  .createQueryBuilder('post')
+  .select('COUNT(post.id)', 'totalCount')
+  .addSelect('AVG(post.viewCount)', 'avgViews')
+  .where('post.authorId = :authorId', { authorId })
+  .getRawOne();
+// result: { totalCount: '42', avgViews: '128.5' }
+```
+
+### find vs QueryBuilder 가이드
+
+| 상황 | 권장 방법 |
+|------|----------|
+| 단순 CRUD (조건 1~2개) | `find`, `findOne`, `findOneBy` |
+| 단순 관계 로딩 | `find` + `relations` 옵션 |
+| 복잡한 WHERE 조건 (OR, 중첩) | `QueryBuilder` |
+| JOIN 조건이 복잡한 경우 | `QueryBuilder` |
+| 집계 함수 (COUNT, SUM, AVG) | `QueryBuilder` + `getRawOne/getRawMany` |
+| 서브쿼리가 필요한 경우 | `QueryBuilder` |
+| 동적 조건 조합 | `QueryBuilder` |
+
+---
+
+## 2. 성능 최적화
+
+### N+1 문제 방지
+
+```typescript
+// Bad - N+1 문제 발생 (users를 조회 후 각 user마다 posts를 개별 조회)
+const users = await this.userRepository.find();
+for (const user of users) {
+  const posts = await this.postRepository.find({ where: { authorId: user.id } });
+}
+
+// Good - relations으로 한 번에 조회
+const users = await this.userRepository.find({
+  relations: ['posts'],
+});
+
+// Good - QueryBuilder로 한 번에 조회
+const users = await this.userRepository
+  .createQueryBuilder('user')
+  .leftJoinAndSelect('user.posts', 'post')
+  .getMany();
+```
+
+### select로 필요한 컬럼만 조회
+
+```typescript
+// Bad - 모든 컬럼 조회
+const users = await this.userRepository.find();
+
+// Good - 필요한 컬럼만 조회
+const users = await this.userRepository.find({
+  select: { id: true, name: true, email: true },
+});
+
+// Good - QueryBuilder에서 select
+const users = await this.userRepository
+  .createQueryBuilder('user')
+  .select(['user.id', 'user.name', 'user.email'])
+  .getMany();
+```
+
+### 인덱스 설정
+
+```typescript
+@Entity()
+@Index(['email'], { unique: true })
+@Index(['isActive', 'role']) // 복합 인덱스 - 자주 함께 조회하는 컬럼
+@Index(['createdAt'])         // 정렬에 자주 사용되는 컬럼
+export class User {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'varchar' })
+  email: string;
+
+  @Column({ type: 'boolean', default: true })
+  isActive: boolean;
+
+  @Column({ type: 'enum', enum: UserRole })
+  role: UserRole;
+
+  @CreateDateColumn()
+  createdAt: Date;
+}
+```
+
+### 인덱스 설정 원칙
+- WHERE 조건에 자주 사용되는 컬럼에 인덱스를 설정한다
+- ORDER BY에 자주 사용되는 컬럼에 인덱스를 설정한다
+- 복합 인덱스는 카디널리티가 높은 컬럼을 앞에 배치한다
+- 불필요한 인덱스는 쓰기 성능을 저하시키므로 남용하지 않는다
+
+### Pagination
+
+```typescript
+async findUsers(page: number, limit: number): Promise<{ data: User[]; total: number }> {
+  const [data, total] = await this.userRepository.findAndCount({
+    order: { createdAt: 'DESC' },
+    take: limit,
+    skip: (page - 1) * limit,
+  });
+
+  return { data, total };
+}
+```

package/.claude/skills/TypeORM/references/migrations.md

@@ -0,0 +1,62 @@
+# TypeORM Migrations - 마이그레이션 가이드
+
+> 이 문서는 `../SKILL.md`의 참조 문서이다.
+
+---
+
+## 1. CLI 명령어
+
+```bash
+# 마이그레이션 자동 생성 (Entity 변경 감지)
+npx typeorm migration:generate src/migrations/AddUserRole -d src/data-source.ts
+
+# 마이그레이션 수동 생성 (빈 파일)
+npx typeorm migration:create src/migrations/SeedInitialData
+
+# 마이그레이션 실행
+npx typeorm migration:run -d src/data-source.ts
+
+# 마이그레이션 되돌리기 (가장 최근 1개)
+npx typeorm migration:revert -d src/data-source.ts
+```
+
+---
+
+## 2. 마이그레이션 파일 작성 패턴
+
+```typescript
+export class AddUserRole1700000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.addColumn(
+      'user',
+      new TableColumn({
+        name: 'role',
+        type: 'enum',
+        enum: ['user', 'admin', 'moderator'],
+        default: `'user'`,
+      }),
+    );
+
+    await queryRunner.createIndex(
+      'user',
+      new TableIndex({
+        name: 'IDX_USER_ROLE',
+        columnNames: ['role'],
+      }),
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropIndex('user', 'IDX_USER_ROLE');
+    await queryRunner.dropColumn('user', 'role');
+  }
+}
+```
+
+---
+
+## 3. 마이그레이션 원칙
+
+- `up`과 `down`을 반드시 쌍으로 작성한다 (되돌릴 수 있어야 한다)
+- `down`은 `up`의 역순으로 실행한다
+- `synchronize: true`는 개발 환경에서만 사용한다 - 프로덕션에서는 마이그레이션만 사용한다