--max-findings 5 を設定した後、システムはどの5件を残しどれを除外するか、どう決定するのか？
公開されている説明は具体的なランキングアルゴリズムを詳述していないが、このパラメータの設計目的（レビュアーに提示される指摘数の上限を制御する）から合理的に推測すると、システムは内部で完全な問題検出を先に完了し、その後何らかの重要度または深刻度のランキングロジックに従って上位数件のみを返すと考えられる——つまり「見つける数が少ない」ことと「すべて見つけているが最も重要なもののみ報告する」ことは別物であり、--max-findings は後者を行う。
もし上限5件のレビューで自分が重要だと考える問題が漏れていたと気づいた場合、実用的な対処法は all で再度実行して完全なリストを取得し比較することだ。ランキングロジックが自分の判断とずれているのか、それともその問題がそもそも検出されていなかったのかを確認できる。
チーム内の異なる人が同じレビューに異なる --max-findings の数値を設定した場合、各自が見るレビュー結果の品質に不整合が生じる可能性はあるか？
理論上は、ある意味で生じる。システム内部のランキングロジックが固定されており、設定する数値によって「最も重要」と判定される問題が変わらないと仮定すれば、小さい数値を設定した人は完全なリストのサブセットを見ているだけで、品質の低いレビュー結果を見ているわけではない——しかし実務上、チーム内である人が3を、別の人が20を習慣的に設定していると、「今回のレビューは問題Xを捉えたか」という議論の際に、各自が見ているリストの長さが違うことで認識のずれが生じ、レビュー品質が不安定だと誤解されやすい。実際には提示範囲が異なるだけである。
--max-findings default と、このパラメータを付けずに /code-review を実行するのとで、結果は同じになるか？
パラメータの設計ロジックから推測すると、同じになるはずだ——default オプションが存在する意味は、スクリプトや設定ファイルで「システムのデフォルト値を使う」という意図を明示的に書けるようにすることにあり、パラメータを省略して挙動が暗黙的にデフォルトに落ち着くのとは異なる。対話的に手動でコマンドを入力するシナリオでは、両者の効果に理論上の違いはないはずだが、/code-review を自動化スクリプトに組み込んでいる場合、--max-findings default と明示的に書くことで、後でそのスクリプトを読む人に「これは意図的にデフォルト動作を選択している」ことがより明確に伝わり、「このパラメータの設定を忘れた」のではないとわかる。
/code-review をチームのワークフローに導入し始めたばかりのチームにとって、--max-findings はどの数字から試すべきか？
万能な数字はないが、合理的な出発点は、まず all で何度か完全なレビューを実行し、典型的な PR が通常どれくらいの指摘数を生み出すか、そのうち実際に対応される割合がおおよそどれくらいかを実際に観察することだ。中規模の PR が頻繁に30件以上の指摘を生み出すが、チームが実際に対応するのは上位5〜8件に集中していることに気づいたなら、日常のデフォルト値をその範囲に設定する方が、何もないところから数字を推測するよりもチームの実際のレビュー行動パターンに近くなる。
Claude Code の /code-review コマンドでコードレビューを行う際、よくある実務上の悩みは次のようなものだ：変更範囲が大きいコミットや PR にレビューを実行すると、Claude が一度に数十件の指摘を返すことがあり、重大なロジックエラーから些細な命名の提案まで混在し、レビュアーはこれらの提案のうち本当に対応すべきものをふるい分けるために余計な労力を費やすことになる。最近のリリースで追加された --max-findings パラメータにより、今回のレビューが返す指摘数の上限を直接制御できるようになった。
/code-review --max-findings <n>|all|default は3つの指定方法をサポートする：具体的な数値を与える（例：--max-findings 5）と、今回のレビューは最大5件の指摘しか返さない；all を指定すると上限なしで見つかったすべての問題を返す；default を指定すると、システム本来のデフォルト動作に従う。このパラメータにより、「レビュー範囲が広く、網羅的にチェックしたい」場合と「レビュー範囲が狭く、最も重要な問題だけを素早く確認したい」場合を、1つのパラメータで直接切り替えられ、毎回長いリストから手動でふるい分ける必要がなくなる。
コードレビューツールの出力品質は、「問題を捉えられているか」だけでなく、「提示の仕方がレビュアーの認知負荷を生んでいないか」も重要だ。一度に指摘を出しすぎると、個々の指摘が妥当であっても、レビュアーの注意が本当に重要な問題から逸れてしまう——これは人間によるコードレビューで「レビューコメントが多すぎて、かえって全部そのまま受け入れたくなる」という現象と似たリスクである。指摘数を制限することは、システムに重要度で問題を順位付けさせ、最も優先すべき数件のみを返すよう強制することに等しく、限られた時間内にレビューを完了する必要があるシナリオで特に有用だ。
マージをブロックする重要な問題（セキュリティ脆弱性、ロジックエラーなど）をまず捉えることを目的とした PR レビューの素早い一次スクリーニング段階であれば、小さい数値（3〜5程度）を設定する方が適している——これによりシステムは最も深刻と判断した数件のみを報告するよう強制され、それらを優先的に対応してから、より網羅的なレビューが必要か判断できる。大規模リファクタリング前の健全性チェックのような、一回限りの網羅的なコード品質点検を行う場合は、all を使ってすべての指摘を返す方が適切だ。このシナリオで本当に必要なのは、フィルタリングされたサブセットではなく完全な問題リストだからだ。
チームが既に /code-review を日常の PR レビューフローに組み込んでいる場合、--max-findings はチームの標準作業手順に組み込む価値があり、完全なリストを確認するかどうかを各自の判断に任せるべきではない——より合理的なのは、異なるレビューの文脈（素早い一次レビュー vs. マージ前の最終レビュー）ごとに異なるデフォルト値を設定し、チームのコードレビューガイドラインに明記することで、レビューの厳密さをレビューの緊急度に合わせ、毎回同じ「全部リストして自分でふるい分ける」方式で不要なレビュー時間コストを増やさないようにすることだ。