はじめに

GMOコネクトの永田です。

Github Copilot Agentとても便利ですよね😊
ただAgentを使っていると、大量の出力結果に対して同じコメントを何度もして、疲弊したり・うんざりすることってありませんか？

そんな時に便利なのが、copilot-instructions.md です。
今回、設計フェーズに対し実際に使ってみて、before/afterがどうなるかの実例をまとめましたので、参考までにどうぞ！

まとめ

copilot-instructions.md を利用することによりGithub Copilot Agentの出力を、お手軽に自分好みにカスタマイズできる
Agentに対し、同じようなコメントが3回ぐらい出てきたら追記する、ぐらいの軽めの運用でも良い
- 最初は1行からでも大丈夫！
自分好みのアウトプットにできるので、Agentの出力結果の大量レビューの負荷が軽減できる

copilot-instructions.md とは

詳細はこちらの記事などを参照してください。

このファイルは、GitHub Copilotがユーザーの指示を処理する前に真っ先に読み込む指示書として機能します。

特別な設定は不要で、プロジェクトの.githubディレクトリ配下にcopilot-instructions.mdという名前で置くだけで認識されます。

なるほど！　これを使うと、毎回同じコメント書かなくても済みそうですね。

`copilot-instructions.md` を試してみた

じゃあ、効果のほどはどうなのよ？ってことで、copilot-instructions.md を導入する前後でのAgentの出力の違いを確認してみました。
ここではAgentのモデルとして Claude Haiku 4.5 を使っています。Claude系は丁寧ですが冗長すぎることがあるので、それを是正するコメントが多くなっています。

入れてみたのは以下になります。試した案件のフェーズが、PoCの設計フェーズなので、設計書作成の観点のみになります。

No1: API設計書時の指示
No2: 詳細な処理フロー設計時の指示

では、それぞれのbefore/afterを見ていきます。

No1追加時のbefore/after

入力prompt

5 tuples(src ip/port, dst src/port, protocol)を受け取り、
5 tuplesにマッチするxFlowレコードを集約した結果を返却するAPIドキュメントを新規作成。
既存のプログラムや仕様書とは完全に独立。

返却値は、通過したRouter一覧、next_hopとする。

before output of No1

430行ぐらいのMarkdownを出力してくれました。
（うーん。丁寧なんですけどね〜・・・　冗長でレビューが辛い😇）

commentNo1-1: OpenAPIにして欲しい

最低限、APIドキュメントはOpenAPIにして欲しいです。（その後の実装やStub作成で、OpenAPIのほうが有用なので）

commentNo1-2: リクエスト例は不要

複雑なparamなら説明あってもいいんですが、これぐらいならOpenAPI yamlを見れば、自明ですので要らないです。

その後、Python、cURL、JavaScript/Node.jsでのAPI呼び出し例まで作ってくれています。
・・・なくても分かるぞ？

No1 comment反映した `copilot-instructions.md`

では、上記のコメントを copilot-instructions.md にいれて、同じpromptを再実行してみましょう！

# 設計時ドキュメントの作成方針

- API設計書作成時は、OpenAPI yamlと各parameterの詳細説明用のMarkdownを作成
  - Markdownには、parameterの説明、制約条件 などを記載
  - ただし、Markdownには、requestとresponseの全体のサンプルは記載しない（OpenAPIと重複するため）
  - OpenAPIを参照すれば自明なリクエスト呼び出し例（curl、JavaScript、Pythonなど）は不要。サンプルがないと実装者が理解しにくい複雑なparamは例があっても良いが、出来るだけOpenAPIの例を充実させる方針とすること。

After output of No1

既存のドキュメント方針に従い、OpenAPI YAMLと詳細説明Markdownを作成します。

とCopilotからも報告もある通り、アウトプットががらっと変わりましたね！

ちゃんとOpenAPIで作成してくれていますね！

ただ、curlの使用例はどうしても入れたかったらしく、残っています😇
この辺りは、Agentにさらに追加コメントして修正してもらってください。

No2追加時のbefore/after

では、引き続き先ほどのAPI仕様書を元に、処理ロジックの設計書を作ってもらいます。

入力prompt

