@choblue/claude-code-toolkit 1.2.5 → 1.2.7

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

@@ -16,8 +16,8 @@ React 컴포넌트 설계 및 개발에 적용되는 핵심 규칙이다.
 - 클래스 컴포넌트를 사용하지 않는다
 - `React.FC`를 사용하지 않는다 - Props를 직접 타이핑한다
 
-### Props interface 명시
-- 모든 컴포넌트는 Props 타입을 `interface`로 선언한다
+### Props 타입 명시
+- 모든 컴포넌트는 Props 타입을 `type`으로 선언한다
 - Props 네이밍은 `컴포넌트명 + Props`로 한다
 
 ### SRP (Single Responsibility Principle)
@@ -35,9 +35,9 @@ const UserPage = () => {
 };
 
 // Good
-interface UserPageProps {
+type UserPageProps = {
   userId: string;
-}
+};
 
 export function UserPage({ userId }: UserPageProps) {
   const { user, isLoading } = useUser(userId);
@@ -68,16 +68,16 @@ export function UserPage({ userId }: UserPageProps) {
 
 ```typescript
 // Bad
-interface ButtonProps {
+type ButtonProps = {
   clickHandler: () => void;
   deleteCallback: () => void;
-}
+};
 
 // Good
-interface ButtonProps {
+type ButtonProps = {
   onClick: () => void;
   onDelete: () => void;
-}
+};
 ```
 
 ### 객체 통째 전달 지양
@@ -86,157 +86,20 @@ interface ButtonProps {
 
 ```typescript
 // Bad - 불필요한 데이터까지 전달
-interface UserAvatarProps {
+type UserAvatarProps = {
   user: User; // user.name, user.avatar만 사용하는데 전체 객체 전달
-}
+};
 
 // Good - 필요한 값만 전달
-interface UserAvatarProps {
+type UserAvatarProps = {
   name: string;
   avatarUrl: string;
-}
-```
-
----
-
-## 3. 상태 관리 원칙
-
-### 가까운 곳에 배치
-- 상태는 그것을 사용하는 가장 가까운 컴포넌트에 배치한다
-- 상위 컴포넌트로의 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`로 복사하지 않는다
-
----
-
-## 4. 커스텀 훅
-
-### 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();
-  // ... 렌더링만 담당
-}
-```
-
----
-
-## 5. 렌더링 최적화
-
-### 불필요한 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} />
-))}
-```
-
----
-
-## 6. 조건부 렌더링 패턴
-
-### 단순 조건
-- 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} />;
-}
+};
 ```
 
 ---
 
-## 7. 네이밍 컨벤션
+## 3. 네이밍 컨벤션
 
 | 대상 | 규칙 | 예시 |
 |------|------|------|
