@kood/claude-code 0.5.1 → 0.5.4

package/templates/.claude/instructions/workflow-patterns/phase-based-workflow.md

@@ -0,0 +1,250 @@
+# Phase-Based Workflow
+
+**목적**: 복잡한 작업을 명확한 단계로 구조화하여 완료 보장
+
+## 4-Phase 구조
+
+모든 복잡한 구현 작업은 다음 4단계를 거칩니다:
+
+| Phase | 이름 | 목적 | 완료 조건 |
+|-------|------|------|----------|
+| **1** | 작업 실행 | 요구사항 구현 | 모든 체크리스트 완료 |
+| **2** | 자동 검증 | 코드 품질 확인 | /pre-deploy 통과 + TODO 0개 |
+| **3** | 플래너 검증 | 아키텍처 승인 | Planner "승인" 응답 |
+| **4** | 완료 | 최종 확인 | 문서 업데이트 완료 |
+
+## Phase 1: 작업 실행
+
+### 목표
+모든 요구사항을 100% 구현
+
+### 주요 활동
+
+1. **요구사항 분석**
+   - Sequential Thinking (3-5단계)
+   - 체크리스트 작성 (TASKS.md)
+
+2. **병렬 구현**
+   - 독립적인 작업 동시 실행
+   - 에이전트 적극 활용
+   - 백그라운드 실행
+
+3. **진행 추적**
+   - TodoWrite로 단계 관리
+   - TASKS.md 체크박스 업데이트
+   - PROCESS.md 의사결정 기록
+
+### 완료 조건
+
+```markdown
+- [ ] 모든 요구사항 구현 완료
+- [ ] TASKS.md 체크리스트 100% 완료
+- [ ] PROCESS.md 업데이트 (Phase 1 완료)
+```
+
+### 예시
+
+```typescript
+// 1. 요구사항 분석
+mcp__sequential-thinking__sequentialthinking({
+  thought: "User 인증 API 구현: login, signup, logout 필요",
+  thoughtNumber: 1,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+})
+
+// 2. 병렬 구현
+Task(subagent_type="implementation-executor", model="sonnet",
+     prompt="Login/Signup Server Functions 구현")
+Task(subagent_type="designer", model="sonnet",
+     prompt="Login/Signup UI 컴포넌트 구현")
+Task(subagent_type="document-writer", model="haiku",
+     prompt="API 문서 작성")
+
+// 3. TASKS.md 업데이트
+Task(subagent_type="document-writer", model="haiku",
+     prompt="TASKS.md: 인증 API 구현 완료 체크")
+```
+
+## Phase 2: 자동 검증
+
+### 목표
+코드 품질 및 빌드 안정성 확보
+
+### 주요 활동
+
+1. **/pre-deploy 실행**
+   ```typescript
+   Skill("pre-deploy")
+   ```
+   - typecheck (tsc --noEmit)
+   - lint (eslint)
+   - build (프로젝트 빌드)
+
+2. **TODO 확인**
+   ```typescript
+   TaskList()  // pending/in_progress 작업 확인
+   ```
+
+3. **에러 수정**
+   - lint-fixer 에이전트 활용
+   - 하나씩 수정 (Sequential Thinking 필수)
+
+4. **검증 결과 기록**
+   - VERIFICATION.md 업데이트
+
+### 완료 조건
+
+```markdown
+- [ ] /pre-deploy 전체 통과
+  - [ ] typecheck: ✅
+  - [ ] lint: ✅
+  - [ ] build: ✅
+- [ ] TODO 리스트: pending/in_progress = 0
+- [ ] VERIFICATION.md 업데이트 완료
+- [ ] PROCESS.md 업데이트 (Phase 2 완료)
+```
+
+### 예시
+
+```typescript
+// 1. /pre-deploy 실행
+Skill("pre-deploy")
+
+// 2. 결과 확인 및 기록
+Task(subagent_type="document-writer", model="haiku",
+     prompt=`VERIFICATION.md 업데이트:
+- typecheck: ✅ 통과
+- lint: ✅ 0 에러
+- build: ✅ 성공`)
+
+// 3. TODO 확인
+TaskList()
+
+// 4. Phase 2 완료 기록
+Task(subagent_type="document-writer", model="haiku",
+     prompt="PROCESS.md: Phase 2 완료 → Phase 3 시작")
+```
+
+## Phase 3: 플래너 검증
+
+### 목표
+아키텍처 및 구현 품질 검증
+
+### 주요 활동
+
+1. **Planner 에이전트 호출**
+   ```typescript
+   Task(
+     subagent_type="planner",
+     model="opus",
+     prompt=`구현 완료 검증 요청
+
+【원본 작업】
+${PROMPT}
+
+【수행 내용】
+- 요구사항 1: 완료 (구체적 설명)
+- 요구사항 2: 완료 (구체적 설명)
+
+【검증 결과】
+- /pre-deploy: ✅ 통과
+- TODO: ✅ 0개
+
+완료 여부를 판단하고, 미흡한 점이 있다면 구체적으로 지적해주세요.`
+   )
+   ```
+
+2. **응답 처리**
+   - "승인" → Phase 4 진행
+   - "수정 필요" → Phase 2로 복귀
+
+3. **결과 기록**
+   - VERIFICATION.md에 Planner 응답 기록
+
+### 완료 조건
+
+```markdown
+- [ ] Planner 에이전트 호출 완료
+- [ ] Planner 응답: "승인" 또는 "완료"
+- [ ] VERIFICATION.md에 응답 기록
+- [ ] PROCESS.md 업데이트 (Phase 3 완료)
+```
+
+### 예시
+
+```typescript
+// Planner 호출
+Task(subagent_type="planner", model="opus", prompt="...")
+
+// 응답 처리
+if (planner_response.includes("승인")) {
+  // Phase 4 진행
+  Task(subagent_type="document-writer", model="haiku",
+       prompt="VERIFICATION.md: Planner 승인 기록")
+} else {
+  // Phase 2로 복귀
+  // 피드백 반영 후 재검증
+}
+```
+
+## Phase 4: 완료
+
+### 목표
+작업 완료 및 최종 문서화
+
+### 주요 활동
+
+1. **최종 문서 업데이트**
+   - PROCESS.md: 완료 시각, 총 소요 시간
+   - TASKS.md: 최종 확인 (모든 체크박스 체크)
+
+2. **완료 출력**
+   ```
+   <promise>{{PROMISE}}</promise>
+   ```
+
+### 완료 조건
+
+```markdown
+- [ ] TASKS.md: 모든 항목 체크 완료
+- [ ] PROCESS.md: 완료 시각 기록
+- [ ] VERIFICATION.md: 모든 검증 통과
+- [ ] <promise> 태그 출력
+```
+
+## 실패 처리
+
+| 실패 Phase | 조치 |
+|-----------|------|
+| **Phase 1** | 미완료 항목 계속 구현 |
+| **Phase 2** | 에러 수정 후 재검증 |
+| **Phase 3** | Planner 피드백 반영 → Phase 2부터 재실행 |
+
+**절대 건너뛰지 않음. 실패 시 수정 → 재검증 반복**
+
+## 금지 사항
+
+| 금지 패턴 | 설명 |
+|----------|------|
+| ❌ Phase 스킵 | 2→4 직행 금지 |
+| ❌ 부분 검증 | /pre-deploy 일부만 실행 금지 |
+| ❌ Planner 우회 | Phase 3 생략 금지 |
+| ❌ 추측 완료 | "아마 완료" 금지 |
+
+## 체크리스트
+
+작업 시작 전:
+
+- [ ] Phase 1-4 구조 이해
+- [ ] 각 Phase 완료 조건 숙지
+- [ ] 문서화 폴더 생성 (.claude/ralph/{timestamp}/)
+- [ ] TASKS.md, PROCESS.md, VERIFICATION.md 초기화
+
+작업 중:
+
+- [ ] 현재 Phase 명확히 인식
+- [ ] Phase 전환 시 문서 업데이트
+- [ ] 실패 시 조기 탈출하지 않고 수정
+
+**4단계 순차 진행으로 작업 완료 보장**

