@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tauri-react-best-practices/rules/ipc-type-safe.md

@@ -0,0 +1,227 @@
+---
+title: Generate TypeScript Bindings with tauri-specta
+impact: HIGH
+impactDescription: End-to-end type safety, eliminate runtime type errors
+tags: ipc, typescript, type-safety, tauri-specta, devex
+---
+
+# tauri-specta로 TypeScript 바인딩 자동 생성
+
+## 왜 중요한가
+
+수동으로 TypeScript 타입을 작성하면 Rust 커맨드와 불일치가 발생하여 런타임 에러가 발생합니다. `tauri-specta`를 사용하면 Rust 타입에서 TypeScript 바인딩을 자동 생성하여 완벽한 타입 안전성을 확보할 수 있습니다.
+
+**영향도:**
+- 타입 안전성: 런타임 에러 사전 방지
+- 개발 경험: 자동 완성, 타입 체크
+- 유지보수: Rust 변경 시 TS 자동 업데이트
+
+## ❌ 잘못된 패턴
+
+**수동 타입 정의 (불일치 위험):**
+
+```rust
+// Rust 커맨드
+#[derive(serde::Serialize)]
+struct User {
+  id: i32,
+  name: String,
+  email: String,
+}
+
+#[tauri::command]
+fn get_user(id: i32) -> Result<User, String> {
+  Ok(User {
+    id,
+    name: "Alice".to_string(),
+    email: "alice@example.com".to_string(),
+  })
+}
+```
+
+```typescript
+// ❌ 수동으로 타입 작성 (Rust와 동기화 안됨)
+interface User {
+  id: number;
+  name: string;
+  // email 필드 누락! 런타임 에러 위험
+}
+
+const user = await invoke<User>('get_user', { id: 1 });
+console.log(user.email); // 타입 체크 통과, 런타임 undefined
+```
+
+**문제점:**
+- Rust 타입 변경 시 TypeScript에 반영 안됨
+- 오타, 필드 누락 등으로 런타임 에러 발생
+- 리팩토링 시 일관성 유지 어려움
+
+## ✅ 올바른 패턴
+
+**tauri-specta로 바인딩 자동 생성:**
+
+### 1. 의존성 추가
+
+```toml
+# src-tauri/Cargo.toml
+[dependencies]
+tauri-specta = { version = "2.0", features = ["derive", "typescript"] }
+specta = { version = "2.0", features = ["derive"] }
+```
+
+### 2. Rust 타입에 derive 추가
+
+```rust
+use specta::Type;
+use serde::{Deserialize, Serialize};
+use tauri_specta::Event;
+
+// ✅ Type derive로 TypeScript 생성 가능
+#[derive(Debug, Clone, Serialize, Deserialize, Type)]
+struct User {
+  id: i32,
+  name: String,
+  email: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Type, Event)]
+struct UserCreatedEvent {
+  user: User,
+  timestamp: String,
+}
+
+#[tauri::command]
+#[specta::specta] // 커맨드 시그니처 추출
+fn get_user(id: i32) -> Result<User, String> {
+  Ok(User {
+    id,
+    name: "Alice".to_string(),
+    email: "alice@example.com".to_string(),
+  })
+}
+
+#[tauri::command]
+#[specta::specta]
+fn create_user(name: String, email: String) -> Result<User, String> {
+  Ok(User {
+    id: 1,
+    name,
+    email,
+  })
+}
+```
+
+### 3. 바인딩 생성 빌드 스크립트
+
+```rust
+// src-tauri/src/lib.rs (또는 main.rs)
+use tauri_specta::{collect_commands, collect_events, Builder};
+
+fn main() {
+  let builder = Builder::<tauri::Wry>::new()
+    .commands(collect_commands![get_user, create_user])
+    .events(collect_events![UserCreatedEvent]);
+
+  #[cfg(debug_assertions)]
+  builder
+    .export(specta_typescript::Typescript::default(), "../src/bindings.ts")
+    .expect("Failed to export typescript bindings");
+
+  tauri::Builder::default()
+    .plugin(builder.into_plugin())
+    .invoke_handler(tauri::generate_handler![get_user, create_user])
+    .run(tauri::generate_context!())
+    .expect("error while running tauri application");
+}
+```
+
+### 4. 생성된 TypeScript 바인딩 사용
+
+```typescript
+// src/bindings.ts (자동 생성됨)
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+export interface UserCreatedEvent {
+  user: User;
+  timestamp: string;
+}
+
+export const commands = {
+  getUser: (id: number) => invoke<User>('get_user', { id }),
+  createUser: (name: string, email: string) =>
+    invoke<User>('create_user', { name, email }),
+};
+
+export const events = {
+  userCreated: (handler: (event: UserCreatedEvent) => void) =>
+    listen<UserCreatedEvent>('user-created', handler),
+};
+```
+
+```typescript
+// ✅ 완벽한 타입 안전성
+import { commands, events } from './bindings';
+
+// 자동 완성, 타입 체크
+const user = await commands.getUser(1);
+console.log(user.email); // 타입 안전
+
+// Rust에서 email 필드 제거하면 TypeScript 컴파일 에러
+```
+
+## 대체 도구: TauRPC
+
+**타입 안전 + RPC 스타일 API:**
+
+```typescript
+// TauRPC는 추가로 함수형 API 제공
+import { createTauRPCProxy } from 'taurpc';
+
+const api = await createTauRPCProxy();
+
+// 함수처럼 호출 가능
+const user = await api.getUser(1);
+const newUser = await api.createUser("Bob", "bob@example.com");
+```
+
+**특징:**
+- `tauri-specta` 기반
+- RPC 스타일 함수 호출
+- 자동 재시도, 에러 처리
+
+## 추가 컨텍스트
+
+**언제 tauri-specta를 사용해야 하는가:**
+- TypeScript 프론트엔드 사용
+- 복잡한 데이터 구조 전달
+- 여러 커맨드 관리
+- 팀 협업 (타입 일관성 필수)
+
+**설정 옵션:**
+
+```rust
+// TypeScript 생성 옵션
+use specta_typescript::Typescript;
+
+let config = Typescript::default()
+  .formatter(specta_typescript::formatter::prettier) // Prettier 포맷팅
+  .header("// Generated by tauri-specta. DO NOT EDIT!") // 헤더 추가
+  .bigint(specta_typescript::BigIntExportBehavior::Number); // BigInt 처리
+
+builder.export(config, "../src/bindings.ts").unwrap();
+```
+
+**주의사항:**
+- `#[specta::specta]` 매크로를 모든 커맨드에 추가 필수
+- `Type` derive는 `Serialize`/`Deserialize`와 함께 사용
+- 생성된 파일은 `.gitignore`에 추가하지 말 것 (팀원도 타입 체크 필요)
+- `cargo run` 시 자동 생성되도록 설정 (CI/CD에서도 동작)
+
+**참고:**
+- [tauri-specta GitHub](https://github.com/specta-rs/tauri-specta)
+- [Specta Documentation](https://docs.rs/specta/)
+- [TauRPC](https://github.com/MatsDK/TauRPC)

package/templates/.claude/skills/tauri-react-best-practices/rules/perf-derived-state.md

@@ -0,0 +1,231 @@
+# 파생 boolean 구독
+
+## 왜 중요한가
+
+연속적인 값(윈도우 크기, 스크롤 위치 등)을 직접 구독하면 픽셀 단위로 리렌더링이 발생합니다. 파생된 boolean 값을 구독하면 리렌더링 빈도를 크게 줄일 수 있습니다. Tauri 앱에서는 윈도우 이벤트, 파일 워처 등에서 특히 중요합니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { getCurrentWindow } from '@tauri-apps/api/window'
+import { useEffect, useState } from 'react'
+
+function Sidebar() {
+  const [width, setWidth] = useState(0)
+
+  useEffect(() => {
+    const appWindow = getCurrentWindow()
+
+    // ❌ 윈도우 크기 변경마다 리렌더링 (연속적)
+    const unlisten = appWindow.listen('tauri://resize', async () => {
+      const size = await appWindow.innerSize()
+      setWidth(size.width)
+    })
+
+    return () => {
+      unlisten.then(fn => fn())
+    }
+  }, [])
+
+  // boolean 변환은 컴포넌트 내부 (매 렌더링마다 계산)
+  const isMobile = width < 768
+
+  return <nav className={isMobile ? 'mobile' : 'desktop'}>...</nav>
+}
+```
+
+**문제점:**
+- 윈도우 크기 변경마다 리렌더링 (픽셀 단위)
+- 실제로는 boolean 값만 필요한데 연속 값 구독
+- 불필요한 렌더링으로 성능 저하
+
+## ✅ 올바른 패턴
+
+```tsx
+import { getCurrentWindow } from '@tauri-apps/api/window'
+import { useEffect, useState } from 'react'
+
+function Sidebar() {
+  // ✅ boolean 값만 구독 (변경 시에만 리렌더링)
+  const [isMobile, setIsMobile] = useState(false)
+
+  useEffect(() => {
+    const appWindow = getCurrentWindow()
+
+    const checkMobile = async () => {
+      const size = await appWindow.innerSize()
+      const mobile = size.width < 768
+      setIsMobile(prev => prev !== mobile ? mobile : prev)  // 값 변경 시에만 업데이트
+    }
+
+    checkMobile()
+
+    const unlisten = appWindow.listen('tauri://resize', checkMobile)
+
+    return () => {
+      unlisten.then(fn => fn())
+    }
+  }, [])
+
+  return <nav className={isMobile ? 'mobile' : 'desktop'}>...</nav>
+}
+```
+
+**useMediaQuery 커스텀 hook (웹과 유사):**
+
+```tsx
+import { getCurrentWindow } from '@tauri-apps/api/window'
+import { useEffect, useState } from 'react'
+
+function useWindowWidth() {
+  const [width, setWidth] = useState(0)
+
+  useEffect(() => {
+    const appWindow = getCurrentWindow()
+
+    const updateWidth = async () => {
+      const size = await appWindow.innerSize()
+      setWidth(size.width)
+    }
+
+    updateWidth()
+    const unlisten = appWindow.listen('tauri://resize', updateWidth)
+
+    return () => {
+      unlisten.then(fn => fn())
+    }
+  }, [])
+
+  return width
+}
+
+function useMediaQuery(breakpoint: number) {
+  const width = useWindowWidth()
+  // ✅ boolean 반환 (리렌더링 빈도 감소)
+  return width < breakpoint
+}
+
+// 사용 예시
+function App() {
+  const isMobile = useMediaQuery(768)
+
+  return (
+    <div>
+      {isMobile ? <MobileView /> : <DesktopView />}
+    </div>
+  )
+}
+```
+
+**파일 워처 예시:**
+
+```tsx
+import { listen } from '@tauri-apps/api/event'
+import { useEffect, useState } from 'react'
+
+type FileEvent = {
+  path: string
+  size: number
+}
+
+function FileMonitor() {
+  // ❌ 파일 크기 연속 업데이트 (불필요)
+  const [fileSize, setFileSize] = useState(0)
+
+  useEffect(() => {
+    let unlisten: UnlistenFn | undefined
+
+    listen<FileEvent>('file-changed', event => {
+      setFileSize(event.payload.size)  // ❌ 매번 리렌더링
+    }).then(fn => unlisten = fn)
+
+    return () => unlisten?.()
+  }, [])
+
+  const isLarge = fileSize > 10 * 1024 * 1024  // 10MB
+
+  return <div>{isLarge ? 'Large file' : 'Normal file'}</div>
+}
+
+// ✅ 개선된 버전
+function FileMonitor() {
+  const [isLarge, setIsLarge] = useState(false)
+
+  useEffect(() => {
+    let unlisten: UnlistenFn | undefined
+
+    listen<FileEvent>('file-changed', event => {
+      const large = event.payload.size > 10 * 1024 * 1024
+      setIsLarge(prev => prev !== large ? large : prev)  // ✅ 변경 시에만 업데이트
+    }).then(fn => unlisten = fn)
+
+    return () => unlisten?.()
+  }, [])
+
+  return <div>{isLarge ? 'Large file' : 'Normal file'}</div>
+}
+```
+
+**스크롤 위치 → 버튼 표시:**
+
+```tsx
+import { useEffect, useState } from 'react'
+
+function ScrollToTop() {
+  // ❌ 스크롤 위치 직접 구독 (연속 업데이트)
+  const [scrollY, setScrollY] = useState(0)
+
+  useEffect(() => {
+    const handleScroll = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handleScroll)
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [])
+
+  const showButton = scrollY > 300
+
+  return showButton ? <button>Top</button> : null
+}
+
+// ✅ 개선된 버전
+function ScrollToTop() {
+  const [showButton, setShowButton] = useState(false)
+
+  useEffect(() => {
+    const handleScroll = () => {
+      const show = window.scrollY > 300
+      setShowButton(prev => prev !== show ? show : prev)  // ✅ boolean만 업데이트
+    }
+
+    window.addEventListener('scroll', handleScroll)
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [])
+
+  return showButton ? <button>Top</button> : null
+}
+```
+
+## 추가 컨텍스트
+
+**파생 boolean 구독이 유용한 경우:**
+- 윈도우 크기 → 모바일/데스크톱 구분
+- 스크롤 위치 → 버튼 표시/숨김
+- 파일 크기 → 경고 표시
+- 타이머 → 만료 여부
+
+**최적화 기법:**
+- `prev !== current ? current : prev` 패턴으로 불필요한 업데이트 방지
+- 연속 값을 구독해야 하는 경우 `useDeferredValue` 사용 (React 18+)
+
+**Tauri 윈도우 이벤트:**
+- `tauri://resize`: 윈도우 크기 변경
+- `tauri://move`: 윈도우 이동
+- `tauri://focus`: 포커스 상태 변경
+- `tauri://blur`: 블러 상태 변경
+
+**성능 비교:**
+- 연속 값 구독: 수십~수백 리렌더링/초
+- boolean 구독: 0~2 리렌더링/이벤트
+
+**참고:** [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)
+
+영향도: MEDIUM - 리렌더링 빈도 감소, 성능 최적화

package/templates/.claude/skills/tauri-react-best-practices/rules/perf-functional-setstate.md

@@ -0,0 +1,191 @@
+# 함수형 setState로 안정적 콜백
+
+## 왜 중요한가
+
+현재 상태 값을 기반으로 상태를 업데이트할 때 상태 변수를 직접 참조하면 stale closure가 발생하고, 콜백이 상태 변경마다 재생성됩니다. 함수형 setState를 사용하면 안정적인 콜백 참조를 유지하고 불필요한 리렌더링을 방지할 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState, useCallback } from 'react'
+
+function NotificationPanel() {
+  const [notifications, setNotifications] = useState<string[]>([])
+
+  // ❌ 콜백이 notifications에 의존 (매번 재생성)
+  const addNotification = useCallback(async (message: string) => {
+    setNotifications([...notifications, message])
+  }, [notifications])  // ❌ notifications 의존성으로 인한 재생성
+
+  // ❌ 의존성 누락 (stale closure 버그)
+  const clearNotifications = useCallback(() => {
+    setNotifications([])  // 항상 초기 notifications 참조
+  }, [])  // ❌ stale closure 위험
+
+  return (
+    <div>
+      <button onClick={() => addNotification('New message')}>Add</button>
+      <button onClick={clearNotifications}>Clear</button>
+      {notifications.map((msg, i) => <div key={i}>{msg}</div>)}
+    </div>
+  )
+}
+```
+
+**문제점:**
+- `notifications`가 변경될 때마다 콜백 재생성
+- 자식 컴포넌트가 불필요하게 리렌더링
+- 의존성 누락 시 stale closure 버그
+
+## ✅ 올바른 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState, useCallback } from 'react'
+
+function NotificationPanel() {
+  const [notifications, setNotifications] = useState<string[]>([])
+
+  // ✅ 안정적인 콜백, 재생성 안 됨
+  const addNotification = useCallback(async (message: string) => {
+    setNotifications(curr => [...curr, message])
+  }, [])  // ✅ 의존성 불필요
+
+  // ✅ 항상 최신 상태 사용
+  const clearNotifications = useCallback(() => {
+    setNotifications([])
+  }, [])  // ✅ 안전하고 안정적
+
+  return (
+    <div>
+      <button onClick={() => addNotification('New message')}>Add</button>
+      <button onClick={clearNotifications}>Clear</button>
+      {notifications.map((msg, i) => <div key={i}>{msg}</div>)}
+    </div>
+  )
+}
+```
+
+**Tauri IPC와 함께 사용:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { listen, UnlistenFn } from '@tauri-apps/api/event'
+import { useEffect, useState, useCallback } from 'react'
+
+function FileWatcher() {
+  const [files, setFiles] = useState<string[]>([])
+
+  // ✅ 함수형 setState로 안정적인 이벤트 핸들러
+  useEffect(() => {
+    let unlisten: UnlistenFn | undefined
+
+    listen<string>('file-added', event => {
+      setFiles(curr => [...curr, event.payload])  // ✅ 최신 상태 참조
+    }).then(fn => unlisten = fn)
+
+    return () => unlisten?.()
+  }, [])  // ✅ 의존성 없음
+
+  // ✅ 안정적인 삭제 핸들러
+  const removeFile = useCallback((fileName: string) => {
+    setFiles(curr => curr.filter(f => f !== fileName))
+  }, [])
+
+  return (
+    <div>
+      {files.map(file => (
+        <div key={file}>
+          {file}
+          <button onClick={() => removeFile(file)}>Remove</button>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+**invoke 호출과 상태 업데이트:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState, useCallback } from 'react'
+
+type TodoItem = {
+  id: string
+  title: string
+  completed: boolean
+}
+
+function TodoList() {
+  const [todos, setTodos] = useState<TodoItem[]>([])
+
+  // ✅ 함수형 setState로 안정적인 추가 로직
+  const addTodo = useCallback(async (title: string) => {
+    const newTodo = await invoke<TodoItem>('create_todo', { title })
+    setTodos(curr => [...curr, newTodo])
+  }, [])
+
+  // ✅ 함수형 setState로 안정적인 토글 로직
+  const toggleTodo = useCallback(async (id: string) => {
+    await invoke('toggle_todo', { id })
+    setTodos(curr =>
+      curr.map(todo =>
+        todo.id === id ? { ...todo, completed: !todo.completed } : todo
+      )
+    )
+  }, [])
+
+  // ✅ 함수형 setState로 안정적인 삭제 로직
+  const deleteTodo = useCallback(async (id: string) => {
+    await invoke('delete_todo', { id })
+    setTodos(curr => curr.filter(todo => todo.id !== id))
+  }, [])
+
+  return (
+    <div>
+      {todos.map(todo => (
+        <div key={todo.id}>
+          <input
+            type="checkbox"
+            checked={todo.completed}
+            onChange={() => toggleTodo(todo.id)}
+          />
+          {todo.title}
+          <button onClick={() => deleteTodo(todo.id)}>Delete</button>
+        </div>
+      ))}
+      <button onClick={() => addTodo('New Task')}>Add Todo</button>
+    </div>
+  )
+}
+```
+
+## 추가 컨텍스트
+
+**장점:**
+1. **안정적인 콜백 참조** - 상태 변경 시 콜백 재생성 불필요
+2. **Stale closure 없음** - 항상 최신 상태 값으로 동작
+3. **적은 의존성** - 의존성 배열 단순화
+4. **버그 방지** - React closure 버그의 가장 흔한 원인 제거
+
+**함수형 업데이트를 사용해야 하는 경우:**
+- 현재 상태 값에 의존하는 모든 setState
+- 상태가 필요한 useCallback/useMemo 내부
+- 상태를 참조하는 이벤트 핸들러
+- 상태를 업데이트하는 비동기 작업 (invoke, listen)
+
+**직접 업데이트를 사용해도 되는 경우:**
+- 정적 값으로 상태 설정: `setCount(0)`
+- props/arguments로만 상태 설정: `setName(newName)`
+- 상태가 이전 값에 의존하지 않는 경우
+
+**Tauri 이벤트 리스너에서 특히 중요:**
+- 이벤트 핸들러는 등록 시점의 상태를 클로저로 캡처
+- 함수형 setState 없이는 초기 상태만 참조 (버그)
+- cleanup 시에도 최신 상태 참조 필요
+
+**참고:** [React useState](https://react.dev/reference/react/useState)
+
+영향도: MEDIUM - 성능, 버그 방지, 콜백 안정성