生成コードを含む複数モジュールのリポジトリを、許された範囲で直す

## 編集の前に、ルートとフォルダごとの指示を読む まず、変更対象のファイルを規定するリポジトリの指針を探す。一般的な技術環境の前提に頼らず、プロジェクト文書と階層ごとの指示ファイルをローカル規約の正本として扱う。 - ルートの指針と、対象ディレクトリに適用されるより具体的な指示を読む。 - 作業に関係するリポジトリ概要、コントリビューションガイド、開発環境設定、テスト指針、リリース文書を確認する。 - リポジトリ全体の指針とモジュール固有の指針が異なる場合は、最も近い範囲に適用される指示に従う。 - 記憶しているコマンドに頼らず、保守されているプロジェクトファイルから参照先の方針を確認する。 - 所有権を定めるファイルを確認し、変更対象を担当するレビュアーを特定する。 - 編集前に、対応する作業手順、必要な承認、検証条件を把握する。 - 正本同士が矛盾するか、影響の大きい判断が未解決の場合にだけ質問する。 ## 変更を受け持つモジュールと、レビューする担当者を見つける 実装場所を決める前に、コードベースの分割方法を理解する。複数モジュールのリポジトリでは、ビルド境界、依存関係の定義、生成領域、サンプル、テスト、リリース単位がディレクトリごとに異なることがある。 - 公開動作を担当するモジュールと、その下位で利用される構成要素を特定する。 - 手書きの実装と、生成コード、テンプレート、仕様、テストデータ、サンプルを区別する。 - モジュール定義を調べ、直接依存と間接依存の境界を理解する。 - 所有権の規則から、コード、サービス、共有基盤の担当者を特定する。 - 変更の影響が単一パッケージ、複数モジュール、共有の互換性面のどこまで及ぶかを追跡する。 - 並行する独自構造を作らず、既存のディレクトリ配置と命名パターンに合わせる。 - 検証済みの依存関係による連動が必要でない限り、無関係なモジュールを変更対象に含めない。 ## プロジェクトが決めたツールのバージョンとタスクのコマンドを使う リポジトリと対象モジュールが定めるツールチェーンを使う。対応バージョン、タスク実行方法、生成ツール、環境準備はプロジェクトの判断事項であり、ローカルにある最新環境から推測しない。 - 現在対応している言語とツールのバージョンを、保守されている方針または設定から確認する。 - 追加の準備を行うリポジトリ管理のタスクがある場合は、言語コマンドの直接実行より優先する。 - 文書化された作業手順が想定するモジュールまたはワークスペースのディレクトリでコマンドを実行する。 - 正式なタスクが行う環境選択、互換性オプション、生成物、その他の設定を維持する。 - 文書化された手順で明示的に必要とされる場合にだけ、システム全体へ前提ツールを追加する。 - 生成ツールとコンパイラのバージョンを、プロジェクトで固定または対応している版に合わせる。 - 必要な前提条件がない場合は、作業手順を黙って変更せず、具体的な阻害要因として報告する。 ## リリース・CIの変更・認証情報を使う前に許可をもらう エージェントは、コードの読み取り、動作説明、変更提案、承認済みの編集、テスト追加、文書改善、課題やレビューの分析を支援できる。影響の大きい操作には、引き続き人による明示的な権限が必要となる。 - 承認なしにリリースを開始したり、リリース段階を承認したり、パッケージを公開したりしない。 - 別の変更に付随する作業として、継続的インテグレーション、デプロイパイプライン、作業フロー制御を変更しない。 - 明示的な許可なしに、ライセンス、法的表示、コンプライアンス方針を変更しない。 - 与えられた作業範囲を越えて、認証情報を使ったり、外部サービスへ接続したり、リモートの状態を変更したりしない。 - 状態変更が承認されていない限り、課題の分類、ラベル候補、重複判定は提案にとどめる。 - 取り消し困難な操作や保護環境の変更前に停止し、必要な判断を求める。 - 通常の範囲内にある実装と検証は、不要な確認を挟まずに続行する。 ## 生成されたファイルは直さず、仕様を直して作り直す 生成されたパッケージには、手書きコードとは異なる変更経路が必要となる。生成結果を手動で編集すると上書きされやすく、実装が正本となる仕様から分離するおそれがある。 - リポジトリの印、定義ファイル、配置情報、文書化されたディレクトリ規則から生成ファイルを識別する。 - プロジェクトが仕様からの再生成を求める場合は、生成結果を手動で修正しない。 - 文書上の正本が仕様、テンプレート、生成入力である場合は、そちらを変更する。 - プロジェクト指定の生成コマンドと必要なツールバージョンを使う。 - 生成された差分を確認し、想定外のファイル、書式だけの大量変更、無関係なAPI変更がないか調べる。 - 手動拡張用の領域は、リポジトリのパターンに従って生成領域から分離する。 - 再生成を実行できない、または許可されていない場合は、一時的な編集を恒久的な修正に見せかけず制約を説明する。 ## 後方互換性を保つ、小さな変更にする 既存のコード規約に従い、互換性を保つ焦点の絞られた変更を優先する。同じ要件を満たせるなら、広いリファクタリングよりも小さくレビューしやすい修正のほうが安全である。 - 近くの実装を読み、使用する補助処理、名前、エラー表現、ファイル配置を決める。 - 互換性を損なう変更が明示的に承認され文書化されていない限り、後方互換性を維持する。 - 公開名、略語、コメント、公開API文書について、ローカルの規約に従う。 - 機密情報を露出させず、有用な文脈を保った説明的なエラーを使う。 - 必要な著作権表示とライセンス表示を維持する。 - モジュールの依存関係方針に従い、既にローカルで実現できる動作のために外部依存を追加しない。 - レビュアーが意図を明確に評価できるよう、無関係な整理を依頼された変更から分離する。 ## 対象のモジュールを先にビルドしてテストし、必要な時だけ広げる まず対象モジュールを直接確認する最小のコマンドを実行し、共有動作またはリポジトリ方針で必要な場合にだけ検証範囲を広げる。成功したコマンドも、変更箇所を確認して初めて意味を持つ。 - 文書化されたタスクまたは言語コマンドで対象モジュールをビルドする。 - 広いパッケージ群やワークスペース全体のテストより先に、直接関係する単体テストを実行する。 - モジュールで必要とされる型検査、静的解析、書式確認、生成ファイル検証を加える。 - テストの選択範囲に、意図したパッケージとテストケースが実際に含まれていたか確認する。 - 統合テストや実環境テストを試す前に、必要な環境変数を確認する。 - 対象が除外されたコマンドや、利用できない外部状態に依存した結果を検証済みと主張しない。 - 実行したコマンド、観察した結果、完了できなかった検査を記録する。 ## ネットや実行の順番に頼らないテストと、動くサンプルを書く テストは動作変更を証明し、異なる環境でも安定して実行できる必要がある。サンプルは、リポジトリの実行可能な例示規約に従いながら、対応している使い方を示す。 - モジュールで確立されたアサーションライブラリとテスト構造を再利用する。 - 不具合を修正する場合は、修正適用前に新しいテストが意図した理由で失敗することを確認する。 - 単体テストをネットワーク、認証情報、時間で変化する状態、実行順序に依存させない。 - テストデータは指定の配置場所に置き、必要最小限に保つ。 - 実環境テストの設定は承認された環境ファイルに分離し、機密値をコミットしない。 - 診断を実質的に改善できる場合は、アサーションに説明文を加える。 - サンプルを所定の命名規則とパッケージ構造に置き、文書化されたテスト手順でコンパイルまたは実行できることを確認する。 ## 動きが変わった時に、モジュールの説明と変更履歴を直す 文書も実装面の一部である。利用者、保守担当者、リリース用ツールに不完全または誤解を招く情報が伝わる場合は更新する。 - 設定手順、対応動作、公開された使い方が変わる場合は、モジュール概要を更新する。 - プロジェクトの文書スタイルに従って、APIコメントを追加または改訂する。 - 利用者に見える変更を、指定された変更履歴へ記録する。 - リポジトリ方針で求められる場合は、新しい公開APIのサンプルを用意する。 - 設定、生成、移行、リリースの手順を実際のコマンドと一致させる。 - 参照先が有効であり、非公開または廃止済みの場所へ読者を誘導しないことを確認する。 - 動作と作業手順が変わらない場合は、不要な文書変更を避ける。 ## 決められたブランチから、差分を全部見てからレビュー依頼を出す リポジトリで承認されたコントリビューション経路を使い、変更全体を確認しやすくする。実装、テスト、文書、判断理由を結び付けつつ、保護された共有履歴は変更しない。 - 承認済みの基点ブランチから作業を始め、許可されたフォークまたはリモート経由で公開する。 - 変更リクエストを開く前に、ブランチ全体の差分を確認する。 - 内容が分かるタイトルを付け、関連する作業がある場合は参照する。 - 将来の回帰を防ぐテストと、方針上必要な文書を含める。 - 保守担当者が別の履歴管理方法を求めない限り、追跡可能な追加変更としてレビュー指摘に対応する。 - 必須の自動検査をすべて確認し、失敗を回避せず原因を調べる。 - 明示的な許可なしに、保護ブランチ、リリースブランチ、共有履歴を変更しない。 ## 互換性を壊す変更や、生成ファイルの間違いがないかレビューする コードレビューでは、正確性、互換性、生成手順の整合性、テスト品質、セキュリティ、保守性を優先する。一般的な書式チェックだけでなく、プロジェクト固有の指針を適用する。 - 変更が選択したモジュールに属し、そのアーキテクチャに従っているか確認する。 - 既定動作の微妙な変化を含め、互換性を損なうAPI変更や動作変更を探す。 - 必要に応じて、成功、失敗、境界条件、再現性をテストが網羅しているか確認する。 - 生成ファイルが承認された正本と生成手順から作られていることを確認する。 - 依存関係とモジュール定義の変更に、方針違反や不要な追加がないか調べる。 - 文書と変更履歴が完全かつ正確か確認する。 - 発見事項を担当者へ伝え、対応必須の不具合と任意の改善を区別する。 ## セキュリティの問題は非公開で報告し、テスト結果を添えて引き継ぐ セキュリティ報告、リリース、パイプライン承認、ライセンス、認証情報には専用の取り扱いが必要となる。通常作業は証拠に基づく引き継ぎで終え、保護対象の操作は権限を持つ担当者に委ねる。 - セキュリティ上の不具合は、公開の課題や議論ではなく、プロジェクト所定の非公開窓口へ報告する。 - 機密値、非公開の連絡先、取り扱いに注意が必要な再現情報を公開物へ含めない。 - リリース開始、デプロイ承認、ライセンス判断は、明示的に権限を与えられた保守担当者へ委ねる。 - 重要な実装判断を説明し、適用されるプロジェクト指針と結び付ける。 - 変更した場所、実行したテスト、観察した結果、残る制約を要約する。 - 追加レビューが必要な場合は、適切なコードまたはサービスの担当者を示す。 - 外部アクセス、利用できないツール、承認境界によって完全な検証ができなかった場合は、その事実を明記する。