最高のAGENTS.mdを生み出すプロンプト ― GitHub Copilotで設定ファイルを作成した話

「AIにブログ記事を書いてもらいたいけど、どうすれば質の高い記事が生成されるんだろう？」

この記事では、GitHub Copilotのコーディングエージェントを使って、ブログ記事生成用の設定ファイル「AGENTS.md」を作成した体験をお伝えします。AIに良い仕事をしてもらうためのプロンプトの書き方や、信頼性の高い記事を生成するための工夫について、具体的な事例とともに解説します。

ウェブで学ぶプログラミングの落とし穴

プログラミングをウェブで学ぶのは、想像以上に大変です。

多くの初心者〜中級エンジニアがブログ記事を頼りに学習していますが、そこには大きな落とし穴があります。私自身、仕事でRubyを使い始めたとき、検索でいろいろな記事を読みましたが、結局は公式ドキュメントに戻りました。

なぜそうなったのでしょうか？

個人ブログの限界

振り返ってみると、ブログ記事が 浅いところしか書いていなかった からだと思います。

基本的な使い方は書いてあるが、なぜそう動くのかの説明がない
エラーが起きたときの対処法が不十分
書かれた当時の情報が古くなっていることがある
出典が明記されていないので、情報の正確性が確認できない

これは個人ブログを批判しているわけではありません。むしろ、私自身がブログを書く際に同じ轍を踏まないようにしたいという思いがあります。

公式ドキュメントの価値

結局のところ、一次情報（公式ドキュメントや仕様書）に当たるのが一番確実 です。

とはいえ、公式ドキュメントは初心者には読みにくいことも事実。だからこそ、ブログ記事には「公式ドキュメントの内容をわかりやすく噛み砕いて伝える」という役割があると考えています。

AGENTS.mdとは何か

AGENTS.md（エージェンツ・エムディー）は、GitHub Copilotのコーディングエージェントに対して どのように振る舞ってほしいかを定義する設定ファイル です。

このファイルをリポジトリのルートに配置することで、Copilotがコードを生成したり、タスクを実行したりする際の振る舞いをカスタマイズできます。

GitHub Copilotコーディングエージェントとは

GitHub Copilotコーディングエージェントは、2025年5月に一般提供（GA）された機能です。従来のコード補完とは異なり、自律的にタスクを実行し、ファイルの作成や編集、プルリクエストの作成まで行えます（GitHub Blog - GitHub Copilot coding agent generally available）。

AGENTS.mdを使うことで、このエージェントの動作を細かく制御できるのです。

最高のAGENTS.mdを作るためのプロンプト

今回、私はCopilotコーディングエージェントに対して、以下のようなプロンプトを使ってAGENTS.mdを作成してもらいました。

実際に使用したプロンプト

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


あなたは AGENTS.md 設計の専門家です。
このリポジトリでは、プログラミングに関するブログ記事を作成します。
初心者〜中級のエンジニア向けに、情熱的で読みやすく、信頼性の高い記事を生成できる
最適な AGENTS.md を作成してください。

■ ブログ記事仕様
- テーマ：プログラミング技術全般
- 対象読者：初級〜中級エンジニア
- 基本的なプログラミング用語は理解しているが、専門領域は浅い前提
- 専門用語は必要最小限に、使用する場合は簡潔に補足をつける
- 図解風の箇条書きや実例などを交えて段階的に説明する
- トーン：丁寧かつフレンドリー
- SEO を意識した見出し構成
- 根拠となる情報は必ず提示する

■ 出典・根拠の扱い
- 一次情報（仕様書、公式ドキュメント、標準規格など）を優先する
- 出典URLはMarkdownリンク形式で、該当内容の近くに配置
- 信頼性が低い情報源（個人ブログ等）は引用しない
- 推測情報はその旨を明記する

■ エージェント機能要件
- 記事作成時に、不足情報をインタビュー形式で質問する
- Markdown形式で出力する
- 各記事でスタイルと品質を統一する
- 禁止事項：曖昧な表現の多用、難解な専門用語の乱発、根拠のない断定等

■ 出力形式
説明文なしで、完成した AGENTS.md のみを Markdown で出力してください。

以上を踏まえて、最高品質の AGENTS.md を作成してください。

プロンプト設計のポイント

このプロンプトには、いくつかの工夫があります。

1. 役割を明確に定義する

冒頭で「AGENTS.md 設計の専門家」という役割を与えています。AIに専門家としての視点を持たせることで、より質の高い出力が期待できます。

2. 目的とコンテキストを伝える

「プログラミングに関するブログ記事を作成する」という目的を明示しています。何のためのAGENTS.mdなのかをAIに理解させることで、適切な内容が生成されやすくなります。

3. 具体的な仕様を列挙する

曖昧な指示ではなく、具体的な仕様を箇条書きで列挙しています。

対象読者
専門用語の扱い方
トーン
出典の扱い方
禁止事項

このように詳細を指定することで、期待する出力に近づけることができます。

4. 出力形式を指定する

「説明文なしで、完成した AGENTS.md のみを Markdown で出力してください」と指定しています。余計な説明を省くことで、すぐに使える成果物を得られます。

生成されたAGENTS.mdの中身

Copilotが生成したAGENTS.mdは、約270行の充実した内容になりました。主な構成要素を紹介します。

役割と対象読者の定義

1
2
3
4
5
6


## 役割

あなたは、プログラミング技術に関するブログ記事を執筆する
テクニカルライターエージェントです。
初心者〜中級エンジニアに向けて、情熱的で読みやすく、
信頼性の高い記事を作成します。

エージェントに明確な役割を与えることで、一貫した振る舞いが期待できます。

出典・根拠の取り扱いルール

特に印象的だったのが、情報源の優先順位を明確に定義している点です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


### 情報源の優先順位

1. **一次情報（最優先）**
   - 公式ドキュメント
   - 仕様書・標準規格（RFC、W3C、ECMA など）
   - 公式ブログ・リリースノート

2. **二次情報（補助的に使用）**
   - 信頼性の高い技術メディア
   - 公式に認められた書籍

3. **使用禁止**
   - 個人ブログ（信頼性が担保できないため）
   - 出典が不明確な情報

これは、私がプロンプトで指定した「信頼性が低い情報源は引用しない」という要件を、より具体的なルールに落とし込んでくれています。

品質チェックリスト

生成されたAGENTS.mdには、記事完成前に確認すべき11項目のチェックリストが含まれていました。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


- [ ] タイトルが具体的で検索意図に合致している
- [ ] 導入文で読者のメリットが明確になっている
- [ ] 見出し構造が論理的で読みやすい
- [ ] 専門用語に適切な補足説明がある
- [ ] コード例が正確で、動作確認済みである
- [ ] 出典が一次情報を優先している
- [ ] 出典 URL が該当箇所の近くに配置されている
- [ ] 推測情報はその旨が明記されている
- [ ] 文体が丁寧かつフレンドリーで統一されている
- [ ] 誤字脱字がない
- [ ] アクセシビリティに配慮している