@kood/claude-code 0.5.0 → 0.5.3

package/templates/.claude/instructions/validation/required-behaviors.md

@@ -0,0 +1,331 @@
+# Required Behaviors (필수 행동)
+
+**목적**: 모든 작업에서 반드시 따라야 할 규칙
+
+## 작업 시작
+
+### 필수 1: Sequential Thinking
+
+**복잡도 MEDIUM 이상 작업은 반드시 Sequential Thinking 실행**
+
+| 복잡도 | 최소 단계 | 예시 |
+|--------|----------|------|
+| LOW | 1-2 | 파일 읽기, 간단한 검색 |
+| MEDIUM | 3-5 | 기능 구현, 버그 수정 |
+| HIGH | 7-10+ | 아키텍처 설계, 대규모 리팩토링 |
+
+```typescript
+// ✅ 필수: 작업 전 Sequential Thinking
+mcp__sequential-thinking__sequentialthinking({
+  thought: "User API 구현 계획: 요구사항 분석 → 스키마 → 구현 → 검증",
+  thoughtNumber: 1,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+})
+```
+
+### 필수 2: 파일 읽기 전 Read 사용
+
+**코드 수정 전 반드시 Read로 파일 읽기**
+
+```typescript
+// ✅ 필수 순서
+Read({ file_path: "src/functions/auth.ts" })  // 1. 읽기
+Edit({ ... })  // 2. 수정
+
+// ❌ 금지
+Edit({ ... })  // 읽지 않고 수정
+```
+
+### 필수 3: 병렬 읽기
+
+**3개 이상 독립 파일은 반드시 병렬로 읽기**
+
+```typescript
+// ✅ 필수: 병렬 읽기
+Read({ file_path: "file1.ts" })
+Read({ file_path: "file2.ts" })
+Read({ file_path: "file3.ts" })
+```
+
+## 코드 작성
+
+### 필수 4: UTF-8 인코딩
+
+**모든 파일은 UTF-8 인코딩 사용**
+
+### 필수 5: 코드 묶음 단위 한글 주석
+
+```typescript
+// ✅ 필수: 코드 블록 상단에 한글 주석
+// 사용자 인증 검증
+const isAuthenticated = await checkAuth(session)
+if (!isAuthenticated) throw new Error('Unauthorized')
+
+// 사용자 데이터 조회
+const user = await prisma.user.findUnique({ where: { id: session.userId } })
+```
+
+### 필수 6: TypeScript strict 모드
+
+```typescript
+// ✅ 필수: 명시적 타입
+function createUser(data: CreateUserInput): Promise<User> {
+  return prisma.user.create({ data })
+}
+
+// ❌ 금지: any 사용
+function createUser(data: any): any {
+  return prisma.user.create({ data })
+}
+```
+
+## API 구현
+
+### 필수 7: Server Function 패턴
+
+**POST/PUT/PATCH는 inputValidator 필수**
+
+```typescript
+// ✅ 필수
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(createUserSchema)  // 필수
+  .handler(async ({ data }) => {
+    return prisma.user.create({ data })
+  })
+```
+
+**인증 필요 시 middleware 필수**
+
+```typescript
+// ✅ 필수
+export const getProfile = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])  // 필수
+  .handler(async ({ context }) => {
+    return prisma.user.findUnique({ where: { id: context.userId } })
+  })
+```
+
+### 필수 8: TanStack Query 사용
+
+**클라이언트에서 Server Function 호출 시 반드시 TanStack Query 사용**
+
+```typescript
+// ✅ 필수: useQuery/useMutation
+const { data } = useQuery({
+  queryKey: ['users'],
+  queryFn: getUsers
+})
+
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] })
+})
+
+// ❌ 금지: 직접 호출
+const users = await getUsers()
+```
+
+## 검증
+
+### 필수 9: 4-Phase 순차 진행
+
+**Phase 1 → 2 → 3 → 4 순서 엄수**
+
+```markdown
+✅ Phase 1: 작업 실행 (모든 요구사항 완료)
+✅ Phase 2: 자동 검증 (/pre-deploy + TODO)
+✅ Phase 3: Planner 검증 (승인 필수)
+✅ Phase 4: 완료 (<promise> 출력)
+```
+
+### 필수 10: /pre-deploy 전체 실행
+
+**typecheck, lint, build 모두 통과 필수**
+
+```typescript
+// ✅ 필수: 전체 검증
+Skill("pre-deploy")
+
+// ❌ 금지: 부분 검증
+Bash({ command: "tsc --noEmit" })  // typecheck만
+```
+
+### 필수 11: Planner 검증
+
+**Phase 3에서 Planner 승인 필수**
+
+```typescript
+// ✅ 필수
+Task(
+  subagent_type="planner",
+  model="opus",
+  prompt=`구현 완료 검증 요청
+
+【원본 작업】
+${PROMPT}
+
+【검증 결과】
+- /pre-deploy: ✅
+- TODO: ✅ 0개
+
+완료 여부 판단 요청`
+)
+```
+
+## 문서화
+
+### 필수 12: Ralph 세션 문서
+
+**Ralph 스킬 사용 시 반드시 문서화**
+
+```
+.claude/ralph/{YYYY-MM-DD_HH-MM}/
+├── TASKS.md          # 필수
+├── PROCESS.md        # 필수
+├── VERIFICATION.md   # 필수
+└── NOTES.md          # 선택
+```
+
+### 필수 13: 문서 업데이트 시점
+
+| 시점 | 업데이트 파일 | 내용 |
+|------|--------------|------|
+| Phase 전환 | PROCESS.md | Phase N 완료 → Phase N+1 시작 |
+| 요구사항 완료 | TASKS.md | 체크박스 체크 |
+| 검증 실행 | VERIFICATION.md | /pre-deploy 결과, TODO 개수 |
+| 주요 의사결정 | PROCESS.md | 결정 내용 및 이유 |
+
+### 필수 14: Prisma Multi-File
+
+**Prisma Multi-File 구조 사용 시 모든 요소에 한글 주석 필수**
+
+```prisma
+// ✅ 필수: 모든 모델/필드/enum에 주석
+
+/// 사용자
+model User {
+  /// 고유 식별자
+  id        Int      @id @default(autoincrement())
+  /// 이메일 (고유)
+  email     String   @unique
+  /// 이름
+  name      String
+  /// 생성 시각
+  createdAt DateTime @default(now())
+}
+
+/// 사용자 역할
+enum UserRole {
+  /// 관리자
+  ADMIN
+  /// 일반 사용자
+  USER
+}
+```
+
+## Git 작업
+
+### 필수 15: git-operator 사용
+
+**Git 작업은 반드시 git-operator 에이전트 사용**
+
+```typescript
+// ✅ 필수
+Task(subagent_type="git-operator", model="haiku",
+     prompt="변경사항 커밋 및 푸시")
+
+// ❌ 금지
+Bash({ command: "git add . && git commit -m 'feat: ...' && git push" })
+```
+
+### 필수 16: 커밋 메시지 형식
+
+**`<prefix>: <설명>` 형식 필수 (한 줄)**
+
+```bash
+# ✅ 필수
+feat: 로그인 API 구현
+fix: 타입 에러 수정
+refactor: auth 모듈 리팩토링
+
+# ❌ 금지
+로그인 기능 추가  # prefix 없음
+feat: 로그인 API 구현\n\nCo-Authored-By: ...  # 여러 줄
+🤖 feat: 로그인  # 이모지
+```
+
+**Prefix 종류:**
+- feat, fix, refactor, style, docs, test, chore, perf, ci
+
+## 에이전트 활용
+
+### 필수 17: 에이전트 위임
+
+**다음 조건 시 반드시 에이전트 위임:**
+
+- [ ] 독립적인 작업
+- [ ] 새 컨텍스트 필요
+- [ ] 전문 지식 필요
+- [ ] 10분 이상 소요 예상
+
+```typescript
+// ✅ 필수: 적절한 에이전트 위임
+Task(subagent_type="implementation-executor", model="sonnet", ...)
+Task(subagent_type="designer", model="sonnet", ...)
+Task(subagent_type="code-reviewer", model="opus", ...)
+```
+
+### 필수 18: 모델 선택
+
+**에이전트 호출 시 model 파라미터 필수**
+
+| 모델 | 사용 시점 |
+|------|----------|
+| haiku | 탐색, 문서, Git |
+| sonnet | 구현, 수정, 분석 (기본) |
+| opus | 아키텍처, 보안, 검증 |
+
+```typescript
+// ✅ 필수: model 명시
+Task(subagent_type="explore", model="haiku", ...)
+Task(subagent_type="planner", model="opus", ...)
+
+// ❌ 금지: model 누락
+Task(subagent_type="explore", ...)
+```
+
+## 종합 체크리스트
+
+작업 시작 전:
+
+- [ ] Sequential Thinking 실행 (MEDIUM 이상)
+- [ ] 파일 읽기 계획 (병렬 여부)
+- [ ] 에이전트 활용 계획
+
+코드 작성 시:
+
+- [ ] UTF-8 인코딩
+- [ ] 한글 주석 (코드 블록 단위)
+- [ ] TypeScript strict 모드
+- [ ] Server Function 패턴 준수
+- [ ] TanStack Query 사용
+
+검증 시:
+
+- [ ] Phase 1 → 2 → 3 → 4 순서
+- [ ] /pre-deploy 전체 실행
+- [ ] Planner 승인 확인
+
+문서화:
+
+- [ ] Ralph 세션 폴더 생성
+- [ ] Phase 전환 시 업데이트
+- [ ] 검증 결과 기록
+
+Git:
+
+- [ ] git-operator 사용
+- [ ] 커밋 메시지 형식 준수
+
+**모든 필수 항목 준수 → 품질 보장**

