code-review

コードレビューのスキル

再現可能なチェックリストに従って、Flutter/Dart プロジェクトの構造的かつ客観的なコードレビューを実施します。

使用するタイミング

このスキルは、次の場合に使用します。

• プルリクエスト、マージリクエスト、またはブランチのレビューを依頼されたとき。
• 変更、追加、削除されたファイルの正確性と品質を評価するとき。
• マージ前に差分を監査するとき。
• 新しいコードがプロジェクトの標準を満たしているか確認するとき。

---

レビューワークフロー

ステップ 1 — ブランチとマージ先を確認する

1. 現在のブランチが、プロジェクトのメインブランチ（例：main、master、develop）ではなく、機能追加、バグ修正、または PR/MR 用のブランチであることを確認します。
2. ブランチがマージ先のブランチに対して最新の状態であることを確認します（未解決の競合がないこと）。
3. マージ先のブランチを特定します。

チェックポイント： ブランチがマージ先より遅れている場合は、続行する前にその旨を指摘します。

ステップ 2 — 変更内容を把握する

1. 変更、追加、削除されたファイルをすべて一覧表示します。
2. 各変更について、コミットタイトルを確認し、関連するコンポーネントがどのように実装されているかをレビューします。
3. 変更を分析します：変更の理由は明確ですか？ 明確でない場合は、関連するメソッドやファイルを調べて理由を明らかにします。報告時には、分析した関連ファイル／メソッドとその理由を明記します。これにより、変更を推測ではなく理解したうえでレビューしたことが示されます。
4. 実装を調査せずに、変更が正しいと決めつけてはいけません。
5. 調査後も変更の内容が明確でない場合は、報告でその旨を明示します。

ステップ 3 — 各ファイルをレビューする

変更されたファイルを一つずつ確認します。各ファイルについて、次の項目を検証します。

項目	検証内容
変更の理解	なぜ変更されたのか？ 関連するメソッド／ファイルをレビューし、分析した対象とその理由を記録する
配置場所	ファイルが正しいディレクトリにある
命名	ファイル名がプロジェクトの命名規則に従っている
責務	ファイルの責務が明確で、変更理由も理解できる
可読性	変数、関数、クラスの名前が説明的で、一貫している
ロジックと正確性	ロジック上のエラーや考慮漏れのエッジケースがない
コードの臭い	以下のコードの臭いのリファレンスに記載された項目を確認する
保守性	コードがモジュール化され、不要な重複がない
エラー処理	エラーや例外が適切に処理されている
セキュリティ	入力検証の漏れや、コードへの秘密情報のコミットがない
パフォーマンス	明らかな非効率性（例：不要な再ビルド、大きなリストに対する O(n^2) のループ）がない
SOLID 原則	不要な定型コードや過度な抽象化を強いることなく、原則への準拠を評価する
Flutter/Dart/ のパターン	プロジェクトに読み込まれているガイドラインや規約と照らし合わせる
ドキュメント	公開 API、複雑なロジック、新しいモジュールにドキュメントがある
テストカバレッジ	新規または変更されたロジックに十分なテストがある（ステップ 4 を参照）
スタイル	コードがプロジェクトのスタイルガイドとリンティング規則に従っている
既存コード	新しい変更に問題がなさそうな場合も、周辺の変更されていない既存コードに臭いがないか確認し、関連するリファクタリングを提案する

生成ファイル（例：*.g.dart、*.freezed.dart）については、最新の状態であり、手動で変更されていないことを確認します。

レビュー範囲を守る： すべての変更にコメントすることが目的ではありません。エラーや具体的な改善点を見つけて指摘してください。問題のないコードに対して、無理にコメントを作らないでください。

Flutter 固有のチェック項目

(注：以下は Bloc/Cubit を使用する例です。Riverpod、Provider、または選択した状態管理パッケージにも同様の原則を適用してください。)

// BAD — rebuilds entire tree on every state change
BlocBuilder<MyCubit, MyState>(
  builder: (context, state) => EntireScreen(state: state),
);

// GOOD — scope rebuilds to the widget that actually changes
BlocSelector<MyCubit, MyState, String>(
  selector: (state) => state.title,
  builder: (context, title) => Text(title),
);

• 動的に生成されるウィジェットで Key が使用されているか確認します。
• コントローラー、ストリーム、アニメーションコントローラーに対して dispose() が呼び出されているか確認します。
• 可能な場合は const コンストラクターが使用されていることを確認します。

コードスメルのリファレンス

各ファイルを確認し、よくあるコードスメルがないかチェックしてください。定義と推奨されるリファクタリングについては、refactoring.guru/refactoring/smellsを参照してください。

カテゴリー	コードスメル
肥大化	長いメソッド、大きなクラス、プリミティブ型への執着、長いパラメーターリスト、データの塊
オブジェクト指向の乱用	インターフェースの異なる代替クラス、継承の拒否、一時フィールド、switch文
変更の阻害要因	発散した変更、並行する継承階層、ショットガン手術
不要なもの	コメント（冗長）、重複コード、データクラス、デッドコード、怠惰なクラス、投機的一般化
結合	フィーチャーエンヴィ、過度な親密さ、不完全なライブラリークラス、メッセージチェーン、中間者

