@choblue/claude-code-toolkit 1.2.2 → 1.2.3

package/.claude/.project-map-cache

@@ -1 +1 @@
-af82e0967a0412bdcaa636fa0ab9e4f750d49608
+3b3477495f8b6aeafca6aa34cc433d15ccdd0622

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

@@ -253,7 +253,67 @@ function UserContent({ isLoading, error, data }: UserContentProps) {
 
 ---
 
-## 8. 금지 사항
+## 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. 금지 사항
 
 - `any` 타입 사용 금지
 - 인라인 스타일(`style={{}}`) 사용 금지 - 프로젝트 스타일링 방식을 따른다
@@ -263,4 +323,6 @@ function UserContent({ isLoading, error, data }: UserContentProps) {
 - `React.FC` 사용 금지
 - 배열 인덱스를 `key`로 사용 금지 (정적 리스트 제외)
 - `useEffect` 내에서 상태 동기화 로직 작성 금지 (파생값으로 처리)
-- Props drilling이 3단계 이상일 때 Context 또는 상태 관리 라이브러리 미사용 금지
+- Props drilling이 3단계 이상일 때 Context 또는 상태 관리 라이브러리 미사용 금지
+- 서버 상태(API 데이터)를 `useState` + `useEffect`로 관리 금지 (서버 상태 라이브러리 사용)
+- 각 함수/컴포넌트마다 try-catch 남발 금지 (에러 경계에서 일괄 처리)

package/.claude/skills/TanStackQuery/SKILL.md

@@ -237,7 +237,56 @@ const queryClient = new QueryClient({
 
 ---
 
-## 9. 금지 사항
+## 9. 캐시 전략 가이드
+
+데이터 특성에 따라 `staleTime`을 다르게 설정한다.
+
+| 데이터 유형 | staleTime | 예시 |
+|------------|-----------|------|
+| 거의 안 바뀜 | `Infinity` | 코드 테이블, 카테고리 목록, 약관 |
+| 가끔 바뀜 | `10~30분` | 사용자 프로필, 설정 |
+| 자주 바뀜 | `1~5분` | 게시글 목록, 댓글 |
+| 실시간 필요 | `0` | 채팅, 알림, 재고 수량 |
+
+### 도메인별 staleTime 설정
+
+```typescript
+// queryKey 팩토리에서 기본 옵션을 함께 관리
+export const categoryKeys = {
+  all: ['categories'] as const,
+  list: () => [...categoryKeys.all, 'list'] as const,
+};
+
+// 거의 안 바뀌는 데이터
+useQuery({
+  queryKey: categoryKeys.list(),
+  queryFn: fetchCategories,
+  staleTime: Infinity,
+});
+
+// 자주 바뀌는 데이터
+useQuery({
+  queryKey: postKeys.list(filters),
+  queryFn: () => fetchPosts(filters),
+  staleTime: 1000 * 60,  // 1분
+});
+```
+
+### 실시간 데이터: refetchInterval 사용
+
+```typescript
+// 폴링 방식 (WebSocket이 없을 때)
+useQuery({
+  queryKey: ['notifications'],
+  queryFn: fetchNotifications,
+  staleTime: 0,
+  refetchInterval: 1000 * 30,  // 30초마다 재요청
+});
+```
+
+---
+
+## 10. 금지 사항
 
 - `useEffect`로 데이터 페칭 금지 - TanStack Query를 사용한다
 - queryKey 하드코딩 금지 - queryKey 팩토리 패턴을 사용한다

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choblue/claude-code-toolkit",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"