Codexにリファクタを任せる前に触る範囲を明示した

はじめに

AI に「このあたりをリファクタして」と頼むと、目的の変更だけでなく、周辺の命名整理、フォーマット、古いコメントの削除まで一緒に入ることがあります。

レビューする側から見ると、機能差分と整理差分が混ざって、何を確認すればよいか分かりにくくなります。そこで、Codex に広めの修正を任せる前に「触ってよい範囲」と「触らない範囲」を先に宣言する運用にしました。

この記事では、実装前にスコープ宣言を置くための最小テンプレートをまとめます。

完成条件の事前宣言そのものは別記事で扱っています。この記事では、特にリファクタで起きやすい「触る範囲が広がって diff が膨らむ」問題に絞ります。

TL;DR / 結論コード

依頼文の先頭に、次のようなスコープ宣言を置きます。

作業スコープ:
- 触ってよい: src/features/schedules/ 配下、関連テスト
- 触らない: 認証、DB schema、package 更新、画面全体のデザイン
- 既存変更: 作業前に git status を確認し、他者変更は戻さない
- 変更方針: 既存パターンに合わせる。新しい抽象化は必要な場合だけ

完成条件:
- 既存テストが通る
- 対象機能の振る舞いが変わらない
- diff にスコープ外の整形が混ざらない

ポイントは、「やること」だけでなく「やらないこと」を同じ粒度で書くことです。

何に詰まったか

AI にリファクタを頼むと、次のような差分が混ざりがちでした。

• 対象ファイルの隣にある無関係な関数まで整形される
• 既存コメントが「不要」と判断されて消える
• 未使用に見えた import が削除される
• ついでに新しい helper や共通化が追加される
• 既存の未コミット変更を、自分の変更のように上書きする

どれも単独では大きな事故に見えません。ただ、レビュー時には「これは依頼した変更か」「既存仕様は変わっていないか」を全部見直す必要があります。

原因

原因は、リファクタ依頼を目的だけで渡していたことでした。

「この処理を整理して」と言うと、AI は整理の対象を広めに解釈します。人間なら暗黙に「このPRの範囲だけ」「既存の未コミット差分は触らない」と判断する場面でも、AI には明示しないと伝わりません。

そこで、依頼文に次の4点を必ず入れるようにしました。

- 触ってよい範囲
- 触らない範囲
- 既存変更の扱い
- 完成条件と確認方法

スコープ宣言の書き方

1. パスで境界を書く

「関連するファイル」ではなく、できるだけパスで書きます。

触ってよい:
- src/renderer/components/SettingsModal.jsx
- src/renderer/hooks/useSchedule.js
- 上記に対応するテスト

触らない:
- package.json / package-lock.json
- DB migration
- 認証処理

AI にとって「関連する」は広すぎます。パスで境界を書くと、diff のレビューもしやすくなります。

2. 既存変更を戻さないと書く

複数エージェントや手元編集が混ざる環境では、作業前の git status が重要です。

作業前に git status を確認する。
自分が触っていない変更は戻さない。
同じファイルに他者変更がある場合は、読んでから最小差分で合わせる。

この1文で、AI が git checkout -- や全面書き換えに寄るリスクを下げられます。

3. 完成条件を diff の形まで含める

リファクタでは、動作確認だけでは不十分です。diff がスコープ内に収まっているかも完成条件に含めます。

完成条件:
- 対象テストが通る
- 既存UIの文言と導線が変わらない
- スコープ外ファイルの整形差分がない
- 新しい抽象化を追加した場合は、既存重複が実際に減っている

注意点

スコープ宣言は、AI の判断を止めるためのものではありません。判断の境界を揃えるためのものです。

「触らない」と書いた範囲に本当にバグ原因がある場合は、AI に無理に修正させず、いったん報告させます。スコープ外を勝手に直すより、次の依頼に分ける方がレビューしやすくなります。

また、スコープを狭くしすぎると、必要なテストや型定義まで触れなくなります。境界を書くときは「関連テスト」「型定義」「ドキュメント更新」など、必要になりやすい周辺だけは明示しておきます。

まとめ

Codex にリファクタを任せる前に、触る範囲を先に書くとレビューが軽くなりました。

• パスで「触ってよい範囲」を書く
• 「触らない範囲」と既存変更の扱いも書く
• 完成条件に diff の収まりを含める

AI に任せる範囲を狭めるというより、レビュー可能な単位に切るための運用です。

参考リンク

• harness17/zenn-articles - 本記事で扱った記事リポジトリ
• AIに「修正して」と頼むと無関係コードまで触られる問題をSurgical Changesルールで抑えた - 小さな修正向けの関連運用
• AIに実装を任せる前に完成条件を宣言するSprint Contract運用 - 完成条件を先に置く関連運用