デバイス自動化ツールのコードを直し、実機で動きを確かめる

## 依頼の種類を先に分け、変更に関わるコードだけを読む まず依頼を分類する。情報提供のみのレビュー、トリアージ、質問は、編集や実行が明示的に求められていない限り読み取り専用とする。コード変更の依頼では、最小限の実装と、その対象範囲に必要な検査を行ってよい。 編集前に前提を明示し、観測可能な成功条件を定める。長期的に使われるドメイン用語、該当するアーキテクチャ上の決定、所有元となる構成または契約を読む。既定ではリポジトリ全体を読まない。 範囲を限定した検索から始める。 - 高速なテキスト検索で、シンボル、コマンド、フラグ、エラーを特定する。 - 所有元のモジュール、共有ヘルパー1つ、下流の呼び出し元またはアダプター1つを読む。 - 大きなファイルでは、該当する型や関数を探してから、範囲を限定して開く。 - 証拠が必要とする場合に限り、インポートとテストを外側へたどる。 タスクが境界をまたぐことを明示していない限り、変更を1つのコマンド系統、プラットフォーム境界、またはモジュール群の内側に保つ。両方が存在するという理由だけで2つのプラットフォーム実装を調べない。範囲を広げる必要がある場合は作業を止め、新しい境界を確認する。 コーディング前に、文書、ヘルプ、スキーマ、スキルへの影響を判断する。変化しやすいファイル一覧より、長期的に有効な正本への参照を優先する。 ## コマンドの名前とオプションを、1つのレジストリで管理する 各コマンドに、その識別情報、能力、タイムアウト方針、バッチ方針、公開用表現を所有する正規記述子を1つ用意する。デーモンまたはサービスのルーティングはルートレジストリ、操作経路の保証は型付きマトリクス、コマンド名は1つのカタログで管理する。ハンドラー内で文字列集合を再作成しない。 トップレベルのルーターは薄く保ち、オーケストレーションだけを担わせる。所有元のハンドラー系統へ振り分け、エントリーポイントにコマンドロジックを蓄積しない。能力に関する判断はその正本に置き、条件分岐を各所へ分散させない。 各公開オプションは、その内容を理解する層だけを通す。 1. 公開フラグと文法を定義する。 2. 所有元となるコマンドメタデータとスキーマへ追加する。 3. コマンド入力へ解析する。 4. ランタイム実行で必要な場合に限り、サービスリクエストへ反映する。 5. それらのインターフェースがオプションを公開する場合に限り、型付きクライアントと正規化処理を拡張する。 6. 公開契約によって所属先が証明された後に限り、ディスパッチとプラットフォームモジュールへ渡す。 7. すべての公開オプションをアーキテクチャ進捗モデルまたはカバレッジモデルで分類する。 セレクターの解析、照合、解決、述語評価を一元化する。要素を対象とする操作は、安定したセレクターまたは記録済み参照を受け入れ、そのセレクターチェーンを維持し、再実行時の不一致があればユーザー状態を黙って書き換えず提案として示す。 ## ファストパスやキャッシュの経路でも、同じ動きか確かめる 経路の境界では保証が損なわれると想定する。ファストパス、委譲パス、キャッシュパス、プラットフォーム固有パスを追加する際は、同等性を主張する前に、影響を受けるコマンドと経路の組み合わせをすべて分類する。 レジストリの登録項目は意味上の証明ではない。実装を読み、保証の定義を満たすことを確認する。エラー後にだけ委譲するフォールバックでは成功経路の同等性を証明できない。ファストパスが、共有パスなら拒否する入力を受け入れる可能性がある。 実験を測定する前に、各実験群が実行可能であることを証明する。変更した分岐が一度も実行されていなければ、2回の成功実行に意味はない。どの実装がリクエストを処理したか示すために必要な経路、バックエンド、理由コード、その他の型付き証拠を記録する。 人間向けメッセージの解析ではなく、構造化シグナルを使う。理由コード、型付き詳細、明示的なタイムアウト値で分岐し、エラー文面の嗅ぎ分けを複製しない。避けられないメッセージ照合は、判断箇所で文書化された負債として扱う。 警告は、それ以前の警告を上書きせず、共有レスポンスビルダーで合成する。ノードや項目ごとにバイト列を繰り返さず、レスポンス全体のメタデータを1回だけ保存する。 互換性フィールドを残す前に、それがリリース済みか確認する。未リリースの公開面はきれいに取り除けるが、リリース済みの公開面には移行と互換性対応が必要となる。 ## ファイルを小さく保ち、テストをソースの構成に合わせる `unknown`は、解析済み入力、ランタイムのペイロード、捕捉したエラー、汎用I/Oなどの信頼境界に限って使う。一度検証したらドメイン型または目的を絞ったパーサーへ型を狭め、不確実性を内部ヘルパーやフォーマッターまで持ち込まない。 言語の型機能によって未対応のケースを不可能にできる場合は、型レベルの網羅性検査を優先する。機械可読な主張を、それが説明するコードと同じ場所に置く。レジストリセルは強制処理への参照の隣、カバレッジマニフェストは契約テストの隣、判断理由のコメントは根拠となる分岐に置く。 各モジュールは1つの問いだけを担当する。実務上の警戒線として、実装ファイルはおよそ300行を目標にする。500行を超えたら動作を追加する前に局所性を改善する。1,000行を超えたら、生成データまたはフィクスチャのスナップショットでない限りアーキテクチャ上の負債として扱う。 ファイルは、それが答えるドメイン概念に基づいて命名する。バレルはパッケージ境界だけで使う。内部バレルは移動の手間を増やす。深い階層のモジュールは、単に行数を減らすためではなく、概念上の所有関係を改善する場合に抽出する。 テストはソースの構成を反映させる。ソースモジュールを分割する際は、同じ変更内でテストも分割する。再利用可能なフィクスチャは、大きなインラインオブジェクトを複製せず、名前を付けた同階層のフィクスチャモジュールへ置く。非公開の詳細をテストしやすくすることだけを目的に、本番コードの公開項目を追加しない。 完了前に、変更箇所と直接隣接するコードを引き締める。不要になった分岐、重複テスト、未使用のインポート、古いフィクスチャ、変更によって不要になった重複を取り除く。無関係な整理は避ける。 ## デバイスのセッションを必ず閉じ、ログと診断情報を分けて残す プロセス実行は共有プロセス抽象化を経由させる。必要な能力が欠けている場合は、コードベース全体で低レベルのプロセスプリミティブを直接インポートせず、その抽象化を拡張する。 手動で開いたデバイスセッションはすべてリソースとして扱う。そのセッション名、プラットフォーム、デバイス識別子、状態ディレクトリを記録し、失敗した実験の後でも、完了前に同じ値を使って閉じる。検証実行に属する古いプロセスのうち、対象を正確に特定できるものだけを停止する。推測で広範なプロセス群を強制終了してはならない。 アプリケーションログ、ランナー出力、リクエスト診断を区別する。アプリケーションログの収集は1つのバックエンドだけが所有する。リクエスト診断は解決済みのセッション識別子とリクエスト識別子の下に保存する。トップレベルのデーモンログは、ライフサイクルと、セッション解決前に発生した障害のために予約する。 診断スコープ、タイマー、イベント発行、伏字化、成果物パスの構築を一元化する。診断サービスがそのデータを所有する場合、ログパスを手作業で組み立てたり、その場限りのファイルを追加したりしない。 ユーザー向けの障害を、コード、簡潔なメッセージ、復旧のヒント、診断識別子、ログパス、型付き詳細を持つ安定したペイロードへ正規化する。エラーをラップする際もこれらのフィールドを保つ。何が失敗したか、分かる場合はその理由、次の復旧操作を示す。 任意のプローブ、キャッシュ検査、事前検査は、機能契約で必須とされていない限りベストエフォートとして扱う。必須操作より短いタイムアウトを設定し、失敗した場合や利用できない形式を返した場合は、確立済みの経路へフォールバックする。 ## 変わった部分に合わせて、走らせるテストを選ぶ 利用できる場合は、リポジトリの影響範囲検査プランナーから始める。このプランナーは、手書きの一覧ではなく正規メタデータから対象を絞ったテストと残りのゲートを導出するものとする。 検査を変更範囲へ対応付ける。 - 型付きソースの変更には、必ず型検査とフォーマットを行う。 - ツールチェーンまたはコンパイラー構成の変更には、ツール検証ゲートと宣言ファイルのビルドが必要となる。 - 共有サービスまたはハンドラーの変更には、対象を絞った単体テスト一式が必要となる。 - レスポンス形式またはプロバイダー境界の変更には、プロバイダー統合検査とカバレッジ検査が必要となる。 - ネイティブランナーの変更には、ネイティブテスト成果物の再ビルドが必要となる。 - クロスプラットフォーム動作には、クロスプラットフォーム統合テスト一式が必要となる。 - 文書だけの作業でランタイムテストが必要なのは、より具体的な契約がそう定める場合に限る。 対象を絞った証拠で十分な場合、既定で広範な統合テストを実行しない。反対に、デバイスに関わる変更を単体テストだけで準備完了としない。 テストは動作を検証するものにする。静的型がすでに証明している内容をアサートしない。単体テストで実時間を待ってはならない。時間枠を注入してそこから実行間隔を導出するか、時間枠が正しく渡されたことをアサートする。 強制検証ゲートが、未分類のフラグ、欠けている保証セル、未検証のシナリオ、レスポンス構築の迂回、ルール同等性の欠落を見つけた場合は、新しい動作を分類するか検証対象に含める。ゲートを抑制したり、説明のない許可リスト項目を追加したりしてはならない。 ## ビルドし直してから、実機やシミュレーターで動きを確かめる 手動検証の前に、ランタイムが実際に利用する成果物をすべて再ビルドし、ホットリロードしないサービスを再起動し、古いネイティブバイナリを提供し続ける可能性がある引き継ぎ済みランナーを無効化または交換する。古い出力を対象とするテストは偽陰性であり、製品の証拠ではない。 どのバックエンドが実行を処理したか証明する。機械可読なスナップショットまたはステータスレスポンスを取得し、バックエンド識別子とヘルパーのバージョンが現在のパッケージに一致することを確認する。黙示的なフォールバックが有効な証拠となるのは、フォールバック動作自体がテスト対象の機能である場合に限る。 分離されたデーモン状態だけでは物理的な対象が分離されないため、並行するワークツリーでは異なるデバイス、シミュレーター、エミュレーターを使う。テストアプリケーション自身のセットアップガイドに従う。アプリケーションがインストール済みであるだけでは不十分であり、ビルド、開発サーバー、画面検査によって意図したバージョンが動作していることを証明する。 製品コードをデバッグする前に環境ノイズを分類する。競合による障害を単独環境と、同じ負荷をかけた未変更のベースで再現する。失敗する対象が変動し、単独では成功するならリソース競合の可能性が高い。変更した経路で安定して失敗するなら回帰を示す証拠としてより強い。 サンドボックスによって必要なローカルリスナー、デバイスブリッジ、ネイティブツールが妨げられる場合は、その拒否を製品のバグと診断せず、承認済みの昇格経路から再実行する。ライブ検証がなお妨げられる場合は、必要なデバイス、権限、コマンド、サービスを正確に報告し、残るリスクを明示する。 ## 本番の経路をたどってレビューし、実機での結果を添えて報告する 差分だけでなく、動機となった課題と承認済みのアーキテクチャ上の決定に照らしてレビューする。コマンドの公開面からリクエストルーティングを経てプラットフォームのバックエンドに至る本番経路をたどる。ルーターを迂回するテストや重要な境界をモックするテストは、出荷される動作を証明しない。 主要な回帰テストごとに、失敗を引き起こすはずの旧実装、取り除いた箇所、または差し戻しを特定する。バグが戻ってもテストが成功したままなら、そのテストは実質的な検証になっていないため強化しなければならない。 意図したリファクタリングと、出力形式、警告の伝播、エラー詳細、成果物パス、再試行段階、フォールバックに潜む動作変更を分ける。実装が別の変更に依存する場合は、関連する変更と分岐の順序を確認する。 外部への公開またはpushは、フォーマット、型検査、lint、テストのいずれかが失敗した後には実行できないよう、単一の成功チェーンの後ろに置く。コミットとpull requestの範囲を限定し、プロジェクトで定着したタイトル形式を使い、作業が完了している場合に限り、既定でレビュー可能な状態として開く。 ユーザーから見える動作、意味のある検証、実機から得た証拠、実際のトレードオフを要約する。ローカルの単体テスト実行だけでCIが成功したとせず、現在の実機証拠なしにプラットフォーム変更をマージ可能としない。文書またはヘルプへの影響、変更範囲、未検証の経路、正確な阻害要因を示す。 引き渡し前にすべてのセッションを閉じ、検証中に開いた全リソースを確認する。後片付けできなかったセッション、プロセス、状態ディレクトリ、成果物があれば報告する。