create-ai-project 1.11.2 → 1.12.0

package/.claude/skills/frontend/typescript-rules/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: frontend/typescript-rules
+description: 型安全性、コンポーネント設計、状態管理、エラーハンドリングを含むReact/TypeScriptフロントエンド開発ルール。
+---
+
+# TypeScript 開発ルール（フロントエンド）
+
+## 型システム
+
+### 型安全性の原則
+- **strictモード必須**: tsconfig.jsonでstrict: trueを設定
+- **any型使用禁止**: コードベースでany型を使用しない
+- **as使用最小化**: 型キャストはやむを得ない場合のみ（理由をコメント）
+- **unknown優先**: any型が必要な場合はunknown + 型ガード
+
+```typescript
+// 良い: 型ガード付きのunknown
+function processData(data: unknown): User {
+  if (!isUser(data)) throw new Error('Invalid user data')
+  return data
+}
+
+// 悪い: any型の使用
+function processData(data: any): User {
+  return data as User
+}
+```
+
+### 型定義のベストプラクティス
+
+#### オブジェクト型
+- **interface優先**: 拡張可能なオブジェクト型にはinterfaceを使用
+- **typeはunion/intersection用**: 複合型やユーティリティ型に使用
+- **readonlyの活用**: 不変なプロパティにはreadonlyを明示
+
+```typescript
+// 良い: 明確な型定義
+interface User {
+  readonly id: string
+  name: string
+  email: string
+}
+
+type UserWithRole = User & { role: 'admin' | 'user' }
+```
+
+#### 関数型
+- **戻り値型を明示**: 複雑なロジックを持つ関数
+- **ジェネリクスの活用**: 再利用可能な型安全な関数
+
+```typescript
+// 良い: 戻り値型を明示
+function calculateTotal(items: CartItem[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0)
+}
+
+// 良い: ジェネリクスの活用
+function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
+  // implementation
+}
+```
+
+## Reactコンポーネント設計
+
+### Function Components必須
+
+```typescript
+// 良い: Function Component
+const UserCard: React.FC<UserCardProps> = ({ user, onSelect }) => {
+  return (
+    <div onClick={() => onSelect(user.id)}>
+      {user.name}
+    </div>
+  )
+}
+
+// 悪い: Class Component（非推奨）
+class UserCard extends React.Component<UserCardProps> { }
+```
+
+### Props型定義
+
+```typescript
+interface ButtonProps {
+  label: string
+  onClick: () => void
+  variant?: 'primary' | 'secondary'
+  disabled?: boolean
+}
+
+const Button: React.FC<ButtonProps> = ({
+  label,
+  onClick,
+  variant = 'primary',
+  disabled = false
+}) => {
+  // implementation
+}
+```
+
+### Children Props
+
+```typescript
+interface LayoutProps {
+  children: React.ReactNode
+  sidebar?: React.ReactNode
+}
+
+const Layout: React.FC<LayoutProps> = ({ children, sidebar }) => (
+  <div>
+    <main>{children}</main>
+    {sidebar && <aside>{sidebar}</aside>}
+  </div>
+)
+```
+
+## 状態管理
+
+### useState型定義
+
+```typescript
+// 良い: 明示的な型
+const [user, setUser] = useState<User | null>(null)
+const [items, setItems] = useState<Item[]>([])
+
+// 良い: 初期値から推論可能な場合
+const [count, setCount] = useState(0)
+```
+
+### useReducerの型安全性
+
+```typescript
+type Action =
+  | { type: 'SET_USER'; payload: User }
+  | { type: 'CLEAR_USER' }
+  | { type: 'SET_ERROR'; payload: string }
+
+interface State {
+  user: User | null
+  error: string | null
+}
+
+const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case 'SET_USER':
+      return { ...state, user: action.payload, error: null }
+    case 'CLEAR_USER':
+      return { ...state, user: null }
+    case 'SET_ERROR':
+      return { ...state, error: action.payload }
+  }
+}
+```
+
+### Custom Hooks
+
+```typescript
+interface UseUserReturn {
+  user: User | null
+  loading: boolean
+  error: Error | null
+  refetch: () => Promise<void>
+}
+
+function useUser(userId: string): UseUserReturn {
+  const [user, setUser] = useState<User | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+
+  const refetch = useCallback(async () => {
+    setLoading(true)
+    try {
+      const data = await fetchUser(userId)
+      setUser(data)
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error('Unknown error'))
+    } finally {
+      setLoading(false)
+    }
+  }, [userId])
+
+  useEffect(() => { refetch() }, [refetch])
+
+  return { user, loading, error, refetch }
+}
+```
+
+## エラーハンドリング
+
+### Error Boundary
+
+```typescript
+interface ErrorBoundaryProps {
+  children: React.ReactNode
+  fallback: React.ReactNode
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean
+}
+
+class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state = { hasError: false }
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true }
+  }
+
+  render() {
+    if (this.state.hasError) return this.props.fallback
+    return this.props.children
+  }
+}
+```
+
+### APIエラーハンドリング
+
+```typescript
+interface ApiError {
+  code: string
+  message: string
+  details?: Record<string, string>
+}
+
+function isApiError(error: unknown): error is ApiError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    'message' in error
+  )
+}
+
+async function fetchWithErrorHandling<T>(url: string): Promise<T> {
+  const response = await fetch(url)
+
+  if (!response.ok) {
+    const error: unknown = await response.json()
+    if (isApiError(error)) {
+      throw new ApiError(error.code, error.message)
+    }
+    throw new Error('Unknown API error')
+  }
+
+  return response.json() as Promise<T>
+}
+```
+
+## イベントハンドリング
+
+### イベント型
+
+```typescript
+const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+  e.preventDefault()
+  // handle click
+}
+
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  const value = e.target.value
+  // handle change
+}
+
+const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+  e.preventDefault()
+  // handle submit
+}
+```
+
+## コーディング規約
+
+### 命名規則
+- **コンポーネント**: PascalCase（例: `UserProfile`）
+- **フック**: camelCase + use接頭辞（例: `useUserData`）
+- **型/インターフェース**: PascalCase（例: `UserProps`）
+- **定数**: SCREAMING_SNAKE_CASE（例: `MAX_RETRY_COUNT`）
+- **ファイル名**: コンポーネントはPascalCase、その他はcamelCase
+
+### インポート順序
+1. React関連
+2. 外部ライブラリ
+3. 内部モジュール（絶対パス）
+4. 内部モジュール（相対パス）
+5. 型のみのインポート
+6. スタイル/アセット
+
+```typescript
+import { useState, useEffect } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { api } from '@/lib/api'
+import { formatDate } from '../utils'
+import type { User } from '@/types'
+import styles from './Component.module.css'
+```
+
+## アンチパターン
+
+### 避けるべきパターン
+
+```typescript
+// 悪い: Propsのスプレッド展開
+const Button = (props: ButtonProps) => <button {...props} />
+
+// 良い: 明示的なPropsの受け渡し
+const Button = ({ label, onClick, disabled }: ButtonProps) => (
+  <button onClick={onClick} disabled={disabled}>{label}</button>
+)
+
+// 悪い: インラインでの複雑なロジック
+{items.filter(i => i.active).map(i => <Item key={i.id} {...i} />)}
+
+// 良い: 事前に変数として抽出
+const activeItems = items.filter(item => item.active)
+{activeItems.map(item => <Item key={item.id} item={item} />)}
+```