ステップ 4 — 変更全体を評価する

1. 変更が、記載された目的に焦点を絞り、範囲内に収まっていることを確認します。無関係な変更が含まれていないことを確かめてください。
2. PR/MR の説明が変更内容を正確に反映しているか確認します。

テストカバレッジ

テストカバレッジを明示的に確認します。見落としやすく、実態をごまかしやすいため、注意深く確認してください。

• 新しいロジックや重要な変更がある場合は、対応するテストファイルを検索し、テストが実際に存在することを確認します。
• テストが、単に正常系だけでなく、変更された機能のエッジケースも含めてカバーしているか確認します。
• テストが実際のコードに対して本当に失敗しうるか、それともモックの動作を確認しているだけなのかを評価します（モックに設定した値をモックが返すことを検証するテストでは、何も証明できません）。
• テストが不足している、または不十分な場合は、カバレッジ不足をコメントで指摘し、黙って見過ごさないでください。

ステップ 5 — CI とテストを確認する

1. すべてのテストがCI で成功することを確認します。
2. 新たなアナライザーの警告やリンター違反がないか確認します。
3. パッケージのベストプラクティスが不明な場合は、公式ドキュメントを取得して確認します。

チェックポイント： CI が失敗している場合や、新しいロジックに対するテストがない場合は、ブロッキング課題として指摘してください。

---

まとめ

ファイルごとの確認を終えたら、最終判断を行います。

• 問題がなく、変更も不要な場合： MR の内容（何が行われたか）と所見をまとめた全体的な結論コメントを投稿し、MR を承認します。
• 新しい変更に問題はないものの、既存コードにスメルを見つけた場合： ブロッカーではなく、任意のリファクタリング提案として記載します。
• 問題が見つかった場合： 作成者が優先して対処すべきことが分かるよう、主な懸念事項を明確にまとめます。

---

フィードバックの基準

• 客観的かつ妥当な評価を行い、機械的な称賛やお世辞は避けてください。
• あえて反対の立場から検討する姿勢を取り、率直で思慮深いフィードバックを提供してください。
• 見つかった問題それぞれに、明確で建設的な提案を添えてください。
• 不明確な点については、確認を求めてください。
• 各指摘に重大度を付けてください：suggestion、minor、major。

---

出力形式

デフォルトでは、チャットの返信としてレビューを提示します。各ファイルについて、次の内容を含む構造化された返信にしてください。

1. 概要 — 変更内容とその理由。
2. 問題点 — それぞれに深刻度（suggestion／minor／major）と、具体的な修正案を記載します。
3. 質問 — ファイルごとに、具体的な確認事項を記載します。
4. 判定 — 次のいずれかを選びます。Approved、Approved with suggestions、Changes requested。

オンラインへのコメント投稿（オプトインのみ）。 チャットでレビューを提示した後、これらのコメントをPR/MRにオンラインでも投稿するかどうかをユーザーに尋ねてください。そうすることで、チームがコメントを確認し、返信できるようになります。ユーザーが明示的に同意した場合にのみ、オンラインに投稿してください。 自発的にプラットフォームへ投稿してはいけません。

ユーザーが同意した場合は、問題点を適切な位置フィールドを使って、正しいファイルと行に紐づくインラインコメントとして投稿します。結論や主な懸念事項はトップレベルのレビューコメントとして投稿し、必要に応じて承認も行います。これにはプラットフォーム（GitHub/GitLab）のreview-bot アクセストークンが必要です。設定されていない場合は、その旨をユーザーに伝え、投稿前に設定するよう依頼してください。

トークンの安全性。 トークンは秘密情報です。設定されているかどうかと、その長さは確認して報告できますが、トークンの値を読み取ったり、チャット、ファイル、コミットなどでエコー、ログ出力、表示、その他の方法で開示したりしてはいけません。curlには環境変数（例：$GITLAB_TOKEN）を参照して渡し、値を直接埋め込んではいけません。また、認証ヘッダーが表示されるため、curl -v／--verboseは使用しないでください。これらはPreToolUseフック（scripts/protect-token.sh）によって適用され、値を露出させる可能性のあるBashコマンドはブロックされます。安全な有無と長さの確認方法については、各リファレンスファイルの「Handling the token safely」セクションを参照してください。

このフックはClaude Code CLIとAgent SDKの両方で動作します。（settingSources／setting_sourcesを明示的に設定するSDKアプリでは、スキルフックを読み込むために"project"を含める必要があります。これはデフォルトで含まれています。）

プラットフォーム固有のAPIの詳細、curlの形式、承認手順については、次を参照してください。

• GitLab → references/gitlab-posting.md（GITLAB_TOKEN環境変数を使用）
• GitHub → references/github-posting.md（GITHUB_TOKEN環境変数を使用）