package/templates/.claude/instructions/validation/verification-checklist.md

@@ -0,0 +1,318 @@
+# Verification Checklist
+
+**목적**: 작업 완료 전 표준 검증 절차
+
+## Phase별 검증
+
+### Phase 1: 작업 실행 검증
+
+**완료 조건:**
+
+- [ ] 모든 요구사항 구현 완료
+- [ ] TASKS.md 체크리스트 100% 완료
+- [ ] 주요 의사결정 PROCESS.md 기록
+- [ ] 독립 작업 병렬 실행 확인
+
+**검증 방법:**
+
+```typescript
+// TASKS.md 읽기
+Read({ file_path: ".claude/ralph/{timestamp}/TASKS.md" })
+
+// 모든 체크박스가 [x]인지 확인
+// 진행률이 100%인지 확인
+```
+
+### Phase 2: 자동 검증
+
+**완료 조건:**
+
+- [ ] typecheck 통과 (tsc --noEmit)
+- [ ] lint 통과 (eslint, 0 에러)
+- [ ] build 통과 (프로젝트 빌드 성공)
+- [ ] pending/in_progress TODO = 0개
+- [ ] VERIFICATION.md 업데이트 완료
+
+**검증 방법:**
+
+```typescript
+// 1. /pre-deploy 실행
+Skill("pre-deploy")
+
+// 2. 결과 확인
+// - typecheck: ✅ (에러 없음)
+// - lint: ✅ (warning/error 0개)
+// - build: ✅ (성공)
+
+// 3. TODO 확인
+TaskList()
+// pending: 0
+// in_progress: 0
+
+// 4. VERIFICATION.md 업데이트
+Task(subagent_type="document-writer", model="haiku",
+     prompt="VERIFICATION.md에 검증 결과 기록")
+```
+
+### Phase 3: Planner 검증
+
+**완료 조건:**
+
+- [ ] Planner 에이전트 호출 완료
+- [ ] Planner 응답: "승인" 또는 "완료"
+- [ ] VERIFICATION.md에 Planner 응답 기록
+- [ ] Phase 2 검증 결과 포함하여 전달
+
+**검증 방법:**
+
+```typescript
+// 1. Planner 호출
+Task(
+  subagent_type="planner",
+  model="opus",
+  prompt=`구현 완료 검증 요청
+
+【원본 작업】
+${ORIGINAL_PROMPT}
+
+【수행 내용】
+- 요구사항 1: ✅ (구체적 설명)
+- 요구사항 2: ✅ (구체적 설명)
+- 요구사항 3: ✅ (구체적 설명)
+
+【검증 결과】
+- /pre-deploy: ✅ typecheck/lint/build 통과
+- TODO: ✅ 0개
+
+완료 여부를 판단하고, 미흡한 점이 있다면 구체적으로 지적해주세요.`
+)
+
+// 2. 응답 확인
+// "승인", "완료", "문제없음" → Phase 4 진행
+// "수정 필요", "미흡" → Phase 2 복귀
+
+// 3. VERIFICATION.md 업데이트
+Task(subagent_type="document-writer", model="haiku",
+     prompt="VERIFICATION.md: Planner 응답 기록")
+```
+
+### Phase 4: 완료
+
+**완료 조건:**
+
+- [ ] TASKS.md 최종 확인 (모든 항목 체크)
+- [ ] PROCESS.md 완료 시각 기록
+- [ ] VERIFICATION.md 모든 검증 통과 확인
+- [ ] `<promise>` 태그 출력
+
+**검증 방법:**
+
+```typescript
+// 1. 최종 문서 확인
+Read({ file_path: ".claude/ralph/{timestamp}/TASKS.md" })
+Read({ file_path: ".claude/ralph/{timestamp}/PROCESS.md" })
+Read({ file_path: ".claude/ralph/{timestamp}/VERIFICATION.md" })
+
+// 2. PROCESS.md 완료 기록
+Task(subagent_type="document-writer", model="haiku",
+     prompt="PROCESS.md: 완료 시각 및 총 소요 시간 기록")
+
+// 3. <promise> 출력
+<promise>작업 완료</promise>
+```
+
+## 코드 품질 검증
+
+### TypeScript 검증
+
+```bash
+# typecheck 실행
+tsc --noEmit
+
+# 예상 출력
+# (에러 없음)
+```
+
+**확인 사항:**
+
+- [ ] 타입 에러 0개
+- [ ] any 타입 사용 없음
+- [ ] @ts-ignore 주석 없음
+- [ ] 모든 함수에 명시적 return type
+
+### ESLint 검증
+
+```bash
+# lint 실행
+eslint .
+
+# 예상 출력
+# ✔ No problems
+```
+
+**확인 사항:**
+
+- [ ] ESLint 에러 0개
+- [ ] ESLint 경고 0개 (또는 정당한 이유)
+- [ ] Prettier 포맷 일치
+
+### Build 검증
+
+```bash
+# 빌드 실행
+npm run build
+# 또는
+vite build
+
+# 예상 출력
+# ✓ built in XXXms
+```
+
+**확인 사항:**
+
+- [ ] 빌드 성공
+- [ ] 번들 크기 적절
+- [ ] 빌드 경고 없음
+
+## 기능 검증
+
+### API 검증
+
+- [ ] Server Function 올바른 메서드 (GET/POST/PUT/DELETE)
+- [ ] POST/PUT/PATCH는 inputValidator 사용
+- [ ] 인증 필요 시 middleware 사용
+- [ ] 에러 처리 적절
+
+```typescript
+// ✅ 검증 예시
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])        // 인증 확인
+  .inputValidator(createUserSchema)    // 입력 검증 확인
+  .handler(async ({ data }) => {       // 핸들러 확인
+    return prisma.user.create({ data })
+  })
+```
+
+### UI 검증
+
+- [ ] TanStack Query 사용 (useQuery/useMutation)
+- [ ] 에러 상태 처리
+- [ ] 로딩 상태 처리
+- [ ] 낙관적 업데이트 (필요 시)
+
+```typescript
+// ✅ 검증 예시
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users'],
+  queryFn: getUsers
+})
+
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['users'] })
+  }
+})
+```
+
+### Database 검증
+
+- [ ] Prisma 스키마 일관성
+- [ ] 관계 올바름 (1:N, N:N)
+- [ ] Index 적절
+- [ ] 한글 주석 (Multi-File 사용 시 필수)
+
+## 문서 검증
+
+### TASKS.md
+
+```markdown
+- [x] 요구사항 1: 완료
+- [x] 요구사항 2: 완료
+- [x] 요구사항 3: 완료
+
+완료: 3 / 총 3
+진행률: 100%
+```
+
+### PROCESS.md
+
+```markdown
+## Phase 4: 완료
+
+**완료 시각:** 2026-01-24 17:00
+**총 소요 시간:** 30분
+
+모든 요구사항 구현 및 검증 완료
+```
+
+### VERIFICATION.md
+
+```markdown
+## /pre-deploy 검증
+
+**실행 시각:** 2026-01-24 16:50
+
+**결과:**
+- Typecheck: ✅ 통과
+- Lint: ✅ 0 에러
+- Build: ✅ 성공
+
+## TODO 확인
+
+**실행 시각:** 2026-01-24 16:52
+
+**결과:** pending/in_progress = 0
+
+## Planner 검증
+
+**실행 시각:** 2026-01-24 16:55
+
+**응답:** "구현 완료 승인. 요구사항 모두 충족."
+```
+
+## Git 검증
+
+### 커밋 메시지
+
+```bash
+# ✅ 올바른 형식
+feat: 로그인 API 구현
+fix: 타입 에러 수정
+
+# ❌ 잘못된 형식
+로그인 기능  # prefix 없음
+feat: 로그인\n\nCo-Authored-By: ...  # 여러 줄
+```
+
+### 커밋 내용
+
+- [ ] 논리적 단위로 분리
+- [ ] 관련 없는 변경 혼재 없음
+- [ ] AI 표시 없음 (Co-Authored-By, 🤖 등)
+
+## 실패 시 조치
+
+| 실패 항목 | 조치 |
+|----------|------|
+| typecheck 실패 | lint-fixer 에이전트로 수정 |
+| lint 실패 | lint-fixer 에이전트로 수정 |
+| build 실패 | 에러 로그 분석 후 수정 |
+| Planner 거절 | 피드백 반영 → Phase 2부터 재실행 |
+| TODO 미완료 | 남은 작업 완료 |
+
+**절대 검증 스킵하지 않음. 실패 시 수정 → 재검증 반복.**
+
+## 최종 체크리스트
+
+작업 완료 전 확인:
+
+- [ ] Phase 1-4 순차 진행 완료
+- [ ] /pre-deploy 전체 통과
+- [ ] TODO 리스트 0개
+- [ ] Planner 승인 획득
+- [ ] 문서 업데이트 완료
+- [ ] Git 커밋 형식 준수
+- [ ] 코드 품질 기준 충족
+
+**모든 항목 체크 완료 후 `<promise>` 출력**

package/templates/.claude/instructions/workflow-patterns/index.md

@@ -0,0 +1,18 @@
+# Workflow Patterns
+
+작업 흐름 및 사고 패턴
+
+## 파일 목록
+
+| 파일 | 설명 |
+|------|------|
+| [sequential-thinking.md](./sequential-thinking.md) | Sequential Thinking - 구조화된 사고 과정 |
+| [todowrite-pattern.md](./todowrite-pattern.md) | TodoWrite 패턴 - 작업 단계 관리 |
+| [phase-based-workflow.md](./phase-based-workflow.md) | Phase 기반 워크플로우 - 4단계 검증 |
+
+## 사용법
+
+```markdown
+@.claude/instructions/workflow-patterns/sequential-thinking.md
+@.claude/instructions/workflow-patterns/phase-based-workflow.md
+```