Vue Best Practices Workflow

このスキルを指示セットとして使用してください。ユーザーが明示的に異なる順序を求めない限り、ワークフローに従って実行してください。

コア原則

• 状態を予測可能に保つ: 単一の情報源、他はすべて導出する。
• データフローを明示的にする: ほとんどの場合、Props down、Events up。
• 小さく焦点を絞ったコンポーネントを優先する: テスト、再利用、保守が容易。
• 不要な再レンダリングを避ける: computed プロパティと watchers を賢く使用する。
• 可読性が重要: 明確で自己説明的なコードを書く。

1) コーディング前にアーキテクチャを確認する（必須）

• デフォルトスタック: Vue 3 + Composition API + <script setup lang="ts">。
• プロジェクトが明示的に Options API を使用している場合、利用可能なら vue-options-api-best-practices スキルを読み込みます。
• プロジェクトが明示的に JSX を使用している場合、利用可能なら vue-jsx-best-practices スキルを読み込みます。

1.1 必読のコア参考資料（必須）

• Vue タスクを実装する前に、以下のコア参考資料を必ず読んで適用してください:
  • references/reactivity.md
  • references/sfc.md
  • references/component-data-flow.md
  • references/composables.md
• これらの参考資料を、特定の問題が現れた時だけでなく、タスク全体を通じて積極的に作業中のコンテキストに保持してください。

1.2 コーディング前にコンポーネント境界を計画する（必須）

重大な機能の場合、実装前に簡単なコンポーネントマップを作成してください。

• 各コンポーネントの単一責任を 1 文で定義します。
• エントリ/ルートおよびルートレベルのビューコンポーネントをデフォルトで合成サーフェスとして保ちます。
• タスクが意図的に小さい単一ファイルデモの場合を除き、機能 UI と機能ロジックをエントリ/ルート/ビューコンポーネント外に移動します。
• マップ内の各子コンポーネントの props/emits コントラクトを定義します。
• 複数のコンポーネントを追加する場合、機能フォルダレイアウト（components/<feature>/..., composables/use<Feature>.ts）を優先します。

2) 本質的な Vue の基礎を適用する（必須）

これらは本質的で必須の基礎です。セクション 1.1 で既に読み込んだコア参考資料を使用して、すべての Vue タスクでこれらをすべて適用します。

リアクティビティ

• セクション 1.1 の必読参考資料: reactivity
• ソース状態を最小限に保ち（ref/reactive）、可能なすべてを computed で導出します。
• 必要に応じて、副作用には watchers を使用します。
• テンプレートで高コストなロジックの再計算を避けてください。

SFC 構造とテンプレートの安全性

• セクション 1.1 の必読参考資料: sfc
• SFC セクションをこの順序で保ちます: <script> → <template> → <style>。
• SFC の責任を焦点を絞って保ちます。大きなコンポーネントは分割します。
• テンプレートを宣言的に保ちます。分岐/導出をスクリプトに移動します。
• Vue テンプレートの安全ルール（v-html、リストレンダリング、条件付きレンダリングの選択肢）を適用します。

コンポーネントを焦点を絞って保つ

コンポーネントが 複数の明確な責任を持つ場合（例：データ オーケストレーション + UI、または複数の独立した UI セクション）は分割します。

• 1 つの「メガコンポーネント」よりも 小さいコンポーネント + composables を優先します
• UI セクション を子コンポーネントに移動します（props in、events out）。
• 状態/副作用 を composables に移動します（useXxx()）。

客観的な分割トリガーを適用します。いずれかの 条件が真の場合、コンポーネントを分割します:

• オーケストレーション/状態と複数のセクション用の実質的なプレゼンテーションマークアップの両方を所有している。
• 3 つ以上の明確な UI セクションがある（例：フォーム、フィルター、リスト、フッター/ステータス）。
• テンプレートブロックが繰り返されているか、再利用可能になる可能性がある（アイテム行、カード、リストエントリ）。

エントリ/ルートおよびルートビュールール:

• エントリ/ルートおよびルートビューコンポーネントを細く保ちます: アプリシェル/レイアウト、プロバイダー配線、および機能の合成。
• それらの機能が独立した部分を含む場合、エントリ/ルート/ビューコンポーネントに完全な機能実装を配置しないでください。
• CRUD/リスト機能（todo、テーブル、カタログ、インボックス）の場合、少なくとも以下に分割します:
  • 機能コンテナコンポーネント
  • 入力/フォームコンポーネント
  • リスト（および/または アイテム）コンポーネント
  • フッター/アクションまたはフィルター/ステータスコンポーネント
