typescript-rules

TypeScript 開発ルール（フロントエンド）

コメントの記述ルール

まずコードを優先します。名前と型には意味があり、コメントにはコードで表現できない情報を追加します。各判断につきコメントは1つで十分です。

• JSX が何を描画するかではなく、コンポーネントがメモ化、ガード、再レンダリングを行う理由を説明します。
• 判断とその根拠を記録し、時系列の履歴はバージョン管理に残します。

型安全性

デフォルトルール：any よりも unknown、ジェネリクス、またはユニオン型を優先します。既存の外部、生成済み、またはレガシーな公開シグネチャで必要な場合、あるいは any を置き換えると、プロジェクトの型チェックで安全なジェネリック関係を表現できなくなる場合に限り、any を維持します。その制約を裏付ける宣言のパスまたは型チェックの結果を記録します。ユーザーのリクエストまたは現在のタスク／設計成果物の範囲内で、ローカルアダプターによって互換性を維持しながら、より安全な型を公開できる場合は、そのアダプターを実装します。それ以外の場合は、any を最小限のアダプターまたは公開シグネチャの境界に限定し、理由を記録したうえで、信頼できないデータが型付きアプリケーションコードに入る前に検証します。

フロントエンドの境界

• React の Props／State：宣言済みのアプリケーション型を使用します。
• 外部 API のレスポンス：未検証のペイロードは unknown として扱い、境界で検証します。生成されたクライアントが実行時にも契約を強制する場合は、宣言済みの型を維持できます。
• localStorage ／ sessionStorage：string | null として扱います。解析済みのデータは、検証されるまで unknown として扱います。
• URL パラメーター：ルーターまたはプラットフォームの nullable な文字列形式として扱い、ドメイン型に変換する前に解析して検証します。
• エクスポートする API と重要な境界：戻り値の型を宣言します。契約が明確な場合は、ローカルの実装で型推論を利用できます。

型の複雑さを見直す際の指標

これらはレビューの観点として使い、合否のしきい値としては扱いません。既存のプロジェクトの規約とコンポーネントの責務を優先します。

• Props の数：10を超える場合は、所有関係の見直しや分割を検討します。
• オプショナルな Props：半数を超える場合は、デフォルト値や所有関係を見直します。
• ネストされた Props の構造：2階層を超える場合は、フラット化を検討します。
• 型アサーション：3つ以上必要な場合は、境界を見直します。
• 外部 API の型：実際の外部データの形状を表し、アプリケーションの境界で変換します。

コーディング規約

コンポーネントとファイルの判断

• 新しいコードでは関数コンポーネントと Hooks を優先してください。受け入れられた作業で移行が必要な場合を除き、動作しているクラスコンポーネントは維持してください。Error Boundary の実装ではクラスも引き続き有効です。
• リポジトリで確立されているコンポーネント、フック、またはモジュールのパターンを使ってロジックを再利用してください。
• プロジェクトで採用されているコンポーネントアーキテクチャとファイル構成に従ってください。ファイルの同じ場所への配置は、既に確立されている場合、または新しい構成として承認されている場合に限ってください。

サーバー／クライアントの境界 — RSC フレームワークの場合のみ

• デフォルトではサーバー上で取得とレンダリングを行い、インタラクティブ性は、それを必要とする最小の "use client" 境界内に分離してください。
• ブラウザー専用 API とイベントハンドラーは、クライアントコンポーネント内に配置してください。
• プロジェクトにサーバーコンポーネントのランタイムがない場合は、これらの規則を適用しないでください。

状態の所有者

• リポジトリで既に定められているローカル、共有、サーバー状態の所有者の境界を維持してください。
• 既存の境界では表現できない所有権またはライフサイクルが、受け入れられた設計で必要な場合にのみ、Context、共有状態レイヤー、またはサーバー状態の依存関係を導入してください。
• 各状態値の権威ある所有者は 1 つにし、React の変更検出に必要な不変更新を使用してください。

