@nqounetです。
AGENTS.md と .github/instructions/post.instructions.md について色々と試行錯誤する中で、ブログを書くのになかなか良い感じになりました。今回は、そのリファクタリング体験と、AIエージェントへの指示ファイルについて詳しくお話しします。
背景・きっかけ
別のプロジェクト「amazon-junkie」で、ブログ記事を書くためのAGENTS.mdを色々試していました。
このAGENTS.mdがなかなか良い感じになったので、このブログ用にも移植することにしました。手書きで。
しかし、移植してみると当然ながら重複しているところがたくさんありました。AGENTS.mdとpost.instructions.mdの両方に同じような内容が書かれている状態です。
これはリファクタリングが必要だ、ということで、Copilotに丸投げしてみました。
AIエージェントへの指示ファイルとは
本題に入る前に、AIエージェントへの指示ファイルについて詳しく説明します。Copilotに限らず、AIエージェントへの指示ファイルは色々なところに書くことができるようになっています。
1. AGENTS.md（業界標準）
まず、業界標準と言えそうなのは AGENTS.md です。
AGENTS.mdは、どのディレクトリに置いても良く、最も近くにある指示ファイルが採用されるという仕組みになっています。リポジトリのルートに置けば全体に適用され、サブディレクトリに置けばそのディレクトリ以下に適用されます。
メリット：
- 複数のAIエージェントサービスで共通して使える
- ディレクトリごとに異なる指示を設定できる
- リポジトリの構造に沿った柔軟な設定が可能
デメリット：
content/ディレクトリにAGENTS.mdを置くと、Hugoなどの静的サイトジェネレーターではコンテンツ扱いになってしまう- 隠しファイル的に「.（ドット）」から始めることができない（
.agents.mdのような形式は対応していない）
2. .github/copilot-instructions.md（GitHub Copilot固有）
GitHub Copilotは .github/copilot-instructions.md を自動的に読み込みます。
検索すればたくさんの情報が出てきますが、この形式はGitHub Copilot専用です。そのため、汎用性の観点からはAGENTS.mdを使う方が良いと考えています。
メリット：
- GitHub Copilotが自動的に認識する
- GitHub公式のフォーマット
デメリット：
- GitHub Copilot以外のAIエージェントでは認識されない
- 汎用性に欠ける
3. .github/instructions/ ディレクトリ（細かい使い分け）
標準化とは言い難いですが、現時点で最も細かく使い分けられるのが instructions です。
.github/instructions/[name].instructions.md として配置します。
|
|
上記のように、どこで有効になるかを front matter の applyTo で指定できます。
メリット：
- ファイルパターンごとに異なる指示を設定できる
content/ディレクトリにファイルを置かなくて良い- 複数の指示ファイルを使い分けられる
デメリット：
- GitHub Copilot固有の機能
- 他のAIエージェントでは認識されない可能性がある
このサイトでの使い分け
このブログサイトでは、以下のように使い分けています：
| ファイル | 用途 | 対象 |
|---|---|---|
AGENTS.md（ルート） |
Hugo全般の設定、プロジェクト構成 | リポジトリ全体 |
.github/instructions/post.instructions.md |
ブログ記事の執筆ガイドライン | content/post/*.md |
全体のシステムはHugoなので、ルートにあるAGENTS.mdはHugoに関する情報が主体です。そして、コンテンツを保管する content/ 配下に対して効果を持たせるようにブログ用の指示ファイルを書いています。
AGENTS.mdをcontent/に置くと、コンテンツ扱いになってしまうので扱いが面倒なんですよね。
4. カスタムエージェント
指示ファイルとは少し用途が異なりますが、エージェントパネルやVS Codeなどのエディタで使えるカスタムエージェントという機能もあります。
これは使い所が難しいと感じています。特定のタスクに特化したエージェントを定義できますが、汎用的な指示ファイルとは異なる運用が必要です。
参考リソース
GitHubの awesome-copilot というリポジトリに、多くのawesomeな設定例が集まっています。プロンプトもたくさんあるので参考にしてみてください。
実際に行ったこと
今回のリファクタリングでは、以下の作業をCopilotに依頼しました：
- AGENTS.mdとpost.instructions.mdの重複を解消
- 役割分担を明確にする
- 冗長な記述を削除
具体的には、PRを作成してCopilotに「リファクタリングしてください」と指示しました。
セッションの詳細は以下で確認できます：
セッションで行われた作業の詳細
セッションでは、Copilotが以下のステップで作業を進めました：
1. 問題の分析
まず、AGENTS.mdとpost.instructions.mdの両ファイルを読み込み、重複・冗長な箇所を特定しました。
2. AGENTS.md のリファクタリング
AGENTS.mdはプロジェクト全体の指針として役割を明確化しました：
- front matter形式の詳細例を削除（post.instructions.mdに一元化）
- ファイル命名規則テーブルを削除（post.instructions.mdに一元化）
- プロジェクト構成に
.github/instructions/ディレクトリを明示 - Dosセクションにfront matter必須項目を追加
- 記事作成固有の詳細はpost.instructions.mdへの参照に変更
3. post.instructions.md のリファクタリング
post.instructions.mdは記事作成に特化した内容に整理しました：
| 変更内容 | 詳細 |
|---|---|
| 品質チェックリストの統合 | 2つあったチェックリストを1つに |
| ワークフローの統合 | 2つあったワークフローを1つに |
| 禁止事項の統合 | 「禁止事項」と「Don’ts」を1つのテーブルに（代替案列付き） |
| サンプル記事構成の削除 | テンプレートで十分と判断 |
| Markdown記法セクションの削除 | 基本知識として想定 |
| 体験記事セクションの統合 | シンプルなテンプレートに統合 |
4. コードレビューへの対応
セッション中、自動でコードレビューが実行され、いくつかの改善点が指摘されました。Copilotはこれらのフィードバックにも対応しています：
- 役割セクションを複数段落に分割して可読性向上
- トーン＆スタイルに「身近な例や図の活用」ガイダンスを追加
- 禁止事項テーブルに代替案列を復元
結果と分析
結果を見ると、Copilotは結構大胆に削ってくれました。
削減率
| ファイル | 変更前 | 変更後 | 削減率 |
|---|---|---|---|
| AGENTS.md | 114行 | 86行 | 約25% |
| post.instructions.md | 438行 | 211行 | 約52% |
合計で256行が削減され、より保守しやすい構成になりました。
変更の具体例
どういう影響があるのかは、本当は細かく見ていく必要があるとは思います。例えば、こんな変更がありました：
| Before | After |
|---|---|
| コード例が正確で、動作確認済みである | コード例が正確である |
Beforeの時だったかは覚えていませんが、セッション内でコードを実行して動作確認をしているのを見たことがあります。ちゃんとやってるんですね。
Afterになってからは、まだそういう記事を書いていないのでわかりません。ただ「正確」をどう捉えるのかがポイントです。
「正確」であれば当然正確に動くはずなので、動作確認はしなくて良い（というか、Afterには動作確認という概念すらない）のでは、という考え方もできます。しかし、どのようにして「正確」足り得るのでしょうか？
この体験から学んだこと
嘘をつかせない工夫
「AIは嘘をつく」と散々言われているので、エージェント指示ファイルには「嘘をつかせないようにする工夫」がたくさん仕込まれています。
特に重要なのは以下の2点です：
- やるべきこと（Dos） を明確にする
- やってはいけないこと（Don’ts） を明確にする
とはいえ、AIは学習済みなので、基本的なことは既に理解していると思われます。
ただし、場合によっては「やってはいけない事をやってほしい場合」もあるかもしれません。そこは明確にしておくのが良いでしょう。
指示ファイルの階層構造
複数の指示ファイルを使い分けることで、以下のようなメリットがあります：
- 関心の分離: システム全体の設定とコンテンツ固有の設定を分離できる
- 保守性の向上: 変更の影響範囲を限定できる
- 柔軟性: 異なるファイルタイプに異なるルールを適用できる
リファクタリングの価値
度重なる修正によって項目が重複したり、冗長になったりすることは避けられません。AIエージェントに対する非常に重要なファイルなので、定期的なリファクタリングが必要です。
今回のようにCopilotに丸投げすることで、客観的な視点からの整理ができました。
まとめ
AIエージェントへの指示ファイルには複数の種類があり、それぞれに特徴があります。
- AGENTS.md: 業界標準で汎用性が高い
- copilot-instructions.md: GitHub Copilot固有だが自動認識される
- instructions/: ファイルパターンごとに細かく設定できる
このブログでは、AGENTS.mdでHugo全般の設定を、post.instructions.mdでブログ記事の執筆ガイドラインを管理しています。
リファクタリングをCopilotに任せることで、重複を解消し、より保守しやすい構成になりました。今後も定期的に見直しを行っていきたいと思います。