1人開発のコードレビューをAIに任せる：検出はAI、範囲と再現の判断は人間が持つ運用を、Issueの記録から見直す

1人開発のいちばんの弱点は、レビュアーがいないことです。チーム開発なら当たり前のコードレビューがなく、書いたコードがそのまま本番に入ります。

そこで、コミット前の品質チェックを CLAUDE.md に書き、AI に実行させています。ただし、AI に最終的な判断は任せていません。AI は問題を見つける役で、見つかった問題をどこまで、いつ直すかは人間が決めます。

この記事では、その手順と、AI のレビューが実際に見つけた指摘、それを人間がどう扱ったかを、Issue に残っている記録から書きます。

レビューの無い開発で起きたこと

この記事を書く1週間ほど前に、次の事故が見つかりました。

監視のジョブが、外部サービスの認証キーを環境変数から読んでいました。ところが、ジョブを起動する設定ファイルにその環境変数を書いていなかったため、キーが空のままでした。キーが空だと、監視の機能は動かずに黙って処理を飛ばす作りでした。本番と検証環境の両方で、監視は16日間止まっていました。

同じキーを使う別のスクリプトは、自分で設定ファイル（.env）を読み込んでいたので、正常に動いていました。そのため、どこも落ちず、エラーも出ませんでした。

この事故は、コードの差分だけを見るレビューでは見つけにくい種類のものです。コードには誤りがなく、問題は実行環境の設定の側にあったからです。AI のレビューで防げるものと、防げないものがあることを、最初に押さえておく必要がありました。

CLAUDE.md に書いている手順

コードを変えたら、コミットの前に次の手順を実行するように、CLAUDE.md に書いています。

1
## Post-Implementation QA Workflow
2

3
コード変更完了後、Git commit前に実行:
4

5
1. /sc:analyze → 品質・セキュリティ・パフォーマンス分析（必須）
6
2. テスト実行（pytest 直接 or /sc:test）（必須）
7
3. /sc:improve → 改善提案（大規模施策のみ。軽微な修正ではスキップ可）
8
4. /sc:document → ドキュメント更新（大規模施策のみ。軽微な修正ではスキップ可）
9

10
例外（全スキップ可）: md/設定ファイルのみの変更、コメント/空白のみの変更、
11
軽微な修正（単一ファイル・100行未満・ロジック変更なし・既存テストで網羅済み）

必須は、分析とテストの2つだけです。改善の提案とドキュメントの更新は、大きな施策のときだけにしています。小さな修正のたびに4つすべてを回すと、時間がかかるわりに得るものが少ないからです。

1つ注意があります。これは CLAUDE.md の指示で、フックなどの仕組みで強制しているわけではありません。AI が手順を飛ばすことはありえます。

実際、直近にマージした PR 200本のうち、本文で分析（/sc:analyze）に触れていたのは37本でした。ドキュメントや設定だけの変更など、例外として分析を省いてよい PR も含まれるので、残りがすべて手順を飛ばしたとは言えません。ただ、PR を読むだけでは、分析を実行したかどうかを確かめられない状態です。PR のテンプレートに分析の結果を書く欄を設けるのが、次の手だと考えています。

AI のレビューが実際に見つけたもの

Issue に残っている記録から、AI の分析が見つけた指摘を3つ挙げます。

1. 同じ役割の関数が、もう1つあった

上流のデータに新しい形式の ID が混ざり、検証の正規表現を直す PR を作りました。その PR の分析で、AI は修正した箇所とは別のモジュールに、ID を正規化する関数がもう1つあることを見つけました。

その関数には入力の文字の種類を確かめるガードが無く、新しい形式の ID を切り詰める作りでした。修正した PR の範囲の外にあった問題です。経緯は「同じ新形式のIDを、正規化は素通しし、検証は全件弾いた」に書いています。

2. 同じ定数が、2か所に手写しされていた

