複数の実装があるモノレポを、動きをそろえたまま直す

## 直す前に、モノレポの構成とその場所の決まりを読む - リポジトリを製品、言語、機能領域、共有ユーティリティ領域、テスト群、リリースツール、設定ごとに整理する。 - 各実装が所有するディレクトリと、リポジトリ全体に適用される最上位規則を特定する。 - 入れ子になった領域を編集する前に、その領域のエージェントガイド、貢献ガイド、設定を読む。ローカル規則は基準を具体化できるが、弱めてはならない。 - 言語固有のビルド、スタイル、テスト規則は、その言語で書かれたコードだけに適用する。 - コマンドや依存関係を選ぶ前に、ワークスペース定義、ルートスクリプト、製品固有の指示を確認する。 ## 利用者に見える変更を、全部の実装へ同じように入れる - 同じユーザー向け製品の並行実装を、対等な正本として扱う。 - 可能な限り、ユーザーに見えるすべての変更を同じ変更リクエスト内ですべての実装へ反映する。 - ユーザーに見える動作には、フラグ、既定値、環境の扱い、エラーコードとメッセージ、ツールが利用するログ、ファイルと状態の形式、保存配置、フックの意味が含まれる。 - 内部リファクタリング、実装内部だけの性能改善、実装固有のテスト整理を、不自然に他の実装へ反映する必要はない。 - 同等の作業を直ちに完了できない場合は、残る差分、その理由、変更を統合する前に必要な作業を正確に示す。 - ある実装を、別の実装から派生したことが文書化されていない移植版にしてはならない。 ## テストが古いコードを試さないよう、使う物をビルドし直す - テスト結果を信頼する前に、リポジトリで定められた初期構築手順で依存関係を導入し、コンパイルする。 - 選択したテストが利用するものと同じ成果物が生成される場合は、素早い反復中に影響を受けるパッケージだけをコンパイルする。 - エンドツーエンドテストが、ソースの生成物、パッケージの生成物、バンドル済み実行ファイルのどれを実行するか確認する。 - エンドツーエンドテストがバンドルを利用する場合、構成パッケージを変更するたびにバンドルを再構築する。そうしなければ、テストが古いコードを実行するおそれがある。 - 変更した各実装について、該当言語向けの適切なビルドを実行する。 - 古い生成物を対象に成功したテストを、有効な証拠として扱ってはならない。 ## 影響する所だけテストし、失敗を全部調べる - 既定で大規模リポジトリのテスト群全体を実行してはならない。影響を受けるプロジェクト、ファイル、または名前付きテストケースから始める。 - 依存関係、共有契約、観測された失敗が必要性を示す場合だけ、テスト範囲を広げる。 - 検証する主張に合わせて、対象の実行環境、ビルド成果物、実装を選ぶ。 - 証拠なしに無関係または以前から存在したと決めつけず、すべての失敗を調査する。 - 変更前から失敗していた場合は原因を特定し、許可された範囲で修正するか、具体的な障害を報告する。黙って省略してはならない。 - 正確なコマンド、対象、結果を記録し、別の貢献者が証拠を再現できるようにする。 ## 変更したコードを、セキュリティ、次に性能の順でレビューする - リポジトリのレビューガイドに従い、指摘を変更対象コードとその直接的な影響に限定する。 - より厳しいプロジェクト規則がない限り、セキュリティを最初、性能を次にレビューする。 - セキュリティ上の指摘では、到達可能な入力、信頼境界、悪用経路、影響を説明する。 - 性能上の指摘では、負荷の高い経路、頻度、割り当てまたはI/Oコスト、想定されるユーザー影響を示す。 - 受け入れ条件として、テスト、リリース意図、実装間の動作同等性を検証する。 - 変更された動作と結び付けられない推測上の指摘を作ってはならない。 ## コードや依存関係を足す前に、今ある物を探す - 自明でないロジックを実装する前に、共有パッケージ、ファイルシステムヘルパー、暗号ユーティリティ、テキストユーティリティ、近接する領域モジュールを検索する。 - 既存の公開ユーティリティがすでにその動作を所有している場合は再利用する。 - 類似ロジックが単一パッケージ内に閉じ込められている場合は、コピーせず、共通契約を適切な最小の共有場所へ抽出する。 - 一般的な機能には、適切で、十分に軽量で、リポジトリ方針が許可する場合、保守されている既存依存関係を優先する。 - 新しい依存関係は、それを必要とする最も限定的なパッケージに追加し、複数パッケージが本当に共有する場合だけ上位へ移す。 - 契約を追加せず、既存操作の名前を変えるか転送するだけのラッパーを追加してはならない。 ## コミットメッセージの決まりを守り、コミットのフックを飛ばさない - リポジトリ指定のコミットメッセージ規則を使い、ユーザーへの影響を表す変更種別を選ぶ。 - コミット前に、リポジトリのフックが導入済みで有効か確認する。新しい作業コピーでは登録されていない場合がある。 - 失敗するコミットガードを迂回したり、フックを無効化したり、抑制ファイルを追加したりしてはならない。根本のメッセージまたは変更を修正する。 - 数字だけの課題参照は、ホスティング基盤が誤ったリポジトリへリンクする可能性があるため避ける。リポジトリを含む参照または絶対URLを使う。 - ユーザー名に見えるコード識別子はインラインコードで囲むか、不要なメンションを取り除き、コミットによって無関係な人物へ通知しないようにする。 - 項目を列挙する場合は、参照記号を伴わないリスト番号を使う。 ## 公開済みのパッケージを変えたら、リリースの記録を足す - 公開済みパッケージに影響する変更では、必ずリリース意図の項目を追加する。 - 影響を受けるすべてのパッケージを挙げ、版への影響を不具合修正、後方互換機能、破壊的変更から選ぶ。 - 項目はユーザー向けに簡潔に書き、実装理由はコミットメッセージへ記載する。 - リポジトリ方針が求める場合、主要実装への変更には主たるコマンドラインパッケージも含める。 - 実装固有の変更では、実際に変わった製品だけを挙げる。動作同等性の変更では、影響を受けるすべての実装のパッケージを挙げる。 - 安定版と先行版のリリース経路、固定バージョングループ、正式版への昇格手順を守る。 ## コードだけでは伝わらない理由を、コメントに書く - 名前、型、ヘルパー境界、制御フローによってコード自体が意図を説明できるようにする。 - 操作を言い換えるだけのコメント、呼び出し先の文書を重複させるコメント、明白な構文を説明するコメントを追加してはならない。 - 共有する理由は、各呼び出し場所で繰り返さず、共通の所有者で一度だけ文書化する。 - 事前条件、事後条件、境界事例、明白でない保証には文書コメントを使う。 - リファクタリング履歴と廃止された設計の説明は、現在のソースコメントではなく版管理履歴と変更メッセージへ残す。 - 説明文を追加する前に、名前変更、構造変更、抽出の方が意図を確実に伝えられないか検討する。 ## リポジトリの整形とエラーの扱い方の決まりに合わせる - リポジトリの整形ツールと言語固有のスタイルガイドを使い、既存のインポート分類と順序を維持する。 - コードベースの慣例が関数を使う場合は状態を持つクラスより関数を優先し、長い引数一覧は型付きオプションオブジェクトへ置き換える。 - ユーザーが到達可能な失敗には安定した領域エラー型を使い、エラーコードと関連情報を保ち、予期しないエラーを決して握り潰さない。 - 想定したエラー条件だけを捕捉し、仮想化されたテスト環境では実行領域をまたいでも安全なネイティブエラー判定を使う。 - 関数名には動詞を使い、用語を統一し、契約が変わった概念はすべての場所で名前を変更する。 - 単純な解析には単純な文字列操作を使い、後戻りを必要とする文法には既存の構造化パーサーを使う。 - 設定可能な値は設定層を経由させ、コマンド処理を表示層から独立させ、方針を直接埋め込まない。 - 非同期I/Oを使い、独立した処理を並行実行し、必要な完了を待ち、ループ内の不変処理を外へ出す。 ## 変更リクエストを、統合まで実際の変更と合わせておく - リポジトリのテンプレートを使って変更リクエストを開始し、必須セクションを保ち、テンプレートが任意と明示する内容だけを削除する。 - 大きな更新のたびに、タイトルと説明を実際の変更と同期させる。 - 対応したレビュー会話には解決内容と根拠となる改訂を返信してから、会話を解決済みにする。 - 機密性の高い実装情報を露出させず、リポジトリ方針に従ってエージェント作成の外部コンテンツへラベルを付ける。 - リポジトリ承認済みの競合解決手順を使い、基準ブランチを最新にし、生成されたロックデータを決定的に再構築し、統合可能性を検証する。 - 自動生成物ではない競合を手作業で確認する。強制更新やその他の外部履歴の書き換えには、明示的な許可と検証済みの対象が必要となる。