package/templates/.claude/instructions/workflow-patterns/sequential-thinking.md

@@ -0,0 +1,217 @@
+# Sequential Thinking Pattern
+
+**목적**: 복잡한 문제를 구조화된 단계로 분해하여 해결
+
+## 핵심 원칙
+
+**작업 시작 전 Sequential Thinking으로 사고 과정을 거칠 것**
+
+## 복잡도별 사고 단계
+
+| 복잡도 | 단계 수 | 예시 |
+|--------|---------|------|
+| **LOW** | 1-2 | 단순 질문, 파일 읽기, 간단한 검색 |
+| **MEDIUM** | 3-5 | 기능 구현, 버그 수정, 문서 작성 |
+| **HIGH** | 7-10+ | 아키텍처 설계, 대규모 리팩토링, 복잡한 디버깅 |
+
+## 사용 시점
+
+| 상황 | 필수 여부 |
+|------|----------|
+| 새 기능 구현 | ✅ 필수 (3-5단계) |
+| 버그 수정 | ✅ 필수 (3-5단계) |
+| 리팩토링 | ✅ 필수 (5-7단계) |
+| 아키텍처 설계 | ✅ 필수 (7-10단계) |
+| 파일 읽기 | ❌ 선택 (1단계) |
+| 간단한 검색 | ❌ 선택 (1단계) |
+
+## 파라미터
+
+| 필수 | 설명 |
+|------|------|
+| `thought` | 현재 사고 내용 |
+| `nextThoughtNeeded` | 추가 사고 필요 여부 (true/false) |
+| `thoughtNumber` | 현재 번호 (1부터 시작) |
+| `totalThoughts` | 예상 총 단계 (동적 조정 가능) |
+
+| 선택 | 설명 |
+|------|------|
+| `isRevision` | 이전 사고 수정 여부 |
+| `revisesThought` | 수정 대상 번호 |
+| `branchFromThought` | 분기 시작점 |
+| `branchId` | 분기 식별자 |
+
+## 코드 예시
+
+### 예시 1: 간단한 작업 (2단계)
+
+```typescript
+// Thought 1: 파일 탐색 계획
+mcp__sequential-thinking__sequentialthinking({
+  thought: "User 관련 파일을 찾기 위해 src/functions/ 디렉토리를 탐색해야 함",
+  thoughtNumber: 1,
+  totalThoughts: 2,
+  nextThoughtNeeded: true
+})
+
+// Thought 2: 실행 결정
+mcp__sequential-thinking__sequentialthinking({
+  thought: "Glob 도구로 **/*user*.ts 패턴 검색 실행",
+  thoughtNumber: 2,
+  totalThoughts: 2,
+  nextThoughtNeeded: false
+})
+```
+
+### 예시 2: 중간 복잡도 (5단계)
+
+```typescript
+// Thought 1: 문제 정의
+mcp__sequential-thinking__sequentialthinking({
+  thought: "로그인 API에서 타입 에러 발생. src/functions/auth.ts 확인 필요",
+  thoughtNumber: 1,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+})
+
+// Thought 2: 탐색 계획
+mcp__sequential-thinking__sequentialthinking({
+  thought: "auth.ts와 관련 타입 파일 (src/types/auth.ts) 병렬로 읽기",
+  thoughtNumber: 2,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+})
+
+// Thought 3: 원인 분석
+mcp__sequential-thinking__sequentialthinking({
+  thought: "LoginInput 타입에 email 필드가 없음. Zod 스키마와 TypeScript 타입 불일치",
+  thoughtNumber: 3,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+})
+
+// Thought 4: 해결 방안
+mcp__sequential-thinking__sequentialthinking({
+  thought: "LoginInput 인터페이스에 email: string 추가. Zod 스키마는 이미 올바름",
+  thoughtNumber: 4,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+})
+
+// Thought 5: 실행 결정
+mcp__sequential-thinking__sequentialthinking({
+  thought: "Edit 도구로 src/types/auth.ts 수정 후 tsc 재실행",
+  thoughtNumber: 5,
+  totalThoughts: 5,
+  nextThoughtNeeded: false
+})
+```
+
+### 예시 3: 동적 조정 (3→5단계)
+
+```typescript
+// Thought 1
+mcp__sequential-thinking__sequentialthinking({
+  thought: "API 엔드포인트 구현 시작. 3단계 예상",
+  thoughtNumber: 1,
+  totalThoughts: 3,
+  nextThoughtNeeded: true
+})
+
+// Thought 2
+mcp__sequential-thinking__sequentialthinking({
+  thought: "기존 패턴 확인 중 인증 미들웨어가 필요함을 발견. 단계 조정",
+  thoughtNumber: 2,
+  totalThoughts: 5,  // 3→5로 증가
+  nextThoughtNeeded: true
+})
+
+// Thought 3-5 계속...
+```
+
+## 주요 기능
+
+### 1. 동적 조정
+
+**totalThoughts는 고정이 아님:**
+- 작업 중 복잡도 재평가 가능
+- 필요 시 단계 추가/감소
+
+### 2. 수정 (Revision)
+
+**이전 사고를 재검토:**
+
+```typescript
+mcp__sequential-thinking__sequentialthinking({
+  thought: "Thought 3의 원인 분석이 잘못됨. 실제 문제는 DB 스키마 불일치",
+  thoughtNumber: 6,
+  totalThoughts: 7,
+  isRevision: true,
+  revisesThought: 3,
+  nextThoughtNeeded: true
+})
+```
+
+### 3. 분기 (Branching)
+
+**여러 접근 방식 탐색:**
+
+```typescript
+mcp__sequential-thinking__sequentialthinking({
+  thought: "방법 A: REST API 사용",
+  thoughtNumber: 4,
+  totalThoughts: 8,
+  branchFromThought: 3,
+  branchId: "approach-a",
+  nextThoughtNeeded: true
+})
+
+mcp__sequential-thinking__sequentialthinking({
+  thought: "방법 B: GraphQL 사용",
+  thoughtNumber: 4,
+  totalThoughts: 8,
+  branchFromThought: 3,
+  branchId: "approach-b",
+  nextThoughtNeeded: true
+})
+```
+
+## 금지 패턴
+
+**다음 표현 사용 금지:**
+
+| 금지 표현 | 이유 | 대체 표현 |
+|----------|------|----------|
+| "~해야 한다" | 추측성 | "~한다" (단정) |
+| "probably" | 불확실 | "확인 후 결정" |
+| "seems to" | 모호함 | "분석 결과 ~임" |
+| "아마도" | 추측 | "검증 필요" |
+| "~것 같다" | 불확실 | "~이다" |
+
+**올바른 표현:**
+
+```typescript
+// ❌ 잘못된 표현
+thought: "이 파일을 수정하면 아마도 해결될 것 같다"
+
+// ✅ 올바른 표현
+thought: "타입 정의 누락 확인. src/types/user.ts 수정으로 해결"
+```
+
+## 체크리스트
+
+작업 시작 전:
+
+- [ ] 복잡도 판단 (LOW/MEDIUM/HIGH)
+- [ ] 최소 단계 수 결정
+- [ ] 첫 번째 thought 작성 (문제 정의)
+- [ ] 마지막 thought에서만 nextThoughtNeeded=false
+
+작업 중:
+
+- [ ] 각 단계마다 명확한 결론
+- [ ] 추측성 표현 금지
+- [ ] 필요 시 totalThoughts 조정
+- [ ] 불확실하면 분기 또는 수정
+
+**모든 복잡한 작업은 Sequential Thinking으로 시작**

