Claude Codeで「既存コード」を安全に直すためのガードレール7選（リファクタ/バグ修正編）

mizoiです。
Claude Code、勢いよく実装させると強い反面、既存コードに対しては 「盛りすぎ」「広げすぎ」 が起きがちです。

そこで最近は、安全に直すための“ガードレール（制約）”を先に敷いてから Claude Codeにお願いする運用にしています。
この記事では、僕がよく使う 7つのガードレールをテンプレ付きでまとめます。

ガードレールとは？

ここでいう「ガードレール」は、道路のガードレールと同じイメージです。

AIに開発を任せると、便利な反面、

直したい箇所以外まで触って差分が増える
勝手に設計を理想形に寄せる
“ついでに改善”が積み重なってレビューが重くなる

みたいに、目的から外れて横に膨らむことがあります。

そこで、あらかじめ

触っていい範囲
やっていいこと / やらないこと
差分の上限
必ず守る仕様（壊したくない挙動）

を決めておく。これがこの記事でいう「ガードレール」です。

要するに、AIを縛るためのルールというより、
**成果物を安全に着地させるための“開発条件”**です。

前提：AIに任せると事故るパターン

直したい箇所以外まで触って差分がでかくなる
命名/設計を勝手に変える
「ついでに改善」されてレビューが重くなる
テストが置き去りになる

→ これを避けるには、最初に“やらないこと”を明確にするのが効きます。

ガードレール1：変更範囲をファイルで固定する

「このファイルだけ触って」だけで差分が小さくなります。

コピペ用

変更していいファイル：A.dart, B.dart のみ
それ以外は変更しない（import整理や整形も不要）
どうしても必要なら、理由と最小差分を提案して止めて

ガードレール2：目的を“1文”にする（スコープ膨張防止）

目的が2つあると、AIはだいたい盛ります。

例

✅「起動時にクラッシュするのを直す」
❌「クラッシュ直してついでに設計も綺麗にして」

ガードレール3：差分上限を決める（行数/コミット単位）

例

「差分は最大50行以内」
「PRを2つに分ける前提で、まずは手順1だけ」

これだけで「最小変更」を守りやすいです。

ガードレール4：既存の命名/設計を尊重させる

AIは“理想の設計”に寄せがちなので、先に封じます。

コピペ用

既存の命名規則とレイヤ構造（MVVM等）を維持する
クラス分割/抽象化/アーキテクチャ変更はしない
必要なら「提案」だけして、今回は実装しない

ガードレール5：エッジケースと「壊したくない挙動」を明示する

ここを書くだけで事故率が下がります。

例

ログイン済みユーザーの動線は絶対に壊さない
オフライン時は従来通りエラー表示
既存APIのレスポンス形式は変えない

ガードレール6：テストを“後回し禁止”にする

実装後に /test を別タスクにするだけでも効きますが、さらに強くするならこれ。

コピペ用

実装したら必ず「確認手順チェックリスト」を出す
可能ならユニット/Widgetテストも1本追加する
テスト追加が難しいなら理由を書いて、手動確認を厚くする

ガードレール7：コミットメッセージまで先に決める（思考の収束）

地味に効きます。ゴールが固定されます。

例

fix: prevent crash on startup when token is null
refactor: extract url validation helper (no behavior change)

僕が実際に使ってる “依頼テンプレ”

そのまま使える形にしておきます。

目的：〇〇を直す（1文で）
現象：〇〇になる
期待：〇〇になるべき

制約（ガードレール）：
- 変更していいファイル：A, B のみ
- 差分は最大50行（ついで修正禁止）
- 既存の命名/構造は維持（設計変更しない）
- 既存挙動で壊したくない点：〇〇、〇〇
- 実装後に手動確認チェックリストを必ず出す

具体例：リファクタ依頼の言い方（良い例 / 悪い例）

悪い例（盛られやすい）

「この画面を綺麗にして、良い感じにリファクタして」

良い例（差分が小さくなる）

「この関数が肥大化して読みにくい。同じ挙動のまま、private メソッドに切り出して」
「パフォーマンスが悪い。ボトルネック箇所の特定 → 最小差分 で改善案を出して」

さいごに

Claude Codeは“実装速度”が魅力だけど、既存コードは 事故らずに積み上げるのが正義だと思ってます。
そのために、最初にガードレールを敷く運用がめちゃくちゃ効きました。