create-ai-project 1.11.2

package/docs/rules-ja/coding-standards.md

@@ -0,0 +1,333 @@
+# 普遍的コーディング規約
+
+## 技術的アンチパターン（赤信号パターン）
+
+以下のパターンを検出したら即座に停止し、設計を見直すこと：
+
+### コード品質のアンチパターン
+1. **同じようなコードを3回以上書いた** - Rule of Threeに違反
+2. **単一ファイルに複数の責務が混在** - 単一責任原則（SRP）違反
+3. **同じ内容を複数ファイルで定義** - DRY原則違反
+4. **依存関係を確認せずに変更** - 予期しない影響の可能性
+5. **コメントアウトでコード無効化** - バージョン管理を活用すべき
+6. **エラーの握りつぶし** - 問題の隠蔽は技術的負債
+7. **型アサーション（as）の多用** - 型安全性の放棄
+
+### 設計のアンチパターン
+- **「一旦動くように」という思考** - 技術的負債の蓄積
+- **継ぎ足し実装** - 既存コードへの無計画な追加
+- **不確実技術の楽観的実装** - 未知要素を「たぶん動く」前提で設計
+- **対処療法的修正** - 根本原因を解決しない表面的な修正
+- **無計画な大規模変更** - 段階的アプローチの欠如
+
+## 基本原則
+
+✅ **積極的なリファクタリング** - 技術的負債を防ぎ、健全性を維持
+❌ **使われない「念のため」のコード** - YAGNI原則（Kent Beck）に反する
+
+## コメント記述ルール
+- **機能説明重視**: コードが「何をするか」を記述
+- **履歴情報禁止**: 開発履歴は記載しない
+- **タイムレス**: いつ読んでも有効な内容のみ記述
+- **簡潔性**: 必要最小限の説明にとどめる
+
+## エラーハンドリングの基本原則
+
+### Fail-Fast原則
+エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ。エラーの握りつぶしは禁止。
+
+詳細な実装方法（Result型、カスタムエラークラス、層別エラー処理など）は各言語・フレームワークのルールを参照。
+
+## Rule of Three - コード重複の判断基準
+
+Martin Fowler「Refactoring」に基づく重複コードの扱い方：
+
+| 重複回数 | 対応 | 理由 |
+|---------|------|------|
+| 1回目 | インライン実装 | 将来の変化が予測できない |
+| 2回目 | 将来の統合を意識 | パターンが見え始める |
+| 3回目 | 共通化実施 | パターンが確立された |
+
+### 共通化の判断基準
+
+**共通化すべきケース**
+- ビジネスロジックの重複
+- 複雑な処理アルゴリズム
+- 一括変更が必要になる可能性が高い箇所
+- バリデーションルール
+
+**共通化を避けるべきケース**
+- 偶然の一致（たまたま同じコード）
+- 将来異なる方向に進化する可能性
+- 共通化により可読性が著しく低下
+- テストコード内の簡単なヘルパー
+
+### 実装例
+```typescript
+// ❌ 1回目の重複で即共通化
+function validateUserEmail(email: string) { /* ... */ }
+function validateContactEmail(email: string) { /* ... */ }
+
+// ✅ 3回目で共通化
+function validateEmail(email: string, context: 'user' | 'contact' | 'admin') { /* ... */ }
+```
+
+## よくある失敗パターンと回避方法
+
+### パターン1: エラー修正の連鎖
+**症状**: エラーを修正すると新しいエラーが発生
+**原因**: 根本原因を理解せずに表面的な修正
+**回避方法**: 5 Whysで根本原因を特定してから修正
+
+### パターン2: 型安全性の放棄
+**症状**: any型やasの多用
+**原因**: 型エラーを回避したい衝動
+**回避方法**: unknown型と型ガードで安全に処理
+
+### パターン3: テスト不足での実装
+**症状**: 実装後にバグ多発
+**原因**: Red-Green-Refactorプロセスの無視
+**回避方法**: 必ず失敗するテストから開始
+
+### パターン4: 技術的不確実性の無視
+**症状**: 新技術導入時の想定外エラー多発
+**原因**: 事前調査なしで「公式ドキュメント通りなら動くはず」
+**回避方法**: 
+- タスクファイル冒頭に確実性評価を記載
+  ```
+  確実性: low（理由: MCP接続の実例がない）
+  探索的実装: true
+  フォールバック: 従来APIを使用
+  ```
+- 確実性lowの場合、最初に最小限の動作確認コードを作成
+- 動作確認できたら本実装、できなければフォールバック実行
+
+### パターン5: 既存コード調査不足
+**症状**: 重複実装、アーキテクチャ不整合、結合時の障害
+**原因**: 実装前の既存コード理解不足
+**回避方法**: 
+- 実装前に類似機能の存在を必ず検索（同じドメイン、責務、設定パターンをキーワードに）
+- 類似機能を発見 → その実装を使用する（新規実装は行わない）
+- 類似機能が技術的負債 → ADRで改善提案を作成してから実装
+- 類似機能が存在しない → 既存の設計思想に沿って新規実装
+- すべての判断と根拠をDesign Docの「既存コードベース分析」セクションに記録
+
+## デバッグ手法
+
+### 1. エラー分析手順
+1. エラーメッセージ（最初の行）を正確に読む
+2. スタックトレースの最初と最後に注目
+3. 自分のコードが現れる最初の行を特定
+
+### 2. 5 Whys - 根本原因分析
+```
+症状: TypeScriptのビルドエラー
+Why1: 型定義が一致しない → Why2: インターフェースが更新された
+Why3: 依存関係の変更 → Why4: パッケージ更新の影響
+Why5: 破壊的変更を含むメジャーバージョンアップ
+根本原因: package.jsonでのバージョン指定が不適切
+```
+
+### 3. 最小再現コード
+問題を切り分けるため、最小限のコードで再現を試みる：
+- 関連のない部分を削除
+- モックで外部依存を置き換え
+- 問題が再現する最小構成を作成
+
+### 4. デバッグログ出力
+```typescript
+console.log('DEBUG:', {
+  context: 'user-creation',
+  input: { email, name },
+  state: currentState,
+  timestamp: new Date().toISOString()
+})
+```
+
+## 型安全性の基礎
+
+**型安全の原則**: `unknown`型と型ガードを使用する。`any`型は型チェックを無効化し、実行時エラーの原因となる。
+
+**any型の代替手段（優先順位順）**
+1. **unknown型 + 型ガード**: 外部入力の検証に使用
+2. **ジェネリクス**: 型の柔軟性が必要な場合
+3. **ユニオン型・インターセクション型**: 複数の型の組み合わせ
+4. **型アサーション（最終手段）**: 型が確実な場合のみ
+
+**型ガードの実装パターン**
+```typescript
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
+}
+```
+
+**モダンな型機能の活用**
+- **satisfies演算子**: `const config = { port: 3000 } satisfies Config` - 型推論維持
+- **const assertion**: `const ROUTES = { HOME: '/' } as const satisfies Routes` - 不変かつ型安全
+- **ブランド型**: `type UserId = string & { __brand: 'UserId' }` - 意味を区別
+- **テンプレートリテラル型**: `type Endpoint = \`\${HttpMethod} \${Route}\`` - 文字列パターンを型で表現
+
+**型の複雑性管理**
+- フィールド数: 20個まで（超えたら責務で分割、外部API型は例外）
+- オプショナル率: 30%まで（超えたら必須/任意で分離）
+- ネスト深さ: 3階層まで（超えたらフラット化）
+- 型アサーション: 3回以上使用したら設計見直し
+- **外部API型の扱い**: 制約を緩和し、実態に合わせて定義（内部では適切に変換）
+
+## リファクタリング手法
+
+**基本方針**
+- 小さなステップ: 段階的改善により、常に動作する状態を維持
+- 安全な変更: 一度に変更する範囲を最小限に抑制
+- 動作保証: 既存の動作を変えないことを確認しながら進める
+
+**実施手順**: 現状把握 → 段階的変更 → 動作確認 → 最終検証
+
+**優先順位**: 重複コード削除 > 長大な関数分割 > 複雑な条件分岐簡素化 > 型安全性向上
+
+## 技術的判断が必要な場面
+
+### 抽象化のタイミング
+- 具体的な実装を3回書いてからパターンを抽出
+- YAGNIを意識し、現在必要な機能のみ実装
+- 将来の拡張性より現在のシンプルさを優先
+
+### パフォーマンス vs 可読性
+- 明確なボトルネックがない限り可読性を優先
+- 計測してから最適化（推測するな、計測せよ）
+- 最適化する場合はコメントで理由を明記
+
+### 型定義の粒度
+- 過度に細かい型は保守性を低下させる
+- ドメインを適切に表現する型を設計
+- ユーティリティ型を活用して重複を削減
+
+## 継続的改善のマインドセット
+
+- **謙虚**: 完璧なコードは存在しない、フィードバック歓迎
+- **勇気**: 必要なリファクタリングは大胆に実行
+- **透明性**: 技術的な判断理由を明確に記録
+
+## 実装作業の完全性担保
+
+### 影響範囲調査の必須手順
+
+**完了定義**: 以下3段階すべての完了
+
+#### 1. 検索（Discovery）
+```bash
+Grep -n "TargetClass\|TargetMethod" -o content
+Grep -n "DependencyClass" -o content
+Grep -n "targetData\|SetData\|UpdateData" -o content
+```
+
+#### 2. 読解（Understanding）
+**必須**: 発見した全ファイルを読み込み、作業に必要な部分をコンテキストに含める：
+- 呼び出し元の目的と文脈
+- 依存関係の方向
+- データフロー: 生成→変更→参照
+
+#### 3. 特定（Identification）
+影響範囲の構造化報告（必須）：
+```
+## 影響範囲分析
+### 直接影響: ClassA、ClassB（理由明記）
+### 間接影響: SystemX、PrefabY（連携経路明記）
+### 処理フロー: 入力→処理1→処理2→出力
+```
+
+**重要**: 検索のみで完了とせず、3段階すべてを実行すること
+
+### 未使用コード削除ルール
+
+未使用コード検出時 → 使用予定？
+- Yes → 即実装（保留禁止）
+- No → 即削除（Git履歴に残る）
+
+対象: コード・ドキュメント・設定ファイル
+
+### 既存コード削除判断フロー
+
+```
+使用中？ No → 即削除（Git履歴に残る）
+      Yes → 動作？ No → 削除+再実装
+                  Yes → 修正
+```
+
+## Red-Green-Refactorプロセス（テストファースト開発）
+
+**推奨原則**: コード変更は必ずテストから始める
+
+**背景**:
+- 変更前の動作を保証し、リグレッションを防止
+- 期待する動作を明確化してから実装
+- リファクタリング時の安全性を確保
+
+**開発ステップ**:
+1. **Red**: 期待する動作のテストを書く（失敗する）
+2. **Green**: 最小限の実装でテストを通す
+3. **Refactor**: テストが通る状態を維持しながらコード改善
+
+**NGケース（テストファースト不要）**:
+- 純粋な設定ファイル変更（.env、config等）
+- ドキュメントのみの更新（README、コメント等）
+- 緊急本番障害対応（ただし事後テスト必須）
+
+## テスト設計原則
+
+### テストケースの構造
+- テストは「準備（Arrange）」「実行（Act）」「検証（Assert）」の3段階で構成
+- 各テストの目的が明確に分かる命名
+- 1つのテストケースでは1つの振る舞いのみを検証
+
+### テストデータ管理
+- テストデータは専用ディレクトリで管理
+- 環境変数はテスト用の値を定義
+- 機密情報は必ずモック化
+- テストデータは最小限に保ち、テストケースの検証目的に直接関連するデータのみ使用
+
+### モックとスタブの使用方針
+
+✅ **推奨: 単体テストでの外部依存モック化**
+- メリット: テストの独立性と再現性を確保
+- 実践: DB、API、ファイルシステム等の外部依存をモック化
+
+❌ **避けるべき: 単体テストでの実際の外部接続**
+- 理由: テスト速度が遅くなり、環境依存の問題が発生するため
+
+### テスト失敗時の対応判断基準
+
+**テストを修正**: 間違った期待値、存在しない機能参照、実装詳細への依存、テストのためだけの実装
+**実装を修正**: 妥当な仕様、ビジネスロジック、重要なエッジケース
+**判断に迷ったら**: ユーザーに確認
+
+## テストヘルパーの活用ルール
+
+### 基本原則
+テストヘルパーは、テストコードの重複を減らし、保守性を高めるために活用します。
+
+### 判断基準
+| モックの特性 | 対応方針 |
+|-------------|---------|
+| **単純で安定** | 共通ヘルパーに集約 |
+| **複雑または変更頻度高** | 個別実装 |
+| **3箇所以上で重複** | 共通化を検討 |
+| **テスト固有ロジック** | 個別実装 |
+
+## テストの粒度原則
+
+### 原則：観測可能な振る舞いのみ
+**テスト対象**：公開API、戻り値、例外、外部呼び出し、永続化された状態
+**テスト対象外**：privateメソッド、内部状態、アルゴリズム詳細
+
+```typescript
+// ✅ 振る舞いをテスト
+expect(calculatePrice(100, 0.1)).toBe(110)
+
+// ❌ 実装詳細をテスト
+expect((calculator as any).taxRate).toBe(0.1)
+```
+
+## 継続性テストの範囲
+
+新機能追加時の既存機能への影響確認に限定。長時間運用・負荷テストはインフラ層の責務のため対象外。

