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 nullrefactor: extract url validation helper (no behavior change)
僕が実際に使ってる “依頼テンプレ”
そのまま使える形にしておきます。
目的：〇〇を直す（1文で）
現象：〇〇になる
期待：〇〇になるべき
制約（ガードレール）：
- 変更していいファイル：A, B のみ
- 差分は最大50行（ついで修正禁止）
- 既存の命名/構造は維持（設計変更しない）
- 既存挙動で壊したくない点：〇〇、〇〇
- 実装後に手動確認チェックリストを必ず出す
具体例：リファクタ依頼の言い方（良い例 / 悪い例）
悪い例（盛られやすい）
- 「この画面を綺麗にして、良い感じにリファクタして」
良い例（差分が小さくなる）
- 「この関数が肥大化して読みにくい。同じ挙動のまま、
privateメソッドに切り出して」 - 「パフォーマンスが悪い。ボトルネック箇所の特定 → 最小差分 で改善案を出して」
さいごに
Claude Codeは“実装速度”が魅力だけど、既存コードは 事故らずに積み上げるのが正義だと思ってます。
そのために、最初にガードレールを敷く運用がめちゃくちゃ効きました。