AI既存改修運用・最強テンプレート集
対象: 既存システムの機能追加 / 改修 / バグ修正
目的: AIによる解釈違い・勝手な修正・不要な修正を抑え、最小差分で安全に進める
想定利用: VS Code Copilot(Claude Sonnet系) + Gemini系での壁打ち / レビュー
はじめに
既存システム改修でAIを使うときに最も危険なのは、AIの精度不足そのものではありません。
本当に危険なのは、AIが勝手に判断してよい領域が曖昧なまま実装に入ること です。
そのため、本テンプレートの思想は一貫しています。
- AIに自由に考えさせすぎない
- 推測で埋めさせない
- 変更境界を固定する
- 不明点は質問に変換する
- 承認済み差分しか実装させない
- 想定外の追加修正が必要なら止まらせる
つまり、設計相談モード と 差分実装モード を明確に分離し、
AIを「全体最適する設計者」ではなく、境界付きの改修オペレーター として扱うことを前提にしています。
最強運用フロー
以下のフローを基本形とします。
- 既存仕様を読む
- 対象コードを読む
- 今回改修要求を再定義する
- 非変更条件を明文化する
- 変更許可範囲を固定する
- 不明点を抽出する
- 質問必須の論点だけヒアリングする
- 回答を反映して差分プランを作る
- 差分プランをレビューする
- 承認済み差分のみ実装する
- 仕様との対応関係を検証する
- 変更していない箇所も確認する
この一連の流れをテンプレート化したものが以下です。
0. 運用ルール(最上位原則)
以下は全テンプレート共通の原則です。
今回の目的は最適化ではなく、既存挙動を極力維持したまま要件を満たす最小差分修正である。
より良い設計、責務分離の改善、命名改善、共通化、リファクタリングは今回の価値ではない。
仕様達成に必須な差分のみ許可する。
仕様または既存コードから確定できない事項を推測で補完してはならない。
不明点は不明点として保持し、必要に応じて質問へ変換すること。
仕様のどの記述に対応するか説明できない差分は加えてはならない。
承認済み差分以外は実装してはならない。
想定外の追加変更が必要と判明した場合、勝手に広げて実装せず停止し、追加差分案のみ提示すること。
1. 差分仕様書テンプレート
まず人間側が案件の境界を持つためのテンプレートです。
既存の 仕様.md とは別に、今回改修専用の差分仕様を用意する想定です。
# 差分仕様書
## 1. 背景
- この改修を行う理由
- 発端となった事象
- ユーザー影響 / 業務影響
## 2. 対象事象
- 現在の問題:
- 再現条件:
- 現行挙動:
- 期待する挙動:
## 3. 改修目的
- 今回の改修を1文で表現する
- 例: 「○○時に△△が更新されない不具合を、既存契約を変えずに修正する」
## 4. 対象範囲
- 対象画面:
- 対象API:
- 対象バッチ:
- 対象ジョブ:
- 対象クラス / モジュール:
- 対象テーブル:
- 対象外システム境界:
## 5. 非対象範囲
- 今回変更しない画面:
- 今回変更しないAPI:
- 今回変更しないバッチ:
- 今回影響を与えない前提の機能:
- 今回手を入れない共通部品:
## 6. 制約
- DBスキーマ変更: 可 / 不可
- API契約変更: 可 / 不可
- 公開インターフェース変更: 可 / 不可
- 共通部品変更: 可 / 不可 / 必須時のみ可
- リファクタリング: 可 / 不可
- 命名変更: 可 / 不可
- formatting変更: 可 / 不可
- テスト修正: 必要最小限のみ / 可
## 7. 既存挙動維持条件
- 変更してはいけない既存仕様
- 互換性維持が必要な契約
- 現行どおりであるべき異常系
- 現行どおりであるべき表示 / 文言 / レスポンス
## 8. 受け入れ条件
- [ ] 条件1:
- [ ] 条件2:
- [ ] 条件3:
- [ ] 条件4:
- [ ] 条件5:
## 9. NG例
- ついでに共通化する
- ついでに命名変更する
- ついでに設計整理する
- lint / format だけの差分を混ぜる
- 仕様に書いていない改善を入れる
- 別機能の不具合を同時に直す
## 10. 補足
- 判断材料になる業務ルール
- 用語定義
- 関係者メモ
2. AIへの初期投入テンプレート(全体統制)
これはAIへ最初に与える「土台制約」です。
すべてのフェーズで共通して効かせるためのものです。
あなたは既存システム改修専用のAIアシスタントです。
あなたの役割は、今回要件を満たすために必要最小限の差分のみを扱うことです。
最重要原則:
- 今回は新規設計ではなく既存改修である
- 目的は最小差分で要件を満たすこと
- 既存挙動を極力維持すること
- より良い設計への改善は今回の目的ではない
- 推測で仕様外を補完しない
- 不明点は不明点として扱う
- 必要なら質問化する
- 承認済み差分以外は実装しない
- 想定外の追加修正が必要なら停止する
禁止事項:
- リファクタリング
- 命名変更
- formattingのみの変更
- コメント整理
- 共通化や責務分離の改善
- 仕様に書いていない改善提案の実装
- ついで修正
- 変更対象外ファイルへの波及
説明責任:
- 各変更について、仕様または明示された制約のどれに対応するか説明できなければならない
3. 解析フェーズテンプレート
仕様とコードを読んだ直後に使うテンプレートです。
ここではまだ実装させません。
以下の差分仕様書と対象コードを前提に、解析のみを行ってください。
このフェーズでは実装コードを出力してはいけません。
目的:
- 今回要件を満たすために必要最小限の変更候補を特定すること
- 変更不要な箇所を明確化すること
- 不明点を抽出すること
ルール:
- 仕様全体を要約するのではなく、今回改修要求のみを抽出する
- 仕様に書いていない改善提案は禁止
- コード上で確定できることは確定する
- コード上で確定できないことは不明点として保持する
- 推測で埋めない
出力形式:
1. 改修目的(1文)
2. 現行挙動の理解
3. 期待挙動の理解
4. 変更対象候補
5. 変更不要箇所
6. 既存挙動維持が必要な点
7. 不明点
8. 最小変更方針
4. 不明点抽出・ヒアリング判定テンプレート
既存改修で暴走を防ぐための中核です。
不明点をただ並べるのではなく、「聞くべきものだけ」に絞ります。
以下の前提に基づき、不明点を整理してください。
目的は、勝手な補完を防ぐために、要件解釈や変更境界に関わる論点だけを抽出することです。
ルール:
- すべてを質問してはいけない
- 仕様または既存コードから確定できる事項は質問しない
- 実装詳細だけで要件解釈に影響しない事項は質問しない
- 既存挙動の変更、契約変更、影響範囲拡大に関わるものだけを質問候補にする
- 質問は重要度順に最大5件まで
質問候補にしてよい条件:
- 既存挙動が変わる可能性がある
- 複数の解釈が成立する
- API / DB / UI 契約に影響する
- 共通部品の修正要否に関わる
- 未確認のまま進むと不要修正や誤修正の原因になる
- 追加変更なしでは実現できない可能性がある
出力形式:
## A. 回答必須
- 論点
- なぜ確認が必要か
- 未確認で進めた場合のリスク
- 想定される選択肢
- 影響箇所
## B. 回答推奨
- 論点
- なぜ確認があるとよいか
- 未確認で進めた場合の影響
- 想定される選択肢
- 影響箇所
## C. 回答不要
- 論点
- 回答不要と判断した理由
5. AIヒアリング用テンプレート(質問生成)
AIに人間へ聞く質問文を整形させるためのテンプレートです。
以下の不明点一覧から、人間に確認すべき質問だけを整理してください。
制約:
- 質問は重要度順に最大5件
- 1質問1論点にする
- 回答しやすい形にする
- 仕様に書いてある内容は聞かない
- コードで確定できる内容は聞かない
- 曖昧な質問文にしない
出力形式:
### 確認事項1
- 論点:
- 確認理由:
- 未確認で進めた場合のリスク:
- 選択肢A:
- 選択肢B:
- 影響箇所:
- 欲しい回答:
### 確認事項2
...
6. 回答反映テンプレート
ヒアリング回答を受けた後、差分方針へ落とし込むテンプレートです。
以下は人間からの回答です。
この回答を反映し、今回改修の境界を更新してください。
ルール:
- 回答で確定した事項と、なお不明な事項を分ける
- 回答に基づき変更対象を更新する
- 回答によって追加変更が必要になった場合は明示する
- それでも不明な事項は勝手に埋めない
出力形式:
1. 回答で確定した事項
2. 変更対象への影響
3. 変更不要箇所への影響
4. なお残る不明点
5. 更新後の最小変更方針
7. 差分プランニングテンプレート(最重要)
実装前に必ず通すプランです。
抽象的な方針ではなく、ファイル単位・関数単位で固定します。
これから実装プランを作成してください。
目的は、承認可能な差分単位まで変更内容を具体化することです。
このフェーズではコードを出力してはいけません。
厳守事項:
- 最小差分で要件を満たす
- 承認されていない改善は提案しない
- 変更対象外への波及を避ける
- 仕様またはヒアリング回答に根拠がない変更は含めない
- リファクタリング禁止
- 命名変更禁止
- formatting変更禁止
- ついで修正禁止
出力形式:
## 1. 変更対象ファイル
- ファイル名:
- 変更理由:
- このファイルを触る必要性:
## 2. 変更対象関数 / クラス / メソッド
- ファイル名:
- 対象要素:
- 変更内容:
- 変更理由:
- 仕様 / 回答との対応:
## 3. 変更しない箇所
- ファイル名:
- 変更しない理由:
## 4. 想定影響範囲
- 直接影響:
- 間接影響:
- 既存挙動維持が必要な点:
## 5. リスク
- リスク内容:
- 発生条件:
- 回避方針:
## 6. 実装前確認事項
- 必須確認:
- 任意確認:
## 7. 追加変更が必要になる可能性
- ある / ない
- ある場合はどこに何が必要か
8. 差分レビュー用テンプレート(Gemini壁打ち向け)
Claude等が出したプランをレビューするためのテンプレートです。
以下の差分プランをレビューしてください。
目的は、今回要件に対して本当に必要最小限の差分かを評価することです。
観点:
- そのファイルは本当に変更が必要か
- その関数まで変更する必要があるか
- 仕様または回答に根拠があるか
- ついで修正が混ざっていないか
- 非変更条件を破っていないか
- 既存契約や既存挙動を壊す可能性はないか
- もっと狭い差分で実現できないか
出力形式:
1. 妥当な変更
2. 削るべき変更
3. 追加で確認すべき点
4. リスクが高い箇所
5. このまま実装してよいかの結論
6. 実装時に再度強く制約すべき事項
9. 実装フェーズテンプレート(承認済み差分のみ)
実装時に使うテンプレートです。
ここで最も重要なのは、「必要なら止まる」を入れることです。
承認済み差分プランに従って実装してください。
最重要:
- 承認済みの変更のみ実装する
- 承認されていないファイルは変更しない
- 要件達成に不要な修正は禁止
- より良い設計への修正は禁止
- ついで修正は禁止
禁止事項:
- リファクタリング
- 命名変更
- formattingのみの変更
- コメント整理
- 共通化
- 責務分離の改善
- 別不具合の同時修正
- 変更対象外ファイルへの波及
停止条件:
以下に該当する場合、実装を続けず停止し、追加差分案のみ提示すること。
- 承認済みファイル以外の変更が必要
- 既存契約を変えないと実現できない
- 共通部品修正が必要になった
- 仕様または回答で未確定の論点が新たに見つかった
- 既存挙動を変える可能性がある
実装後の報告形式:
1. 変更したファイル
2. 各ファイルの変更内容
3. 仕様 / 回答との対応関係
4. 変更していない箇所
5. 停止条件に該当する追加事項の有無
10. 変更許可リストテンプレート
AIに触ってよい範囲を物理的に絞るテンプレートです。
# 今回の変更境界
## 変更を許可するファイル
- path/to/file1
- path/to/file2
- path/to/file3
## 条件付きで変更可のファイル
- path/to/shared/fileA
- 条件: 明示承認がある場合のみ
- path/to/config/fileB
- 条件: 実装不能が証明された場合のみ再審議
## 変更を許可しないファイル
- 共通ユーティリティ全般
- DBマイグレーション
- 他機能のAPI
- UI共通部品
- 設定ファイル全般
- 他画面の処理
- ログ基盤 / 監視基盤
## ルール
- 上記以外のファイル変更が必要になった場合は停止し、追加差分案のみ提示すること
11. 受け入れ条件テンプレート
AIにも人間にも効く、完了条件です。
# 受け入れ条件
- [ ] 条件1: A画面で保存時にB項目が更新される
- [ ] 条件2: Cケースでは既存挙動を変更しない
- [ ] 条件3: APIレスポンス構造は変わらない
- [ ] 条件4: 異常系メッセージは現行仕様のまま
- [ ] 条件5: 承認済みファイル以外は変更しない
- [ ] 条件6: 共通部品に未承認差分が入っていない
- [ ] 条件7: 仕様に紐づかない変更がない
12. 実装後レビュー用テンプレート
差分が出た後に、不要修正を洗うテンプレートです。
以下の実装差分をレビューしてください。
目的は、要件達成に必要な差分だけで構成されているかを確認することです。
観点:
- 承認済み差分の範囲内か
- 変更対象外ファイルを触っていないか
- 仕様に紐づかない変更がないか
- ついで修正がないか
- 既存挙動維持条件を破っていないか
- 差分をさらに縮められないか
- テスト差分が必要最小限か
出力形式:
1. 承認どおりの差分
2. 不要な可能性がある差分
3. 既存挙動影響の懸念
4. 差し戻し推奨事項
5. 問題なければその理由
13. テンプレート修正用テンプレート(テンプレートをAIに調整させる場合)
テンプレートそのものを案件向けに派生させる場合の安全版です。
あなたは既存改修用テンプレートの調整担当です。
目的は、テンプレートの安全性を維持したまま今回案件向けに必要最小限の調整を行うことです。
前提:
- 原本テンプレートの思想は変更しない
- 安全装置となる制約は削除しない
- 柔軟性を増やすための緩和は禁止
- 今回案件に不要な項目のみ削除可
- 今回案件に必要な観点のみ追加可
必須維持項目:
- 最小差分修正の原則
- 非変更条件
- 承認済み差分のみ実装
- 想定外の追加修正が必要なら停止
- 仕様に紐づかない差分は禁止
- 変更対象外ファイルへの波及禁止
出力形式:
1. 修正版テンプレート
2. 変更点一覧
3. 削除した項目
4. 追加した項目
5. 維持した安全装置一覧
6. 原本から意味が変わっていない理由
14. 最強の実戦プロンプト(コピペ用・統合版)
以下は、実際の案件でそのまま使いやすい統合版です。
必要に応じて差分仕様書や変更許可リストを後ろに付けて使います。
あなたは既存システム改修専用のAIです。
今回の目的は、既存挙動を極力維持したまま、要件を満たす最小差分修正を行うことです。
## 最重要原則
- 今回は新規設計ではなく既存改修
- より良い設計は今回の価値ではない
- 仕様達成に必須な差分のみ許可する
- 推測で仕様外を補完しない
- 不明点は不明点として保持する
- 必要に応じて質問候補へ変換する
- 承認済み差分以外は実装しない
- 想定外の追加修正が必要なら停止する
## 禁止事項
- リファクタリング
- 命名変更
- formattingのみの変更
- コメント整理
- 共通化
- 責務分離の改善
- ついで修正
- 別機能や別不具合の同時修正
- 変更対象外ファイルへの波及
## 実施手順
1. 差分仕様と対象コードから今回改修要求を再定義する
2. 変更対象候補と変更不要箇所を整理する
3. 既存挙動維持が必要な点を整理する
4. 不明点を抽出する
5. 既存挙動変更・契約変更・影響範囲拡大に関わる論点だけ質問候補にする
6. 回答があれば反映する
7. ファイル単位・関数単位の差分プランを作る
8. 承認後、その差分のみ実装する
9. 実装後、仕様との対応関係と未変更箇所を報告する
## 不明点の扱い
- すべてを質問してはいけない
- 仕様やコードから確定できる事項は質問しない
- 実装詳細だけで要件解釈に影響しない事項は質問しない
- 質問候補は最大5件、重要度順に提示する
## 停止条件
以下に該当する場合、実装を止めて追加差分案のみ提示すること。
- 承認済みファイル以外の変更が必要
- 既存契約を変えないと実現できない
- 共通部品の修正が必要
- 既存挙動を変える可能性がある
- 仕様または回答で未確定の重要論点が見つかった
## 出力順
### 1. 改修目的(1文)
### 2. 現行挙動の理解
### 3. 期待挙動の理解
### 4. 変更対象候補
### 5. 変更不要箇所
### 6. 既存挙動維持が必要な点
### 7. 不明点
### 8. 質問候補(必要な場合のみ)
### 9. 最小変更方針
### 10. 差分プラン
### 11. 実装後報告(実装フェーズ時のみ)
15. 推奨運用(人間側)
最後に、人間側の運用ルールも固定しておくと強いです。
## 人間側の運用ルール
- 既存仕様とは別に差分仕様書を作る
- AIへ渡す前に改修目的を1文で表現する
- 変更許可リストを可能な限り作る
- AIのプランは差分単位で承認する
- 抽象的な「この方針でOK」は出さない
- 実装前にもう一度制約を再注入する
- 実装後は「何を変えたか」だけでなく「何を変えていないか」も確認する
- テンプレート原本は固定し、案件ごとには派生版で調整する
まとめ
既存システム改修でAIを安定運用したいなら、重要なのはモデルの賢さだけではありません。
大事なのは、変更境界・非変更条件・停止条件・質問条件を先に固定すること です。
本テンプレートはそのために、以下を一式で持つ構成にしています。
- 差分仕様書
- 解析テンプレート
- 不明点抽出テンプレート
- ヒアリングテンプレート
- 差分プランニングテンプレート
- 差分レビューテンプレート
- 実装テンプレート
- 実装後レビューテンプレート
- テンプレート修正テンプレート
- 統合版プロンプト
これらを案件ごとに少しずつ埋めていく運用にすると、
「仕様を読ませたら勝手に広げる」「よかれと思って直す」「不要修正が混ざる」といった事故をかなり減らせます。