@choblue/claude-code-toolkit 1.0.0

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

@@ -0,0 +1,317 @@
+# React Hook Form Skill - 폼 관리 규칙
+
+React Hook Form + Zod를 사용한 폼 관리 규칙을 정의한다.
+공통 코딩 원칙은 `../Coding/SKILL.md`를 참고한다.
+
+---
+
+## 1. Zod 스키마 정의
+
+### 기본 스키마
+
+```typescript
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  name: z.string().min(1, '이름을 입력해주세요').max(50, '이름은 50자 이내로 입력해주세요'),
+  email: z.string().email('올바른 이메일 형식이 아닙니다'),
+  age: z.number().min(1, '나이는 1 이상이어야 합니다').max(150, '올바른 나이를 입력해주세요'),
+  role: z.enum(['admin', 'user', 'guest']),
+});
+```
+
+### Refinement와 Transform
+
+```typescript
+const signupSchema = z
+  .object({
+    password: z.string().min(8, '비밀번호는 8자 이상이어야 합니다'),
+    confirmPassword: z.string(),
+    phone: z.string().transform((val) => val.replace(/-/g, '')), // 하이픈 제거
+  })
+  .refine((data) => data.password === data.confirmPassword, {
+    message: '비밀번호가 일치하지 않습니다',
+    path: ['confirmPassword'], // 에러가 표시될 필드
+  });
+```
+
+---
+
+## 2. 타입 추론
+
+Zod 스키마에서 폼 타입을 자동으로 추론한다. 별도의 타입을 수동으로 정의하지 않는다.
+
+```typescript
+// Good - 스키마에서 타입 추론
+const createUserSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+});
+
+type CreateUserForm = z.infer<typeof createUserSchema>;
+// { name: string; email: string; }
+
+// Bad - 수동으로 타입 정의 (스키마와 불일치 위험)
+interface CreateUserForm {
+  name: string;
+  email: string;
+}
+```
+
+---
+
+## 3. zodResolver 연동
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+function CreateUserForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<CreateUserForm>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: {
+      name: '',
+      email: '',
+    },
+  });
+
+  const onSubmit = async (data: CreateUserForm) => {
+    // data는 스키마 검증을 통과한 안전한 데이터
+    await createUser(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        생성
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## 4. Controller 패턴
+
+`register`를 사용할 수 없는 제어 컴포넌트 (Select, DatePicker, 커스텀 UI 라이브러리 등)에 사용한다.
+
+```typescript
+import { Controller, useForm } from 'react-hook-form';
+
+function UserForm() {
+  const { control, handleSubmit } = useForm<UserFormValues>({
+    resolver: zodResolver(userSchema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="role"
+        control={control}
+        render={({ field, fieldState: { error } }) => (
+          <>
+            <Select
+              value={field.value}
+              onChange={field.onChange}
+              options={roleOptions}
+            />
+            {error && <span>{error.message}</span>}
+          </>
+        )}
+      />
+
+      <Controller
+        name="birthDate"
+        control={control}
+        render={({ field, fieldState: { error } }) => (
+          <>
+            <DatePicker
+              selected={field.value}
+              onChange={field.onChange}
+            />
+            {error && <span>{error.message}</span>}
+          </>
+        )}
+      />
+    </form>
+  );
+}
+```
+
+---
+
+## 5. 에러 핸들링
+
+### errors 객체로 직접 표시
+
+```typescript
+// 간단한 에러 표시
+{errors.email && <span className="error">{errors.email.message}</span>}
+```
+
+### 재사용 가능한 에러 컴포넌트
+
+```typescript
+interface FieldErrorProps {
+  error?: FieldError;
+}
+
+function FieldError({ error }: FieldErrorProps) {
+  if (!error) return null;
+  return <span className="field-error">{error.message}</span>;
+}
+
+// 사용
+<input {...register('email')} />
+<FieldError error={errors.email} />
+```
+
+---
+
+## 6. 폼 검증 모드
+
+### mode 옵션
+
+| mode | 동작 | 용도 |
+|------|------|------|
+| `onSubmit` (기본) | 제출 시에만 검증 | 대부분의 폼 |
+| `onBlur` | 포커스를 벗어날 때 검증 | 긴 폼, 단계별 입력 |
+| `onChange` | 입력할 때마다 검증 | 실시간 피드백이 필요한 필드 |
+| `onTouched` | 첫 blur 이후부터 onChange로 검증 | 사용자 친화적 검증 |
+
+```typescript
+const { register, handleSubmit } = useForm<FormValues>({
+  resolver: zodResolver(schema),
+  mode: 'onBlur', // 포커스를 벗어날 때 검증
+});
+```
+
+---
+
+## 7. 동적 필드 (useFieldArray)
+
+반복되는 필드 그룹을 동적으로 추가/삭제한다.
+
+```typescript
+const orderSchema = z.object({
+  items: z.array(
+    z.object({
+      productId: z.string().min(1, '상품을 선택해주세요'),
+      quantity: z.number().min(1, '수량은 1개 이상이어야 합니다'),
+    })
+  ).min(1, '최소 1개 이상의 상품을 추가해주세요'),
+});
+
+type OrderForm = z.infer<typeof orderSchema>;
+
+function OrderForm() {
+  const { control, register, handleSubmit } = useForm<OrderForm>({
+    resolver: zodResolver(orderSchema),
+    defaultValues: { items: [{ productId: '', quantity: 1 }] },
+  });
+
+  const { fields, append, remove } = useFieldArray({
+    control,
+    name: 'items',
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {fields.map((field, index) => (
+        <div key={field.id}>
+          <input {...register(`items.${index}.productId`)} />
+          <input
+            type="number"
+            {...register(`items.${index}.quantity`, { valueAsNumber: true })}
+          />
+          <button type="button" onClick={() => remove(index)}>
+            삭제
+          </button>
+        </div>
+      ))}
+      <button type="button" onClick={() => append({ productId: '', quantity: 1 })}>
+        상품 추가
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## 8. 중첩 객체 / 배열 스키마
+
+### 중첩 객체
+
+```typescript
+const addressSchema = z.object({
+  zipCode: z.string().length(5, '우편번호는 5자리입니다'),
+  city: z.string().min(1, '도시를 입력해주세요'),
+  detail: z.string().min(1, '상세 주소를 입력해주세요'),
+});
+
+const userSchema = z.object({
+  name: z.string().min(1),
+  address: addressSchema,       // 중첩 객체
+  tags: z.array(z.string()),    // 문자열 배열
+});
+
+type UserForm = z.infer<typeof userSchema>;
+
+// register로 점 표기법 사용
+<input {...register('address.zipCode')} />
+<input {...register('address.city')} />
+<input {...register('address.detail')} />
+
+// 에러 접근도 점 표기법
+{errors.address?.zipCode && <span>{errors.address.zipCode.message}</span>}
+```
+
+### 스키마 재사용
+
+```typescript
+// 공통 스키마를 조합하여 재사용한다
+const baseUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+const createUserSchema = baseUserSchema.extend({
+  password: z.string().min(8),
+});
+
+const updateUserSchema = baseUserSchema.partial(); // 모든 필드 optional
+```
+
+---
+
+## 9. 네이밍 컨벤션
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 스키마 변수 | camelCase + `Schema` | `createUserSchema` |
+| 폼 타입 | PascalCase + `Form` | `CreateUserForm` |
+| 스키마 파일 | 도메인 + `.schema.ts` | `user.schema.ts` |
+| 폼 컴포넌트 | PascalCase + `Form` | `CreateUserForm.tsx` |
+
+---
+
+## 10. 금지 사항
+
+- 스키마 없이 수동 검증 금지 - 반드시 Zod 스키마를 정의하고 `zodResolver`를 사용한다
+- `any` 타입 사용 금지 - `z.infer<typeof schema>`로 타입을 추론한다
+- `register` 없이 `<input>` 사용 금지 - 모든 입력 필드는 `register` 또는 `Controller`로 연결한다
+- `handleSubmit` 없이 `onSubmit` 직접 처리 금지 - `handleSubmit`이 검증을 수행한다
+- 폼 타입과 스키마를 별도로 정의 금지 - 타입 불일치 위험이 있으므로 `z.infer`를 사용한다
+- 에러 메시지 하드코딩 금지 - Zod 스키마에 메시지를 정의한다

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

@@ -0,0 +1,161 @@
+# TDD Skill - 핵심 원칙
+
+이 문서는 모든 테스트 코드 작성 시 적용되는 공통 원칙을 정의한다.
+FE/BE별 상세 규칙은 각각의 파일을 참고한다.
+- `frontend.md` - React Testing Library 기반 프론트엔드 테스트 규칙
+- `backend.md` - NestJS 백엔드 테스트 규칙
+
+---
+
+## 1. TDD 핵심 사이클
+
+모든 기능 구현은 Red-Green-Refactor 사이클을 따른다.
+
+### Red (실패하는 테스트 작성)
+- 구현 코드보다 **테스트를 먼저** 작성한다
+- 테스트가 실패하는 것을 확인한 뒤 다음 단계로 진행한다
+- 실패 이유가 "기능이 없어서"여야 한다 (문법 에러가 아님)
+
+### Green (최소한의 코드로 통과)
+- 테스트를 통과시키는 **가장 단순한** 코드를 작성한다
+- 완벽한 설계나 최적화를 고려하지 않는다
+- 하드코딩이라도 괜찮다 - 목표는 "초록불"이다
+
+### Refactor (리팩토링)
+- 테스트가 통과하는 상태를 유지하면서 코드를 개선한다
+- 중복을 제거하고, 네이밍을 개선하고, 구조를 정리한다
+- 리팩토링 후 반드시 테스트를 다시 실행한다
+
+```
+[Red] 실패하는 테스트 작성
+  ↓
+[Green] 최소 구현으로 통과
+  ↓
+[Refactor] 코드 개선 (테스트 유지)
+  ↓
+[Red] 다음 테스트 작성 ...
+```
+
+---
+
+## 2. FIRST 원칙
+
+좋은 테스트는 다음 5가지 특성을 갖는다.
+
+| 원칙 | 설명 | 위반 예시 |
+|------|------|-----------|
+| **Fast** | 빠르게 실행된다 | DB 연결, 네트워크 호출이 포함된 단위 테스트 |
+| **Isolated** | 다른 테스트에 의존하지 않는다 | 테스트 실행 순서에 따라 결과가 달라짐 |
+| **Repeatable** | 어떤 환경에서도 동일한 결과를 낸다 | 현재 시각, 랜덤 값에 의존하는 테스트 |
+| **Self-validating** | 성공/실패가 자동 판별된다 | console.log로 결과를 수동 확인 |
+| **Timely** | 구현 코드와 함께(또는 먼저) 작성된다 | 구현 완료 후 나중에 테스트 추가 |
+
+---
+
+## 3. AAA 패턴 (Arrange-Act-Assert)
+
+모든 테스트는 3단계로 구성한다. 각 단계를 빈 줄로 구분하여 가독성을 높인다.
+
+```typescript
+it('should calculate total price with discount', () => {
+  // Arrange - 테스트 전제 조건을 설정한다
+  const cart = new Cart();
+  cart.addItem({ name: 'Book', price: 10000 });
+  const discount = 0.1;
+
+  // Act - 테스트 대상을 실행한다
+  const totalPrice = cart.calculateTotal(discount);
+
+  // Assert - 기대 결과를 검증한다
+  expect(totalPrice).toBe(9000);
+});
+```
+
+### 규칙
+- **Arrange**: 테스트에 필요한 데이터, Mock, 환경을 준비한다
+- **Act**: 테스트 대상 함수/메서드를 **한 번만** 호출한다
+- **Assert**: 결과를 검증한다. 하나의 테스트에서 관련된 단언만 포함한다
+- 빈 줄 또는 주석(`// Arrange`, `// Act`, `// Assert`)으로 구분한다
+
+---
+
+## 4. 테스트 네이밍
+
+### describe-it 패턴
+
+```typescript
+describe('CartService', () => {
+  describe('calculateTotal', () => {
+    it('should return 0 when cart is empty', () => {});
+    it('should sum all item prices', () => {});
+    it('should apply discount rate to total', () => {});
+    it('should throw error when discount is negative', () => {});
+  });
+
+  describe('addItem', () => {
+    it('should add item to cart', () => {});
+    it('should increase quantity when same item is added', () => {});
+  });
+});
+```
+
+### 규칙
+- `describe`: 테스트 대상 (클래스명, 함수명, 컴포넌트명)
+- `it`: `should` + 동작을 서술한다
+- 중첩 `describe`로 메서드/시나리오를 그룹핑한다
+- 테스트 이름만으로 **어떤 상황에서 어떤 결과가 나오는지** 파악할 수 있어야 한다
+
+---
+
+## 5. Mock / Stub / Spy 가이드라인
+
+### 용어 정의
+
+| 종류 | 역할 | 사용 시점 |
+|------|------|-----------|
+| **Stub** | 정해진 값을 반환한다 | 외부 의존성의 반환값을 제어할 때 |
+| **Mock** | 호출 여부/인자를 검증한다 | 특정 함수가 호출되었는지 확인할 때 |
+| **Spy** | 실제 구현을 유지하면서 호출을 추적한다 | 실제 동작은 유지하되 호출 여부만 확인할 때 |
+
+### 사용해야 하는 경우
+- 외부 시스템 호출 (API, DB, 파일 시스템)
+- 비결정적 동작 (현재 시각, 랜덤 값)
+- 느린 의존성 (네트워크, 디스크 I/O)
+- 에러/예외 시나리오 재현
+
+### 피해야 하는 경우
+- 테스트 대상 자체를 Mock하는 것 (의미 없는 테스트)
+- 내부 구현 세부사항을 Mock하는 것 (리팩토링에 취약)
+- 과도한 Mock으로 실제 동작과 괴리가 생기는 것
+
+```typescript
+// Bad - 내부 구현을 Mock하여 리팩토링 시 테스트가 깨짐
+jest.spyOn(service, 'privateHelper');
+expect(service['privateHelper']).toHaveBeenCalled();
+
+// Good - 공개 인터페이스의 결과를 검증
+const result = service.processOrder(orderDto);
+expect(result.status).toBe('COMPLETED');
+```
+
+### 원칙
+- **Mock은 경계(boundary)에서만 사용한다** (외부 시스템과의 접점)
+- **공개 인터페이스를 통해 검증한다** (구현이 아닌 행동을 테스트)
+- Mock이 많아지면 설계를 의심한다 (의존성이 과도한 신호)
+
+---
+
+## 6. 테스트 품질 체크리스트
+
+테스트 작성/리뷰 시 다음을 확인한다:
+
+- [ ] 테스트가 구현 없이 실패하는가? (Red 단계 확인)
+- [ ] 하나의 테스트가 하나의 동작만 검증하는가?
+- [ ] AAA 패턴이 명확하게 구분되는가?
+- [ ] 테스트 이름만으로 시나리오를 이해할 수 있는가?
+- [ ] Mock이 경계(외부 의존성)에서만 사용되었는가?
+- [ ] 테스트 간 의존성이 없는가? (실행 순서 무관)
+- [ ] 테스트가 구현 세부사항이 아닌 행동을 검증하는가?
+- [ ] 엣지 케이스가 포함되어 있는가? (빈 값, null, 경계값)
+- [ ] 에러/예외 케이스가 포함되어 있는가?
+- [ ] 불필요한 테스트 코드 중복이 없는가? (`beforeEach` 활용)