@kood/claude-code 0.3.3 → 0.3.5

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

@@ -15,6 +15,8 @@
 
 | 분류 | 금지 |
 |------|------|
+| **라우트** | Flat 파일 라우트 (`routes/users.tsx`) |
+| **Route Export** | `export const IndexRoute`, `const Route` (export 안함) |
 | **API** | `/api` 라우터 생성 (Server Functions 사용) |
 | **레이어** | Service Layer 건너뛰기, Routes에서 직접 DB 접근 |
 | **검증** | Handler 내부 수동 검증, 인증 로직 분산 |
@@ -28,6 +30,8 @@
 
 | 분류 | 필수 |
 |------|------|
+| **라우트 구조** | 페이지마다 폴더 생성 (`routes/users/index.tsx`) |
+| **Route Export** | `export const Route = createFileRoute(...)` 필수 |
 | **계층 구조** | Routes → Server Functions → Services → Database |
 | **Route Group** | 목록 → `(main)/`, 생성/편집 → 외부 |
 | **페이지 분리** | 100줄+ → `-components`, 200줄+ → `-sections` |
@@ -80,12 +84,60 @@
 
 ---
 
+<route_export_rule>
+
+## Route Export 규칙
+
+> ⚠️ **`export const Route` 필수**
+>
+> TanStack Router는 모든 라우트 파일에서 **정확히 `Route`라는 이름**으로 내보내야 합니다.
+>
+> `tsr generate` 및 `tsr watch` 명령어가 자동으로 경로를 생성하고 업데이트합니다.
+
+| ❌ 금지 | ✅ 필수 |
+|--------|--------|
+| `const Route = createFileRoute(...)` | `export const Route = createFileRoute(...)` |
+| `export const IndexRoute = ...` | `export const Route = ...` |
+| `export default createFileRoute(...)` | `export const Route = createFileRoute(...)` |
+
+```typescript
+// ❌ 금지: export 없음
+const Route = createFileRoute('/users')({
+  component: UsersPage,
+})
+
+// ❌ 금지: 다른 이름
+export const UsersRoute = createFileRoute('/users')({
+  component: UsersPage,
+})
+
+// ✅ 필수: 정확히 'Route' 이름으로 export
+export const Route = createFileRoute('/users')({
+  component: UsersPage,
+})
+```
+
+</route_export_rule>
+
+---
+
 <layers>
 
 ## Layer Architecture
 
 ### 1. Routes Layer
 
+> ⚠️ **페이지마다 폴더 생성 필수**
+>
+> 모든 페이지는 **반드시 폴더 구조**로 만들어야 합니다. Flat 파일 방식(`routes/users.tsx`)은 금지됩니다.
+>
+> **이유:** -components/, -functions/, -hooks/ 등 페이지 전용 리소스를 체계적으로 관리하기 위함입니다.
+>
+> | ❌ 금지 | ✅ 필수 |
+> |--------|--------|
+> | `routes/users.tsx` | `routes/users/index.tsx` |
+> | `routes/posts.tsx` | `routes/posts/(main)/index.tsx` |
+
 ```
 routes/<route-name>/
 ├── (main)/                # route group (목록 페이지)

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>