@choblue/claude-code-toolkit 1.0.0

package/.claude/agents/tdd/backend.md

@@ -0,0 +1,207 @@
+# TDD Agent - Backend (NestJS)
+
+NestJS 기반 백엔드 테스트를 작성할 때 이 규칙을 따른다.
+공통 규칙은 `common.md`를 함께 참고한다.
+
+---
+
+## 테스트 우선순위
+
+NestJS 레이어별 테스트 중요도에 따라 우선순위를 정한다:
+
+1. **Service** - 비즈니스 로직이 집중된 핵심 레이어 (필수)
+2. **Controller** - 요청/응답 매핑, DTO 바인딩 검증 (권장)
+3. **Guard / Interceptor / Pipe** - 횡단 관심사 검증 (필요 시)
+4. **E2E** - 전체 요청 흐름 통합 검증 (주요 시나리오)
+
+---
+
+## 단위 테스트 패턴
+
+### Test.createTestingModule 사용
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+
+describe('UserService', () => {
+  let service: UserService;
+  let repository: jest.Mocked<UserRepository>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UserService,
+        {
+          provide: UserRepository,
+          useValue: {
+            findById: jest.fn(),
+            save: jest.fn(),
+            delete: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<UserService>(UserService);
+    repository = module.get(UserRepository);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+});
+```
+
+### Mock 패턴: Provider 오버라이드
+```typescript
+// 방법 1: useValue - 직접 Mock 객체 제공
+{
+  provide: UserRepository,
+  useValue: {
+    findById: jest.fn().mockResolvedValue(mockUser),
+  },
+}
+
+// 방법 2: useClass - Mock 클래스 제공
+{
+  provide: UserRepository,
+  useClass: MockUserRepository,
+}
+
+// 방법 3: useFactory - 동적 Mock 생성
+{
+  provide: UserRepository,
+  useFactory: () => ({
+    findById: jest.fn(),
+  }),
+}
+```
+
+### jest.Mocked 타입 활용
+```typescript
+// 타입 안전한 Mock 사용
+let repository: jest.Mocked<UserRepository>;
+
+// 자동 완성과 타입 체크가 가능하다
+repository.findById.mockResolvedValue(mockUser);
+expect(repository.findById).toHaveBeenCalledWith('1');
+```
+
+### Controller 테스트
+```typescript
+describe('UserController', () => {
+  let controller: UserController;
+  let service: jest.Mocked<UserService>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [UserController],
+      providers: [
+        {
+          provide: UserService,
+          useValue: {
+            getUserById: jest.fn(),
+            createUser: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<UserController>(UserController);
+    service = module.get(UserService);
+  });
+
+  describe('GET /users/:id', () => {
+    it('should return user when valid id is given', async () => {
+      const mockUser = { id: '1', name: 'Alice' };
+      service.getUserById.mockResolvedValue(mockUser);
+
+      const result = await controller.getUserById('1');
+
+      expect(result).toEqual(mockUser);
+    });
+  });
+});
+```
+
+---
+
+## E2E 테스트 패턴
+
+### supertest + INestApplication
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import * as request from 'supertest';
+import { AppModule } from '../src/app.module';
+
+describe('UserController (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('/users (GET) should return user list', () => {
+    return request(app.getHttpServer())
+      .get('/users')
+      .expect(200)
+      .expect((res) => {
+        expect(Array.isArray(res.body)).toBe(true);
+      });
+  });
+
+  it('/users (POST) should create a new user', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .send({ name: 'Alice', email: 'alice@example.com' })
+      .expect(201)
+      .expect((res) => {
+        expect(res.body).toHaveProperty('id');
+        expect(res.body.name).toBe('Alice');
+      });
+  });
+});
+```
+
+---
+
+## 파일 네이밍
+
+### 단위 테스트 (co-located)
+```
+src/
+├── modules/
+│   └── user/
+│       ├── user.service.ts
+│       ├── user.service.spec.ts        # Service 테스트
+│       ├── user.controller.ts
+│       └── user.controller.spec.ts     # Controller 테스트
+```
+
+### E2E 테스트
+```
+test/
+├── user.e2e-spec.ts
+├── auth.e2e-spec.ts
+└── jest-e2e.json
+```
+
+---
+
+## 규칙
+
+- 단위 테스트 파일명은 `*.spec.ts`로 소스 파일 옆에 배치한다 (co-located)
+- E2E 테스트 파일명은 `*.e2e-spec.ts`로 `test/` 디렉토리에 배치한다
+- `Test.createTestingModule`로 의존성을 격리한다 - 직접 `new`로 생성하지 않는다
+- DB 의존 테스트는 테스트용 DB 또는 인메모리 DB를 사용한다
+- E2E 테스트에서 `afterAll`로 반드시 앱을 종료(`app.close()`)한다
+- `.claude/skills/TDD/backend.md`의 규칙을 따른다

package/.claude/agents/tdd/common.md

@@ -0,0 +1,137 @@
+# TDD Agent - 공통 규칙
+
+당신은 테스트 코드 작성 및 실행 전문가다. Red-Green-Refactor 사이클에 따라 테스트를 설계하고 작성한다.
+
+---
+
+## 핵심 원칙
+
+- **테스트가 먼저다.** 구현 코드보다 테스트를 먼저 작성한다.
+- **하나의 테스트, 하나의 검증.** 한 테스트 케이스에서 하나의 동작만 검증한다.
+- **AAA 패턴을 준수한다.** 모든 테스트는 Arrange-Act-Assert 구조를 따른다.
+- `.claude/skills/TDD/SKILL.md`의 원칙을 따른다.
+
+---
+
+## 작업 절차 (Red-Green-Refactor)
+
+### 1. Red - 실패하는 테스트 작성
+- 구현할 기능의 기대 동작을 테스트로 정의한다
+- `describe` / `it` 블록으로 테스트 구조를 명확히 한다
+- 아직 구현이 없으므로 테스트가 실패하는 것을 확인한다
+- 경계값, 에러 케이스, 정상 케이스를 모두 고려한다
+
+```typescript
+// AAA 패턴 예시
+it('should return user by id', () => {
+  // Arrange - 테스트 데이터 준비
+  const mockUser = { id: '1', name: 'Alice' };
+  repository.findById.mockResolvedValue(mockUser);
+
+  // Act - 테스트 대상 실행
+  const result = await service.getUserById('1');
+
+  // Assert - 결과 검증
+  expect(result).toEqual(mockUser);
+  expect(repository.findById).toHaveBeenCalledWith('1');
+});
+```
+
+### 2. Green - 최소 구현 요청
+- 테스트를 통과시키기 위한 최소한의 코드 구현을 `code-writer` 에이전트에 위임 요청한다
+- 위임 시 테스트 파일 경로와 기대 동작을 명시한다
+- 구현 후 테스트가 통과하는지 실행하여 확인한다
+
+### 3. Refactor - 리팩토링 포인트 식별
+- 테스트 통과를 유지하면서 리팩토링 포인트를 식별한다
+- 중복 제거, 네이밍 개선, 구조 개선 등을 보고한다
+- 리팩토링이 필요하면 `code-writer` 에이전트에 위임 요청한다
+- 리팩토링 후 모든 테스트가 여전히 통과하는지 재확인한다
+
+---
+
+## 테스트 실행 및 검증
+
+### 실행 명령
+```bash
+# 전체 테스트 실행
+npm test
+
+# 특정 파일 테스트
+npx jest path/to/file.spec.ts
+
+# watch 모드
+npx jest --watch
+
+# 커버리지 포함
+npx jest --coverage
+```
+
+### 검증 체크리스트
+- [ ] 모든 테스트가 통과하는가
+- [ ] 테스트가 독립적으로 실행 가능한가 (다른 테스트에 의존하지 않는가)
+- [ ] Mock/Stub이 올바르게 정리(cleanup)되는가
+- [ ] 경계값과 에러 케이스가 포함되어 있는가
+
+---
+
+## 테스트 설계 가이드
+
+### describe 구조
+```typescript
+describe('UserService', () => {
+  describe('getUserById', () => {
+    it('should return user when valid id is given', () => { ... });
+    it('should throw NotFoundException when user does not exist', () => { ... });
+    it('should throw BadRequestException when id is empty', () => { ... });
+  });
+});
+```
+
+### Mock 사용 원칙
+- 외부 의존성(DB, API, 파일시스템)은 항상 Mock한다
+- 테스트 대상의 내부 구현은 Mock하지 않는다
+- Mock은 최소한으로 사용한다 - 과도한 Mock은 테스트 신뢰도를 떨어뜨린다
+
+---
+
+## 출력 형식
+
+```
+## Test Report
+
+### 테스트 파일
+- `path/to/file.spec.ts` (신규/수정) - 설명
+
+### 테스트 현황
+- 전체: N개
+- 성공: N개
+- 실패: N개
+- 건너뜀: N개
+
+### 커버리지 (가능한 경우)
+- Statements: N%
+- Branches: N%
+- Functions: N%
+- Lines: N%
+
+### Red-Green-Refactor 결과
+- Red: 작성한 실패 테스트 목록
+- Green: 통과 확인 여부
+- Refactor: 식별된 리팩토링 포인트
+
+### 참고 사항
+- 추가 테스트가 필요한 영역
+- 테스트하기 어려운 부분과 그 이유
+```
+
+---
+
+## 규칙
+
+- 테스트 코드도 프로덕션 코드와 동일한 품질 기준을 적용한다
+- 테스트 설명(`it` / `describe`)은 행동 중심으로 작성한다 ("should ..." 형식)
+- 매직 넘버를 사용하지 않는다 - 의미 있는 변수명을 사용한다
+- `beforeEach` / `afterEach`로 테스트 간 상태를 격리한다
+- 비동기 테스트는 반드시 `async/await`를 사용한다
+- Frontend/Backend별 상세 규칙은 각각의 파일을 참고한다

package/.claude/agents/tdd/frontend.md

@@ -0,0 +1,250 @@
+# TDD Agent - Frontend (React)
+
+React 기반 프론트엔드 테스트를 작성할 때 이 규칙을 따른다.
+공통 규칙은 `common.md`를 함께 참고한다.
+
+---
+
+## Testing Library 쿼리 우선순위
+
+접근성과 사용자 관점을 반영하여 아래 순서로 쿼리를 선택한다:
+
+1. **`getByRole`** - 가장 우선. 접근성 역할 기반 (e.g., `button`, `textbox`, `heading`)
+2. **`getByLabelText`** - 폼 요소에 적합. label 연결 기반
+3. **`getByPlaceholderText`** - label이 없는 입력 필드
+4. **`getByText`** - 비대화형 요소의 텍스트 기반
+5. **`getByDisplayValue`** - 현재 값이 표시된 폼 요소
+6. **`getByAltText`** - 이미지, area 요소
+7. **`getByTitle`** - title 속성 기반
+8. **`getByTestId`** - 최후의 수단. 다른 쿼리로 불가능할 때만 사용
+
+```typescript
+// 좋은 예 - 역할 기반 쿼리
+const submitButton = screen.getByRole('button', { name: '제출' });
+const emailInput = screen.getByRole('textbox', { name: '이메일' });
+
+// 피할 예 - testId 의존
+const submitButton = screen.getByTestId('submit-btn');
+```
+
+---
+
+## 사용자 이벤트
+
+### userEvent 사용 (fireEvent보다 우선)
+```typescript
+import userEvent from '@testing-library/user-event';
+
+it('should call onSubmit when form is submitted', async () => {
+  const user = userEvent.setup();
+  const handleSubmit = jest.fn();
+
+  render(<LoginForm onSubmit={handleSubmit} />);
+
+  // userEvent는 실제 사용자 행동을 시뮬레이션한다
+  await user.type(screen.getByRole('textbox', { name: '이메일' }), 'alice@example.com');
+  await user.type(screen.getByLabelText('비밀번호'), 'password123');
+  await user.click(screen.getByRole('button', { name: '로그인' }));
+
+  expect(handleSubmit).toHaveBeenCalledWith({
+    email: 'alice@example.com',
+    password: 'password123',
+  });
+});
+```
+
+### fireEvent vs userEvent
+- `userEvent`: 실제 사용자 동작 시뮬레이션 (클릭, 타이핑, 탭 이동 등). **기본으로 사용한다.**
+- `fireEvent`: DOM 이벤트 직접 발생. `scroll`, `resize` 등 userEvent가 지원하지 않는 이벤트에만 사용한다.
+
+---
+
+## 커스텀 훅 테스트
+
+### renderHook 패턴
+```typescript
+import { renderHook, waitFor } from '@testing-library/react';
+
+describe('useCounter', () => {
+  it('should increment counter', () => {
+    const { result } = renderHook(() => useCounter(0));
+
+    act(() => {
+      result.current.increment();
+    });
+
+    expect(result.current.count).toBe(1);
+  });
+});
+```
+
+### Provider가 필요한 훅
+```typescript
+describe('useUser', () => {
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={new QueryClient()}>
+      {children}
+    </QueryClientProvider>
+  );
+
+  it('should fetch user data', async () => {
+    const { result } = renderHook(() => useUser('1'), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toEqual(mockUser);
+  });
+});
+```
+
+---
+
+## Provider Wrapper 패턴
+
+### 공통 테스트 렌더 함수
+```typescript
+// test/utils.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import { render, RenderOptions } from '@testing-library/react';
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+}
+
+interface CustomRenderOptions extends Omit<RenderOptions, 'wrapper'> {
+  initialEntries?: string[];
+}
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  options: CustomRenderOptions = {},
+) {
+  const { initialEntries = ['/'], ...renderOptions } = options;
+  const queryClient = createTestQueryClient();
+
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={initialEntries}>
+          {children}
+        </MemoryRouter>
+      </QueryClientProvider>
+    );
+  }
+
+  return render(ui, { wrapper: Wrapper, ...renderOptions });
+}
+```
+
+---
+
+## MSW (Mock Service Worker) API 모킹
+
+### 핸들러 정의
+```typescript
+// mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  http.get('/api/users', () => {
+    return HttpResponse.json([
+      { id: '1', name: 'Alice' },
+      { id: '2', name: 'Bob' },
+    ]);
+  }),
+
+  http.post('/api/users', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: '3', ...body }, { status: 201 });
+  }),
+
+  http.get('/api/users/:id', ({ params }) => {
+    const { id } = params;
+    return HttpResponse.json({ id, name: 'Alice' });
+  }),
+];
+```
+
+### 서버 설정
+```typescript
+// mocks/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+```
+
+### 테스트에서 사용
+```typescript
+import { server } from '../mocks/server';
+import { http, HttpResponse } from 'msw';
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+it('should display user list', async () => {
+  render(<UserList />);
+
+  await waitFor(() => {
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+  });
+});
+
+it('should display error message on server error', async () => {
+  // 특정 테스트에서 핸들러 오버라이드
+  server.use(
+    http.get('/api/users', () => {
+      return HttpResponse.json(null, { status: 500 });
+    }),
+  );
+
+  render(<UserList />);
+
+  await waitFor(() => {
+    expect(screen.getByText('오류가 발생했습니다')).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## 파일 네이밍
+
+```
+src/
+├── components/
+│   └── UserCard/
+│       ├── UserCard.tsx
+│       └── UserCard.test.tsx        # 컴포넌트 테스트
+├── hooks/
+│   ├── useAuth.ts
+│   └── useAuth.test.ts              # 훅 테스트
+├── utils/
+│   ├── formatDate.ts
+│   └── formatDate.test.ts           # 유틸리티 테스트
+└── mocks/
+    ├── handlers.ts                  # MSW 핸들러
+    └── server.ts                    # MSW 서버 설정
+```
+
+---
+
+## 규칙
+
+- 테스트 파일명은 `*.test.tsx` (컴포넌트) 또는 `*.test.ts` (훅/유틸)을 사용한다
+- `getByTestId`는 다른 쿼리로 선택이 불가능할 때만 최후의 수단으로 사용한다
+- `userEvent`를 기본으로 사용한다 - `fireEvent`는 특수한 경우에만 사용한다
+- `waitFor` / `findBy`로 비동기 렌더링을 올바르게 처리한다
+- API 모킹은 MSW를 사용한다 - `jest.mock`으로 fetch/axios를 직접 모킹하지 않는다
+- 스냅샷 테스트(`toMatchSnapshot`)는 지양한다 - 행동 기반 테스트를 작성한다
+- `.claude/skills/TDD/frontend.md`의 규칙을 따른다

package/.claude/hooks/quality-gate.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# quality-gate.sh
+# UserPromptSubmit hook - 매 프롬프트마다 실행되어 품질 체크 프로토콜을 상기시킨다.
+
+# 사용자 프롬프트를 stdin으로 받는다
+PROMPT=$(cat)
+
+# 품질 체크 메시지를 출력한다 (Claude가 읽는 컨텍스트)
+cat << 'EOF'
+[Quality Gate Reminder]
+- 작업 전: 적절한 Agent/Skill이 있는지 확인하라
+- 코드 구현: code-writer 에이전트에 위임하라 (직접 작성 금지)
+- 코드 구현 전: tdd 에이전트로 실패하는 테스트를 먼저 작성하라
+- 코드 수정 후: code-reviewer 에이전트로 리뷰하라
+- Git 작업: git-manager 에이전트에 위임하라
+- Context 절약: 탐색은 explore 에이전트에 위임하라
+EOF

package/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/quality-gate.sh"
+          }
+        ]
+      }
+    ]
+  }
+}