• 単一ファイル実装は非常に小さい一時的なデモの場合のみ許可します。選択された場合、分割が不要な理由を明示的に正当化してください。

コンポーネントデータフロー

• セクション 1.1 の必読参考資料: component-data-flow
• Props down、Events up を主要モデルとして使用します。
• 真の双方向コンポーネントコントラクトにのみ v-model を使用します。
• ディープツリー依存関係または共有コンテキストにのみ provide/inject を使用します。
• 必要に応じて defineProps、defineEmits、および InjectionKey でコントラクトを明示的で型付けされたものにしておきます。

Composables

• セクション 1.1 の必読参考資料: composables
• ロジックが再利用される、ステートフル、または副作用の多い場合は composables に抽出します。
• composable API を小さく、型付けされ、予測可能に保ちます。
• 機能ロジックをプレゼンテーションコンポーネントから分離します。

3) 要件が要求する場合のみオプション機能を検討する

3.1 標準的なオプション機能

デフォルトではこれらを追加しないでください。要件が存在する場合のみ一致する参考資料を読み込みます。

• Slots: 親が子のコンテンツ/レイアウトを制御する必要がある -> component-slots
• Fallthrough attributes: ラッパー/ベースコンポーネントが attrs/events を安全に転送する必要がある -> component-fallthrough-attrs
• ビルトインコンポーネント <KeepAlive> ステートフルなビュー キャッシング用 -> component-keep-alive
• ビルトインコンポーネント <Teleport> オーバーレイ/ポータル用 -> component-teleport
• ビルトインコンポーネント <Suspense> 非同期サブツリーフォールバック境界用 -> component-suspense
• アニメーション関連機能: 必須のモーション動作に最も適した最もシンプルなアプローチを選択します。
  • ビルトインコンポーネント <Transition> enter/leave エフェクト用 -> transition
  • ビルトインコンポーネント <TransitionGroup> アニメーション付きリスト変異用 -> transition-group
  • enter/leave 以外のエフェクト用クラスベースアニメーション -> animation-class-based-technique
  • ユーザー入力駆動アニメーション用ステート駆動アニメーション -> animation-state-driven-technique

3.2 あまり一般的でないオプション機能

明示的な製品または技術的ニーズがある場合のみこれらを使用します。

• Directives: 動作は DOM 固有であり、composable/コンポーネントフィットが悪い -> directives
• 非同期コンポーネント: 重い/めったに使用されない UI を遅延ロードすべき -> component-async
• レンダー関数はテンプレートが要件を表現できない場合のみ -> render-functions
• 動作がアプリ全体でインストールされる必要がある場合はプラグイン -> plugins
• 状態管理パターン: アプリ全体の共有状態が機能境界を越える -> state-management

4) 動作が正しい後にパフォーマンス最適化を実行する

パフォーマンス作業は機能後のパスです。コア動作が実装および確認されるまで最適化しないでください。

• 大規模リストレンダリングのボトルネック -> perf-virtualize-large-lists
• 静的サブツリーが不要に再レンダリングされている -> perf-v-once-v-memo-directives
• ホットリストパスでの過剰な抽象化 -> perf-avoid-component-abstraction-in-lists
• 高コストな更新がしばしばトリガーされている -> updated-hook-performance

5) 完了前の最終的なセルフチェック

• コア動作が機能し、要件に一致する。
• すべての必読参考資料が読まれ適用されている。
• リアクティビティモデルは最小限で予測可能である。
• SFC 構造とテンプレートルールが従われている。
• コンポーネントは焦点を絞っており、よく因数分解されており、必要に応じて分割している。
• エントリ/ルートおよびルートビューコンポーネントは、明示的な小デモ例外がない限り合成サーフェスのままである。
• コンポーネント分割の決定は明示的で防御可能である（責任境界は明確である）。
• データフローコントラクトは明示的で型付けされている。
• Composables は再利用/複雑性が正当化する場合に使用されている。
• 該当する場合、状態/副作用を composables に移動している。
• オプション機能は要件がそれを要求する場合のみ使用されている。
• パフォーマンス変更は機能が完了した後にのみ適用された。