> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # コードレビューのやり方 — 観点・コメント・セルフレビュー > コードレビューが組織にもたらす価値、要件の種類ごとに重視する観点、ツールによるチェックの自動化、セルフレビューとコメントの書き方を解説します。 ## 概要 コードレビューとは、変更をマージする前に作成者以外の視点で確認し、その確認結果をもとに、その変更をコードベースの一部として取り込んでよいかを判断する実践です。 このページでは、レビューが組織にもたらす価値から始め、レビュアーが実際に何を確認するのかを見た上で、そのチェック作業をツールがどう肩代わりしてきたかを扱い、最後に自分の変更を先にレビューする・対応しやすいコメントを書くという2つの実践的な習慣で締めくくります。プルリクエスト自体の粒度・テンプレート・タイトルやコミットの規約、そして依頼からマージまでの基本的な流れはすでに整っている前提です。それらは[プルリクエスト](/ja/development/pull-request#レビューを最優先にする)を、変更を検証可能にする土台は[テストコード](/ja/development/testing)を参照してください。 ## レビューが組織にもたらす価値 出荷前に欠陥を見つけることはレビューを行うわかりやすい理由であり、それ自体は本当のことです。ただし、そこで止まってしまうと、レビューが持つ価値の大部分を取りこぼします。 変更を確認する過程で、作成者以外の誰かがその変更を理解せざるを得なくなります。なぜその変更が存在し、どう動くのかという知識が、一人の頭の中だけにとどまることはありません。 規約は、レビューでの「うちではこうしない」という一度きりの指摘から始まります。十分な数のレビューで繰り返されることで、次の作成者がすでに知っているルールになります。チームの共通の基準は、レビュー1回ごとに育っていきます。 レスポンスタイム・セキュリティ上の露出・コード外のルールへの準拠は、失敗するテストとして表面化することがほとんどありません。それらを尋ねるチェックポイントは、レビューだけであることが多くあります。 すでに動いている変更も、さらに良いものへとレビューできます。レビュアーがより良いやり方を提案すれば、「動くかどうか」の基準を守るだけでなく、その基準自体を引き上げます。 ## レビューで確認する観点 | 観点 | 何を確認するか | 例となる問い | | ---------- | --------------------------------------------- | ------------------------------------- | | 機能要件 | 通常ケースと境界ケースの両方で、変更が依頼どおりに動作するか | Issueの受入基準を満たしているか | | 非機能要件 | 挙動以外の制約を満たしているか。パフォーマンス、セキュリティ、コード外のルールへの準拠など | 期待されるレスポンスタイムに収まっているか。新たな攻撃対象を作っていないか | | 設計・アーキテクチャ | 不要な結合を増やさず、既存の構造になじんでいるか | この処理はこのモジュールに置くべきか、それとも別の場所か | | テストスイート | 変更が主張する挙動が、それがないと落ちるテストで裏付けられているか | 修正をrevertしたら、テストが失敗するか | | 可読性・規約 | 作成者に聞かなくても次の読み手が変更を追えるか | この命名は周辺コードの書き方と揃っているか | 機能要件は、Issueの受入基準やチケットの説明として明示されていることがほとんどなので、確認作業は主に、コンパイルが通るかではなく実際に依頼された内容と差分を照らし合わせる作業になります。 非機能要件は見落としやすい観点です。遅いクエリはビルドを失敗させませんし、コンプライアンス上の欠落も例外を投げないため、わざわざ声を上げてくれないからです。 設計の適合・テストスイート・可読性は、確認作業の残りを支えます。設計の適合はその要件が追加される先のコードベースを守り、テストスイートは次にこのコードに触れる人を守り、可読性は変更を保守し続けるコストという、マージ後しばらく経つまで表に出てこないコストを隠したままにしません。 ## ツールがレビューの機械的なチェックを肩代わりしてきた歴史 かつては、上表のすべての観点が人間によって確認されており、レビューとはそれらすべてを目視で見つけることを意味していました。 レビューが長引く要因はいくつかありますが、そのうち最も本質的でないのが、機械がすでに作成者へ伝えられたはずのことを人間が改めて洗い出しているケースです。 lint違反・テストの不足・スタイルガイドですでに決着している命名の不一致などがその典型です。さらに悪いことに、簡単な項目と難しい項目を一緒に洗い出すとレビュアーの注意が分散し、本来判断が必要な項目こそ見落とされやすくなります。 linterやフォーマッタは、まさにこの問題への標準的な解決策として登場しました。命名・フォーマット・そして年々増えていく既知のバグパターンを、人間のレビュアーが差分を開くより前に自動でチェックします。これが現代の多くのチームが前提としている土台です。 セミコロンの付け忘れや命名の不一致を捕まえるためにレビュアーの時間が使われることは、もうありません。すでにツールがそれをやっているからです。 AIはこの発想をさらに一歩進めます。linterが固定的で一般的なルールとしか照合できないのに対し、AIによるチェックはチーム独自のコーディング規約や文脈とも照合できます。これは、以前はそのコードベースをすでに知っている人にしかできなかった種類の判断です。 正解がルール、あるいはチーム独自の規約で決まるもの。 * 命名・コーディング規約への準拠 * 変更行のテストカバレッジ * 固定のルールセットと照合できる既知のバグ・脆弱性パターン 正解が文脈に依存する判断。 * 設計・アーキテクチャが周辺システムになじんでいるか * 変更が実際に要件を満たしているか * セキュリティリスクの受容とマージの最終判断 ```mermaid theme={null} flowchart LR PR[プルリクエスト作成] --> AUTO[機械的なチェック
規約・カバレッジ・既知パターン] AUTO -->|指摘を解消| HUMAN[人間のレビュー
設計・要件整合・セキュリティ判断] HUMAN --> MERGE[マージ] ``` ファインディでは、この機械的なチェックをAIによるセルフレビューに任せ、プルリクエストを作成する前に実行しています。大事なのはルールで判定できる部分と人間の判断が必要な部分を分けておくことです。この考え方がAI生成コード全般にどう当てはまるかは、[Agentic Workflow](/ja/ai/agentic-workflow#aiと人間の責任分担)を参照してください。 この境界は固定されたものではありません。規約が定着し、チームが信頼するチェックが増えるほど、人間の側から機械の側へ移せる項目は増えていきます。ただし、その移行は放置して自然に進むものではなく、チームが意図して決める判断であるべきです。 ## 自分の変更を先にレビューする レビュアーに依頼する前に、初めて見るつもりで差分を読みます。距離を置くと見え方が変わります。書いているときには見えなかった間違いも、他人として変更を見直すと気づけるようになり、ここで見つけたものはすべて、他人の注意力を借りる往復ではなく、その場での修正で済みます。 差分を、自分が書いた順ではなくレビュアーが見る順、つまり上から下へファイルごとに、途中で直さずに読み通すと、最初にぶつかった1件だけでなく、レビュアーが気づくのと同じ粗い箇所に気づけます。 ```markdown セルフレビューチェックリストの例 theme={null} ## レビュー依頼前に確認する - [ ] 変更した行はすべて、それがないと落ちるテストで裏付けられている - [ ] シークレット・認証情報・環境変数の値がハードコードされてコミットされていない - [ ] 命名・構造が周辺コードと揃っている - [ ] デバッグ用の出力・コメントアウトされたコード・Issueへのリンクがないままの TODO が残っていない - [ ] Issueに記載された受入基準を満たしている ``` チェックリスト自体もバージョン管理下に置き、他の規約と同じように見直します。セルフレビューで見逃した項目を後から人間が見つけたら、その見逃しを追加し、同じ抜け漏れが繰り返されないようにします。 ## レビューコメントの書き方 コメントの役目は、往復を最小限にして正しい修正にたどり着かせることです。そのためには、作成者がコメントの意味も緊急度も推測せずに行動へ移せる必要があります。 曖昧な反応は、その推測作業を作成者へ押し付けます。「これは違和感があります」だけでは、何が問題で、どこにあり、マージをブロックするのかどうかがわかりません。反応だけでなく具体的な場所と理由を書くと、コメントは先に解くべきパズルではなく、そのまま行動できるものになります。 コメントの先頭に、その重みを示す短いラベルを付けると、もう1つの推測作業をなくせます。よく使われるラベルの組み合わせは次のとおりです。 | ラベル | 意味 | | ------ | ------------------------- | | `must` | マージ前に対応が必須 | | `imo` | レビュアー自身の意見。適用するかは作成者が判断する | | `nits` | ブロックしない些細な指摘（typoやスタイルなど） | | `ask` | まだ判断ではなく、純粋な質問 | ```text 曖昧なコメント theme={null} これは違和感があります。 ``` ```text ラベル付きで具体的なコメント theme={null} [must] 共有している`order`オブジェクトを直接書き換えているため、呼び出し元が保持するコピーも変わってしまいます。引数を書き換えず、新しいオブジェクトを返してください。 ``` 可能であれば、問題を指摘するだけでなく修正案まで示します。そうすると、議論の往復が確認の往復に変わります。正解が本当にわからない場合は、断定より質問を選びます。不確かな点を質問として投げかけると、その主張自体が間違っている可能性を巡って議論するのではなく、レビュアーにはなく作成者だけが持つ文脈を引き出せます。 ## 関連ページ レビューを依頼し、その結果を適用する場所。粒度・テンプレート・マージの仕組みを扱います。 そもそも変更を検証可能にするもの。レビューがテストコードに対して確認するパターン。 上記の機械的なチェックと判断の分担が土台とする、AI生成コード全般に対するAIと人間の広範な責任分担。 AIが生成したコードの検証責任が、レビューに届く前から人間に残り続ける理由。