外部のサービスに書き込む機能を試作した PR の分析では、「外部に影響を与えるモード」の一覧が、2つのモジュールに手で写されていることが指摘されました。2つを結び付けるテストもありませんでした。

今のコードは正しく動きます。しかし、片方にモードを足したときに、もう片方が古いまま残り、検査をすり抜ける経路ができます。差分を読むだけの人間のレビューでは、見落としやすい種類の問題です。

3. 急ぎの修正に、古いコメントと重複が残っていた

外部サービスへの接続を見張るシェルスクリプトを、急ぎで直した PR の分析では、次の3点が見つかりました。

• スクリプトの冒頭のコメントが、実際の起動方式と食い違っていた（修正より前からの食い違い）
• 同じ4行の処理が、2か所に重複していた
• ファイルが消えるタイミングによっては、コマンドの失敗でスクリプトが異常終了しうる箇所があった

どれも、AI が得意な「パターンとして見つけられる問題」です。

人間が判断したこと

AI が問題を見つけたあと、どう扱うかは人間が決めました。記録を見ると、判断は3つの形で出ています。

範囲から外す

3つめの急ぎの修正では、見つかった3点を、その PR には入れませんでした。本番の障害を止めるための修正だったので、範囲を広げずにマージし、3点は別の Issue に分けました。

3点は4日後に別の PR で直しました。同じ Issue に書いた残りのリスク1件は、本番の観察が落ち着くまで保留にしています。

再現するまで直さない

2つめの試作の PR では、AI の指摘を「再現できた（CONFIRMED）」と「エージェントの報告だけ（Plausible）」に分けて記録しました。

重大度の高い4件はその PR の中で直し、残りは Issue に集約しました。そのうち「エージェントは再現したと報告しているが、こちらではまだ再現していない」1件は、「着手する前に、自分で再現して確定する」と書き、すぐには直しませんでした。後のフェーズで再現を確かめてから直しています。

AI の報告は、それだけでは事実として扱いません。この考え方は「AIの報告を鵜呑みにしない」に書きました。

優先度を決める

1つめの正規化の関数は、AI の指摘のとおり新しい形式を切り詰める作りでしたが、優先度は「中」にしました。その時点で対象のデータに新しい形式が1件もなく、照会の側で元に戻ってもいたので、すぐには害が出ないと判断したからです。

PR を突き返すのではなく、範囲と順番を決める

マージせずに閉じた PR は、記録の中に1本もありませんでした。人間の判断は、PR を突き返す形ではなく、「この PR で直すもの」「後で直すもの」「確かめてから直すもの」に指摘を振り分ける形で出ています。

1人開発では、PR を書くのも読むのも自分（と AI）です。突き返す相手がいないので、振り分けがレビューの判断の中心になります。

AI が見つけにくいもの

上の3つの指摘は、どれも重複や食い違いといった、コードの中で形として見つけられる問題でした。逆に、次のようなものは見つけにくいと考えています。

冒頭の16日間の事故は、1つめの種類にあたります。この事故のあとには、スクリプト自身が設定ファイルを読み込むように直し、教訓をルールとして文書に残しました。

効果は数えていない

この運用で事故が何件減ったかは、数えられていません。

障害の Issue に付けているラベルで月ごとに数えると、1件の月も29件の月もあります。ただ、どの変更で何が防げたかを記録していないので、この件数をレビューの効果として読むことはできません。

言えるのは、上に挙げたように、AI の分析が人間の見落としやすい問題を実際に見つけていたこと、そしてそれを人間が振り分けていたことまでです。効果を数えるなら、「分析が見つけた指摘のうち、直したもの、後回しにしたもの、見送ったもの」を記録していく必要があります。

まとめ

AI のレビューは、レビュアーの代わりではなく、見落としを見つける道具として使っています。見つかったものをどこまで、いつ直すかを決めるのは人間で、その判断が1人開発のレビューの中心になります。施策の進め方全体は「施策ワークフロー」にまとめています。