AIプログラミングエージェント向けの指示ファイルは、際限なく拡張するのではなく、継続的に見直す必要があります。モデルがミスをするたびに新しいルールが追加され、ツールが変わるたびに回避策が追加される一方で、新しいモデルが登場した後も以前のモデル向けのガイダンスが残り続けます。その結果、開発者向けのセットアップガイド、スタイルガイド、トラブルシューティングの記録、古いプロンプト作成手法が混在するファイルになる可能性があります。
本稿によれば、このような蓄積によってプログラミングエージェントの有効性が低下する可能性があります。現代のモデルは、リポジトリを探索し、一般的なフレームワークを認識し、既存のパターンに従い、通常のエラーに対処する能力が以前より高まっています。しかし、チーム固有の意思決定、隠れた制約、チーム内に蓄積された運用上の知識は知りません。したがって目標は、指示ファイルを可能な限り短くすることではなく、結果を実際に変える、信号強度の高い情報を最小限の集合として残すことです。
コンテキストを限られたリソースとして扱う
指示ファイルは、該当するすべてのリクエストでモデルが利用できるコンテキストに追加されます。その行は、開発者のタスク、関連するコード、ツールの出力、会話履歴、その他の指示と、モデルの注意を奪い合います。コンテキストウィンドウが広いからといって、追加のトークンにコストがないわけではありません。
実務上の問いは「リポジトリについて何をモデルに伝えられるか」ではなく、「モデルが発見、推測、または信頼できる形で取得できないため、知る必要があるものは何か」です。本稿は、具体的で、影響があり、推測が難しい情報に集中することを推奨しています。
ファイルに残すべきもの
最も価値の高い情報には、システムに関する分かりにくい事実が含まれます。たとえば、リポジトリのコンポーネント間の所有境界、古いディレクトリが依然として本番環境で使用されていること、特定のファイルが生成物で手動編集してはならないことなどです。フォルダー名からモデルに境界を推測させるのではなく、特定のインターフェースが公開HTTPコントラクトを所有していることや、ドメインルールが特定のレイヤーに属していることを明示すると有用です。
また、検証とビルドのための、テスト済みのコマンドだけに絞った、最短の信頼できる手順を文書化するべきです。本稿の例には、最初のビルドの前にdotnet restore App.slnxを実行し、その後dotnet build App.slnx --no-restoreを使用すること、APIインターフェースを変更した際に特定のテストを実行すること、コントラクトを変更した後に生成ファイルの検証ツールを実行することが挙げられています。統合テストにはDockerが必要で並列実行してはならない、といった固有の要件も明示する必要があります。誤ったコマンドを自信を持って繰り返すことは、コマンドがない場合よりも悪いからです。
コードだけでは一貫して決められないローカルな選択も記録すると有用です。たとえば、採用しているテストフレームワーク、コントローラーよりもMinimal APIsを優先すること、予期されるドメインエラーの処理にResult<T>パターンを使うこと、システム時計を直接呼び出す代わりにTimeProviderを使うことなどです。これらは一般的なプログラミング規則ではなく、コードベース固有の意思決定であるため、指示ファイルに適しています。
厳格な制約については、「常に」「決して」「〜しなければならない」といった言葉を、実際に絶対的なルールである場合に限って使うべきです。たとえば、公開JSONコントラクトを維持すること、顧客データをログに記録しないこと、データベースマイグレーションを以前のバージョンと互換性のあるものにすること、明示的なデプロイタスクなしに本番環境のファイルを変更しないことなどです。UI設計ガイドのファイル、ランタイム環境のバージョン指定ファイル、デプロイ文書、アーキテクチャ決定など、内容を複製するのではなく情報源を示すこともできます。
削除または移動できるもの
本稿は、「クリーンなコードを書く」「ベストプラクティスに従う」「意味のある名前を使う」「エラーを適切に処理する」といった一般的な助言を削除するよう勧めています。これらの表現は実際の判断を決めるものではありません。一方、ローカルで具体的なルールの方が有用です。たとえば、既存のProblemDetailsツールを使い、検証エラーには400レスポンス、存在しないリソースには404レスポンス、同時実行の競合には409レスポンスを返す、といったルールです。
通常、ファイルにディレクトリの完全な一覧を含める必要はありません。モデルはリポジトリの構造をすばやく読み取れるからです。ツールが強制するフォーマット規則を繰り返す必要もなく、dotnet format --verify-no-changesのような適切な検証コマンドを記載すれば十分です。README、アーキテクチャガイド、コントリビューションガイドを丸ごとコピーすることも避けるべきです。保守コストが上がったり、文書間に矛盾が生じたりするためです。
本稿は、「深呼吸をする」「上級エンジニアとして振る舞う」「変更を加える前にすべてのファイルを読む」といった古い「プロンプトの神話」にも注意を促しています。これらの表現はプロジェクトに関する知識を追加せず、不要な探索を引き起こす可能性があります。望ましいのは、結果、制約、必要な検証を記述することです。つまり、根本原因に対処する最小限の変更を行い、公開されている挙動を維持し、対象を絞ったテストを実行することです。
一時的な回避策は、それを必要とした問題を修正した後に削除するべきです。そうしなければ、エージェントはもはや壊れていない経路を避け続けます。また、指示は特定のバージョンではなく、モデルの種類に合わせて書くべきです。モデルごとの固有の経路に分岐する指示は、モデルとその挙動が変化すると脆弱になります。
指示の範囲を選択し、見直す
すべての指示が、リポジトリ全体のファイルに適しているわけではありません。GitHub Copilotは、.github/copilot-instructions.mdに一般的な指示を、.github/instructions/以下にパス固有のファイルを、AGENTS.mdなどにエージェント向けの指示を配置することをサポートしています。該当するパス固有のファイルがある場合、一般的な指示ファイルとともに使用されます。
システム構造、共通コマンド、一般的な制約は全体の範囲に置き、フレームワークの規則、テストパターン、特定部分に固有の生成ファイルに関するルールはパス固有のファイルへ移すべきです。詳細な説明、意思決定の履歴、まれな手順は、関連文書に残す方がよいでしょう。これにより、Reactコンポーネントのテストに関するルールが、データベースマイグレーションの作業中にモデルの注意を消費することを防げます。
本稿は、各指示を4つの結果のいずれかに分類して見直すことを提案しています。維持するのは、正しく、影響があり、推測が難しい場合です。削除するのは、モデルが知っている、ツールが強制している、曖昧になった、または古くなった場合です。移動するのは、有用だが別のパスや文書に関係する場合です。検証するのは、コマンド、一時的な回避策、または変更された可能性のあるバージョンについて述べている場合です。
見直しのタイミングには、より高性能なモデルを採用したとき、ビルドシステムを変更したとき、リポジトリを再編成したとき、エージェントが指示を無視したり誤って適用したりしていることに気づいたときが含まれます。その後、より小さくしたファイルを特定のタスクでテストし、実際の失敗事例を記録し、再発を防ぐための最小限の指示を追加して、別のタスクで再テストします。
プロジェクト保守の一部
本稿は、指示ファイルの変更を通常のプルリクエストでレビューし、ルールが再利用可能なものなのか、それとも単一のタスクだけに対処するものなのかをレビュアーに確認してもらい、運用コマンドと環境要件の所有者を決めるよう呼びかけています。また、問題の根本原因を解決するプルリクエスト自体で一時的な回避策を削除し、SDKパッケージ、フレームワーク、テストツール、ビルドパスを更新した後にはコマンドを再確認するべきです。
ファイルの品質は、その行数で測るべきではありません。30行のファイルに誤った命令が含まれている場合、複数プロジェクトのリポジトリの境界やモデルが推論できない情報を記述した100行のファイルよりも悪い可能性があります。より適切な基準は、そのファイルによって、有能なモデルが迅速に作業を開始できるようになるかどうかです。そのためには、チームだけが知っている情報、つまりシステムが何であるか、重要な境界、ローカルな選択、ビルドと検証の方法、壊してはならないもの、そしてより深い詳細の所在を提供します。