多言語の自動化モノレポを、互換性を壊さずにAIに直させる

## 全体のルールの後に、直すファイルに近い指示を読む リポジトリ全体のルールから始め、次に変更対象ファイルに最も近い指示を読む。言語バインディング、共有基盤、ネイティブコンポーネント、リリースツールには、それぞれさらに狭い制約が定められている場合がある。 リポジトリに、コントリビューターの設定、生成物、下書き作業、分離したビルド結果を置くための追跡対象外のローカル領域がある場合は、作業開始前にそこに記載された指示の上書きを確認する。ユーザー定義のローカル指示は、現在のタスクと上位の安全ルールの範囲内で追加コンテキストとして扱う。 責務に基づいてリポジトリを把握する。 - 言語バインディングは、各言語固有のAPI、テスト、スタイルを所有する。 - 共有プロトコル、通信、ビルド、フィクスチャ、スクリプトの領域は、複数の利用側へ影響する。 - ネイティブ管理機能、グリッドやルーティングのサービス、依存関係の定義は、影響範囲が広い。 - タスクでベンダー保守が明示されていない限り、第三者のソースは読み取り専用として扱う。 - 生成結果を手作業で編集してはならない。 エンドユーザー向け文書、コントリビューター向けガイド、生成されたAPIリファレンスが同じ場所にあるとは想定しない。 ## 公開APIの互換性を保ち、元に戻せる小さな差分にする タスクで互換性の破壊が明示的に許可されていない限り、公開APIとバイナリ互換性を維持する。通常、ユーザーはバージョン番号を変えるだけでアップグレードできる状態を保つ。 リポジトリ全体のリファクタリング、書式の一括変更、無関係な整理を避ける。1つの問題を解決する、小さく元に戻せる差分を優先する。 公開動作の提供を終了する前に非推奨として明示し、分かりやすい移行先を示す。セマンティックバージョニングを採用していないことを、移行期間なしで機能を終了してよい理由にしてはならない。 履歴を保てる場合は、追跡中のファイルを作り直すより、移動またはコピーを優先する。 ユーザーが変更をすでに明示している場合を除き、高リスク領域を変更する前に確認を求める。高リスク領域には、共有プロトコルの意味、ワイヤー形式のシリアライズ、ケイパビリティ解析、依存関係の再固定、共有テストフィクスチャ、ビルド配線、ルーティング、分配キュー、複数のバインディングが利用するコードが含まれる。 ## 固定のビルドツールで、影響する最小の対象だけをビルドする 言語別のローカル開発環境が設定済みだと想定せず、リポジトリで固定されたハーメチックなビルド入口を使う。 ツリーの広い範囲を読む前にビルドグラフを調べる。対象ラベルと依存関係を照会し、変更をカバーする最小の対象だけをビルドまたはテストする。 まず標準のビルドコマンドを直接試す。サンドボックス、ネットワーク、ツールチェーンの制約で実行できない場合は、阻害要因を報告し、ユーザーが別環境で実行できる正確なコマンドを示す。 標準の結果格納先が制限されている場合や、別の作業ツリーを使っている場合は、ビルド結果を分離する。 - `output-base`の起動オプションは、build、test、queryの各コマンドより前に置く。 - どのディレクトリからでも同じ場所を解決できるよう、パスをリポジトリルートに固定する。 - 分離した結果は、追跡対象外のローカル領域に置く。 日常的なトラブル対応として破壊的なキャッシュ消去を行わない。対象を絞った再ビルドを優先し、実際にキャッシュの無効化が必要なら理由を説明する。 ## ほかの言語のバインディングと同じ動きか比べる ユーザーから見える動作を変更する場合は、少なくとも1つの別言語バインディングと実装を比較する。 特に次の項目の整合性を確認する。 - 公開メソッド名、引数、既定値、戻り値の動作。 - プロトコルコマンドとシリアライズ。 - リモート通信とエラーの対応付け。 - ケイパビリティとオプションの解析。 - 非推奨化と移行経路。 - 文書の例とユーザー向けログ。 共有される低レベル動作では、その変更を利用し得るすべてのバインディングまたはサービスを特定する。現在のタスク内ですべてを安全に更新できない場合は、必要な整合作業を報告するか、追跡可能な課題の作成を提案する。 各言語へ同一の内部構造を強制しない。共有動作を保ちながら、それぞれのバインディングで確立された慣用表現とテスト規約を尊重する。 ## モックを使わず、小さな失敗するテストから始める 動作を変更する実装の前に、失敗するテストを書くことを優先する。小さな単体テストまたは契約テストから始め、下位レベルで確実に検証できない場合だけブラウザテストやエンドツーエンドテストを使う。 公開プロトコルやバインディングの契約を誤って表す恐れがある場合は、モックを避ける。実際のパーサー、シリアライザー、ローカルフィクスチャ、軽量サーバー、既存の統合テスト基盤を優先する。 ビルドグラフを使って、関連する最小のテスト対象を選ぶ。有用な制御には次が含まれる。 - 小規模テストだけに絞る。 - デバッグ時にテスト結果をすべて表示する。 - 実際の再実行が必要な場合は、キャッシュされたテスト結果を使わない。 - 正しい対象とフラグについて、言語固有の指示を確認する。 想定したテストが実際に走ったことを確認する。一致するテストがない状態でビルドツールが正常終了しても、正しさの証明にはならない。 対象を絞ったテストが通った後は、直接影響するバインディング、共有対象、統合範囲に限って検証を広げる。 ## 役に立つログとコメントを書き、書式直しは変えた所だけにする 重要な状態、再試行、ルーティング、失敗原因をユーザーや運用担当者が把握する必要がある場所にはログを追加する。言語固有のログ規約に従い、下位レベルの診断と重複する騒がしいメッセージを避ける。 コメントには、適切に命名されたコードがすでに示す内容ではなく、制約や回避策が存在する理由を書く。 リポジトリ標準のフォーマッターを使う。pre-commitまたはpre-pushフックが関連範囲の書式をすでに処理する場合は、重複実行せずフックに任せる。 変更を処理するフックがない場合は、予定する引き渡しに合う最小範囲のフォーマッターモードを実行する。1ファイルの変更を理由にリポジトリ全体の書式を変えない。 レビュー、切り戻し、言語間の影響を理解しやすくするため、提案する各変更は1つの目的に集中させる。 ## ビルドとテストが本当に走ったか確かめ、走らなかった物も報告する 完了前に次を確認する。 1. 変更対象がハーメチックなツールチェーンでビルドできる。 2. 対象を絞ったテストを実行し、意図した動作が検証されたことを確かめる。 3. 関連する書式検査または静的検査を実行する。 4. 無関係な変更や生成結果が差分に入っていないか確認する。 5. 互換性と非推奨化への影響を確認する。 6. ユーザーから見える変更では、少なくとも1つの別言語バインディングと比較する。 7. 変更した高リスク共有領域をすべて特定する。 変更内容、実際に走った対象とテスト、実行できなかった確認、その理由を報告する。高リスクファイル、共有動作、言語間の影響、後続作業も明示する。 1つの言語バインディングのテストだけで広範な互換性を主張しない。ハーメチックなツールチェーンを利用できなかった場合は、検証が未完了であることを明示せずに完了を主張しない。