実際のレビュー指摘から Claude Code のルールを改善する

Last updated at 2026-08-09Posted at 2026-08-09

はじめに

前回の記事で、CLAUDE.md に書くこと・書かないことの判断基準をまとめました。要点は「消しても Claude がミスしないルールは削除する」です。

今回はこの基準を、チームのリポジトリのコーディング規約（.claude/rules/）に以下の手順で適用してみました。

直近3ヶ月のチームの人間レビュアーのコメント約400件を調べてみました。すると、頻繁に出てくる指摘の多くが、既に規約ファイルに文書化されている内容でした。

規約ファイルは AI のコンテキストに毎回読み込まれています。しかし、公式ドキュメントでは、これは強制ではなくあくまでコンテキストで、長いファイルはコンテキストを消費し遵守を下げると警告されています。

そこで、AI が読んで従える形に規約を作り直すことにしました。以下はその作業記録です。

約400件の指摘を分類すると、リポジトリの構造や扱うデータに起因する頻出するバグのパターンが見つかりました。

これを新しいルールファイル1つにまとめました。採用基準は2つです。

このファイルは常時読み込みにしました。レビューで見つけるより前の、コードを書いている時点で防げるようにします。

もともとあった規約ファイルを前記事の基準で見直しました。「書く価値がない」として実際に削ったのは次のようなものです。

標準知識を教えるコード例：try/finally の書き方、?? と || の違いなど、Claude が既に知っていることの NG/OK 例
→ 数十行のコード例を、検証可能な指示文数行に置き換える
同じ規約の重複記載：規約がスキルとエージェント定義の2箇所に書かれ、実際に内容が乖離していた
→ 定義は1箇所にして、他は参照だけにする

判断に迷ったときは「この記述の有無で、実際にコードを書く AI の行動が変わるか」を確認し、変わらないなら削除します。

規約の作り直しという編集作業ではミスが起きました。今回は次の2つの方法で検証し、ミスを見つけました。

1. 移動元の文と1行ずつ突き合わせる：削りすぎて落ちた情報がないか確かめる

2. 別コンテキストの Claude にレビューさせる：書いた本人の判断に引きずられずに、意味の変化や矛盾がないか確かめる

書き直した規約に効果があるのか、過去のプルリクエスト5件で確かめました。

最初は、人間レビュアーの指摘を正解表にして検出率を測ろうとして、失敗しました。人間の指摘はマージ前に修正されるため、マージ後のコードを対象にすると「直された欠陥は見つからなくて正解」になります。測るなら、レビューが付く前の時点のコミットを対象にすべきでした。

そこで、同じ PR を旧規約と新規約のレビュアーに別々にレビューさせて、検出内容を突き合わせる方法に切り替えました。レビュアーは同一モデルで、コンテキストだけ分けています。計12試行で、1件の PR は結果のばらつきを見るため新旧2回ずつレビューさせました。

以下のことがわかりました。

旧規約のレビュアーも重要な欠陥を見つけていました。新規約では、見つかる欠陥が増え、レビュー結果が安定しました。