code-review-excellence

コードレビューの卓越性

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

このスキルを使用する場面

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

基本原則

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 分）

Before diving into code, understand:

1. Read PR description and linked issue
2. Check PR size (>400 lines? Ask to split)
3. Review CI/CD status (tests passing?)
4. Understand the business requirement
5. Note any relevant architectural decisions

フェーズ 2：全体的なレビュー（5-10 分）

1. **Architecture & Design**
   - Does the solution fit the problem?
   - Are there simpler approaches?
   - Is it consistent with existing patterns?
   - Will it scale?

2. **File Organization**
   - Are new files in the right places?
   - Is code grouped logically?
   - Are there duplicate files?

3. **Testing Strategy**
   - Are there tests?
   - Do tests cover edge cases?
   - Are tests readable?

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

For each file:

1. **Logic & Correctness**
   - Edge cases handled?
   - Off-by-one errors?
   - Null/undefined checks?
   - Race conditions?

2. **Security**
   - Input validation?
   - SQL injection risks?
   - XSS vulnerabilities?
   - Sensitive data exposure?

3. **Performance**
   - N+1 queries?
   - Unnecessary loops?
   - Memory leaks?
   - Blocking operations?

4. **Maintainability**
   - Clear variable names?
   - Functions doing one thing?
   - Complex code commented?
   - Magic numbers extracted?

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

1. Summarize key concerns
2. Highlight what you liked
3. Make clear decision:
   - ✅ Approve
   - 💬 Comment (minor suggestions)
   - 🔄 Request Changes (must address)
4. Offer to pair if complex

レビューコメントを書く前に、チェックリスト、質問の組み立て方、コラボレーション、重大度の判断方法について、references/review-techniques.mdを読んでください。

言語固有のレビュー、アーキテクチャレビュー、テスト品質レビュー、セキュリティレビューの前に、レビューパターンとチェックリストについて、references/review-patterns.mdを読んでください。

難しいフィードバックの伝え方

パターン：サンドイッチ法（応用版）

Traditional: Praise + Criticism + Praise (feels fake)

Better: Context + Specific Issue + Helpful Solution

Example:
"I noticed the payment processing logic is inline in the
controller. This makes it harder to test and reuse.

[Specific Issue]
The calculateTotal() function mixes tax calculation,
discount logic, and database queries, making it difficult
to unit test and reason about.

[Helpful Solution]
Could we extract this into a PaymentService class? That
would make it testable and reusable. I can pair with you
on this if helpful."

意見の相違への対処

When author disagrees with your feedback:

1. **Seek to Understand**
   "Help me understand your approach. What led you to
   choose this pattern?"

2. **Acknowledge Valid Points**
   "That's a good point about X. I hadn't considered that."

3. **Provide Data**
   "I'm concerned about performance. Can we add a benchmark
   to validate the approach?"

4. **Escalate if Needed**
   "Let's get [architect/senior dev] to weigh in on this."

5. **Know When to Let Go**
   If it's working and not a critical issue, approve it.
   Perfection is the enemy of progress.

ベストプラクティス

1. 速やかにレビューする：24 時間以内、できれば当日中に行います
2. PR の規模を抑える：効果的なレビューのため、最大 200-400 行にします
3. 時間を区切ってレビューする：最長 60 分とし、休憩を取ります
4. レビューツールを使う：GitHub、GitLab、または専用ツールを使います
5. 自動化できることは自動化する：リンター、フォーマッター、セキュリティスキャンを活用します
6. 信頼関係を築く：絵文字、称賛、共感が大切です
7. 対応できる状態にする：複雑な問題についてはペア作業を提案します
8. 他の人から学ぶ：他の人のレビューコメントを確認します

よくある落とし穴

• 完璧主義：細かなスタイルの好みを理由に PR をブロックする
• スコープの拡大：「ついでに、これもお願いできますか……」
• 一貫性の欠如：人によって異なる基準を適用する
• レビューの遅延：PR を何日も放置する
• 音信不通：変更を依頼した後、姿を消す
• 形式的な承認：実際にレビューせず承認する
• 些末な議論：取るに足らない詳細について延々と議論する

テンプレート

PR レビューコメントのテンプレート

## Summary

[Brief overview of what was reviewed]

## Strengths

- [What was done well]
- [Good patterns or approaches]

## Required Changes

🔴 [Blocking issue 1]
🔴 [Blocking issue 2]

## Suggestions

💡 [Improvement 1]
💡 [Improvement 2]

## Questions

❓ [Clarification needed on X]
❓ [Alternative approach consideration]

## Verdict

✅ Approve after addressing required changes