code-review-playbook

コードレビューのプレイブック

このスキルは、コードの品質を高め、知識を共有し、コラボレーションを促進する効果的なコードレビューのための包括的なフレームワークを提供します。フィードバックを行うレビュアーにも、レビューに備えてコードを準備する作成者にも、このプレイブックはレビューを徹底的で一貫性のある建設的なものにします。

概要

• プルリクエストまたはマージリクエストをレビューする
• レビューに向けてコードを準備する（セルフレビュー）
• チームのコードレビュースタンダードを確立する
• 新しい開発者にレビューのベストプラクティスを教える
• コードの品質に関する意見の相違を解決する
• レビュープロセスと効率を改善する

上流のカバレッジ（内容を繰り返さないこと）

このスキルは薄いラッパーです。一般的なレビューの技法は、他のファーストパーティの資料に記載されています。 ここに記載するのは、OrchestKit 独自の判断のみです。廃止されたファイルから引き継がれたルールについては、Read("references/ork-delta.md") を読み込んでください。

トピック	代わりに参照する資料
レビューの理念、速度、トーン、PR の規模	https://google.github.io/eng-practices/review/
Conventional Comments のラベルと装飾	references/conventional-comments.md、https://conventionalcomments.org/
OWASP Top 10 のレビュー項目	rules/security-baseline.md、https://owasp.org/Top10/
一般的な言語およびフレームワークのレビューチェックリスト	rules/typescript-quality.md、rules/python-quality.md、rules/linting-biome-rules.md
レビューレポートの形式と、複数のエージェントによる PR 全体のレビュー	ork:review-pr
作業ツリーへの指摘事項の適用	/code-review --fix、/simplify（下記参照）
現在のブランチに対するセキュリティのみのレビュー	/security-review
GitHub のレビュー操作（承認、変更のリクエスト、インラインコメント）	https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests

---

Conventional Comments

issue [blocking]: Missing error handling for API call
If the API returns a 500 error, this will crash. Add try/catch.

security [blocking]: API endpoint is not authenticated
The /api/admin/users endpoint is missing auth middleware.

完全な形式、ラベル（praise、nitpick、suggestion、issue、question、security、bug、breaking）、装飾（[blocking]、[non-blocking]、[if-minor]）、および例については、Read("references/conventional-comments.md") を読み込んでください。

---

レビュープロセス

1. レビュー前

コンテキストを確認する：

• PR/MR の説明を読む
• 目的と範囲を把握する
• 関連するチケットや課題を確認する
• CI/CD パイプラインのステータスを確認する

自動チェックを確認する：

• テストに合格している
• リントエラーがない
• 型チェックに合格している
• コードカバレッジが目標を満たしている
• マージコンフリクトがない

時間を確保する：

• 小規模な PR（200 行未満）：15～30 分
• 中規模な PR（200～500 行）：30～60 分
• 大規模な PR（500 行超）：1～2 時間（または分割を依頼する）

2. レビュー中

決まった手順に沿って進める：

1. 概要レビュー（5～10 分）

   • PR の説明を読み、意図を把握する
   • 変更されたファイルをすべてざっと読み、概要をつかむ
   • アーキテクチャの観点から、アプローチに問題がないことを確認する
   • 変更が明記された目的に沿っていることを確認する

2. 詳細レビュー（20～45 分）

   • コードを行ごとにレビューする
   • ロジック、エッジケース、エラー処理を確認する
   • 新しいコードがテストでカバーされていることを確認する
   • セキュリティの脆弱性を探す
   • コードがチームの規約に従っていることを確認する

3. テストに関する検討（5～10 分）

   • テストは包括的か？
   • テストは適切な項目を検証しているか？
   • エッジケースはカバーされているか？
   • テストデータは現実的か？

4. ドキュメントの確認（5 分）

   • 複雑な箇所にコメントがあるか？
   • 公開 API が文書化されているか？
   • 破壊的変更について記載されているか？
   • 必要に応じて README が更新されているか？

3. レビュー後

判断を明確に伝える：

• ✅ 承認：コードはマージ可能です
• 💬 コメント：フィードバックを提供しました。対応は不要です
• 🔄 変更をリクエスト：マージ前に問題への対応が必要です

作成者に返信する：

• 質問に速やかに回答する
• 変更後に再レビューする
• 問題が解決したら承認する
• フィードバックへの対応に感謝を伝える

---

レビューチェックリスト

コード全般の品質