package/docs/rules-ja/documentation-criteria.md

@@ -0,0 +1,180 @@
+# ドキュメント作成基準
+
+## 作成判定マトリクス
+
+| 条件 | 必要ドキュメント | 作成順序 |
+|-----|--------------|---------|
+| 新機能追加 | PRD → [ADR] → Design Doc → 作業計画書 | PRD承認後 |
+| ADR条件該当（下記参照） | ADR → Design Doc → 作業計画書 | 即座に開始 |
+| 6ファイル以上 | ADR → Design Doc → 作業計画書（必須） | 即座に開始 |
+| 3-5ファイル | Design Doc → 作業計画書（推奨） | 即座に開始 |
+| 1-2ファイル | なし | 直接実装 |
+
+## ADR作成条件（いずれか該当で必須）
+
+### 1. 型システム変更
+- **3階層以上のネスト型追加**: `type A = { b: { c: { d: T } } }`
+  - 判断理由: 深いネストは複雑性が高く、影響範囲が広い
+- **3箇所以上で使用される型の変更・削除**
+  - 判断理由: 複数箇所への影響は慎重な判断が必要
+- **型の責務変更**（例: DTO→Entity）
+  - 判断理由: 概念モデルの変更は設計思想に関わる
+
+### 2. データフロー変更
+- **保存場所変更**（DB→ファイル、メモリ→キャッシュ）
+- **3ステップ以上の処理順序変更**
+  - 例: 「入力→検証→保存」から「入力→保存→非同期検証」
+- **データ受け渡し方法変更**（props→Context、直接参照→イベント）
+
+### 3. アーキテクチャ変更
+- レイヤー追加・責務変更・コンポーネント再配置
+
+### 4. 外部依存変更
+- ライブラリ・フレームワーク・外部API導入・置換
+
+### 5. 複雑な実装ロジック（規模に関わらず）
+- 3つ以上の状態を管理
+- 5つ以上の非同期処理の連携
+
+## 各ドキュメントの詳細定義
+
+### PRD（Product Requirements Document）
+
+**目的**: ビジネス要件とユーザー価値を定義
+
+**含むもの**:
+- ビジネス要件とユーザー価値
+- 成功指標とKPI（測定可能な形式）
+- ユーザーストーリーとユースケース
+- MoSCoW法による優先順位（Must/Should/Could/Won't）
+- MVPとFutureフェーズの分離
+- ユーザージャーニー図（必須）
+- スコープ境界図（必須）
+
+**含まないもの**:
+- 技術実装詳細（→Design Doc）
+- 技術選定理由（→ADR）
+- **実装フェーズ**（→作業計画書）
+- **タスク分解**（→作業計画書）
+
+### ADR（Architecture Decision Record）
+
+**目的**: 技術的決定の理由と背景を記録
+
+**含むもの**:
+- 決定事項（何を選択したか）
+- 根拠（なぜその選択をしたか）
+- 選択肢の比較（最低3案）とトレードオフ
+- アーキテクチャへの影響
+- 実装への原則的な指針（例:「依存性注入を使用」）
+
+**含まないもの**:
+- 実装スケジュール、期間（→作業計画書）
+- 実装手順の詳細（→Design Doc）
+- 具体的なコード例（→Design Doc）
+- 担当者の割り当て（→作業計画書）
+
+### Design Document
+
+**目的**: 技術的実装方法を詳細定義
+
+**含むもの**:
+- **既存コードベース分析**（必須）
+  - 実装パスマッピング（既存と新規の両方を記載）
+  - 統合点の明確化（新規実装でも既存との接続点を記載）
+- 技術的実装アプローチ（垂直/水平/ハイブリッド）
+- **技術的依存関係と実装制約**（実装の必要順序）
+- インターフェース定義と型定義
+- データフローとコンポーネント設計
+- **統合ポイントでのE2E確認手順**
+- **受入条件（EARS形式: When/While/If-then/無印）**
+- 変更影響マップ（直接影響/間接影響/波及なしを明記）
+- 統合点の完全な列挙
+- データ契約の明確化
+- **合意事項チェックリスト**（関係者との合意内容）
+- **前提となるADR**（共通ADR含む）
+
+**必須構造要素**:
+```yaml
+変更影響マップ:
+  変更対象: [コンポーネント/機能]
+  直接影響: [ファイル/関数]
+  間接影響: [データ形式/処理時間]
+  波及なし: [影響を受けない機能]
+
+インターフェース変更マトリクス:
+  既存: [メソッド名]
+  新規: [メソッド名]
+  変換必要性: [あり/なし]
+  互換性確保: [方法]
+```
+
+**含まないもの**:
+- なぜその技術を選んだか（→ADR参照）
+- いつ実装するか、期間（→作業計画書）
+- 誰が実装するか（→作業計画書）
+
+### 作業計画書
+
+**目的**: 実装タスクの管理と進捗追跡
+
+**含むもの**:
+- **フェーズ構成**（Design Docの技術的依存関係を基に作成）
+- タスク分解と依存関係（最大2階層まで）
+- スケジュールと期間見積もり
+- **Design DocのE2E確認手順を各フェーズに配置**
+- **最終フェーズに品質保証を含む**（必須）
+- 進捗記録（チェックボックス形式）
+
+**含まないもの**:
+- 技術的な根拠（→ADR）
+- 設計の詳細（→Design Doc）
+- 技術的依存関係の決定（→Design Doc）
+
+**タスク完了定義の3要素**:
+1. **実装完了**: コードが動作する
+2. **品質完了**: テスト・型チェック・リントがパス
+3. **統合完了**: 他コンポーネントとの連携確認
+
+## 作成プロセス
+
+1. **問題分析**: 変更規模判定、ADR条件確認
+2. **ADR選択肢検討**（ADR時のみ）: 3案以上比較、トレードオフ明記
+3. **作成**: テンプレート使用、測定可能な条件記載
+4. **承認**: レビュー後「Accepted」で実装可
+
+## 保存場所
+
+| ドキュメント | パス | 命名規則 | テンプレート |
+|------------|-----|---------|------------|
+| PRD | `docs/prd/` | `[機能名]-prd.md` | `template-ja.md` |
+| ADR | `docs/adr/` | `ADR-[4桁]-[タイトル].md` | `template-ja.md` |
+| Design Doc | `docs/design/` | `[機能名]-design.md` | `template-ja.md` |
+| 作業計画書 | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | `template-ja.md` |
+
+※作業計画書は`.gitignore`で除外
+
+## ADRステータス
+`Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`
+
+## AI自動化ルール
+- 5ファイル以上: ADR作成提案
+- 型・データフロー変更検出: ADR必須化
+- 既存ADR確認してから実装
+
+## 図表作成要件
+
+各ドキュメントで必須の図表（mermaid記法使用）：
+
+| ドキュメント | 必須図表 | 目的 |
+|------------|---------|-----|
+| PRD | ユーザージャーニー図、スコープ境界図 | ユーザー体験と範囲の明確化 |
+| ADR | 選択肢比較図（必要時） | トレードオフの視覚化 |
+| Design Doc | アーキテクチャ図、データフロー図 | 技術構造の理解 |
+| 作業計画書 | フェーズ構成図、タスク依存関係図 | 実装順序の明確化 |
+
+## 共通ADRとの関係性
+1. **作成時**: 共通技術領域（ログ、エラーハンドリング、非同期処理等）を特定し、既存共通ADRを参照
+2. **不足時**: 必要な共通ADRが存在しない場合は作成を検討
+3. **Design Doc**: 「前提となるADR」セクションで共通ADRを明記
+4. **準拠確認**: 設計が共通ADRの決定事項と整合しているかを検証

