大きなTypeScriptモノレポに、テストで確かめた小さな変更を加える

## 編集の前に、リポジトリの構成と使っているツールを調べる リポジトリの正本となるエージェントガイドを、唯一の指示源として扱う。別のエージェント入口は正本への薄い参照に保ち、アーキテクチャ、ツール、バージョン、作業手順、コントリビューター規則が変わった時は正本を更新する。 次を特定する。 - 実際のリポジトリルート、主要ソース領域、ビルドスクリプト領域、文書、テスト用アプリケーション、生成される作業空間 - 必須の基準ブランチ、実行環境のバージョン、パッケージマネージャー、タスクオーケストレーター、リンター、フォーマッター、CIが対応するOS - 外部向けエクスポートと、明示的に内部専用とされたエクスポート - パッケージ固有の型検査器、およびリポジトリ検査、エディターツール、下流API利用者の間にあるコンパイラーバージョンの違い 共有設定は、対応するすべてのコンパイラー経路で有効に保つ。最新の検査器が受理するという理由だけで、オプションや構文を採用してはならない。 モジュール式UIツールでは、実行時レンダラー、バンドルエンジン、および両者をフレームワーク設定と組み合わせる統合層を区別する。実行時に読み込む前の静的索引など、高速起動のアーキテクチャを維持する。1つの無効なユーザーモジュールが、ナビゲーション画面や管理画面全体を停止させてはならない。 ## 変更に必要なビルドとチェックだけを、小さい範囲から実行する コマンドは文書化された作業ディレクトリから実行し、タスクグラフを指定する時は配布パッケージ名ではなく、作業空間のプロジェクト名を使う。 まず、キャッシュを利用でき、依存関係を認識し、本番用ではないタスクから始める。 1. 影響を受けるプロジェクトまたはパッケージ群をコンパイルする。 2. 範囲を限定して型検査を行う。 3. 変更したファイルを整形し、静的検査を行う。 4. 最も近い関連テストを実行する。 5. 内部開発UIで動作を検証する。 テンプレート統合、本番タスクの接続、またはパッケージ間動作に変更が依存する場合だけ、本番設定、生成サンドボックス、CI同等の手順へ進む。検証済みの後半段階から意図的に再開する場合を除き、タスクの依存関係を守る。 長時間動く開発サーバーを標準動作として起動してはならない。テンプレート、対象、環境が必要なコマンドには、それらを明示的に渡す。 生成サンドボックスが失敗した場合は、ビルドアーキテクチャを変える前に、文書化された内部UIを診断用の代替経路として使う。 ## コードの種類に合うテストを選び、テストどうしが影響しないようにする 動作に合うテスト形式を選ぶ。 - 描画されるコンポーネントは、同じ場所にあるストーリーと操作関数を通して、アクセシビリティと利用者の操作を含めてテストする。 - 純粋なユーティリティ、フック、描画を伴わないモジュールには単体テストを使う。 - 外観には視覚検証ツールを使う。 - 統合契約には、エンドツーエンド、スモーク、またはランナーの各テスト群を使う。 内部実装の詳細ではなく、エクスポートされた動作と観測可能な副作用をテストする。型、静的検査規則、ストーリー操作、または上位のブラウザーテストですでに保証される内容を重複させてはならない。 ファイルシステムを扱うコードでは、実際の一時ディレクトリやモジュール全体の置き換えよりも、メモリー内ファイルシステムを優先する。各テストの前に仮想状態を初期化し、必要なファイルシステムメソッドだけを差し替え、有用な場合は仮想ディスクの状態を検証する。 テスト内で環境全体に作用するグローバル値を直接代入してはならない。テスト基盤が追跡できるグローバルスタブを使い、以前存在しなかったキーも含めてテスト後に元へ戻す。直接代入すると、ファイルの実行順に依存する状態漏れが起きる。 期待するパスは実行環境のパスユーティリティで正規化し、UnixとWindowsの両方でファイルシステム検証が通るようにする。 ## 思い込みを先に確かめ、要らない抽象化を足さない アーキテクチャの前提にする前に、小さな使い捨ての確認処理で環境上の仮定を検証する。バンドラー、メタデータ、ローダー、生成結果に関する未検証の思い込みを、恒久的なコメントや抽象化へ変えてはならない。 永続的な前提は、まず型と既存の静的検査規則で表す。静的な強制が現実的でない場合は、境界に低コストの実行時検査を追加し、違反を発生源の近くで失敗させる。 将来の柔軟性を推測して足すより、不要な仕組みを取り除き、直接的な実装を選ぶ。存在しない利用者のために抽象化、代替経路、拡張点を追加してはならない。 コメントは調査記録ではなく、保守用の文書である。長く有効な理由を1〜2文で説明し、チケットコード、確認作業の履歴、バイト比較の経緯、壊れやすい行番号参照は省く。 セキュリティに関わる経路と古い移行処理には、幅広い境界条件のテストを使う。互換コードには明確なバージョン範囲を設け、対応期間が終わった時に取り扱いを終えられるようにする。 ## 生成ファイルを勝手に変えず、決められた整形とログのツールを使う 編集後にリポジトリのフォーマッターを実行し、続いて変更ファイルの静的検査と関連テストを行う。設定済みのツールを使い、廃止済みのリンターへ置き換えたり、フォーマッターが管理するコードを手作業で整形したりしてはならない。 新しいTypeScriptスクリプトは、リポジトリの現行の正式経路から実行し、設定で求められる場合はTypeScript用の明示的なインポート拡張子を使う。旧式ローダーの移行は、今回触れる範囲だけに限定する。 通常のサーバーコードとクライアントコードでは、プロジェクトのログ抽象化を使う。生のコンソール呼び出しは、ロガーを取り込むことが不合理な独立スクリプトに限る。 意図しない生成ファイルの変更をコミットしてはならない。生成物を変更できるのは、同じ作業内の意図的なソース変更から決定的に生じた場合だけである。それ以外は触れずに残し、生成処理のずれが繰り返される場合は報告する。 パス、子プロセス、テストではUnixとWindowsの両方を考慮する。CIの複数プラットフォーム対応は任意の整理ではなく、互換性要件として扱う。 ## コンパイルが通っただけで終わらせず、動きを確かめて変更を仕上げる 通常の変更では、次の順に進める。 1. 必要な場合だけ依存関係を導入する。 2. 関連する依存関係グラフをコンパイルする。 3. 一貫性を保てる最小の編集を行う。 4. 影響を受けるパッケージを再コンパイルする。 5. 範囲を限定した型検査、整形、静的検査、契約に合うテストを行う。 6. 内部UIで検証する。 7. 直接関係する場合だけ、サンドボックスまたは本番同等の検査を追加する。 レンダラー、フレームワーク、ビルダー、プラグインの統合では、所有するパッケージを編集し、まず本番モードを使わずにコンパイルする。その後、対応する生成アプリケーションと、関連するランナーまたはエンドツーエンド手順でテストする。 ビルドが失敗した場合は、メモリー上限を増やしたりアーキテクチャを変えたりする前に、依存関係を更新して範囲限定のコンパイルを再試行する。サンドボックスの動作が内部UIと異なる場合は、生成結果とキャッシュを確認する。 コンパイルだけで準備完了を主張してはならない。必要な証拠は、変更したパッケージ境界、対応するコンパイラー経路、観測可能な動作、複数OSの前提、直接影響する統合手順を覆う最小の一式である。