frontend-ai-guide

AI 開発者ガイド — 技術的な判断基準とアンチパターン集（フロントエンド）

価値を最優先するエンジニアリング

必要なユーザー価値またはメンテナー価値を提供しながら、UI の正確性と保守性を維持できる、総合的な複雑さが最も低い解決策を証拠に基づいて特定できるまで調査します。

• 確認済みの問題は、確認済みのスコープ内、または成果に必要な依存関係の範囲内で解決します。それ以外の指摘は、担当する境界と証拠を示して報告し、現在の変更範囲を拡大しません。
• 現在の成果、確認済みの制約、または証拠に裏付けられた重大なリスクによって必要な場合に、状態、props、バリアント、抽象化、または推測に基づくエッジケース処理を導入します。
• リポジトリの証拠から、観測可能な製品スコープを拡大することなく、変更の曖昧さ、重複した責任、欠陥リスク、または将来の実装・検証コストを低減できると判断できる場合、確認済みの責任範囲内での動作を変えない保守作業も、現在のメンテナー価値として扱います。

有効化されるユーザーの判断、props、状態、バリアント、概念、出力、永続状態、コンポーネントやフックの各経路に加え、それらに伴う UX、実行時、実装、テスト、ドキュメント、保守のコストを含めて、総合的な複雑さを判断します。実行可能なアプローチ間で異なる側面のみを比較します。同じ確認済みの価値をより低い総合的な複雑さで実現できる場合は、既存の仕組みを再利用するか、新たな仕組みを導入しないことを優先します。

技術的なアンチパターン（危険信号となるパターン）

以下のパターンを検出した場合、該当する判断を保留し、設計を見直します。

コード品質に関するアンチパターン

1. 独立して保守される複数のコンポーネントで、1つの UI 責任を重複させる — 重複した動作や契約を1つの担当箇所に集約すべきか見直します
2. 1つのコンポーネントに複数の責任を混在させる — 単一責任の原則（SRP）に反します
3. 同じコンテンツを複数のコンポーネントで定義する — DRY 原則に反します
4. 依存関係を確認せずに変更する — 予期しない影響が生じる可能性があります
5. コメントでコードを無効化する — バージョン管理を使用します
6. エラーを抑制する — 問題を隠すと技術的負債が生じます
7. 保証の代わりに型アサーションを使う — チェックでも既存の契約でも確立されていない型を宣言します
8. 状態の所有者を分かりにくくする props の中継チェーン — 中間コンポーネントが値を転送するだけで、より広い範囲での所有者が明確な場合は、コンポジション、Context、またはプロジェクトの状態管理レイヤーを使用します。明示的な props によって局所的な所有関係が保たれ、責任が局所的である間に広範囲の状態管理を導入すると調整コストが増える場合は、明示的な props を維持します
9. 独立して変化する責任を混在させるコンポーネント — 描画、状態・データの所有、または再利用可能・テスト可能な動作が独立した責任を形成する場合は分割します。分割すると回避可能な props や状態の同期が増える場合は、まとまりのあるコンポーネントを維持します

設計に関するアンチパターン

• 「とりあえず動けばよい」という考え方 — 技術的負債が蓄積します
• 場当たり的な実装 — 既存のコンポーネントに計画なく追加します
• 不確かな技術を楽観的に実装する — 不明な要素を「たぶん動く」と仮定して設計します
• 症状への対処 — 根本原因を解決しない表面的な修正です
• 計画のない大規模な変更 — 段階的なアプローチを欠いています

フォールバック設計の原則

中核原則：Fail-Fast

フォールバック実装よりも、主要なコードの信頼性向上を優先する設計思想です。

フォールバック実装の基準

• フォールバックのルール：受け入れ済みの要件、境界の契約、プロジェクトのポリシー、または Design Doc で、劣化時の動作と復旧の責任者が定義されている場合にフォールバックを実装します
• レイヤーごとの責任：
  • 子コンポーネントのサブツリーにおける描画の失敗（描画中にスローするフックを含む）：プロジェクトの Error Boundary を使用します
  • イベントハンドラー、通常の非同期コールバック、SSR、描画外のフックや API の操作：それぞれのエラー契約に従い、担当するイベント、フック、API、またはサーバーの境界で処理します

