mariadb-operator-pr-review

mariadb-operator PR レビュー

mariadb-operator のメンテナーとして、プルリクエストの初回レビューを行います。正確性、安全性、潜在的な問題、後方互換性、コード品質を評価し、総合評価を示してください。

AGENTS.md を唯一の情報源とする

レビューの前に、リポジトリルートにある AGENTS.md を読んでください。 これは、このプロジェクトのアーキテクチャ、パターン、注意点、ガードレールを説明する権威ある文書です。このスキルでは、差分をそれらに照らして確認する方法を示すため、ルール自体はあえて繰り返しません。以下で「§ 」とある場合は、AGENTS.md の該当セクションを指します。チェック項目に「§ X に照らして確認する」とある場合は、そのセクションを開き、差分と照合してください。

GitHub の認証情報

このスキルで GitHub を呼び出す場合（PR のコンテキスト取得またはレビューの送信）は、以下の順にアクセス方法を選択し、前の方法が利用できない場合にのみ次へ進んでください。

1. プロジェクト専用の GitHub MCP ツール（mcp__github-mariadb-operator__* のような名前）。これらは遅延ツールとして表示される場合があります。その場合は、呼び出す前に ToolSearch でスキーマを読み込んでください（例： ToolSearch({query: "select:mcp__github-mariadb-operator__get_file_contents", max_results: 1})）。
2. プロジェクト専用トークンを使った gh CLI（mariadb-operator MCP サーバーに接続されていない場合）。環境にある gh auth セッションではなく、GITHUB_MARIADB_OPERATOR_TOKEN を明示的に使用してください（GH_TOKEN="$GITHUB_MARIADB_OPERATOR_TOKEN" gh ...）。
3. 汎用の GitHub MCP ツール（上記のいずれも利用できない場合、mcp__github__*）。
4. デフォルトの認証情報を使った gh CLI（最後の手段として、上記のいずれも使えない場合に限り、明示的なトークンを指定せず通常の gh auth を使用）。

---

ステップ 0 — コンテキストを収集する

PR の URL または番号を指定されたら、GitHub の認証情報セクションで選択したアクセス方法を使って情報を取得してください（以下の gh コマンドはその方法を前提としています。適宜 GH_TOKEN を指定するか、同等の MCP ツールに置き換えてください）。

gh pr view <n> --json title,body,author,state,additions,deletions,files,labels,baseRefName
gh pr diff <n>                       # full unified diff
gh pr view <n> --json reviews,comments   # existing review discussion

次に、差分だけでは分からない周辺コンテキストを、ローカルのチェックアウトから取得してください。

• 変更前のバージョン：変更対象の api/v1alpha1/、internal/controller/、internal/webhook/、pkg/controller/ にあるファイル。動作の変化を判断するには、変更前の内容が必要です。

  git fetch origin <baseRefName>
  git show origin/<baseRefName>:<path/to/file.go>
  

• 影響範囲：新規または変更された関数シグネチャの呼び出し元、および名前が変更・削除されたフィールドや型の利用箇所を git grep で検索してください。
• 関連する docs/<feature>.md（§ Feature Map）。意図されたセマンティクスを把握するには、コードを読むより効率的です。

大規模な PR では、リスクに応じて確認にかける時間を配分してください。まず HA／バックアップ／CRD／Webhook／ビルダーの変更を一行ずつ確認し、次にコントローラー、最後にその他を確認します。差分の統計情報（gh pr diff <n> --name-only）を使うと、確認を始める場所が分かります。

生成ファイルの内容はレビューのために読まないでください（§ Token Savers）。レビューでは、差分に生成ファイルが含まれているかどうかだけを確認します。api/v1alpha1/ の型を変更したのに生成物が更新されていない場合は、すぐに却下してください。

ステップ 1 — トリアージ

• PR を分類します：機能追加、バグ修正、リファクタリング、ドキュメント／サンプルのみ、依存関係の更新、または生成ファイルのみ。
• 影響を受けるサブシステムを特定し、§ Feature Map と § Phase-based reconciliation のフェーズ一覧に対応付けます。
• 動作上の変更と、純粋に構造上の変更（名前変更、フォーマット、移動）を区別します。
• ステップ 0 で取得した既存のレビュー議論を確認します。決着済みの指摘を再度持ち出さず、以前のフィードバックで変更が求められていた場合は、後続のコミットで実際に対応されているか確認します。
• 変更の規模に応じてレビューの範囲を調整します。dependabot の更新やドキュメントの誤字に、5 つの観点すべてからのレビューは不要です。そう明記して次に進みます。調停処理、HA（pkg/replication、pkg/galera）、バックアップ／復元／PITR、CRD スキーマ、Webhook、または pkg/builder に関わる変更は、詳しくレビューします。
• 事実をコードベースと照合するのは、その主張がこの変更にとって重要な根拠となる場合、つまり変更の正確性や安全性がその事実に依存する場合に限ります。環境上の不変条件（モジュールパス、リンターのバージョンやしきい値、ドキュメントに記載された一覧が現在のコードと一致しているかなど）を抜き取り確認しないでください。これらは CI の担当であり、確認してもレビューに有益な情報は加わりません。ドキュメント／ガイダンス／ツーリングに関する PR（AGENTS.md、スキル、README）では、内容自体がリポジトリについての主張です。読者が実際に行動する際に参考にし、誤っていた場合に重大な害が生じる可能性のある、少数の記述だけを確認してください。すべての記述を漏れなく再検証する必要はありません。