package/templates/.claude/instructions/workflow-patterns/todowrite-pattern.md

@@ -0,0 +1,215 @@
+# TodoWrite Pattern
+
+**목적**: 복잡한 작업을 단계별로 추적하고 진행 상황 관리
+
+## 핵심 개념
+
+TodoWrite는 작업을 작은 단위로 나누고 각 단계를 체크리스트로 관리하는 도구입니다.
+
+## 사용 시점
+
+| 상황 | 사용 여부 |
+|------|----------|
+| 3개 이상 단계 작업 | ✅ 권장 |
+| 여러 파일 수정 | ✅ 권장 |
+| 순차적 의존성 | ✅ 필수 |
+| Plan 모드 | ✅ 필수 |
+| 간단한 1-2단계 작업 | ❌ 불필요 |
+
+## 기본 구조
+
+```typescript
+TodoWrite({
+  todos: [
+    { text: "1단계: 파일 탐색", done: false },
+    { text: "2단계: 타입 수정", done: false },
+    { text: "3단계: 테스트 실행", done: false }
+  ]
+})
+```
+
+## 워크플로우
+
+### 1. 작업 시작 시
+
+```typescript
+// 모든 단계를 done: false로 초기화
+TodoWrite({
+  todos: [
+    { text: "요구사항 분석", done: false },
+    { text: "파일 탐색", done: false },
+    { text: "코드 수정", done: false },
+    { text: "테스트 검증", done: false }
+  ]
+})
+```
+
+### 2. 단계 완료 시
+
+```typescript
+// 완료된 항목을 done: true로 업데이트
+TodoWrite({
+  todos: [
+    { text: "요구사항 분석", done: true },  // ✅
+    { text: "파일 탐색", done: true },      // ✅
+    { text: "코드 수정", done: false },     // 진행 중
+    { text: "테스트 검증", done: false }
+  ]
+})
+```
+
+### 3. 작업 완료 시
+
+```typescript
+// 모든 항목 done: true
+TodoWrite({
+  todos: [
+    { text: "요구사항 분석", done: true },
+    { text: "파일 탐색", done: true },
+    { text: "코드 수정", done: true },
+    { text: "테스트 검증", done: true }
+  ]
+})
+```
+
+## 실전 예시
+
+### 예시 1: 버그 수정
+
+```typescript
+// 초기 상태
+TodoWrite({
+  todos: [
+    { text: "1. 버그 재현 및 원인 파악", done: false },
+    { text: "2. 관련 파일 탐색 (src/functions/auth.ts)", done: false },
+    { text: "3. 타입 에러 수정", done: false },
+    { text: "4. tsc 검증", done: false },
+    { text: "5. 테스트 실행", done: false }
+  ]
+})
+
+// 1-2단계 완료 후
+TodoWrite({
+  todos: [
+    { text: "1. 버그 재현 및 원인 파악", done: true },
+    { text: "2. 관련 파일 탐색 (src/functions/auth.ts)", done: true },
+    { text: "3. 타입 에러 수정", done: false },  // 현재 작업
+    { text: "4. tsc 검증", done: false },
+    { text: "5. 테스트 실행", done: false }
+  ]
+})
+```
+
+### 예시 2: 새 기능 구현
+
+```typescript
+TodoWrite({
+  todos: [
+    { text: "1. 요구사항 분석 및 Sequential Thinking (5단계)", done: false },
+    { text: "2. DB 스키마 설계 (Prisma)", done: false },
+    { text: "3. Server Function 구현 (inputValidator + middleware)", done: false },
+    { text: "4. UI 컴포넌트 구현 (TanStack Query 연동)", done: false },
+    { text: "5. 검증 (typecheck, lint, build)", done: false },
+    { text: "6. 문서 작성 (API 문서, README)", done: false }
+  ]
+})
+```
+
+### 예시 3: 동적 항목 추가
+
+```typescript
+// 초기 계획
+TodoWrite({
+  todos: [
+    { text: "1. 파일 읽기", done: true },
+    { text: "2. 코드 수정", done: false }
+  ]
+})
+
+// 작업 중 추가 단계 발견
+TodoWrite({
+  todos: [
+    { text: "1. 파일 읽기", done: true },
+    { text: "2. 코드 수정", done: false },
+    { text: "3. 의존성 업데이트 (새로 발견)", done: false },  // 추가
+    { text: "4. 테스트 수정 (새로 발견)", done: false }      // 추가
+  ]
+})
+```
+
+## Sequential Thinking과의 조합
+
+**Sequential Thinking**: 사고 과정
+**TodoWrite**: 실행 단계
+
+```typescript
+// 1. Sequential Thinking으로 계획 수립
+mcp__sequential-thinking__sequentialthinking({
+  thought: "User API 구현 계획: 스키마 → Server Function → UI → 검증",
+  thoughtNumber: 1,
+  totalThoughts: 3,
+  nextThoughtNeeded: true
+})
+
+// 2. TodoWrite로 작업 목록 생성
+TodoWrite({
+  todos: [
+    { text: "Prisma 스키마 정의", done: false },
+    { text: "Server Function 구현", done: false },
+    { text: "UI 컴포넌트 구현", done: false },
+    { text: "/pre-deploy 검증", done: false }
+  ]
+})
+
+// 3. 각 단계 실행 후 TodoWrite 업데이트
+```
+
+## 장점
+
+| 장점 | 설명 |
+|------|------|
+| **진행 추적** | 어디까지 완료했는지 명확 |
+| **우선순위** | 다음에 할 일이 명확 |
+| **컨텍스트 복구** | Context compaction 후 재개 용이 |
+| **투명성** | 사용자가 진행 상황 확인 가능 |
+
+## 주의사항
+
+### 금지 패턴
+
+```typescript
+// ❌ 너무 큰 단위
+TodoWrite({
+  todos: [
+    { text: "전체 기능 구현", done: false }  // 너무 모호
+  ]
+})
+
+// ✅ 적절한 단위
+TodoWrite({
+  todos: [
+    { text: "DB 스키마 정의", done: false },
+    { text: "API 구현", done: false },
+    { text: "UI 구현", done: false },
+    { text: "테스트", done: false }
+  ]
+})
+```
+
+### 권장 사항
+
+- 각 항목은 30분 이내 완료 가능한 크기
+- 5-10개 항목이 적절 (너무 많으면 분할)
+- 구체적이고 측정 가능한 표현
+- 순서가 중요하면 번호 부여
+
+## 체크리스트
+
+TodoWrite 사용 전:
+
+- [ ] 작업이 3단계 이상인가?
+- [ ] 각 단계가 명확한가?
+- [ ] 순서가 논리적인가?
+- [ ] 각 항목이 측정 가능한가?
+
+**복잡한 작업은 TodoWrite로 체계적 관리**