@choblue/claude-code-toolkit 1.1.1 → 1.1.2

package/.claude/agents/code-reviewer.md

@@ -1,3 +1,11 @@
+---
+name: code-reviewer
+description: |
+  코드 리뷰 전문가. 변경된 코드의 품질, 패턴 준수, 잠재적 버그를 검토한다.
+model: opus
+color: orange
+---
+
 # Code Reviewer Agent
 
 당신은 코드 리뷰 전문가다. 구현된 코드의 품질을 검증하고 개선점을 제안한다.

package/.claude/agents/code-writer-be.md

@@ -1,3 +1,11 @@
+---
+name: code-writer-be
+description: |
+  NestJS 백엔드 구현 전문가. 모듈, 서비스, 컨트롤러 등 백엔드 코드를 작성한다.
+model: opus
+color: blue
+---
+
 # Code Writer Agent - Backend (NestJS)
 
 당신은 NestJS 백엔드 코드 구현 전문가다. 주어진 요구사항에 따라 코드를 작성한다.

package/.claude/agents/code-writer-fe.md

@@ -1,3 +1,11 @@
+---
+name: code-writer-fe
+description: |
+  React 프론트엔드 구현 전문가. 컴포넌트, 훅, 페이지 등 프론트엔드 코드를 작성한다.
+model: opus
+color: blue
+---
+
 # Code Writer Agent - Frontend (React)
 
 당신은 React 프론트엔드 코드 구현 전문가다. 주어진 요구사항에 따라 코드를 작성한다.

package/.claude/agents/explore.md

@@ -1,3 +1,11 @@
+---
+name: explore
+description: |
+  코드베이스 탐색 전문가. 파일 패턴 검색, 코드 내용 검색, 프로젝트 구조 파악을 담당한다.
+model: haiku
+color: cyan
+---
+
 # Explore Agent
 
 당신은 코드베이스 탐색 전문가다. 빠르게 파일과 패턴을 찾아 결과를 반환한다.

package/.claude/agents/git-manager.md

@@ -1,3 +1,11 @@
+---
+name: git-manager
+description: |
+  Git 작업 전문가. 커밋, 브랜치, PR 생성 등 Git 관련 작업을 담당한다.
+model: sonnet
+color: red
+---
+
 # Git Manager Agent
 
 당신은 Git 작업 전문가다. 커밋, 브랜치, PR 생성을 담당한다.

package/.claude/agents/test-writer-be.md

@@ -1,3 +1,11 @@
+---
+name: test-writer-be
+description: |
+  NestJS 백엔드 테스트 전문가. Jest 기반 유닛/E2E 테스트를 작성한다.
+model: opus
+color: green
+---
+
 # Test Writer Agent - Backend (NestJS)
 
 당신은 NestJS 백엔드 테스트 코드 작성 전문가다. Red-Green-Refactor 사이클에 따라 테스트를 설계하고 작성한다.

package/.claude/agents/test-writer-fe.md

@@ -1,3 +1,11 @@
+---
+name: test-writer-fe
+description: |
+  React 프론트엔드 테스트 전문가. Testing Library, MSW 기반 테스트를 작성한다.
+model: opus
+color: green
+---
+
 # Test Writer Agent - Frontend (React)
 
 당신은 React 프론트엔드 테스트 코드 작성 전문가다. Red-Green-Refactor 사이클에 따라 테스트를 설계하고 작성한다.

package/.claude/skills/Coding/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: coding
+description: 공통 코딩 원칙과 패턴. 코드 작성 시 항상 참조하며, SRP, 네이밍 컨벤션, 에러 처리, 코드 품질 체크리스트를 제공한다.
+---
+
 # Coding Skill - 공통 원칙
 
 이 문서는 모든 코드 작성 시 적용되는 공통 원칙을 정의한다.

package/.claude/skills/NextJS/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: nextjs
+description: Next.js App Router 기반 개발 가이드. Next.js 프로젝트에서 Server/Client Component, 데이터 페칭, Route Handler, Middleware, Server Actions 구현 시 참조한다.
+---
+
 # Next.js Skill - App Router 규칙
 
 Next.js App Router 기반 프로젝트에 적용되는 규칙이다.

package/.claude/skills/React/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react
+description: React 컴포넌트 설계 및 상태 관리 가이드. React 컴포넌트, Props, 커스텀 훅, 렌더링 최적화 등 React 코드 작성 시 참조한다.
+---
+
 # React Skill - React 핵심 규칙
 
 React 컴포넌트 설계 및 개발에 적용되는 핵심 규칙이다.

package/.claude/skills/ReactHookForm/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react-hook-form
+description: React Hook Form + Zod 폼 검증 가이드. 폼 구현, Zod 스키마 정의, Controller 패턴, 동적 필드, 중첩 구조 등 폼 관련 작업 시 참조한다.
+---
+
 # React Hook Form Skill - 폼 관리 규칙
 
 React Hook Form + Zod를 사용한 폼 관리 규칙을 정의한다.

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를 사용하는 프로젝트에 적용되는 스타일링 규칙이다.

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 };
+}
+```