関数と Props の境界

• パラメーターは 0〜2 個を優先してください。関連する値が 3 個以上ある場合は、名前が明確になる、または 1 つのドメイン入力を表すのであればオブジェクトを使用してください。ただし、リポジトリの規約または外部 API で必要な場合は、位置引数を維持してください。
• リポジトリで確立されている状態と依存関係の境界に従い、型付き props、フック、Context、または注入されるモジュールを通じてコンポーネントの依存関係を宣言してください。

環境変数

• クライアント側の環境変数は、プロジェクトのバンドラー用アクセサーと公開プレフィックスを通じて読み取ってください。
• 必須の値はリポジトリの型付き設定レイヤーで検証してください。デフォルト値を追加するのは、オプションの値、または明示的に定義されたローカル開発モードの場合に限ってください。

クライアントのセキュリティ

• 認証情報とシークレットはサーバー上に保持してください。ブラウザーに配信されるコードと公開環境変数は、クライアントから確認できます。
• ローカル環境ファイルはバージョン管理の対象から除外し、エラー出力に機密情報が含まれないようにしてください。

非同期処理

• リポジトリの Promise スタイルに従い、処理順序とエラーの伝播が明確になる場合は async／await を使用してください。
• イベントハンドラーと非同期処理の失敗は、それらを所有する境界で処理してください。Error Boundary が対象とするのは子孫のレンダリング失敗であり、通常のコールバックや非同期処理ではありません。
• リポジトリのキャンセル機構またはサーバー状態の仕組みを通じて、副作用が引き起こすリクエストによる古い更新やアンマウント後の更新を防いでください。

フォーマット

• リポジトリのフォーマッター、命名規則、モジュール解決、およびパッケージ境界の設定に従ってください。
• インポートエイリアスは、プロジェクト設定で解決できる場合にのみ使用してください。

エラー処理

捕捉したエラーには、意図された結果を 1 つだけ持たせてください。エラーを伝播する、リポジトリの型付き境界結果に変換する、またはユーザーに表示するエラー状態として表す、のいずれかです。コンテキストを維持し、診断または復旧を担う境界で一度だけログに記録し、機密データはマスキングしてください。

• Error Boundary：子孫のレンダリング失敗から UI が復旧する方法が定義されている場所に配置してください。
• カスタムフック：アプリケーションの既存のエラー契約を維持してください。
• API レイヤー：通信の失敗を、リポジトリで確立されているドメインまたは境界の表現に変換してください。
• イベントハンドラーと非同期ワークフロー：それらを所有するレイヤーの例外、結果、または UI 状態の契約を使用してください。

パフォーマンスの最適化

• React Compiler が有効な場合は、それに任せてください。手動で React.memo、useMemo、または useCallback を追加するのは、計測でボトルネックが確認された場合、または外部 API／エフェクトとの境界で安定した識別子が必要な場合に限ります。
• 設定済みのバンドルサイズ予算を超過した場合、または受け入れ条件でバンドルサイズが成果として明示され、リポジトリのバンドルレポートで変更したインポートが関連する増加の原因と特定された場合に、コード分割やインポートの変更を適用してください。リポジトリで既に採用されている読み込みパターンに従い、変更後に同じ指標を確認してください。

非機能要件

• ブラウザー互換性：PRD、設計ドキュメント、Browserslist、またはビルド設定に記載されたサポートポリシーに従って実装してください。いずれにも定義がない場合は、リポジトリの現在のトランスパイル／ポリフィルの基準を維持し、新たに使用するブラウザー依存 API を未解決の互換性判断事項として提示してください。
• パフォーマンス：プロジェクトで定義された予算と、影響を受けるエクスペリエンスを表す指標に照らして検証してください。予算が定義されていない場合は、変更した処理経路を計測し、しきい値を独自に設けるのではなく、観測結果を報告してください。