大きなリポジトリで、AIにコードを読んでから直させ、レビューを通してだけ変更を出させる

## 最初に全体のルール、次に作業するフォルダのガイドを読む ルート文書には絶対方針とルーティングだけを置き、各領域の詳細なワークフローはスコープ別ガイドに任せる。サブツリー内で作業する前に、そのツリーを管轄するガイドを読むこと。 ### ルールの種類ごとに置き場所を一つに決める 絶対方針、横断的な境界線、どのガイドが何を管轄するかはルートに置く。タスク固有の手順は、それが対象とするコードのそばにあるスコープ別ガイドに置く。同じワークフローを2箇所に書いて内容がずれる状態を作らない。 ### コードの参照はリポジトリの流儀に従う ファイルを引用する際は、絶対パスやホームディレクトリからのパスではなく、リポジトリ相対パスで示す。そうすることで、誰が読んでも同じ意味になる。 ## 自分で作る前に、使える既存のライブラリやツールを探す 独自のシステム・機能・ツール・連携・自動化を提案または構築する前に、それをすでに十分な水準で解決している既存のライブラリ・プラグイン・無料プラットフォームがないか、軽く確認する。 ### 実績のある選択肢を優先する 既存の選択肢で十分なら、それを使う。独自構築をするのは、代替案が不適切・高コスト・保守されていない・安全でない・規約に反する場合、またはユーザーが明示的に独自構築を求めた場合に限る。 ### 確認は軽く済ませる これは簡単な事前チェックであり、本格的な調査業務ではない。ユーザーが費用を承認していない限り、有料サービスを勧めない。 ## 差分だけでなく、呼び出し元やテストまで読んでレビューする 修正・トリアージ・レビューには、目に見える変更からの推測ではなく、実際に読み込んだ上での高い確信度が必要になる。差分だけを見るレビューでは不十分。 ### 結論を出す前に対象範囲全体を読む 「良い」「悪い」「最善の修正」「十分な検証」と言う前に、変更された関数・モジュール全体に加え、その呼び出し元・呼び出し先、同系統の実装、隣接するテスト、スコープ別ドキュメント、依存先の契約まで読む。 ### 小さな根拠マップを作る 変更対象、そのエントリーポイント、所有境界、少なくとも1つの呼び出し元と呼び出し先、同じ不変条件を共有する同系統の対象、既存テスト、現在リリースされている挙動を明示する。どれか欠けていたら、結論を出さずに欠けている点を伝える。 ### 異論が出たら、反論する前にまず読む 結論に疑問が呈されたら、まず未確認だった経路を確認する。実際に見るまでは、以前の結論を擁護しない。 ## ライブラリは本物のソースを読み、外部APIは実際に試す 挙動がライブラリや外部サービスに依存する場合は、記憶・ラッパー・生成されたスキーマ・他のエージェントの報告ではなく、実物に対して検証する。 ### 依存先自体のソースを読む 依存関係が絡む挙動については、上流のソースコード・ドキュメント・型定義を直接読み、何を確認したかを示す。大半の依存関係はオープンソースなので、デフォルト値・エラー・タイミングを推測で済ませる理由はない。 ### 外部サービスは実際にテストする 外部APIに関わる作業には、実際のテストと最新の裏付けが必要。記憶だけでAPIについて断言しない。可能な限り実環境で検証し、その過程で機密情報を出力しない。 ## 動くだけの修正ではなく、一番良い修正かを見きわめる レビューの結論は、その変更がたまたま動くだけのものではなく最善の修正かどうかを判断するものでなければならない。結論を出す前に、所有境界・呼び出し元・同系統の対象・テスト・現在の挙動を比較する。 ### 片側だけの修正には同系統への裏付けが必要 ある対象だけを修正し、同系統の他の対象に触れない場合は、それらが影響を受けないことの裏付けか、それらをカバーする明示的なフォローアップが必要。 ### 好みを指摘事項として扱わない 変更されたコードがスコープ別ガイドに従っており、ユーザーに見える影響・実行時の問題・セキュリティリスク・保守上のリスクがない場合、単なるリポジトリ方針の好みを指摘事項として挙げない。 ## 設定の読み方を1つにし、古いキーは捨てずに移す 実行時には、設定とデータの現在の正規の形式だけを読み込む。古いキーや不正な形式のキーへの黙示的な互換性は存在しない。 ### 古いパスは削除する 明示的にリリース済みの契約やタグ付きのアップグレードパスが示されていない限り、正規パスを一本化し古いパスは削除する。2つ目のパスを残したリファクタリングは、大抵の場合失敗している。 ### 移行はしても、黙って捨てない 変更によって既存の設定が無効になる場合は、専用の移行・修復ステップに対応する移行処理を追加する。キーを黙って削除してはいけない。削除されたキーは隠れた挙動変化になるため。 ### 設定面は最小限に保つ 設定・環境変数の面には高いハードルを設ける。オプションを追加する前に、既存の挙動では解決できないことを証明し、オプションの削除・統合を優先する。文書化されたセットアップ手順は互換性に敏感なものとして扱い、既存のスニペットを壊すよりも追加型のフラグを優先する。 ## モジュール固有の処理は、共有コードでなくそのモジュールに置く 共有コード・コアコードは汎用的なままにし、所有者固有の挙動は所有モジュール内に置く。境界を越えるのは文書化された公開の接点を通じてのみとし、他のモジュールの内部に直接手を伸ばさない。 ### 責務はラップせず、移動させる 標準的な修正のあり方は、最小限のパッチではなく、ロジックを正しい所有者に移し、古い抽象化・重複したポリシー・使われなくなった分岐を削除する、境界の明確なクリーンなリファクタリングである。 ### 正しさは必須だが、過剰設計にはしない 実際の入力や状態に対する正しさは必須だが、想像上の入力に対する余分なレイヤーやガードは、厳密さではなく欠陥である。ありそうにないエッジケースを実際のシンプルさと引き換えにする場合は、それが見落としではなく意図的な判断であるとわかるよう、そのトレードオフを明示する。 ## 実行中の状態を、別ファイルに散らさず決まった保存先に置く 実行時の状態はプロジェクトの正規のストアに保持する。本来ストアが持つべき状態・キャッシュ・キュー・インデックス・作業用データを、サイドカーファイルとして散らばらせない。 ### 古い形式の扱いは移行処理が担う レガシーなファイルストアや廃止された形式の正規化は、実行前の移行処理・修復処理でのみ行う。定常状態の実行時にフォールバック先を読み込むことは絶対にない。 ### スキーマバージョンを独断で上げない 古い読み取り側が対応できないスキーマバージョンの変更には、事前にユーザーとの明示的な協議と承認が必要であり、自律的に進めてはいけない。古いビルドでも問題なく扱える純粋な追加変更であれば、バージョンを上げる必要はない。 ## 一度調べた情報を、リクエストのたびに調べ直さず使い回す ホットパスは、リクエストのたびに情報を再取得するのではなく、あらかじめ解決済みの情報を引き継いで運ぶべきである。 ### 一度解決したら使い回す 識別子、解決済みのパス、機能に関する情報は先へと渡し、準備済みのオブジェクトを使い回す。リクエスト時に繰り返し発生する探索処理を、キャッシュをあちこちに散らして解決しようとしない。正規の情報をより早い段階に移し、重複した参照処理を削除する。 ### ループ内で最新性のポーリングをしない インストール情報・マニフェスト・解決済みパスのようにプロセス内で安定しているメタデータは、再起動や明示的なリロード時にしか変化しない。そのため、ホットパスが再読み込みや再ハッシュ化によって最新性を確認し直してはいけない。プロセスローカルなキャッシュは、ライフサイクルが管理され範囲が限定されている場合に限り許容される。 ## 厳密な型で、短く読みやすいコードを書く 厳密な型チェックを常に有効にし、コードを誠実に保つ。目指すのは最小の差分ではなく、小さく明快なコードである。 ### 境界には型を付け、分岐は閉じる 何でも受け入れる動的な型は避け、実体のある型と用途を絞ったアダプターを使う。外部からの入力はスキーマで検証する。自由形式の文字列や特別な値ではなく、判別可能なユニオン型や閉じた結果コードで分岐させ、あり得ない状態をそもそも表現できないようにする。 ### 読みやすさを重視した構造にする 入れ子になったピラミッド構造よりも早期リターンを優先し、処理を「収集」「正規化」「判断」「実行」に分ける。呼び出し箇所は退屈なくらいシンプルに保つ。複雑な判断はその上流で行い、引数は名前・リテラル・単純な参照にとどめる。 ### 自明でない点にコメントを付ける 自明でない不変条件、順序に関する制約、所有境界、後片付けの結びつきについては、インラインコメントを付ける価値がある。その分岐がなぜ存在し、削除すると何が壊れるかを1〜3行で書く。構文をそのままなぞる説明はしない。 ## リファクタリングでコードが長くなったら、削るか理由を説明する リファクタリングは、追加する分と同じくらいの局所的な複雑さを削除するべきである。本番コードの行数が増えることは、当然のこととして受け入れるものではなく、正当化が必要な悪臭である。 ### 完了前にサイズを確認する 小さくないリファクタリングを完了させる前に、変更の規模を比較する。テスト以外のコードが増えていたら、削るか、経路が減ったのになぜ行数が増えたのかをはっきり説明する。 ### 新しく作る要素には見合った働きをさせる 新しいヘルパーやファイルは、追加した時点で呼び出し経路・概念・重複ロジックを実際に減らすものでなければならない。1回限りの互換性対応、フィールド名の変更、憶測に基づく耐障害性のためだけに追加しない。公開インターフェースは狭く保ち、実用上必要最小限の形を返す。 ## 文言ではなく動きをテストし、テストどうしを独立させる テストは挙動を証明し、リグレッションを防ぐためのものであり、内部のあらゆる分岐を網羅するためのチェック項目ではない。 ### 文言ではなく挙動をテストする ドキュメントやポリシー文字列をgrepで探すようなテストより、挙動そのものをテストすることを優先する。運用者向けの注意事項はテストのアサーションではなくドキュメントに書く。新しいテストは取り込む前にレビューし、価値の低いテスト(たった今削除した経路のテストを含む)は削除する。 ### テストは独立させ、誠実に保つ タイマー・環境変数・グローバル変数・モック・一時的な状態は後片付けする。モックは、同一性チェックで使われるエラー型も含め、実際のコードが触れるすべてのバインディングをエクスポートしなければならない。承認を得ずに、チェックを黙らせるためだけにベースラインファイルやスナップショットファイルを編集しない。 ### 実データはコピーの上でテストする 現実的なデータが重要になる場合は、状態を作業用の場所にコピーし、そのコピーに対してテストする。明示的な承認なしに、稼働中のサービスの状態をその場で直接変更してはいけない。 ## 信頼できないコードは手元で動かさず、重いビルドはリモート実行環境に送る どこまで検証するかを決める前に、まずソースの信頼度を分類する。検証をどこで実行するかも、その信頼度に応じて決める。 ### 信頼できないコードをローカルで実行しない 信頼できるソースであれば、依存関係が整っている場合に限り、絞り込んだ少数のテストや軽量な静的チェックをローカルで実行してよい。信頼できないコードや外部から提供されたコードは、検証の規模にかかわらず、それ自身のスクリプト・テスト・フック・設定をローカルで一切実行しない。代わりに、隔離され認証情報を持たない実行環境を使う。 ### 重い処理はリモート実行環境に送る フルスイート・ビルド・型チェック・パッケージング・クロスプラットフォームの検証は、リモート実行環境で行う。リモート実行環境は最初の重い処理が必要になった時点で確保し、1セッションの間使い回し、引き渡し前に解放する。リモート実行環境が使えない場合、信頼できる作業はローカルにフォールバックしてよいが、信頼できない作業は決してフォールバックしない。 ### 最新のレビューを取り込みの関門にする 取り込む前に、対応が必要な指摘がなくなるまで最新の自動レビューを実行する。変更範囲が些細である場合やユーザーが明示的に不要とした場合を除き、継続的インテグレーションが通っているというだけで取り込まない。検証が行えない場合は、何が足りず、なぜ足りないのかを正確に伝える。 ## 決まった手順でissueやプルリクエストを出し、リリースは承認を取る 共有部分を変更することは社会的な行為である。プロジェクトのコントリビューションプロセスに従い、取り返しのつかないステップはすべて承認を得る。 ### レビューとマージのプロセスに従う 何かを開く前に、コントリビューションガイド、issueとプルリクエストのテンプレート、コードオーナーファイルを読む。バグ、ユーザー向け機能、アーキテクチャに関する判断については、まずissueを立てる。プルリクエストの本文には、問題・影響・根拠をきちんと書き、変更を加える前にプラットフォーム自体のツールを通じて現在の状態を確認する。 ### 頼まれていない取り返しのつかないことはしない 頼まれていないのに、ラベル付け・タイトル変更・リベース・取り込みを行わない。公開コメントは、ユーザーが明示的に投稿を求めない限り、まず下書きとして見せる。投稿済みのコメントにはすべてリンクを明示する。issueやプルリクエストの作業を終える際は、その項目の完全なURLを添える。 ### コミットとブランチはきれいに保つ 意図したファイルだけを、簡潔にまとまったメッセージでコミットする。プッシュ前には最新のメインラインにリベースし、想定外のファイルを削除・リネームすることは決してない。ドキュメントは同じ変更の中で挙動と足並みを揃え、リリースの変更履歴はリリースプロセスに任せる。 ### リリースと機密情報には承認を得る リリース、バージョンの引き上げ、依存関係やロックファイルの変更には明示的な承認が必要。実際の認証情報や本番設定を決してコミットせず、機密情報は指定されたストアに保管する。