code-review-skill

コードレビューのスキル

建設的なフィードバック、体系的な分析、協力的な改善を通じて、コードレビューを門番的なものから知識共有の場へと変えます。

このスキルを使う場面

• プルリクエストやコード変更をレビューするとき
• チームのコードレビュー標準を確立するとき
• レビューを通じてジュニア開発者を指導するとき
• アーキテクチャレビューを実施するとき
• レビューチェックリストやガイドラインを作成するとき
• チームの協業を改善するとき
• コードレビューのサイクルタイムを短縮するとき
• コード品質の標準を維持するとき

基本原則

1. レビューの心構え

コードレビューの目標：

• バグやエッジケースを見つける
• コードの保守性を確保する
• チーム内で知識を共有する
• コーディング標準を徹底する
• 設計とアーキテクチャを改善する
• チーム文化を築く

目標ではないこと：

• 知識をひけらかす
• 書式を細かく指摘する（リンターを使う）
• 不必要に進行を妨げる
• 自分の好みに合わせて書き直す

2. 効果的なフィードバック

良いフィードバックとは：

• 具体的で実行可能
• 批判的ではなく、学びにつながる
• 人ではなくコードに焦点を当てる
• バランスが取れている（良い仕事も褒める）
• 優先順位が明確（重大な問題と、できれば対応してほしい事項）

❌ Bad: "This is wrong."
✅ Good: "This could cause a race condition when multiple users
         access simultaneously. Consider using a mutex here."

❌ Bad: "Why didn't you use X pattern?"
✅ Good: "Have you considered the Repository pattern? It would
         make this easier to test. Here's an example: [link]"

❌ Bad: "Rename this variable."
✅ Good: "[nit] Consider `userCount` instead of `uc` for
         clarity. Not blocking if you prefer to keep it."

3. レビューの範囲

レビューする項目：

• ロジックの正確さとエッジケース
• セキュリティの脆弱性
• パフォーマンスへの影響
• テストのカバレッジと品質
• エラー処理
• ドキュメントとコメント
• API の設計と命名
• アーキテクチャとの適合性

手作業でレビューしない項目：

• コードの書式（Prettier、Black などを使う）
• インポートの整理
• リンター違反
• 単純な誤字

レビュープロセス

フェーズ 1：コンテキストの把握（2〜3 分）

コードを詳しく見る前に、以下を把握します。

1. PR の説明とリンク先のイシューを読む
2. PR の規模を確認する（400 行超の場合は、分割を依頼する）
3. CI/CD の状態を確認する（テストは通っているか）
4. ビジネス要件を理解する
5. 関連するアーキテクチャ上の決定事項を確認する

差分が大きい場合は、差分を scripts/pr-analyzer.py に渡し（git diff main...HEAD | python scripts/pr-analyzer.py）、コードを読む前に複雑さを分類して、推奨されるレビュー方法を確認してください。

フェーズ 2：概要レビュー（5〜10 分）

1. アーキテクチャと設計 - 解決策は問題に適していますか？
   • 重要な変更の場合は、アーキテクチャレビューガイドを参照します
   • 確認項目：SOLID 原則、結合度／凝集度、アンチパターン
2. パフォーマンス評価 - パフォーマンス上の懸念はありますか？
   • パフォーマンスが重要なコードの場合は、パフォーマンスレビューガイドを参照します
   • 確認項目：アルゴリズムの計算量、N+1 クエリ、メモリ使用量
3. ファイル構成 - 新しいファイルは適切な場所にありますか？
4. テスト戦略 - エッジケースをカバーするテストはありますか？

フェーズ 3：行ごとのレビュー（10〜20 分）

各ファイルについて、以下を確認します。

• ロジックと正確さ - エッジケース、1 つずれの誤り、null チェック、競合状態
• セキュリティ - 入力検証、インジェクションのリスク、XSS、機密データ
• パフォーマンス - N+1 クエリ、不要なループ、メモリリーク
• 保守性 - わかりやすい名前、単一責任、コメント
• 再利用 - 新しいコードを受け入れる前に、代わりに使用できる既存のユーティリティやヘルパーを検索します。隣接するファイルや共有モジュールに、類似したパターンがないか確認します。パラメーターの乱用、抽象化の漏れ、ネストされた条件分岐、文字列に依存した型付け、TOCTOU、何もしない更新などのアンチパターンについては、汎用コード品質ガイドを参照してください。

フェーズ 4：まとめと判断（2〜3 分）

1. 主な懸念点をまとめる
2. 良かった点を伝える
3. 判断を明確にする：
   • ✅ 承認
   • 💬 コメント（軽微な提案）
   • 🔄 変更を依頼（対応必須）
4. 複雑な場合は、ペア作業を提案する

レビュー手法

手法 1：チェックリスト方式

一貫したレビューのためにチェックリストを使います。包括的なセキュリティチェックリストについては、セキュリティレビューガイドを参照してください。

手法 2：質問方式

問題を断定するのではなく、質問します。

❌ "This will fail if the list is empty."
✅ "What happens if `items` is an empty array?"

❌ "You need error handling here."
✅ "How should this behave if the API call fails?"

テクニック 3: 命令ではなく提案する

協調的な言葉遣いを使います:

❌ "You must change this to use async/await"
✅ "Suggestion: async/await might make this more readable. What do you think?"

❌ "Extract this into a function"
✅ "This logic appears in 3 places. Would it make sense to extract it?"

テクニック 4: 重大度を区別する

ラベルを使って優先度を示します:

