大きな型付きモノレポを、AIに壊さず直させる

## 直す前に、変更を受け持つパッケージを見つける リポジトリのルートから確認を始め、要求された動作を所有するパッケージを特定します。 - コアライブラリ、フレームワーク統合、デプロイ可能なアプリケーション、サンプル、内部ツールを区別します。 - ルートのガイドと最も近いパッケージ単位のガイドを読みます。パッケージの動作には、より具体的なガイドを適用します。 - 開発コマンドを実行する前に、固定されたランタイム、パッケージマネージャー、ワークスペース構成、前提となるビルドを確認します。 - ルートに開発サーバーが存在すると決めつけないでください。所有元のパッケージを起動するか、その上流依存関係を含むワークスペースフィルターを使います。 - コンシューマーを変更する前に、共有型、ユーティリティ、スタイル、生成済みアセットを正本となるパッケージまでたどります。 - 公開契約が実際に複数パッケージへ及ぶ場合を除き、変更はそれを所有する最小のパッケージ内に留めます。 ## ビルドと依存関係の決まりを守る 1つのツールをワークスペース全体に押しつけず、パッケージに合ったビルド経路を選びます。 - 純粋な型付きライブラリにはコンパイラー中心のビルドを、UIパッケージにはコンポーネント用バンドラーを使います。 - ライブラリの成果物では依存関係を外部化します。成果物にランタイム依存関係を同梱しなければならない場合に限り、明示的なスタンドアロンビルドを使います。 - 内部依存関係にはワークスペースプロトコルを使い、共有するサードパーティー製品のバージョンは中央のバージョンカタログから取得します。 - 共有型は広範なパッケージルートではなく、文書化されたエントリーポイントからインポートします。 - パッケージが複数の形式を公開する場合は、宣言された各成果物とその型宣言を検証します。 - ビルド構成、ロックファイル、共有コンパイラー設定、ワークスペースカタログは、広い検証を必要とする影響範囲の大きいファイルとして扱います。 ## 新しいコードを書く前に、共有ユーティリティを使い回す 新しいユーティリティを書く前に、共有ヘルパーパッケージを検索します。 配列、オブジェクト、文字列、URL、HTTP、JSON、Markdown、エラー、ファイル、キュー、書式設定、正規表現、テスト用の既存ヘルパーを確認します。適したヘルパーはそのまま再利用します。既存の動作に合うものがなく、複数のコンシューマーが新しい抽象化を利用できる場合に限り、新しいヘルパーを共有パッケージへ追加します。 機能パッケージにほぼ同じ実装を作らないでください。既存の動作が近いものの完全には一致しない場合は、拡張するか、ドメイン固有のローカル関数として維持するかを決める前に、契約、境界事例、バンドルへの影響、呼び出し元を比較します。 ## `any`を使わず、関数とコンポーネントのpropsに型を付ける 推論を有用に保ちながら、公開契約を明示するコードを書きます。 - コードベースの標準がそう定めている場合は、インターフェースや列挙型よりも型エイリアスと文字列リテラルのユニオンを優先します。 - 関数には戻り値の型を明示し、`any`ではなく`unknown`を使い、型専用インポートを指定し、原則として不変の束縛を使います。 - インポートは直接行います。意図されたパッケージエントリーポイントを除いてバレルファイルを避け、ワイルドカードによる再エクスポートも避けます。 - 型エラーを包括的に抑制してはいけません。エラーが意図的であることを証明する理由がある場合に限り、予期済みエラーのディレクティブを使います。 - すべてのPromiseを処理し、待機する処理がない関数を非同期として指定しないでください。 - コンポーネントファイルでは、プロパティとイベントに型を付け、デフォルト値を分割代入し、複雑なテンプレートロジックを算出値へ移し、既定のセットアップ順序に従います。 - コメントとAPIドキュメントには、コードを言い換えるのではなく、制約が存在する理由を書きます。 ## 全体ではなく、影響するパッケージからテストする 変更を証明できる最小範囲のテストを実行します。 1. 単体テストはソースの隣に配置し、最上位のテストスイートにはファイルに対応する名前を付けます。 2. 動作に対するアサーションと純粋関数を優先します。モックは最小限にし、ユーザー動作が契約である場合は、マークアップ構造やスタイルの詳細をテストしないでください。 3. 明示的なパスフィルターを指定し、影響を受けるパッケージを1回実行します。監視モードは開発作業中に限って使います。 4. 変更したアダプターには統合テストを、影響を受けるユーザー動線にはエンドツーエンドテストを実行します。 5. 必要なローカルテストサービスを起動し、サービスに依存するテストの前に準備完了を待ちます。単体テストから実ネットワークを使ってはいけません。 6. モノレポ全体のテストスイートは、意図的な最終統合確認または広範な共有契約の変更に限って実行します。 変更と無関係な既存の失敗は分けて扱います。変更範囲の外で再現し、その事実を報告し、環境の成功や変更が原因の失敗と誤って表現しないでください。 ## 変更したファイルにlint、影響するパッケージに型チェックをかける 変更ファイルの集合を特定し、各ツールが担当する構文だけに適用します。 - 変更した型付き言語のファイルに、その言語用のリンターとフォーマッターを実行します。 - 変更したコンポーネント、ドキュメント、データ、スタイル、構成ファイルに、コンポーネント用リンターと汎用フォーマッターを実行します。 - 影響を受けるすべてのパッケージを、各ワークスペーススクリプトで型検査します。 - レビューを作成または更新する前に、未使用のエクスポート、ファイル、依存関係をスキャンします。 - 関連するlint、format、型、テスト、未使用コードの各検査がすべて問題なく通ることを必須とします。 パッケージフィルターのほうが無関係なノイズを減らして強い根拠を得られる場合は、リポジトリ全体を対象とするコマンドを使わないでください。基盤構成が変わった場合、または依存関係の分析で複数の下流コンシューマーが示された場合は、検証範囲を広げます。 ## レビューのタイトルをtype(scope)の形で書き、changesetを足す 専用ブランチを使い、関連するパッケージのスコープを含む、慣例に沿った現在形の変更説明を書きます。 - レビューのタイトルは、許可された変更種別を使い、`type(scope): subject`というセマンティック形式にします。 - チケットと課題への参照は、適切な終了用または非終了用キーワードとともにレビュー説明へ記載します。必須の追跡識別子をコメント内に埋もれさせないでください。 - 追跡リンクが提供されている場合は、専用のチケット節を追加します。 - 公開可能なパッケージ、統合、アプリケーションを変更した場合は、リリースノートの状態を確認し、バージョンを上げるべきときはpatchまたはminorのchangesetを追加します。通常の作業手順でmajor更新を導入してはいけません。 - 一時的な回避策はTODOで見える状態に保ち、取り除く条件を説明します。 - lint、型、テスト、未使用エクスポートに既知の失敗がある変更をコミットしてはいけません。 ## UIの変更が見えるプレイグラウンドで、スクリーンショットを撮って確かめる 上流パッケージをビルドしてから、変更した動作を最も直接的に確認できるプレイグラウンドを選びます。 - 基本コントロールにはコンポーネントカタログ、レンダリングとナビゲーションにはドキュメント画面、編集、認証、リクエスト、レスポンスにはクライアント画面を使います。 - 共有コンポーネント、テーマ、構文レンダリング、アイコンが複数の製品へ反映される場合は、副次的な画面も確認します。 - 変更したUIには変更前後のスクリーンショット、新しい動作には利用状況が分かるスクリーンショット、操作には短い録画を残します。 - 成果物には内容が分かる名前を付け、レビュー説明の専用ビジュアル節に証拠を埋め込みます。 - 変更が複数の画面やレイアウトに影響する場合は、1枚のスクリーンショットを普遍的な証明とみなさず、実質的に異なる結果をそれぞれ記録します。 視覚的な成果物は自動テストを補足するものであり、動作アサーション、アクセシビリティ検査、型検証の代わりにはなりません。 ## プロジェクトの用語をそろえ、実際に通した確認だけを報告する コード、ドキュメント、テスト、レビュー文書では、プロジェクトの用語集を一貫して使います。プロトコル形式とAPI記述、データスキーマとドキュメント、参照解除と解決をそれぞれ区別し、バンドルも後者の2つの処理とは別のものとして扱います。 完了前に、次を行います。 - 最終差分をレビューし、変更したすべてのファイルが意図した範囲に属することを確認します。 - 該当するビルド、テスト、lint、format、型、未使用コードスキャン、視覚的証拠を検証します。 - パッケージのエントリーポイント、依存関係カタログ、changesetが実装と一致していることを確認します。 - 実行できなかった検査を列挙し、その正確な失敗証拠を保持します。 - パッケージ範囲の検査しか実行していない場合は、モノレポ全体の結果だと主張しないでください。 影響を受けたパッケージ、実行したコマンド、直接得られた結果、残存リスク、意図的に延期した作業を報告します。