同期・非同期のクライアントライブラリを、APIを壊さずそろえて直す

## 直す前に、変えてはいけない公開の動きを洗い出す 編集前に、外部へ公開された動作、対応するランタイムのバージョン、関連するアーキテクチャ、変更対象を所有する最小限のファイル群を特定する。 - 公開シグネチャ、引数名、既定値、戻り値の型、例外、境界条件での動作を互換性の契約として扱う。 - 同期クライアントと非同期クライアントなど、同じ動作を担うすべての並行実装を探す。 - その動作に関わる可能性があるルーティング、解析、ポリシー、接続、応答整形の各層を特定する。 - パターンを選ぶ前に、近接する実装、テスト、型オーバーロードを読む。 - 依頼された変更が明示的に必要としない限り、既存のプロトコルとサーバーの意味論を維持する。 - 無関係な整理へ作業範囲を広げない。 依頼された動作が文書化済みの不変条件と矛盾する場合、契約を暗黙に再定義せず、作業を止めて矛盾を明示する。 ## 同期と非同期のクライアントに、同じ変更を入れる ライブラリが同等のクライアントスタックを提供している場合、両者の同等性を必須要件として扱う。 1. 変更する同期側のシンボルを非同期側の対応要素へ、またはその逆方向に対応付ける。 2. シグネチャ、オーバーロード、型ヒント、既定値、戻り値の形、エラー、副作用を比較する。 3. 文書化されたランタイム差異によって不可能な場合を除き、両方のスタックへ同等の動作を適用する。 4. 共有コマンドの公開面、ルーティング表、パーサーのコールバック、ポリシーのメタデータを一致させる。 5. 両方のスタックがその動作を公開している場合は、対応するテストを追加する。 コードベースで確立された型構文とオーバーロード規約を使う。一方だけを変更すべき場合は、具体的なアーキテクチャ上の理由を記録し、その非対称性が意図されたものか検証する。 ## 受け持つ層だけを直し、今あるヘルパーを使い回す 既存のヘルパーと規約を再利用する、対象を絞った変更を優先する。 - その動作を所有する層だけを変更する。 - 公開APIとエラーの意味論を維持する。 - 既存の仕組みで要件を満たせない場合を除き、新しい依存関係を加えない。 - 現在のヘルパーやパターンで十分な場合は、新しい抽象化を導入しない。 - 遅延インポートが技術的に必要な場合を除き、インポートは最小限にしてモジュールスコープへ置く。 - 動作を変更したらドキュメント文字列も更新し、型との整合を保つ。 正確性を最優先する。最適化は動作が正しいと確認した後に限り、割り当て量の削減や実行速度の向上と引き換えに正確性を損なってはならない。 ## よく通る処理を遅くせず、プロトコルの動きも変えない 高頻度で通る処理の変更について、回避できる割り当て、解析の繰り返し、処理の重複、大きな一時データ構造がないか確認する。 - 確立されたヘルパーとキャッシュ済みメタデータを再利用する。 - 通信プロトコルの選択を、利用者向けの応答整形とは独立して維持する。 - ルーティングと集約のポリシーをコマンドの意味論と一致させる。 - 関連する場合は、リダイレクト、再試行、トポロジーの差異、エラー伝播を明示的に扱う。 - 基盤サービスが区別して示す境界条件を、暗黙に正規化しない。 性能変更でも、外部から観測できる動作を同一に保たなければならない。最適化によって正確性や同等性が複雑になる場合は、より単純で正しい実装を選ぶ。 ## 失敗するテスト1つから、全マトリクスまで広げてテストする 範囲を段階的に広げて根拠を積み上げる。 1. 修正前には失敗する、決定論的なテストを追加または更新する。 2. 関連する最小のテストまたはテストスイートを実行する。 3. ミラー構成の同期・非同期カバレッジを実行する。 4. 意味のあるプロトコル、応答モード、トポロジー、任意機能の組み合わせを確認する。 5. プロジェクトが求めるリンター、フォーマット確認、型検査を実行する。 6. 変更が共有動作へ影響し得る場合は、対応対象の全テストマトリクスを実行する。 テストスイートを通すことだけを目的に、アサーションを弱めたり、カバレッジを対象から外したり、失敗の分類を変えたりしてはならない。外部インフラを必要とするテストは、既定のローカルスイートから明確に分離しておく。 ## 最後の差分で、デバッグコードと同期・非同期のずれを探す 完了前に変更全体を確認し、次を検証する。 - 関連するファイルと行だけが変更されている。 - デバッグコード、意図しないロジックの欠落、無関係なフォーマット変更が残っていない。 - 明示的な意図がない限り、公開APIとエラー動作が変わっていない。 - ミラー実装と型ヒントの整合が保たれている。 - テストが成功経路、境界条件、失敗経路を網羅している。 - リンターと必要なテストスイートが合格している。 - ドキュメントが実装済みの動作と一致している。 - 不要な依存関係、割り当て、抽象化が導入されていない。 見つかった問題はすべて直し、影響する確認を繰り返す。変更内容、検証内容、明示的に未確認の外部シナリオを報告し、実施範囲を超える検証を行ったとは述べない。