@@ -253,142 +116,7 @@ function UserContent({ isLoading, error, data }: UserContentProps) {
 
 ---
 
-## 8. 에러 처리
-
-### 원칙: 에러 처리를 각 함수/컴포넌트에 흩뿌리지 않는다
-- 각 함수마다 try-catch를 덕지덕지 붙이지 않는다
-- `useState`로 에러 상태를 직접 관리하지 않는다 (TanStack Query가 제공)
-- 에러 처리는 **경계(Boundary)**에서 한 번에 처리한다
-
-### API 에러: 서버 상태 라이브러리에 위임
-
-```typescript
-// Bad - useState + useEffect로 에러 직접 관리
-function UserList() {
-  const [error, setError] = useState<Error | null>(null);
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(false);
-
-  useEffect(() => {
-    setLoading(true);
-    fetchUsers()
-      .then(setData)
-      .catch(setError)
-      .finally(() => setLoading(false));
-  }, []);
-}
-
-// Good - 서버 상태 라이브러리가 에러를 관리
-function UserList() {
-  const { data: users, isLoading, error } = useUserList();
-  if (error) return <ErrorDisplay error={error} />;
-}
-```
-
-### 렌더링 에러: Error Boundary
-
-```typescript
-<ErrorBoundary fallback={<ErrorFallback />}>
-  <UserContent />
-</ErrorBoundary>
-```
-
-### 전역 API 에러: interceptor 또는 라이브러리 설정에서 일괄 처리
-- axios interceptor, QueryClient defaultOptions 등 프로젝트 설정에 따른다
-- 개별 컴포넌트가 아닌 앱 수준에서 에러 알림(toast 등)을 처리한다
-
-### 에러 UI 분기: early return 패턴
-
-```typescript
-function UserPage({ userId }: UserPageProps) {
-  const { data: user, isLoading, error } = useUser(userId);
-
-  if (isLoading) return <Skeleton />;
-  if (error) return <ErrorDisplay error={error} />;
-  if (!user) return <EmptyState />;
-
-  return <UserContent user={user} />;
-}
-```
-
----
-
-## 9. 접근성 (a11y)
-
-### 시맨틱 HTML 사용
-- 클릭 가능한 요소는 반드시 `<button>` 또는 `<a>`를 사용한다
-- `<div onClick>`, `<span onClick>`을 금지한다
-
-```typescript
-// Bad
-<div onClick={handleDelete} className="cursor-pointer">삭제</div>
-
-// Good
-<button type="button" onClick={handleDelete}>삭제</button>
-```
-
-### 아이콘 버튼에 aria-label 필수
-
-```typescript
-// Bad - 스크린 리더가 내용을 알 수 없음
-<button onClick={onClose}><XIcon /></button>
-
-// Good
-<button onClick={onClose} aria-label="닫기"><XIcon /></button>
-```
-
-### 이미지에 alt, width, height 필수
-
-```typescript
-// Bad
-<img src={user.avatar} />
-
-// Good
-<img src={user.avatar} alt={`${user.name} 프로필`} width={40} height={40} />
-```
-
-### focus-visible 보장
-- `outline: none`을 사용할 때 반드시 `focus-visible` 대체 스타일을 제공한다
-
-```typescript
-// Bad - 포커스 표시 완전 제거
-<button className="outline-none">
-
-// Good - 키보드 포커스 시 표시
-<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500">
-```
-
-### 폼 접근성
-- 모든 입력 필드에 `<label>` 또는 `aria-label`을 연결한다
-- 적절한 `type`, `inputMode`, `autoComplete` 속성을 사용한다
-- 붙여넣기(`onPaste`)를 차단하지 않는다
-
----
-
-## 10. UX 패턴
-
-### 파괴적 액션에 확인 단계
-- 삭제, 초기화 등 되돌릴 수 없는 동작에는 확인 UI를 추가한다
-
-### URL 파라미터와 UI 상태 동기화
-- 탭, 필터, 페이지 등 공유 가능한 UI 상태는 URL 파라미터에 반영한다
-
-```typescript
-// Bad - 새로고침하면 상태 소실
-const [tab, setTab] = useState('overview');
-
-// Good - URL에 상태 반영 (deep-link 가능)
-const [searchParams, setSearchParams] = useSearchParams();
-const tab = searchParams.get('tab') ?? 'overview';
-```
-
-### 대규모 리스트 가상화
-- 50개 이상의 항목을 렌더링할 때는 가상화 라이브러리를 사용한다
-- `@tanstack/react-virtual`, `react-window` 등을 활용한다
-
----
-
-## 11. 금지 사항
+## 4. 금지 사항
 
 - `any` 타입 사용 금지
 - 인라인 스타일(`style={{}}`) 사용 금지 - 프로젝트 스타일링 방식을 따른다
@@ -404,4 +132,14 @@ const tab = searchParams.get('tab') ?? 'overview';
 - `<div onClick>`, `<span onClick>` 금지 (`<button>` 또는 `<a>` 사용)
 - 아이콘 버튼에 `aria-label` 누락 금지
 - `outline: none` 단독 사용 금지 (`focus-visible` 대체 필수)
-- 입력 필드에 `onPaste` 차단 금지
+- 입력 필드에 `onPaste` 차단 금지
+
+---
+
+## 심화 참조
+
+| 파일 | 설명 |
+|------|------|
+| `references/state-hooks.md` | 상태 관리 원칙 (배치, 파생값, 서버/클라이언트 분리) + 커스텀 훅 패턴 |
+| `references/rendering-patterns.md` | 렌더링 최적화 (useMemo/useCallback, key) + 조건부 렌더링 패턴 |
+| `references/a11y-ux.md` | 에러 처리 (Error Boundary, 서버 상태 위임) + 접근성 (시맨틱 HTML, aria-label, focus-visible) + UX 패턴 (파괴적 액션 확인, URL 동기화, 가상화) |

package/.claude/skills/React/references/a11y-ux.md

@@ -0,0 +1,134 @@
+# 에러 처리, 접근성 (a11y) 및 UX 패턴
+
+## 1. 에러 처리
+
+### 원칙: 에러 처리를 각 함수/컴포넌트에 흩뿌리지 않는다
+- 각 함수마다 try-catch를 덕지덕지 붙이지 않는다
+- `useState`로 에러 상태를 직접 관리하지 않는다 (TanStack Query가 제공)
+- 에러 처리는 **경계(Boundary)**에서 한 번에 처리한다
+
+### API 에러: 서버 상태 라이브러리에 위임
+
+```typescript
+// Bad - useState + useEffect로 에러 직접 관리
+function UserList() {
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    setLoading(true);
+    fetchUsers()
+      .then(setData)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, []);
+}
+
+// Good - 서버 상태 라이브러리가 에러를 관리
+function UserList() {
+  const { data: users, isLoading, error } = useUserList();
+  if (error) return <ErrorDisplay error={error} />;
+}
+```
+
+### 렌더링 에러: Error Boundary
+
+```typescript
+<ErrorBoundary fallback={<ErrorFallback />}>
+  <UserContent />
+</ErrorBoundary>
+```
+
+### 전역 API 에러: interceptor 또는 라이브러리 설정에서 일괄 처리
+- axios interceptor, QueryClient defaultOptions 등 프로젝트 설정에 따른다
+- 개별 컴포넌트가 아닌 앱 수준에서 에러 알림(toast 등)을 처리한다
+
+### 에러 UI 분기: early return 패턴
+
+```typescript
+function UserPage({ userId }: UserPageProps) {
+  const { data: user, isLoading, error } = useUser(userId);
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorDisplay error={error} />;
+  if (!user) return <EmptyState />;
+
+  return <UserContent user={user} />;
+}
+```
+
+---
+
+## 2. 접근성 (a11y)
+
+### 시맨틱 HTML 사용
+- 클릭 가능한 요소는 반드시 `<button>` 또는 `<a>`를 사용한다
+- `<div onClick>`, `<span onClick>`을 금지한다
+
+```typescript
+// Bad
+<div onClick={handleDelete} className="cursor-pointer">삭제</div>
+
+// Good
+<button type="button" onClick={handleDelete}>삭제</button>
+```
+
+### 아이콘 버튼에 aria-label 필수
+
+```typescript
+// Bad - 스크린 리더가 내용을 알 수 없음
+<button onClick={onClose}><XIcon /></button>
+
+// Good
+<button onClick={onClose} aria-label="닫기"><XIcon /></button>
+```
+
+### 이미지에 alt, width, height 필수
+
+```typescript
+// Bad
+<img src={user.avatar} />
+
+// Good
+<img src={user.avatar} alt={`${user.name} 프로필`} width={40} height={40} />
+```
+
+### focus-visible 보장
+- `outline: none`을 사용할 때 반드시 `focus-visible` 대체 스타일을 제공한다
+
+```typescript
+// Bad - 포커스 표시 완전 제거
+<button className="outline-none">
+
+// Good - 키보드 포커스 시 표시
+<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500">
+```
+
+### 폼 접근성
+- 모든 입력 필드에 `<label>` 또는 `aria-label`을 연결한다
+- 적절한 `type`, `inputMode`, `autoComplete` 속성을 사용한다
+- 붙여넣기(`onPaste`)를 차단하지 않는다
+
+---
+
+## 3. UX 패턴
+
+### 파괴적 액션에 확인 단계
+- 삭제, 초기화 등 되돌릴 수 없는 동작에는 확인 UI를 추가한다
+
+### URL 파라미터와 UI 상태 동기화
+- 탭, 필터, 페이지 등 공유 가능한 UI 상태는 URL 파라미터에 반영한다
+
+```typescript
+// Bad - 새로고침하면 상태 소실
+const [tab, setTab] = useState('overview');
+
+// Good - URL에 상태 반영 (deep-link 가능)
+const [searchParams, setSearchParams] = useSearchParams();
+const tab = searchParams.get('tab') ?? 'overview';
+```
+
+### 대규모 리스트 가상화
+- 50개 이상의 항목을 렌더링할 때는 가상화 라이브러리를 사용한다
+- `@tanstack/react-virtual`, `react-window` 등을 활용한다

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();
+  // ... 렌더링만 담당
+}
+```