過剰なフォールバックの検出

• 既存のリカバリー責任を重複または分断する catch を追加する場合は、設計レビューを必須とします。異なる障害モードに対応し、文書化されたリカバリー担当者とユーザーに見える UI 上の結果がある場合は、その catch を維持します
• 同じ障害を複数のコンポーネント／フック／API 層で捕捉し、リカバリー担当者が一元化されていない場合、またはネストされたハンドラーによってユーザーに見える UI 状態が不明瞭になる場合は、設計レビューを必須とします
• フォールバックを実装する前に、合意されたリカバリー契約を特定します
• 診断またはリカバリーを担当する境界で、既存の UI、ログ、またはメトリクスのいずれか 1 つのチャネルを通じて、フォールバックの発動を観測できるようにします。新しいチャネルの追加は、運用上の要件またはプロジェクトのポリシーで必要とされる場合に限ります

コード重複の判断基準

類似性が偶然のもの、または UI の責任範囲が異なる間は、具体的な実装を分けたままにします。リポジトリ内の証拠から、共通のインタラクション、検証ルール、視覚的な契約、または連携した変更責任が確認できる場合は、統合します。

共通化の判断基準

共通化するケース

• ビジネスロジックの重複
• 複雑な処理アルゴリズム
• コンポーネントパターン（フォームフィールド、カードなど）
• カスタムフック
• 検証ルール

共通化を避けるケース

• 偶然の一致（たまたまコードが同じ）
• 異なる方向に発展する可能性がある
• 共通化によって可読性が大幅に低下する
• テストコード内の単純なヘルパー

よくある失敗パターンと回避方法

パターン 1：エラー修正の連鎖

症状：1 つのエラーを修正すると、新たなエラーが発生します 原因：根本原因を理解せず、表面的な修正を行います 回避方法：修正前に、5 Whys で根本原因を特定します

パターン 2：型保証の回避

症状：チェックや契約で確立されていない型を any または as で宣言します 原因：型エラーを避けたいという衝動です 回避方法：宣言した型を、その保証が成り立つ境界でのチェック、または型を保証する既存の契約によって裏付けます

パターン 3：テスト不足のまま実装

症状：実装後に多くのバグが発生します 原因：Red-Green-Refactor プロセスを無視しています 回避方法：新しい動作や変更した動作、および再現可能なバグ修正では、まず失敗するテストを作成します。動作を維持するリファクタリングでは、変更前後に既存のテストまたは特性テストが成功することを確認します

パターン 4：技術的な不確実性の軽視

症状：新しい技術を導入する際に、予期しないエラーが頻繁に発生します 原因：事前に調査せず、「公式ドキュメントによれば動作するはず」と決めつけています 回避方法：

• 実装または検証の判断に影響する箇所では、確実性を記録します

  Certainty: low (Reason: new experimental feature with limited production examples)
  Exploratory implementation: true
  Fallback: use established patterns
  

• 確実性が低い場合は、まず最小限の検証コードを作成します

パターン 5：既存コードの調査不足

症状：実装の重複、アーキテクチャの不整合、統合の失敗が発生します 原因：実装前に既存コードを十分に理解していません 回避方法：

• 実装前に、ドメイン、責任範囲、コンポーネントパターンをキーワードとして、類似機能を必ず検索します
• 類似機能が見つかった場合 → その props、ライフサイクル、デザインシステムにおける役割、リポジトリ内での使用状況が参考になるかを確認します。互換性があれば再利用または拡張し、互換性がなければ有効なモデルではない理由を記録します
• 類似機能が技術的負債である場合 → 現在の成果を妨げている場合、現在の変更によって生じた場合、または確認済みの範囲に含まれる場合は修正します。それ以外は別途報告します。修正にアーキテクチャ上の決定が必要な場合は、ADR を作成します
• 類似機能が存在しない場合 → 既存の設計思想に従って新しい機能を実装します
• 再利用、拡張、分離、修正の各判断の根拠を、該当する実装記録または設計記録に残します

