@choblue/claude-code-toolkit 1.2.6 → 1.2.7

package/.claude/skills/React/references/rendering-patterns.md

@@ -0,0 +1,62 @@
+# 렌더링 최적화 및 조건부 렌더링 패턴
+
+## 1. 렌더링 최적화
+
+### 불필요한 useMemo/useCallback 금지
+- 성능 문제가 실제로 측정된 경우에만 사용한다
+- 참조 동일성이 필요한 경우(의존성 배열, memo된 자식 컴포넌트)에만 사용한다
+
+```typescript
+// Bad - 불필요한 메모이제이션
+const userName = useMemo(() => `${first} ${last}`, [first, last]);
+
+// Good - 단순 계산은 그냥 수행
+const userName = `${first} ${last}`;
+```
+
+### key 올바르게 사용
+- 리스트 렌더링 시 고유한 식별자를 `key`로 사용한다
+- 배열 인덱스를 `key`로 사용하지 않는다 (정적 리스트 제외)
+
+```typescript
+// Bad
+{items.map((item, index) => (
+  <Item key={index} data={item} />
+))}
+
+// Good
+{items.map((item) => (
+  <Item key={item.id} data={item} />
+))}
+```
+
+---
+
+## 2. 조건부 렌더링 패턴
+
+### 단순 조건
+- 2개 이하의 조건은 삼항 연산자 또는 `&&`를 사용한다
+
+```typescript
+// 단순 표시/숨김
+{isVisible && <Modal />}
+
+// 이분기
+{isLoading ? <Skeleton /> : <Content />}
+```
+
+### 복잡한 조건
+- 3개 이상의 분기는 early return 또는 별도 컴포넌트로 분리한다
+
+```typescript
+// Bad - 중첩된 삼항
+{isLoading ? <Skeleton /> : error ? <Error /> : data ? <Content /> : <Empty />}
+
+// Good - early return
+function UserContent({ isLoading, error, data }: UserContentProps) {
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorDisplay error={error} />;
+  if (!data) return <EmptyState />;
+  return <Content data={data} />;
+}
+```

package/.claude/skills/React/references/state-hooks.md

@@ -0,0 +1,73 @@
+# 상태 관리 및 커스텀 훅
+
+## 1. 상태 관리 원칙
+
+### 가까운 곳에 배치
+- 상태는 그것을 사용하는 가장 가까운 컴포넌트에 배치한다
+- 상위 컴포넌트로의 lifting은 실제로 필요할 때만 수행한다
+
+### 파생값은 상태가 아니다
+- 기존 상태에서 계산할 수 있는 값은 별도 상태로 만들지 않는다
+
+```typescript
+// Bad - 파생값을 상태로 관리
+const [items, setItems] = useState<Item[]>([]);
+const [itemCount, setItemCount] = useState(0);
+// items가 변경될 때마다 setItemCount를 호출해야 함
+
+// Good - 파생값은 계산
+const [items, setItems] = useState<Item[]>([]);
+const itemCount = items.length;
+```
+
+### 서버 상태와 클라이언트 상태 분리
+- **서버 상태**: API에서 가져온 데이터 -> React Query / SWR 사용
+- **클라이언트 상태**: UI 상태 (모달 열림, 탭 선택 등) -> useState / useReducer 사용
+- 서버 데이터를 `useState`로 복사하지 않는다
+
+---
+
+## 2. 커스텀 훅
+
+### use 접두사
+- 모든 커스텀 훅은 `use`로 시작한다
+
+### 하나의 관심사
+- 하나의 훅은 하나의 관심사만 다룬다
+
+### 데이터 페칭/상태 로직 분리
+- 컴포넌트에서 데이터 페칭과 상태 로직을 커스텀 훅으로 분리한다
+
+```typescript
+// Bad - 컴포넌트에 로직이 섞여 있음
+function UserList() {
+  const [users, setUsers] = useState<User[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    setIsLoading(true);
+    fetchUsers()
+      .then(setUsers)
+      .catch(setError)
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  // ... 렌더링
+}
+
+// Good - 커스텀 훅으로 분리
+function useUserList() {
+  const { data: users = [], isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: fetchUsers,
+  });
+
+  return { users, isLoading, error };
+}
+
+function UserList() {
+  const { users, isLoading, error } = useUserList();
+  // ... 렌더링만 담당
+}
+```

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