以下のAPI設計書を元に、/xflow/aggregate の詳細な処理フローをMarkdownの設計書としてまとめる

##### 参照するドキュメント

- docs/2_design/xflow_aggregation_api.yaml
- docs/2_design/xflow_aggregation_api.md

before output of No2

できました！！

1400行弱もある！！😊　
~~アウトプット多ければ良いってわけじゃねえ・・・レビューしたくねえ・・・・~~

確認し、コメントしていきます。

commentNo2-1: アスキーアート

アスキーアートで描くの好きですよね。でもね、MarkdownならMermaidのほうが見やすいし構造化されていて有用ですよね。

commentNo2-2: そもそもアスキーアートである必要ある？？

これRequest paramのvalidationですが、アスキーアートである必要はないですよね。
Tableとかで一覧化するほうが簡潔かつ、見通しが良くなります。

comment2-3: サンプルソースコードではなく「設計（アルゴリズム）」を設計書には書いて欲しい

ソースじゃないと意図が伝わりにくい非常に難解なアルゴリズムを除き、一般的なロジックならサンプルソースコードは冗長かと思います。

まずは処理ステップを箇条書きとか、フローチャートで書いて欲しいですよね。

No2 commentも反映した `copilot-instructions.md`

# 設計時ドキュメントの作成方針

- API設計書作成時は、OpenAPI yamlと各parameterの詳細説明用のMarkdownを作成
  - Markdownには、parameterの説明、制約条件 などを記載
  - ただし、Markdownには、requestとresponseの全体のサンプルは記載しない（OpenAPIと重複するため）
  - OpenAPIを参照すれば自明なリクエスト呼び出し例（curl、JavaScript、Pythonなど）は不要。サンプルがないと実装者が理解しにくい複雑なparamは例があっても良いが、出来るだけOpenAPIの例を充実させる方針とすること。
- 詳細処理フローの設計書を書く際、図はMermaid記法(Sequence Diagram or Flow Diagram)で作成すること
- 詳細処理フローの設計書は、要点のみを簡潔に記載すること（一定以上の開発スキルがある開発者を読者とするため）
  - 実装例のソースコードは不要であり、アルゴリズムの要点を説明する程度に留めること
  - Request parameterのvalidationを記載する場合、アスキーアートではなく、Table形式で簡潔にまとめること。その際、1つのparameterは1行にまとめ、列として必須チェック、形式チェック、範囲チェックなどの検証項目を設けること

では、全く同じpromptでもう一度試してみましょう。

After output of No2

とりあえずMarkdownが370行まで簡素化されました。
短ければ良いって訳ではないですが、先ほどが冗長過ぎたので、改善はしていそうです。早速中身を見ていきます。

Mermaidで処理フローを書いていてくれて、良い感じですね！

やや複雑なロジックは、プログラミング言語っぽい書き方で書いてくれています。

1つあたりがこれぐらいの量なら、このような表現でも良いかな、とは個人的には思います、がこの辺りは好みかと思います。（Loopとかを図で書き始めるよりは、このようなプログラミング言語っぽい方が記載として簡潔になるので）

copilot-instructions.md を入れる前に比べると、最初のアウトプットがかなり好みのスタイルになりました😊

所感

copilot-instructions.md のサンプルを最初見た時、

何を書けば良いの？
いっぱい書かないといけないの？

とか思いましたが、今回のように実際にAgentを利用した上で、同じようなコメントが3回ぐらい出てきたら、copilot-instructions.md に追記する、ぐらいの運用でも良いかと思いました。

（再掲）まとめ

copilot-instructions.md を利用することによりGithub Copilot Agentの出力を、お手軽に自分好みにカスタマイズできる
Agentに対し、同じようなコメントが3回ぐらい出てきたら追記する、ぐらいの軽めの運用でも良い
- 最初は1行からでも大丈夫！
自分好みのアウトプットにできるので、Agentの出力結果の大量レビューの負荷が軽減できる

最後に、GMOコネクトでは研究開発や国際標準化に関する支援や技術検証をはじめ、幅広い支援を行っておりますので、何かありましたらお気軽にお問合せください。

お問合せ: https://gmo-connect.jp/contactus/