品質チェックワークフロー

リポジトリで設定されている品質チェックの実行入口と、それらが対象とするカテゴリを確認します。リポジトリで宣言されているパッケージ管理ツールと規約に従い、該当する根拠のチェックリストとして以下のカテゴリを使用します。

該当するチェックカテゴリ

• Lint／フォーマット — プロジェクトで設定されているフォーマッターとリンター
• 型チェック — プロジェクトで設定されている型検証
• ビルド — 設定されている本番用またはパッケージ用のビルド
• 動作チェック — 変更された動作を検証する、設定済みの最小限のテスト。さらに、変更が統合テストや E2E テストの境界を越える場合、生成されたスケルトンで必要な場合、またはリポジトリのゲートに含まれる場合は、統合テストや E2E テストのスイートも対象です

リポジトリで宣言されているコマンドの組み合わせや実行順序がある場合は、それに従います。ない場合は、コマンド間の依存関係を考慮し、有用なフィードバックを得られる順序を選択します。完了するには、該当する設定済みチェックをすべてパスする必要があります。

トラブルシューティング

• ポートがすでに使用中 — ポートを使用している古い開発／プレビュー／テストプロセスを停止します
• キャッシュが古い — プロジェクトのキャッシュをクリアするオプションを指定して再実行します
• 依存関係のエラー — 依存関係をクリーンインストールします

技術的な判断が必要な状況

抽象化のタイミング

• リポジトリの根拠から共通の UI 上の責務と連携した変更パターンが確認できた後で、共有の抽象化を切り出します
• YAGNI を意識し、現在必要な機能のみを実装します
• 将来の拡張性より、現時点でのシンプルさを優先します

パフォーマンスと可読性

• プロジェクトのパフォーマンス予算、または React DevTools Profiler による比較で、対象のインタラクションに意味のあるボトルネックが確認されない限り、可読性を優先します
• 最適化する前に、React DevTools Profiler で計測します
• 最適化する際は、その理由をコメントに記録します

コンポーネント／型定義の粒度

• コンポーネントや型を細かく分けすぎると、保守性が低下します
• UI パターンを適切に表現するコンポーネントを設計します
• 継承より合成を使用します

実装の完全性の保証

リスクに応じた影響分析手順

完了条件：3 つのステージをすべて完了します。共有コントラクト、ルーティング、状態の所有権、ビルド／設定への影響がない、独立したコンポーネントの変更では、簡潔な検索／調査メモで十分です。コンポーネントをまたぐ変更やリスクの高い変更では、構造化されたレポートを使用します。

1. 発見

変更されたコンポーネントまたはフック、そのインポート関数、および Props／State 型への参照を、リポジトリ内で漏れなく検索します。

2. 理解

以下を把握するために必要な、発見したファイルを読みます。

• 呼び出し元の目的とコンテキスト
• コンポーネント階層
• データフロー：Props → State → イベントハンドラー → コールバック

3. 特定

コンポーネントをまたぐ変更やリスクの高い変更では、構造化された影響レポートを作成します。

## Impact Analysis
### Direct Impact: ComponentA, ComponentB (with reasons)
### Indirect Impact: FeatureX, PageY (with integration paths)
### Processing Flow: Props → Render → Events → Callbacks

承認されたスコープ、利用側、状態の流れ、必要な関連変更、および該当するチェックが特定できたら、次に進みます。

未使用コードの削除ルール

依頼された変更によってコンポーネント、フック、ユーティリティ、ドキュメント、または設定項目が不要になる場合は、利用側と生成／運用での使用状況を確認したうえで削除します。不確かなクリーンアップやスコープ外のクリーンアップは保持して報告し、無関係な休眠コードは実装スコープ外とします。

既存コードの削除判断フロー

Required by the requested change? No → Preserve unless the change proves it obsolete
                               Yes → Working and compatible? Yes → Fix/extend
                                                             No → Repair or replace with migration/rollback evidence