@kood/claude-code 0.3.2 → 0.3.4

package/templates/.claude/commands/refactor.md

@@ -0,0 +1,527 @@
+---
+description: 코드 리팩토링 계획 수립. @refactor-advisor 우선 활용. Sequential Thinking 3-7 필수. 기능 유지하며 개선만.
+allowed-tools: Read, Glob, Grep, Bash(git:*, ast-grep:*), Task, Write, mcp__sequential-thinking__sequentialthinking
+argument-hint: <대상 파일/모듈 또는 개선 목표>
+---
+
+# Refactor Command
+
+> 코드 품질 개선을 위한 리팩토링 계획 수립 및 실행 전략 제시.
+
+**리팩토링 대상**: $ARGUMENTS
+
+---
+
+<argument_validation>
+
+## ARGUMENT 필수 확인
+
+```
+$ARGUMENTS 없음 → 즉시 질문:
+
+"무엇을 리팩토링해야 하나요? 구체적으로 알려주세요.
+
+예시:
+- 특정 파일/모듈 개선
+- 복잡도 감소
+- 중복 코드 제거
+- 구조 개선
+- 성능 최적화"
+
+$ARGUMENTS 있음 → 다음 단계 진행
+```
+
+</argument_validation>
+
+---
+
+<workflow>
+
+## 실행 흐름
+
+| 단계 | 작업 | 도구 |
+|------|------|------|
+| 1. 입력 확인 | ARGUMENT 검증, 없으면 질문 | - |
+| 2. Agent 판단 | @refactor-advisor 사용 여부 결정 | - |
+| 3. 복잡도 판단 | Sequential Thinking으로 분석 범위 결정 | sequentialthinking (1단계) |
+| 4. 코드 분석 | 현재 코드 구조, 문제점 파악 | Task (Explore) + Read/Grep |
+| 5. 개선 옵션 도출 | 가능한 접근 4-5개 → 주요 2-3개 선정 | sequentialthinking (2-6단계) |
+| 6. 옵션 제시 | 장단점, 영향 범위, 추천안 제시 | - |
+| 7. 계획 문서 작성 | 선택 시 리팩토링 계획 생성 | Write |
+
+</workflow>
+
+---
+
+<agent_priority>
+
+## @refactor-advisor Agent 우선 사용
+
+**기본 원칙:**
+```
+리팩토링 요청 → @refactor-advisor 먼저 고려
+```
+
+### 사용 조건
+
+| 조건 | 설명 |
+|------|------|
+| **코드 품질 개선** | 복잡도, 중복, 명명, 구조 개선 |
+| **기능 변경 없음** | 동작은 유지하며 코드만 개선 |
+| **점진적 개선** | 단계적 리팩토링 계획 필요 |
+
+### Agent 활용 흐름
+
+```
+1. @refactor-advisor 호출
+   → 코드 분석, 우선순위별 개선점 도출
+
+2. 분석 결과 기반 옵션 정리
+   → 사용자에게 2-3개 옵션 제시
+
+3. 선택 후 계획 문서 작성
+   → .claude/plans/refactor-[이름].md
+```
+
+### Agent 미사용 케이스
+
+```
+✅ @refactor-advisor 사용:
+- 기존 코드 개선
+- 복잡도/중복 감소
+- 구조 개선
+
+❌ 직접 처리:
+- 아키텍처 변경
+- 새 기능 추가와 함께 리팩토링
+- 프레임워크 마이그레이션
+```
+
+</agent_priority>
+
+---
+
+<thinking_strategy>
+
+## Sequential Thinking 가이드
+
+### 복잡도 판단 (thought 1)
+
+```
+thought 1: 복잡도 판단
+- 영향 범위: 파일 수, 함수 수
+- 현재 문제: 복잡도, 중복, 명명, 구조
+- 리스크: 기존 기능 영향, 테스트 커버리지
+- 우선순위: High/Medium/Low
+```
+
+### 복잡도별 전략
+
+| 복잡도 | 사고 횟수 | 판단 기준 | 사고 패턴 |
+|--------|----------|----------|------------|
+| **간단** | 3 | 1-2 파일, 명확한 개선점 | 복잡도 판단 → 현재 분석 → 개선 방안 |
+| **보통** | 5 | 3-5 파일, 구조 변경 | 복잡도 판단 → 현재 분석 → 문제점 → 옵션 비교 → 추천안 |
+| **복잡** | 7+ | 다중 모듈, 점진적 변경 필요 | 복잡도 판단 → 심층 분석 → 우선순위 → 접근 방식 → 비교 → 단계별 계획 → 추천안 |
+
+### 보통 복잡도 패턴 (5단계)
+
+```
+thought 1: 복잡도 판단 및 분석 범위 결정
+thought 2: 현재 코드 분석 (복잡도, 중복, 구조)
+thought 3: 가능한 개선 방법 열거 (4-5개)
+thought 4: 주요 옵션 3개 선정 및 장단점 분석
+thought 5: 최종 옵션 정리 및 추천안 도출
+```
+
+### 복잡한 경우 패턴 (7단계)
+
+```
+thought 1: 복잡도 판단
+thought 2: 현재 코드 심층 분석 (메트릭, 패턴)
+thought 3: 개선 우선순위 정리 (High/Medium/Low)
+thought 4: 가능한 접근 방식 탐색
+thought 5: 각 접근 방식 비교 분석
+thought 6: 옵션 3개 선정 및 상세 장단점
+thought 7: 단계별 계획 및 추천안
+```
+
+### 핵심 원칙
+
+```text
+✅ 사고 과정을 출력해야 실제로 생각이 일어남
+✅ 복잡도가 불확실하면 높게 책정 (5→7로 확장 가능)
+✅ 각 thought에서 구체적 분석 필요 (추상적 설명 금지)
+✅ 필요 시 isRevision으로 이전 사고 수정
+```
+
+</thinking_strategy>
+
+---
+
+<refactoring_areas>
+
+## 리팩토링 영역
+
+### 6가지 개선 영역
+
+| 영역 | 문제 | 개선 방향 |
+|------|------|----------|
+| **복잡도** | 긴 함수, 깊은 중첩 | 함수 분리, Early Return |
+| **중복** | 동일/유사 코드 반복 | 공통 함수/모듈 추출 |
+| **명명** | 모호한 변수/함수명 | 의도 명확한 이름 |
+| **구조** | 파일/모듈 구조 불명확 | 관심사 분리, 계층화 |
+| **패턴** | 안티패턴 사용 | 디자인 패턴 적용 |
+| **타입** | any 남용, 타입 불안정 | 명시적 타입 정의 |
+
+### 체크리스트
+
+```text
+✅ 함수 길이: 20줄 이하 목표
+✅ 중첩 깊이: 3단계 이하 목표
+✅ 파일 길이: 200-300줄 권장
+✅ 순환 의존성: 제거
+✅ 매직 넘버: 상수화
+✅ 주석: 코드로 설명 불가능한 것만
+```
+
+</refactoring_areas>
+
+---
+
+<option_presentation>
+
+## 옵션 제시 형식
+
+### 옵션 3개 제시 (표준)
+
+```markdown
+## 분석 결과
+
+### 현재 상태
+- 문제점 1
+- 문제점 2
+- 개선 필요 영역
+
+---
+
+### 옵션 1: [옵션 이름] (추천)
+
+**개선 방법:**
+- 설명 1
+- 설명 2
+
+| 장점 | 단점 |
+|------|------|
+| 장점 1 | 단점 1 |
+| 장점 2 | 단점 2 |
+
+**영향 범위:**
+- 파일: `src/module/`
+- 예상 작업량: 중간
+- 리스크: 낮음
+- 테스트 영향: 최소
+
+---
+
+### 옵션 2: [옵션 이름]
+
+**개선 방법:**
+...
+
+| 장점 | 단점 |
+|------|------|
+| ... | ... |
+
+**영향 범위:**
+...
+
+---
+
+### 옵션 3: [옵션 이름]
+
+**개선 방법:**
+...
+
+---
+
+## 추천 및 근거
+
+옵션 1을 추천합니다.
+- 근거 1
+- 근거 2
+
+어떤 옵션을 선택하시겠습니까? (1/2/3)
+```
+
+### 옵션 2개 제시 (개선점이 명확한 경우)
+
+```markdown
+## 분석 결과
+
+두 가지 접근 방식이 있습니다:
+
+### 옵션 A: [옵션 이름]
+...
+
+### 옵션 B: [옵션 이름]
+...
+
+어떤 옵션을 선택하시겠습니까? (A/B)
+```
+
+</option_presentation>
+
+---
+
+<document_generation>
+
+## 계획 문서 작성
+
+### 문서 작성 질문
+
+```
+옵션 [N]을 선택하셨습니다.
+
+리팩토링 계획 문서를 작성할까요?
+- Y: .claude/plans/refactor-[이름].md 생성
+- N: 바로 구현 시작
+
+선택해주세요. (Y/N)
+```
+
+### 리팩토링 계획 문서 템플릿
+
+**파일 위치:** `.claude/plans/refactor-[이름].md`
+
+```markdown
+# [모듈명] 리팩토링 계획
+
+## 개요
+
+**목표:** [무엇을 개선할 것인가]
+**선택된 접근 방식:** [옵션 N]
+**예상 영향 범위:** [파일/모듈 목록]
+
+## 현재 상태
+
+### 문제점
+
+| 문제 | 영향 | 우선순위 |
+|------|------|---------|
+| 문제 1 | 설명 | High |
+| 문제 2 | 설명 | Medium |
+
+### 메트릭
+
+- 복잡도: [현재 값]
+- 중복률: [현재 값]
+- 테스트 커버리지: [현재 값]
+
+## 개선 단계
+
+### 1단계: [단계 이름]
+
+**목표:** [이 단계에서 달성할 것]
+
+**작업:**
+- [ ] 작업 1
+- [ ] 작업 2
+
+**변경 파일:**
+- `src/file1.ts`
+- `src/file2.ts`
+
+**검증:**
+- 테스트 통과
+- 빌드 성공
+
+### 2단계: [단계 이름]
+
+**목표:** [이 단계에서 달성할 것]
+
+**작업:**
+- [ ] 작업 3
+
+**변경 파일:**
+- `src/file3.ts`
+
+### 3단계: [단계 이름]
+...
+
+## 개선 후 기대 효과
+
+| 메트릭 | Before | After | 개선율 |
+|--------|--------|-------|--------|
+| 복잡도 | X | Y | -Z% |
+| 중복률 | X | Y | -Z% |
+| 코드 라인 | X | Y | -Z% |
+
+## 리스크 관리
+
+### 리스크
+
+| 리스크 | 영향도 | 완화 방안 |
+|--------|--------|----------|
+| 리스크 1 | High | 방안 1 |
+| 리스크 2 | Medium | 방안 2 |
+
+### 롤백 계획
+
+문제 발생 시:
+1. 단계별 커밋 활용
+2. 이전 단계로 되돌리기
+3. 테스트 재실행
+
+## 검증 방법
+
+### 기능 검증
+- [ ] 기존 기능 동작 확인
+- [ ] 회귀 테스트 통과
+- [ ] 통합 테스트 통과
+
+### 품질 검증
+- [ ] 복잡도 감소 확인
+- [ ] 중복 제거 확인
+- [ ] 타입 안정성 확인
+
+## 참조
+
+- 관련 문서 링크
+- 참고 패턴
+```
+
+</document_generation>
+
+---
+
+<validation>
+
+## 검증 체크리스트
+
+실행 전 확인:
+
+```text
+✅ ARGUMENT 확인 (없으면 질문)
+✅ @refactor-advisor 사용 여부 판단
+✅ Sequential Thinking 최소 3단계
+✅ Task (Explore)로 코드 분석
+✅ 옵션 최소 2개, 권장 3개
+✅ 각 옵션에 장단점 명시
+✅ 영향 범위 및 예상 작업량 제시
+✅ 기능 유지 원칙 강조
+```
+
+절대 금지:
+
+```text
+❌ ARGUMENT 없이 분석 시작
+❌ Edit 도구 사용 (코드 수정 금지)
+❌ Sequential Thinking 3단계 미만
+❌ 옵션 1개만 제시
+❌ 코드 분석 없이 추측으로 옵션 제시
+❌ 사용자 선택 없이 구현 시작
+❌ 기능 변경 포함
+❌ 장단점 없이 옵션만 나열
+```
+
+</validation>
+
+---
+
+<examples>
+
+## 실전 예시
+
+### 예시 1: 복잡한 함수 분리
+
+```bash
+사용자: /refactor src/utils/auth.ts - 너무 복잡함
+
+1. @refactor-advisor 고려:
+   → 단일 파일, 복잡도 감소 → Agent 활용 추천
+
+2. Sequential Thinking (5단계):
+   thought 1: "단일 파일, 함수 복잡도 - 보통 복잡도"
+   thought 2: "auth.ts 분석: 200줄, 5단계 중첩, 여러 책임"
+   thought 3: "접근 방식: 함수 분리, 책임 분리, 타입 개선"
+   thought 4: "옵션 3개 선정 및 장단점"
+   thought 5: "점진적 분리 추천 - 단계적 검증 가능"
+
+3. 옵션 제시:
+   옵션 1: 점진적 함수 분리 (추천)
+   - 장점: 안전, 단계별 검증
+   - 단점: 시간 소요
+
+   옵션 2: 모듈 분리
+   - 장점: 명확한 구조
+   - 단점: 큰 변경
+
+   옵션 3: 타입 개선 우선
+   - 장점: 빠른 개선
+   - 단점: 근본 해결 아님
+
+4. 사용자 선택: 1
+
+5. 문서 작성: Y
+
+6. .claude/plans/refactor-auth.md 생성
+```
+
+### 예시 2: 중복 코드 제거
+
+```bash
+사용자: /refactor 여러 파일에 중복 코드가 많음
+
+1. @refactor-advisor 활용:
+   → 다중 파일, 중복 분석 → Agent 활용 적합
+
+2. Sequential Thinking (5단계):
+   thought 1: "다중 파일 중복 - 보통 복잡도"
+   thought 2: "중복 패턴 분석: 3가지 유형"
+   thought 3: "접근: 공통 함수, 유틸리티, 훅 추출"
+   thought 4: "옵션 비교: 점진적 vs 일괄"
+   thought 5: "점진적 추출 추천"
+
+3. Task 탐색:
+   Task (Explore): "중복 코드 패턴 분석"
+   → src/components/, src/hooks/ 파악
+
+4. 옵션:
+   옵션 1: 점진적 공통 함수 추출 (추천)
+   옵션 2: 새 유틸리티 모듈 생성
+   옵션 3: 커스텀 훅 추출
+
+5. 선택 후 계획 문서 생성
+```
+
+### 예시 3: 구조 개선
+
+```bash
+사용자: /refactor 프로젝트 구조를 더 명확하게
+
+1. @refactor-advisor 판단:
+   → 구조 변경, 다중 모듈 → 직접 처리 (Agent 미사용)
+
+2. Sequential Thinking (7단계):
+   thought 1: "구조 개선 - 복잡도 높음, 다중 모듈"
+   thought 2: "현재 구조 분석: src/ 내 혼재"
+   thought 3: "요구사항: 관심사 분리, 계층 명확화"
+   thought 4: "접근: 모듈화, 디렉토리 재구성, 경로 정리"
+   thought 5: "각 접근 비교: 영향 범위, 리스크"
+   thought 6: "옵션 3개 선정 및 상세 분석"
+   thought 7: "점진적 재구성 추천 - 단계적 이동"
+
+3. Task 탐색 (병렬):
+   Task (Explore): "현재 디렉토리 구조 분석"
+   Task (Explore): "모듈 간 의존성 파악"
+   Task (Explore): "import 경로 패턴 분석"
+
+4. 옵션:
+   옵션 1: 점진적 모듈 분리 (추천)
+   옵션 2: 레이어 기반 재구성
+   옵션 3: 기능별 도메인 분리
+
+5. 계획 문서 작성 (필수)
+```
+
+</examples>