package/docs/rules-ja/frontend/technical-spec.md

@@ -0,0 +1,143 @@
+# 技術設計ルール（フロントエンド）
+
+## 技術スタックの基本方針
+TypeScriptベースのReactアプリケーション実装。アーキテクチャパターンはプロジェクトの要件と規模に応じて選択する。
+
+## 環境変数管理とセキュリティ
+
+### 環境変数管理
+- **ビルドツールの環境変数システムを使用**: `process.env`はブラウザ環境で動作しない
+- 設定レイヤーを通じて環境変数を一元管理
+- TypeScriptによる適切な型安全性の実装
+- デフォルト値設定と必須チェックの適切な実装
+
+```typescript
+// ✅ ビルドツールの環境変数（公開値のみ）
+const config = {
+  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
+  appName: import.meta.env.APP_NAME || 'My App'
+}
+
+// ❌ フロントエンドでは動作しない
+const apiUrl = process.env.API_URL
+```
+
+### セキュリティ（クライアントサイド制約）
+- **重要**: すべてのフロントエンドコードは公開され、ブラウザで見える
+- **クライアントサイドに秘密情報を保存しない**: APIキー、トークン、シークレットを環境変数に含めない
+- `.env`ファイルをGitに含めない（バックエンドと同様）
+- 機密情報のログ出力を禁止（パスワード、トークン、個人情報）
+- エラーメッセージに機密情報を含めない
+
+**秘密情報の正しい取り扱い**:
+```typescript
+// ❌ セキュリティリスク: APIキーがブラウザで露出
+const apiKey = import.meta.env.VITE_API_KEY
+const response = await fetch(`https://api.example.com/data?key=${apiKey}`)
+
+// ✅ 正しい: バックエンドが秘密情報を管理、フロントエンドはプロキシ経由でアクセス
+const response = await fetch('/api/data') // バックエンドがAPIキー認証を処理
+```
+
+## アーキテクチャ設計
+
+### フロントエンドアーキテクチャパターン
+選択したプロジェクトパターンを厳格に遵守。プロジェクト固有の詳細は`docs/rules/architecture/`を参照。
+
+**Reactコンポーネントアーキテクチャ**:
+- **Function Components**: 必須、class componentsは非推奨
+- **Custom Hooks**: ロジック再利用と依存性注入のため
+- **コンポーネント階層**: Atoms → Molecules → Organisms → Templates → Pages
+- **Props-driven**: コンポーネントは必要なすべてのデータをPropsで受け取る
+- **Co-location**: テスト、スタイル、関連ファイルをコンポーネントと同じ場所に配置
+
+**状態管理パターン**:
+- **Local State**: コンポーネント固有の状態には`useState`
+- **Context API**: コンポーネントツリー全体で状態を共有（テーマ、認証等）
+- **Custom Hooks**: 状態ロジックと副作用をカプセル化
+- **Server State**: APIデータのキャッシュにはReact QueryまたはSWR
+
+## データフロー統一原則
+
+### クライアントサイドのデータフロー
+Reactアプリケーション全体で一貫したデータフローを維持：
+
+- **Single Source of Truth**: 各状態には1つの権威あるソースがある
+  - UI状態: コンポーネントStateまたはContext
+  - サーバーデータ: React Query/SWRでキャッシュされたAPIレスポンス
+  - フォームデータ: React Hook Formを使ったControlled Components
+
+- **単方向フロー**: データはPropsを通じて上から下へ流れる
+  ```
+  APIレスポンス → State → Props → Render → UI
+  ユーザー入力 → イベントハンドラ → State更新 → 再レンダリング
+  ```
+
+- **Immutable Updates**: State更新には不変パターンを使用
+  ```typescript
+  // ✅ 不変なState更新
+  setUsers(prev => [...prev, newUser])
+
+  // ❌ 可変なState更新
+  users.push(newUser)
+  setUsers(users)
+  ```
+
+### データフローにおける型安全性
+- **Frontend → Backend**: Props/State（型保証済み） → APIリクエスト（シリアライゼーション）
+- **Backend → Frontend**: APIレスポンス（`unknown`） → 型ガード → State（型保証済み）
+
+```typescript
+// ✅ 型安全なデータフロー
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`)
+  const data: unknown = await response.json()
+
+  if (!isUser(data)) {
+    throw new Error('Invalid user data')
+  }
+
+  return data // User型として保証
+}
+```
+
+## ビルドとテスト
+package.jsonの`packageManager`フィールドに応じた実行コマンドを使用すること。
+
+### ビルドコマンド
+- `dev` - 開発サーバー
+- `build` - 本番ビルド
+- `preview` - 本番ビルドのプレビュー
+- `type-check` - 型チェック（出力なし）
+
+### テストコマンド
+- `test` - テスト実行
+- `test:coverage` - カバレッジ付きテスト実行
+- `test:coverage:fresh` - カバレッジ付きテスト実行（キャッシュクリア）
+- `test:safe` - 安全なテスト実行（自動クリーンアップ付き）
+- `cleanup:processes` - Vitestプロセスのクリーンアップ
+
+### 品質チェック要件
+実装完了時に品質チェックは必須：
+
+**Phase 1-3: 基本チェック**
+- `check` - Biome（lint + format）
+- `build` - TypeScriptビルド
+
+**Phase 4-5: テストと最終確認**
+- `test` - テスト実行
+- `test:coverage:fresh` - カバレッジ測定
+- `check:all` - 全体統合チェック
+
+### カバレッジ要件
+- **必須**: 単体テストのカバレッジは60%以上
+- **コンポーネント別目標**:
+  - Atoms: 70%以上
+  - Molecules: 65%以上
+  - Organisms: 60%以上
+  - Custom Hooks: 65%以上
+  - Utils: 70%以上
+
+### 非機能要件
+- **ブラウザ互換性**: Chrome/Firefox/Safari/Edge（最新2バージョン）
+- **レンダリング時間**: 主要ページで5秒以内