即時却下の条件 — いずれかに該当する場合は、冒頭で目立つように指摘してください。

• api/v1alpha1/ の CRD 型が変更されているのに、再生成された成果物が差分に含まれていない（§ コード生成と生成ファイル）。
• 新しい動作に対応するテストがない、または PR のスモークテスト対象としてタグ付けされたテストがない（§ テスト）。
• RBAC マーカーが追加または変更されているのに、手動で Helm チャートへ反映されていない（これを検知する CI ジョブはありません）（§ 注意点 → チャートの RBAC は生成されません）。
• 機能上の必要がないのに StatefulSet の Pod テンプレートが変更されている（§ 安全ガードレール → ローリング再起動）。
• 変更に不要な複雑さ（具体的なユースケースのない新しい抽象化、設定オプション、spec フィールド、フラグ、依存関係、または現実的には起こり得ない例外ケースのための仕組み）が含まれている。これは他の欠陥と同様に扱い、よりシンプルな代替案を明示してください。

ステップ 2 — 5 つの観点で評価する

各観点について、PASS／CONCERN／FAIL のいずれかを判定してください。PASS の場合は、判定を示したらそこで終わりにしてください。理由を書くとしても最大 1 行にとどめ、個々のチェック項目、file:line、確認した AGENTS.md のルールには触れず、領域を大まかに示してください。修正が必要な場合にのみ説明に文字数を使ってください。CONCERN／FAIL にはすべて、具体的な file:line、失敗する状況、違反した AGENTS.md のルールの簡潔な言い換え（該当する § セクション名を含む）を記載し、指摘の根拠となる規約を作者に伝えてください。緑色の判定理由を延々と並べても、作者が読み飛ばすだけです。以下のチェックは、あなたが実施するものであり、報告するものではありません。

PASS の場合、確認した内容を明示的に列挙しないでください。 確認が興味深いものだった場合や、実施が容易でなかった場合も同様です。確認した事実、抜き取り確認したファイルや行、妥当性が確認された主張、遵守されていたルールを列挙したり、言い換えて記載したりすることは、どのような表現であっても PASS 違反です。領域を大まかに示す 1 行の要約だけを書いてください。セクション見出しの ✅ ですでに判定を示しているため、本文で ✅ PASS を繰り返さないでください。列挙は作業メモにとどめ、出力には含めないでください。

指摘の品質基準。 レビューの価値は、指摘の数ではなく、作者が対応するいくつかの指摘にあります。指摘を挙げる前に、保守担当者がこの内容をブロックしたり、コメントしたりするかを考えてください。すべての CONCERN／FAIL には、(a) file:line、(b) 具体的な失敗状況（どの入力やクラスター状態で問題が起きるか）、(c) 適切な重大度の明示が必要です。失敗する状況を具体的に説明できないなら、それは指摘ではなく所見です。コードを確認して（呼び出し元を読む、変更前のバージョンを確認するなど）検証するか、取り下げてください。golangci-lint が検出しないスタイル上の意見は指摘に含めません。

以下の各観点では、評価対象と、ルールが記載されている AGENTS.md のセクションを示しています。AGENTS.md を正とし、該当セクションを読んで差分を確認してください。出力でルールを言い換えるのは、そのルールが指摘の根拠となる場合に限り、簡潔に記載してください（下記参照）。PASS の場合、確認したルールをまとめてはいけません。

A. 正確性

コードは PR の主張どおりに動作し、制御フロー、API の使い方、境界ケース（nil／空／ゼロ、境界値、競合、ポインター／ジェネリック／インターフェースの利用）の処理は適切ですか？差分が § Architecture and Code Patterns に記載されたパターンに触れている場合、再実装したり迂回したりせず、そのパターンに従っているか確認してください。

B. 安全性

差分を § Safety Guardrails の該当するサブセクションに照らして確認し、そこに危険とされる領域を 1 行ずつ精査してください。

C. 落とし穴の検出