package/templates/tanstack-start/docs/architecture.md

@@ -18,7 +18,6 @@
 | **API** | `/api` 라우터 생성 (Server Functions 사용) |
 | **레이어** | Service Layer 건너뛰기, Routes에서 직접 DB 접근 |
 | **검증** | Handler 내부 수동 검증, 인증 로직 분산 |
-| **Server Fn** | `createServerFn` 사용 (명시 요청 없으면 `createServerOnlyFn`) |
 | **Barrel Export** | `functions/index.ts` 생성 (Tree Shaking 실패, 서버 라이브러리 Client 오염) |
 
 </forbidden>
@@ -34,7 +33,7 @@
 | **페이지 분리** | 100줄+ → `-components`, 200줄+ → `-sections` |
 | **beforeLoad** | 인증 체크, Context 전달, 리다이렉트 |
 | **loader** | 데이터 로딩 (beforeLoad 완료 후 병렬 실행) |
-| **Server Fn** | `createServerOnlyFn` 기본 사용 |
+| **Server Fn** | `createServerFn` 기본 사용 |
 | **검증** | `inputValidator` (POST/PUT/PATCH), Zod 스키마 |
 | **인증** | `middleware` (authMiddleware) |
 | **에러 처리** | `errorComponent` (라우트), `notFoundComponent` (404) |