• 🔴 [blocking] - マージ前に必ず修正
• 🟡 [important] - 修正すべき、同意できない場合は議論する
• 🟢 [nit] - あると良いが、ブロッキングではない
• 💡 [suggestion] - 検討すべき代替アプローチ
• 📚 [learning] - 教育的なコメント、対応不要
• 🎉 [praise] - 良い仕事、その調子！

重大度レベル: 🔴 / 🟡 / 🟢 は、このスキル内のすべてのガイドで標準として使用される 3 つの重大度ティアです — 🔴 はマージをブロックし、🟡 は対応すべきで、🟢 は任意です。残りのマーカー (💡 / 📚 / 🎉) は非ブロッキングの注釈です。

言語別ガイド

レビュー対象のコード言語に応じて、対応する詳細ガイドを参照してください:

言語/フレームワーク	参照ファイル	主なトピック
React	React ガイド	Hooks、useEffect、React 19 Actions、RSC、Suspense、TanStack Query v5
Vue 3	Vue ガイド	Composition API、リアクティビティシステム、Props/Emits、Watchers、Composables
Angular 17+	Angular ガイド	Signals、Standalone、RxJS、Zoneless、テンプレート最適化、テスト、ルートガード、HttpInterceptor
Rust	Rust ガイド	所有権/借用、Unsafe レビュー、非同期コード、キャンセル安全性、エラー処理
TypeScript	TypeScript ガイド	型安全性、async/await、不変性、テスト、モジュール解決、TS 5.x
Python	Python ガイド	可変デフォルト引数、例外処理、クラス属性
Django / DRF	Django ガイド	セキュリティレビュー、N+1 クエリ、Serializer アンチパターン、ViewSet、非同期ビュー
FastAPI	FastAPI ガイド	Depends、Pydantic v2 validation、async correctness、sessions/N+1、auth vs authorization、test-driven verification
Java	Java ガイド	Java 17/21 の新機能、Spring Boot 3、仮想スレッド、Stream/Optional
Java 8 / レガシー	Java 8 ガイド	Java 8、Spring Boot 2、javax.*、Stream/Optional、java.time、CompletableFuture
PHP	PHP ガイド	PHP 8.x type system、PDO、security review、Composer、PHPUnit/PHPStan
Ruby / Rails	Ruby ガイド	Ruby semantics、Rails 8、Active Record、Active Job、security、testing
C# / .NET	C# ガイド	C# 12 の機能、非同期プログラミング、EF Core パフォーマンス、ASP.NET Core、LINQ
Go	Go ガイド	エラー処理、goroutine/channel、context、インターフェース設計
Kotlin / Android	Kotlin ガイド	コルーチン、Flow、Jetpack Compose、Null 安全、メモリリーク、アーキテクチャパターン
Swift / SwiftUI	Swift ガイド	Optionals、Swift Concurrency、Sendable/actors、SwiftUI property wrappers、value vs reference types、API design
Dart / Flutter	Dart ガイド	Widget rebuilds、const constructors、null safety、isolates、async in build、Riverpod/Bloc、platform channels、keys、disposal
NestJS	NestJS ガイド	依存性注入、レイヤードアーキテクチャ、DTO バリデーション、Guard/Interceptor、循環依存
Svelte / SvelteKit	Svelte ガイド	Runes、Load 関数、Form Actions、Store 移行、SSR/CSR 境界
C	C ガイド	ポインタ/バッファ、メモリ安全、UB、安全なコーディング、移植性、テスト
C++	C++ ガイド	RAII、スマートポインタ、C++20/23、constexpr、テスト
Zig	Zig ガイド	Allocators、error unions、defer/errdefer、comptime、C interop
CSS/Less/Sass	CSS ガイド	変数規約、!important、パフォーマンス最適化、レスポンシブ、互換性
Qt	Qt ガイド	オブジェクトモデル、シグナル/スロット、Model/View、QML、Qt6 移行、テスト

分野横断ガイド

すべてのコードレビューに適用できる、言語に依存しないパターンです。

トピック	参照ファイル	主なトピック
アーキテクチャレビュー	アーキテクチャレビューガイド	SOLID、アンチパターン、結合度／凝集度、依存関係の方向
パフォーマンスレビュー	パフォーマンスレビューガイド	Web Vitals、N+1、アルゴリズムの計算量、メモリリーク、キャッシュ
セキュリティレビュー	セキュリティレビューガイド	SQLi、XSS、CSRF、SSRF、IDOR、コマンドインジェクション、言語横断の例
普遍的な品質	普遍的な品質ガイド	再利用の監査、パラメーターの乱立、漏れやすい抽象化、ネストした条件分岐、文字列型に依存したコード、TOCTOU、何もしない更新、冗長な状態
よくあるバグ	よくあるバグのチェックリスト	言語固有のバグパターン、よくある落とし穴
SQL インジェクション対策	SQL インジェクションガイド	パラメーター化クエリ、ORM の安全性、6 言語、動的な識別子、検出
XSS 対策	XSS 対策ガイド	出力のエンコード、CSP、5 つのフレームワーク、入力検証とエンコードの違い、検出
N+1 クエリ	N+1 クエリガイド	Eager Loading、バッチ取得、DataLoader、5 言語、検出
エラー処理	エラー処理ガイド	フェイルファスト、エラー階層、7 言語、アンチパターン、ロギング
非同期処理と並行性	並行性ガイド	Goroutine、async/await、アクター、構造化された並行性、7 言語
レビューのベストプラクティス	コードレビューベストプラクティス	コミュニケーション、レビュアーの心構え、フィードバックの伝え方、重大度ラベル

追加リソース

• PR レビューテンプレート - PR レビューコメントのテンプレート
• レビューチェックリスト - クイックリファレンスのチェックリスト