PR が § Gotchas and Non-obvious Rules に反していないことを確認し、§ Kubernetes best practices にも照らして再確認してください。現在は成り立っていても今後成り立たなくなる可能性のある、重要な前提条件と、差分で省かれているテストシナリオ（§ Testing）を探してください。

D. 後方互換性

差分を § Safety Guardrails → Backward compatibility に照らして確認してください。各指摘を additive（安全）、behavioral（リスクあり）、または breaking に分類してください。v1alpha1 では変更が認められていますが、breaking change であっても、事前の告知と移行手順が必要です。

E. コード品質

コードは読みやすく、保守しやすく、周囲のコードベースと一貫していますか？§ CI — what a PR must pass に記載されている golangci-lint／CI のチェックを手作業で再確認してはいけません。リンターでは検出できない問題だけを指摘してください。§ Testing に従ってテストが用意され、適切な階層で実施されること、変更範囲が適切であること（不要なコード、デバッグの残骸、過剰な設計がないこと）を確認してください。

ステップ 3 — 判定

次のいずれかを選んでください。

• 承認 — 実質的な問題はなく、正確で、安全で、よく書けています。
• 注記付きで承認 — 正確で安全ですが、マージ前に記録しておく価値のある運用上の考慮事項があります。
• 変更をリクエスト — 正確性または安全性に関する問題があり、先に修正する必要があります。
• ブロック — アプローチに問題がある、重大な安全上のリスクがある、または移行を伴わない破壊的変更です。

リスクレベルを割り当ててください：LOW / MEDIUM / HIGH。HA のシーケンス処理、バックアップ／復元／PITR、または CRD との互換性に関わるものは、影響範囲に応じてリスクが高まるものとして、MEDIUM から開始します。

---

指摘しないこと

• コード品質の問題としての生成ファイルの内容 — これらは機械的に生成された出力です。（ただし、CRD を変更する PR に生成ファイルが含まれていない場合は、引き続き有効な指摘事項です。）
• § Gotchas で意図的なものとして宣言されていること。
• 内部関数に godoc がないこと — これはプロジェクトの慣習ではありません。
• Dependabot による Go モジュールの更新 — 信頼できる自動化です。
• 対応するコードがない docs/ または examples/ の先行更新。
• 自動フォーマットによる空白の差異 — CI でフォーマットが適用されます。

提出方法

デフォルトでは、レビューを GitHub に投稿せず、返信でユーザーに返してください。 ユーザーが明示的に依頼した場合にのみ、GitHub 認証情報のセクションに記載されたアクセス方法を使って（例：gh pr comment）、GitHub に投稿してください。

出力形式

レビューは、PR コメントにそのまま貼り付けられるよう、整った GitHub Flavored Markdown で作成してください。以下の絵文字の凡例を使い、判定をひと目で確認できるようにしてください。各項目が PASS の場合は、対象領域を大まかに示す1行の要約を記載してください。セクション見出しの ✅ ですでに判定が示されているため、本文で ✅ PASS を繰り返さないでください。file:line の一覧や、合格した項目のまとめは記載しないでください。理由、参照先、失敗シナリオは CONCERN / FAIL に限って記載してください。

絵文字の凡例：

• 項目の判定：✅ PASS · ⚠️ CONCERN · ❌ FAIL
• 全体評価：✅ 承認 · 📝 注記付きで承認 · 🔧 変更をリクエスト · 🚫 ブロック
• リスクレベル：🟢 LOW · 🟡 MEDIUM · 🔴 HIGH

以下の構成を厳守してください。

## 🔍 PR Review
<1-2 sentences: what the PR does and why>

### Verdict at a glance

| Dimension | Result |
|---|---|
| Correctness | ✅ PASS |
| Safety | ✅ PASS |
| Pitfall Detection | ⚠️ CONCERN |
| Backwards Compatibility | ✅ PASS |
| Code Quality | ✅ PASS |

**Overall:** 📝 Approve with notes — **Risk:** 🟡 MEDIUM

---

### ✅ Correctness
<verdict; on CONCERN/FAIL add justification with `file:line` references and failure scenario>

### ✅ Safety
<verdict; on CONCERN/FAIL add justification with `file:line` references and failure scenario>

### ⚠️ Pitfall Detection
<verdict; on CONCERN/FAIL add justification with `file:line` references and failure scenario>

### ✅ Backwards Compatibility
<verdict; on CONCERN/FAIL bullets classifying each finding as additive / behavioral / breaking>

### ✅ Code Quality
<verdict; on CONCERN/FAIL add justification with `file:line` references>

---

### 📋 Suggested before merge
<actionable items as a checklist, or "None">

各項目の見出しとサマリー表では、その項目の実際の判定に対応する絵文字を使い、Overall と Risk の絵文字もそれぞれの判定に合わせてください。表とセクション見出しの判定は一致させてください。