package/.claude/skills/frontend/typescript-testing/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: frontend/typescript-testing
+description: Vitest、React Testing Library、MSWを使用したフロントエンドテストルール。カバレッジ要件、テスト設計原則、品質基準を含む。
+---
+
+# TypeScript テストルール（フロントエンド）
+
+## テストフレームワーク
+- **Vitest**: このプロジェクトではVitestを使用
+- **React Testing Library**: コンポーネントテスト用
+- **MSW (Mock Service Worker)**: APIモック用
+- テストのインポート: `import { describe, it, expect, beforeEach, vi } from 'vitest'`
+- コンポーネントテストのインポート: `import { render, screen, fireEvent } from '@testing-library/react'`
+- モックの作成: `vi.mock()` を使用
+
+## テストの基本方針
+
+### 品質要件
+- **カバレッジ**: 単体テストのカバレッジは60%以上を必須（フロントエンド標準 2025）
+- **独立性**: 各テストは他のテストに依存せず実行可能
+- **再現性**: テストは環境に依存せず、常に同じ結果を返す
+- **可読性**: テストコードも製品コードと同様の品質を維持
+
+### カバレッジ要件
+**必須**: 単体テストのカバレッジは60%以上
+**コンポーネント別目標**:
+- Atoms（Button、Text等）: 70%以上
+- Molecules（FormField等）: 65%以上
+- Organisms（Header、Footer等）: 60%以上
+- Custom Hooks: 65%以上
+- Utils: 70%以上
+
+**指標**: Statements（文）、Branches（分岐）、Functions（関数）、Lines（行）
+
+### テストの種類と範囲
+1. **単体テスト（React Testing Library）**
+   - 個々のコンポーネントや関数の動作を検証
+   - 外部依存はすべてモック化
+   - 最も数が多く、細かい粒度で実施
+   - ユーザーから観測可能な振る舞いに焦点を当てる
+
+2. **統合テスト（React Testing Library + MSW）**
+   - 複数のコンポーネントの連携を検証
+   - MSW（Mock Service Worker）でAPIをモック
+   - 実際のDB接続なし（DBはバックエンドが管理）
+   - 主要な機能フローの検証
+
+3. **E2Eテストでの機能横断検証**
+   - 新機能追加時、既存機能への影響を必ず検証
+   - Design Docの「統合ポイントマップ」で影響度「高」「中」の箇所をカバー
+   - 検証パターン: 既存機能動作 → 新機能有効化 → 既存機能の継続性確認
+   - 判定基準: 表示内容の変化なし、レンダリング時間5秒以内
+   - CI/CDでの自動実行を前提とした設計
+
+## テストの実装規約
+
+### ディレクトリ構造（Co-location原則）
+```
+src/
+└── components/
+    └── Button/
+        ├── Button.tsx
+        ├── Button.test.tsx  # コンポーネントと同じ場所に配置
+        └── index.ts
+```
+
+**理由**:
+- React Testing Libraryのベストプラクティス
+- ADR-0002 Co-location原則
+- 実装と一緒にテストを見つけやすく、保守しやすい
+
+### 命名規則
+- テストファイル: `{ComponentName}.test.tsx`
+- 統合テストファイル: `{FeatureName}.integration.test.tsx`
+- テストスイート: 対象のコンポーネントや機能を説明する名前
+- テストケース: ユーザー視点から期待される動作を説明する名前
+
+### テストコードの品質ルール
+
+**推奨: すべてのテストを常に有効に保つ**
+- メリット: テストスイートの完全性を保証
+- 実践: 問題があるテストは修正して有効化
+
+**避けるべき: test.skip()やコメントアウト**
+- 理由: テストの穴が生まれ、品質チェックが不完全になる
+- 対処: 不要なテストは完全に削除する
+
+## モックの型安全性の徹底
+
+### MSW（Mock Service Worker）セットアップ
+```typescript
+// 型安全なMSWハンドラー
+import { rest } from 'msw'
+
+const handlers = [
+  rest.get('/api/users/:id', (req, res, ctx) => {
+    return res(ctx.json({ id: '1', name: 'John' } satisfies User))
+  })
+]
+```
+
+### コンポーネントモックの型安全性
+```typescript
+// 必要な部分のみ
+type TestProps = Pick<ButtonProps, 'label' | 'onClick'>
+const mockProps: TestProps = { label: 'Click', onClick: vi.fn() }
+
+// やむを得ない場合のみ、理由明記
+const mockRouter = {
+  push: vi.fn()
+} as unknown as Router // 複雑なRouter型構造のため
+```
+
+## React Testing Libraryの基本例
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button', () => {
+  it('should call onClick when clicked', () => {
+    const onClick = vi.fn()
+    render(<Button label="Click me" onClick={onClick} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Click me' }))
+    expect(onClick).toHaveBeenCalledOnce()
+  })
+})
+```
+
+## テスト品質基準
+
+### 境界値・異常系の網羅
+正常系に加え、境界値と異常系を含める。
+```typescript
+it('renders empty state for empty array', () => {
+  render(<UserList users={[]} />)
+  expect(screen.getByText('ユーザーがいません')).toBeInTheDocument()
+})
+
+it('displays error message on API failure', async () => {
+  server.use(rest.get('/api/users', (req, res, ctx) => res(ctx.status(500))))
+  render(<UserList />)
+  expect(await screen.findByText('エラーが発生しました')).toBeInTheDocument()
+})
+```
+
+### ユーザー中心のクエリ
+
+```typescript
+// 良い: アクセシブルなクエリ
+screen.getByRole('button', { name: 'Submit' })
+screen.getByLabelText('Email')
+screen.getByText('Welcome')
+
+// 悪い: 実装詳細への依存
+screen.getByTestId('submit-btn')
+container.querySelector('.btn-primary')
+```
+
+### 非同期処理のテスト
+
+```typescript
+it('loads and displays user data', async () => {
+  render(<UserProfile userId="1" />)
+
+  // ローディング状態を確認
+  expect(screen.getByText('Loading...')).toBeInTheDocument()
+
+  // データ表示を待機
+  expect(await screen.findByText('John Doe')).toBeInTheDocument()
+
+  // ローディングが消えていることを確認
+  expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
+})
+```
+
+### フォームテスト
+
+```typescript
+it('submits form with valid data', async () => {
+  const onSubmit = vi.fn()
+  render(<LoginForm onSubmit={onSubmit} />)
+
+  await userEvent.type(screen.getByLabelText('Email'), 'test@example.com')
+  await userEvent.type(screen.getByLabelText('Password'), 'password123')
+  await userEvent.click(screen.getByRole('button', { name: 'Login' }))
+
+  expect(onSubmit).toHaveBeenCalledWith({
+    email: 'test@example.com',
+    password: 'password123'
+  })
+})
+```
+
+## アンチパターン
+
+```typescript
+// 悪い: 実装詳細のテスト
+it('calls setState', () => {
+  const setState = vi.spyOn(React, 'useState')
+  render(<Counter />)
+  // ...
+})
+
+// 良い: ユーザーが見る結果をテスト
+it('increments count when clicked', () => {
+  render(<Counter />)
+  fireEvent.click(screen.getByRole('button', { name: '+' }))
+  expect(screen.getByText('Count: 1')).toBeInTheDocument()
+})
+```

package/{docs/rules-ja/architecture/implementation-approach.md → .claude/skills/implementation-approach/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: implementation-approach
+description: メタ認知的アプローチによる実装戦略選択フレームワーク。確認レベル、統合ポイント定義を含む。
+---
+
 # 実装戦略選択フレームワーク（メタ認知的アプローチ）
 
 ## メタ認知的戦略選択プロセス
@@ -86,7 +91,7 @@
 **適用条件**: 機能間の依存が少ない、ユーザーが利用可能な形で出力、アーキテクチャ全層への変更が必要
 **確認方法**: 各機能完成時のエンドユーザー価値提供
 
-#### 水平スライス（基盤駆動）  
+#### 水平スライス（基盤駆動）
 **特徴**: アーキテクチャ層別の段階的構築
 **適用条件**: 基盤システムの安定性が重要、複数機能が共通基盤に依存、層別の段階的確認が有効
 **確認方法**: 全基盤層完成時の統合動作確認
@@ -105,7 +110,7 @@
 各タスクの完了確認における優先順位：
 
 - **L1: 機能動作確認** - エンドユーザー機能として動作（例：検索実行可能）
-- **L2: テスト動作確認** - 新規テストが追加されパス（例：型定義テスト）  
+- **L2: テスト動作確認** - 新規テストが追加されパス（例：型定義テスト）
 - **L3: ビルド成功確認** - コンパイルエラーなし（例：インターフェース定義）
 
 **優先順位**: L1 > L2 > L3 の順で確認可能性を重視
@@ -121,7 +126,7 @@
 ## アンチパターン
 
 - **パターン固執**: リスト内の戦略のみで選択し、独自の組み合わせを検討しない
-- **分析不足**: Phase 1の分析フレームワークを飛ばして戦略選択  
+- **分析不足**: Phase 1の分析フレームワークを飛ばして戦略選択
 - **リスク軽視**: Phase 3のリスク分析マトリクスを省略して実装着手
 - **制約無視**: Phase 4の制約チェックリストを確認せず戦略決定
 - **根拠省略**: Phase 6の文書化テンプレートを使用せず戦略選択
@@ -129,8 +134,8 @@
 ## メタ認知的実行のための指針
 
 1. **既知パターンの活用**: 出発点として参考し、創造的組み合わせを探索
-2. **WebSearch積極活用**: 同種技術スタックの実装事例を調査  
+2. **WebSearch積極活用**: 同種技術スタックの実装事例を調査
 3. **5 Whys適用**: 根本理由を追求し本質を把握
 4. **複数観点評価**: Phase 1-4の各観点から網羅的に評価
 5. **創造的思考**: 複数戦略の順序適用やプロジェクト固有の制約を活かした設計を検討
-6. **判断根拠明示**: 設計ドキュメントでの戦略選択根拠を明示化
+6. **判断根拠明示**: 設計ドキュメントでの戦略選択根拠を明示化