@@ -300,7 +299,7 @@ const { data } = useQuery({
 })
 
 // Server Function
-export const getUsers = createServerOnlyFn()
+export const getUsers = createServerFn()
   .middleware([authMiddleware])
   .handler(async () => prisma.user.findMany())
 ```
@@ -327,7 +326,7 @@ const mutation = useMutation({
 })
 
 // Server Function
-export const createUser = createServerOnlyFn({ method: 'POST' })
+export const createUser = createServerFn({ method: 'POST' })
   .middleware([authMiddleware])
   .inputValidator(createUserSchema)
   .handler(async ({ data }) => prisma.user.create({ data }))
@@ -345,12 +344,11 @@ export const createUser = createServerOnlyFn({ method: 'POST' })
 
 | 타입 | 실행 위치 | 사용 시나리오 |
 |------|----------|-------------|
-| **createServerOnlyFn** | 서버 | DB 접근, 비밀키 (기본) |
-| createServerFn | 서버 (RPC) | 일반 서버 로직 |
+| **createServerFn** | 서버 | DB 접근, 비밀키, 서버 로직 (기본) |
 | createClientOnlyFn | 클라이언트 | localStorage, window |
 | createIsomorphicFn | 양쪽 | 환경별 구현 |
 
-**기본 규칙**: 별도 요청 없으면 `createServerOnlyFn` 사용
+**기본 규칙**: 별도 요청 없으면 `createServerFn` 사용
 
 ### Middleware 패턴
 
@@ -364,7 +362,7 @@ export const authMiddleware = createMiddleware()
   })
 
 // 2. 사용
-export const createPost = createServerOnlyFn({ method: 'POST' })
+export const createPost = createServerFn({ method: 'POST' })
   .middleware([authMiddleware])
   .inputValidator(createPostSchema)
   .handler(async ({ data, context }) => {

package/templates/.claude/commands/subagent-creator.md

@@ -1,118 +0,0 @@
----
-description: Task 도구로 subagent 생성. 복잡한 작업 위임.
-allowed-tools: Task, mcp__sequential-thinking__sequentialthinking
-argument-hint: <생성할 subagent 작업 설명>
----
-
-# Subagent Creator
-
-> Task 도구를 사용하여 전문 subagent를 생성하고 복잡한 작업을 위임하는 커맨드.
-
----
-
-<agent_types>
-
-## 주요 Agent Types
-
-| Type | 용도 | 예시 |
-|------|------|------|
-| **Explore** | 코드베이스 구조 탐색, 파일 검색 | "React 컴포넌트 구조 분석" |
-| **Plan** | 구현 전략 수립, 설계 계획 | "마이그레이션 단계별 계획" |
-| **Bash** | Git 작업, 터미널 명령 실행 | "브랜치 생성 및 커밋" |
-| **general-purpose** | 복합 작업, 다단계 조사 | "여러 모듈 의존성 분석" |
-
-</agent_types>
-
----
-
-<usage_patterns>
-
-## 사용 패턴
-
-### 단일 Subagent
-
-```typescript
-Task({
-  subagent_type: 'Explore',
-  description: '인증 구조 분석',
-  prompt: `
-    현재 인증 관련 코드 분석:
-    - 사용 중인 라이브러리
-    - 세션 관리 방식
-    - 관련 파일 위치
-  `
-})
-```
-
-### 병렬 Subagent (독립 작업)
-
-```typescript
-// 단일 메시지에 여러 Task 호출
-Task({
-  subagent_type: 'Explore',
-  description: '프론트엔드 구조',
-  prompt: '프론트엔드 인증 흐름 분석'
-})
-
-Task({
-  subagent_type: 'Explore',
-  description: '백엔드 API',
-  prompt: '백엔드 인증 엔드포인트 분석'
-})
-
-Task({
-  subagent_type: 'Bash',
-  description: 'Git 이력 확인',
-  prompt: 'git log --grep="auth" 최근 커밋 조사'
-})
-```
-
-### Model 선택 (선택적)
-
-```typescript
-Task({
-  subagent_type: 'Explore',
-  description: '간단한 파일 탐색',
-  prompt: 'config 파일 위치 찾기',
-  model: 'haiku'  // 빠르고 저렴한 작업
-})
-```
-
-</usage_patterns>
-
----
-
-<quick_tips>
-
-## Quick Tips
-
-| 팁 | 설명 |
-|----|------|
-| **description** | 3-5단어로 작업 요약 (사용자에게 표시) |
-| **prompt** | 구체적 작업 내용, 명확한 목표 |
-| **병렬 실행** | 독립적 작업은 단일 메시지에 여러 Task 호출 |
-| **model** | 간단한 작업 → `haiku`, 복잡한 작업 → 생략(sonnet) |
-| **Sequential Thinking** | agent 생성 전 복잡도 판단 권장 (3-5단계) |
-
-</quick_tips>
-
----
-
-<validation>
-
-## 체크리스트
-
-```text
-✅ 작업이 복잡하여 subagent 필요
-✅ description 3-5단어 (사용자 표시용)
-✅ prompt 명확하고 구체적
-✅ 독립 작업 → 병렬 실행 (단일 메시지)
-✅ 의존 작업 → 순차 실행 (결과 대기)
-
-❌ 단순 파일 읽기에 Task 사용 (Read 직접)
-❌ 특정 클래스 검색에 Task 사용 (Glob 직접)
-❌ 의존 작업을 병렬로 실행
-❌ placeholder 값 전달 (결과 대기 후 전달)
-```
-
-</validation>