はじめに
10年以上運用されている PHP 製のレガシーシステムに対して、
GitHub Copilot を本格的に開発・運用へ組み込む取り組みを進めています。
ただし、いわゆるモダンな前提（Laravel等のFW / 明確なMVC / 設計書完備）は一切ありません。
- 独自フレームワーク
- 責務境界が時代ごとに変化した構成
- 仕様はコードと運用の積み重ね
- 一部処理・DB定義は別リポジトリ管理
- Smarty にロジックが残存
- 文字コード制約あり
このような環境では、AIにそのままコードを渡しても期待どおりには動きません。
本記事では、
- GitHub Copilot に「レガシーの前提」を理解させる工夫
-
copilot-instructions.mdと 再利用プロンプトによる知識の蓄積 - instructions 自体を AIが更新する運用
- 周辺業務（マスタデータ作成・マークアップ）での AI 活用
について、実務目線で整理していきます。
レガシープロジェクトにおける AI 活用の壁
まず前提として、Copilot（AI）は以下を暗黙に期待しています。
- 一貫したアーキテクチャ
- リポジトリ単体で完結する設計
- Model / View / Controller の明確な責務
- UTF-8 前提の安全な編集
しかし、長期運用されたレガシーシステムはその真逆であることが多いです。
結果として、
- 勝手に責務分離を進めようとする
- 存在しない前提を補完してしまう
- 文字コードを破壊する
- 「正しそうな修正」で事故を起こす
という事態が頻発します。
AIを使う前に、人間側で「前提」を明文化する必要がある、という結論に至りました。
copilot-instructions.md による前提共有
そこで活用しているのが、
.github/copilot-instructions.md です。
このファイルに、プロジェクト全体の前提・制約を明示します。
例：
- このリポジトリは独自フレームワークである
- MVC は一貫していない
- 仕様はコードと運用の積み重ね
- リポジトリ外依存が存在する
- 文字コード変換・自動整形は禁止
- 修正は最小差分が原則
これにより、Copilot Chat に投げるすべてのリクエストに
**「このプロジェクトの文脈」**が自動で付与されます。
ディレクトリ単位の instructions（*.instructions.md）
全体指示だけでは不十分なため、
特定ディレクトリ・拡張子向けに 局所ルールも定義しています。
例：
- Smarty テンプレート用 instructions
- レガシー Model 群向け instructions
- 比較的新しい実装パターン用 instructions
applyTo を使い、対象パスを明示することで、
「このファイルを触るときは、この前提で考える」
という知識を AI に持たせることができます。
instructions を“育てる”という発想
しかし、ここで問題になります。
instructions 自体も最初から完成しているわけではない
レガシーシステムでは、
修正を通じて初めて分かる暗黙知が非常に多いためです。
そこで採用したのが、
instructions を AI 自身に更新させる仕組み
です。
再利用プロンプトで instructions を更新する
.github/prompts/update-instructions.prompt.md
という再利用プロンプトを用意しています。
このプロンプトは以下を自律的に行います。
-
origin/develop...HEADを基準に差分を取得 - 今回の変更で新たに判明した前提・制約を抽出
- 適切な
copilot-instructions.md/*.instructions.mdに追記 - 追記は専用ブロック内のみ
人間が行う操作は、
/update-instructions
を実行するだけです。
重要なのは、
- instructions 以外は絶対に編集させない
- 推測で書かせない
- 追記は短い箇条書きのみ
という 安全弁をプロンプト側で強く制御している点です。
これにより、
実装 → 学習 → 知識蓄積
というループが自然に回ります。
.github/prompts/update-instructions.prompt.md 叩き
---
mode: 'agent'
description: '現在のブランチ差分から Copilot instructions を更新する'
tools:
- codebase
- terminal
---
あなたは「GitHub Copilot 用 instructions を育てるメンテナ」です。
## 目的
現在のブランチにおける変更差分を確認し、
今回の修正によって新たに判明した
暗黙知・前提・制約・局所ルールを
以下のファイルに追記してください。
- .github/copilot-instructions.md
- .github/instructions/*.instructions.md
## 実行手順
1. origin/develop...HEAD を基準に差分を取得する
2. 差分から、次回同種の修正を行う AI が誤解しやすい点を抽出する
3. 内容に応じて適切な instructions ファイルへ追記する
4. 追記は必ず AI-AUTO ブロック内のみ行う
## 厳守ルール
- instructions 以外のファイルは変更しない
- 推測で書かない。不確実な場合は「要人間確認」と明示する
- 追記は短い箇条書きにする
- 既存記述と重複する内容は追加しない
## 完了条件
- 変更内容を要約して提示する
- 追記が不要な場合はその旨を明示して終了する
マスタデータ作成では Google スプレッドシートの AI 関数が有効
コード以外の作業でも AI は活躍しています。
マスタデータ作成・整形では、
Google スプレッドシートの AI 関数が非常に有用でした。
- 表記ゆれの正規化
- 既存データからの補完
- description系テキストの自動生成
エンジニアがスクリプトを書くほどでもない作業を、
非エンジニア含めて処理できる点が大きな利点です。
デザインからのマークアップは前回記事の方法を継続
デザインカンプからの HTML / CSS 生成については、
前回記事で紹介した方法を継続しています。
- Figma デザインを SVG として扱う
- AI に SVG → HTML / CSS を変換させる
- ベースCSSとの干渉を人間が調整
詳細は以下をご参照ください。
👉 https://zenn.dev/aprilknights/articles/944bcfbd6c857d
※ Gemini3 Pro, GPT5.2だとSVGだけでなくキャプチャも指定することでよりHTML・CSSへの置換精度がよくなりました！
まとめ：AIを「使う」だけでなく「育てて、任せる」
レガシープロジェクトにおける AI 活用は、
- 丸投げする
- 魔法を期待する
という使い方では成立しません。
一方で、
- 前提を言語化する
- 制約を明示する
- 学習結果を残す
といった作業を すべて人間がやり続けるのも現実的ではありません。
そこで本記事で紹介したように、
copilot-instructions.md*.instructions.md- instructions を更新する再利用プロンプト
を用意し、
instructions 自体の作成・更新も AI に任せる
という運用にしています。
実装作業の中で AI が学んだことを、
そのまま次回以降の前提として残す。
これにより、
「レガシーの理解コスト」そのものを AI に肩代わりさせる
ことが可能になります。
AIは単なるコード補完ツールではなく、
プロジェクト固有の知識を蓄積していく存在として扱う。
この前提に立つことで、10年以上続くレガシープロジェクトでもある程度はAIを実戦投入できるようになりました。
このような記事をひたすら読み漁りたい。
Discussion