• 可読性：コードが理解しやすい
• 命名：変数と関数に明確で説明的な名前が付いている
• コメント：複雑なロジックが説明されている
• フォーマット：コードがチームのスタイルガイドに従っている
• DRY：不要な重複がない
• SOLID 原則：該当する場合、コードが SOLID に従っている
• 関数のサイズ：関数の役割が明確で、50 行未満である
• 循環的複雑度：関数の複雑度が 10 未満である

セキュリティ

• 認証：保護されたエンドポイントで認証が必須になっている
• 認可：ユーザーが自分のデータにのみアクセスできる
• 入力のサニタイズ：SQL インジェクションと XSS が防止されている
• シークレット管理：認証情報や API キーがハードコードされていない
• 暗号化：機密データが保存時と転送時に暗号化されている
• レート制限：エンドポイントが悪用から保護されている

---

クイックスタートガイド

レビュアー向け：

1. PR の説明を読み、目的を理解する
2. 自動チェックがすべて合格していることを確認する
3. 高い視点でレビューする（アーキテクチャ、アプローチ）
4. 詳細にレビューする（ロジック、エッジケース、テスト）
5. 明確に伝えるため、Conventional Comments を使用する
6. 判定を伝える：承認、コメント、または変更依頼

作成者向け：

1. PR の説明を明確に記述する
2. レビューを依頼する前にセルフレビューを行う
3. 自動チェックがすべて合格していることを確認する
4. PR の範囲を絞り、適切なサイズ（400 行未満）に保つ
5. フィードバックには迅速かつ丁寧に対応する
6. 依頼された変更を行うか、その理由を説明する

---

CC 組み込みレビューコマンド（2.1.152+）

このプレイブックは手動で行うためのフレームワークです。Claude Code には、その一部を自動化する組み込みコマンドが用意されています。

• /code-review — 現在の差分をレビューし、正確性に関するバグと、再利用・簡素化・効率化のための改善点を確認します。
• /code-review --fix（CC 2.1.152+）— レビューを実行した後、検出事項を作業ツリーに適用します（正確性と再利用・簡素化・効率化を対象とするバグ検出レビューです）。
• /code-review --comment — 検出事項をインラインの PR コメントとして投稿します。
• /simplify — CC 2.1.154 で動作が変更されました：現在はクリーンアップのみのレビュー（再利用、簡素化、効率化、高水準の観点）を実行し、修正を適用します。従来のように完全な /code-review --fix のバグ検出を実行することはなくなりました。コードの整理には /simplify、バグ検出と修正には /code-review --fix を使用してください。

組み込みコマンドは、差分に範囲を絞った迅速な確認に使用してください。セキュリティ、テスト、アーキテクチャを含む複数エージェントによる PR 全体のレビューには ork:review-pr を使用してください。

---

スキルのバージョン：2.0.0 最終更新日：2026-01-08 メンテナンス担当：OrchestKit

関連スキル

• ork:architecture-patterns - コードレビュー中にテストとアーキテクチャのベストプラクティスを徹底する
• ork:security-patterns - 手動レビューを補完する認証、入力検証、OWASP のパターン
• ork:testing-unit - レビュー時に検証する単体テストのパターン

ルール

各カテゴリの個別のルールファイルは rules/ にあり、必要に応じて読み込まれます。

カテゴリ	ルール	影響度	主なパターン
TypeScript の品質	rules/typescript-quality.md	高	any を使用しない、Zod による検証、網羅的な switch、React 19
Python の品質	rules/python-quality.md	高	Pydantic v2、ruff、厳格な mypy、非同期タイムアウト
セキュリティベースライン	rules/security-baseline.md	重大	シークレットを含めない、エンドポイントで認証を必須にする、入力検証
リンティング	rules/linting-biome-setup.md	高	Biome のセットアップ、ESLint からの移行、段階的な導入
リンティング	rules/linting-biome-rules.md	高	Biome の設定、型を考慮したルール、CI との統合

合計：4 カテゴリにわたる 5 つのルール

利用可能なスクリプト

• scripts/review-pr.md - GitHub データを自動取得する動的な PR レビュー

  • 自動取得項目：PR のタイトル、作成者、状態、変更されたファイル、差分の統計、コメント数
  • 使用方法：review-pr [PR-number]
  • 必要なもの：GitHub CLI（gh）
  • ライブ PR データには $ARGUMENTS と !command を使用します

• assets/pr-template.md - PR の説明テンプレート

ここにはレビュー報告用のテンプレートが意図的にありません。この出力形式は ork:review-pr が管理します。references/ork-delta.md を参照してください。