@@ -107,201 +107,7 @@ function CreateUserForm() {
 
 ---
 
-## 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. 네이밍 컨벤션
+## 4. 네이밍 컨벤션
 
 | 대상 | 규칙 | 예시 |
 |------|------|------|
@@ -312,7 +118,7 @@ const updateUserSchema = baseUserSchema.partial(); // 모든 필드 optional
 
 ---
 
-## 10. 금지 사항
+## 5. 금지 사항
 
 - 스키마 없이 수동 검증 금지 - 반드시 Zod 스키마를 정의하고 `zodResolver`를 사용한다
 - `any` 타입 사용 금지 - `z.infer<typeof schema>`로 타입을 추론한다
@@ -320,3 +126,9 @@ const updateUserSchema = baseUserSchema.partial(); // 모든 필드 optional
 - `handleSubmit` 없이 `onSubmit` 직접 처리 금지 - `handleSubmit`이 검증을 수행한다
 - 폼 타입과 스키마를 별도로 정의 금지 - 타입 불일치 위험이 있으므로 `z.infer`를 사용한다
 - 에러 메시지 하드코딩 금지 - Zod 스키마에 메시지를 정의한다
+
+---
+
+## 심화 참조
+
+- `references/advanced-patterns.md` - Controller 패턴, 에러 핸들링, 폼 검증 모드, 동적 필드(useFieldArray), 중첩 객체/배열 스키마

package/.claude/skills/ReactHookForm/references/advanced-patterns.md

@@ -0,0 +1,193 @@
+# React Hook Form 심화 패턴
+
+## 1. 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>
+  );
+}
+```
+
+---
+
+## 2. 에러 핸들링
+
+### errors 객체로 직접 표시
+
+```typescript
+// 간단한 에러 표시
+{errors.email && <span className="error">{errors.email.message}</span>}
+```
+
+### 재사용 가능한 에러 컴포넌트
+
+```typescript
+type 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} />
+```
+
+---
+
+## 3. 폼 검증 모드
+
+### mode 옵션
+
+| mode | 동작 | 용도 |
+|------|------|------|
+| `onSubmit` (기본) | 제출 시에만 검증 | 대부분의 폼 |
+| `onBlur` | 포커스를 벗어날 때 검증 | 긴 폼, 단계별 입력 |
+| `onChange` | 입력할 때마다 검증 | 실시간 피드백이 필요한 필드 |
+| `onTouched` | 첫 blur 이후부터 onChange로 검증 | 사용자 친화적 검증 |
+
+```typescript
+const { register, handleSubmit } = useForm<FormValues>({
+  resolver: zodResolver(schema),
+  mode: 'onBlur', // 포커스를 벗어날 때 검증
+});
+```
+
+---
+
+## 4. 동적 필드 (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>
+  );
+}
+```
+
+---
+
+## 5. 중첩 객체 / 배열 스키마
+
+### 중첩 객체
+
+```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
+```

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

@@ -7,8 +7,8 @@ description: TDD(테스트 주도 개발) 공통 원칙. 테스트 작성 시 Re
 
 이 문서는 모든 테스트 코드 작성 시 적용되는 공통 원칙을 정의한다.
 FE/BE별 상세 규칙은 각각의 파일을 참고한다.
-- `frontend.md` - React Testing Library 기반 프론트엔드 테스트 규칙
-- `backend.md` - NestJS 백엔드 테스트 규칙
+- `references/frontend.md` - React Testing Library 기반 프론트엔드 테스트 규칙
+- `references/backend.md` - NestJS 백엔드 테스트 규칙
 
 ---