@choblue/claude-code-toolkit 1.2.1 → 1.2.3

package/.claude/.project-map-cache

@@ -1 +1 @@
-72f0d82c6beeee9deaddcfec2329fc707c2667ec
+3b3477495f8b6aeafca6aa34cc433d15ccdd0622

package/.claude/CLAUDE.md

@@ -46,10 +46,12 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 3. **Commit**: `git-manager`로 커밋/PR 생성
 
 ### L 티어 (complex)
-풀 프로세스를 따른다.
-1. **Planning**: 요구사항 정리 → `explore`로 탐색 → 사용자 승인
-2. **Implementation + Test**: `implementer`에 구현+테스트 동시 위임 → 테스트 통과 확인
-3. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
+파일 기반 설계 후 구현한다.
+1. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
+2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, 작업 순서)
+3. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
+4. **Implementation + Test**: `implementer`에 plan.md 전달하여 구현+테스트 동시 위임
+5. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
 
 ### 풀스택 작업 (FE + BE 동시 변경)
 티어는 영향도 기준으로 판단하되, 위임 순서는 BE 선행 → FE 후행을 따른다.

package/.claude/skills/Planning/SKILL.md

@@ -13,32 +13,65 @@
 3. **설계 결정**: 새로운 아키텍처/패턴 도입이 필요한가? → Yes면 L
 4. **위 모두 No**: 파일 수와 변경 단순성으로 S/M 판단
 
-## 2. 작업 분해 템플릿
+## 2. L 티어 Planning: 파일 기반 설계
 
-### 요구사항 정리
-- [ ] 사용자가 원하는 최종 결과물은?
-- [ ] 변경되는 레이어는? (UI / API / Domain / DB)
-- [ ] 기존 코드에 영향을 주는 범위는?
+L 티어는 채팅이 아닌 **파일 기반**으로 설계를 진행한다. 세션이 끝나도 기록이 남고, 사용자가 에디터에서 직접 수정할 수 있다.
 
-### 작업 단위 분해
-각 작업 단위는 **독립적으로 테스트 가능한 단위**로 나눈다:
-```
-1. [작업명] - [대상 파일/모듈] - [티어]
-2. [작업명] - [대상 파일/모듈] - [티어]
+### Step 1: research.md 작성
+관련 코드베이스를 **깊이 분석**하여 파일로 작성한다.
+```markdown
+# Research: [기능명]
+
+## 관련 코드 분석
+- [파일경로]: [역할 및 현재 동작]
+
+## 기존 패턴
+- [프로젝트에서 사용 중인 관련 패턴]
+
+## 제약 조건
+- [기술적 제약, 호환성 이슈 등]
 ```
 
-### 의존성 확인
-- [ ] 작업 간 순서 의존성이 있는가? (예: BE API 먼저 → FE 연동)
-- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)
+### Step 2: plan.md 작성
+research 기반으로 구현 계획을 작성한다.
+```markdown
+# Plan: [기능명]
+
+## 접근 방식
+- [선택한 방식과 이유]
+
+## 변경 파일
+- `path/to/file.ts` - [변경 내용]
+
+## 트레이드 오프
+- [장점] vs [단점]
 
-## 3. 계획 출력 형식
+## 작업 순서
+1. [작업] → [담당 에이전트]
+2. [작업] → [담당 에이전트]
+```
 
-사용자에게 계획을 제시할 때 다음 형식을 따른다:
+### Step 3: 주석 사이클
+1. 사용자가 plan.md를 에디터에서 열어 메모/수정을 남긴다
+2. Claude가 메모를 반영하여 plan.md를 업데이트한다
+3. **사용자가 승인할 때까지 구현하지 않는다**
+4. 승인 후 implementer 에이전트에 plan.md를 전달하여 구현한다
 
+## 3. M 티어 Planning: 채팅 기반
+
+M 티어는 파일 없이 채팅에서 간단히 계획을 제시한다:
 ```
-**티어**: S / M / L
+**티어**: M
 **변경 범위**: [레이어 목록]
 **작업 목록**:
 1. [작업] → [담당 에이전트]
 2. [작업] → [담당 에이전트]
-```
+```
+
+## 4. 작업 분해 체크리스트
+
+- [ ] 사용자가 원하는 최종 결과물은?
+- [ ] 변경되는 레이어는? (UI / API / Domain / DB)
+- [ ] 기존 코드에 영향을 주는 범위는?
+- [ ] 작업 간 순서 의존성이 있는가?
+- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)

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.1",
+  "version": "1.2.3",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"