Microsoft (有志)Publicationへの投稿
🍣

Spec Kit に学ぶ、GitHub Copilot の prompt / agent 運用プラクティス

Junya Yamaguchi
に公開
2025/12/21
VS Code
GitHub Copilot
tech

はじめに

GitHub Copilot のプロンプトファイル (.github/prompts/*.prompt.md) やカスタムエージェント (.github/agents/*.agent.md) は便利です。便利なんですが、次のような悩みに直面することも多いです。

  • プロンプトとエージェントの使い分けがわからない（同じようなことが両方で書けてしまう）
  • 名前がバッティングする（review とか research とかやたら乱立する）
  • 人に使ってもらう時に「最初に何を叩けば良いのかわからない」迷子状態になる

最近、Spec Kit を触ってみたところ、「この辺、まとめて解決してるな」と感じました。そこで、この記事では Spec Kit そのものというより、Spec Kit から学べる Copilot 運用のプラクティスにフォーカスします。上記の 3 つの悩みに対して、それぞれどんな工夫がされているかを紐解きます。

なお、Spec Kit 自体は Spec-Driven Development を支えるツールキットです。思想や全体像は公式の説明が詳しいです[1]。

https://github.com/github/spec-kit

Spec Kit でプロジェクトを初期化すると何が入るか

Spec Kit でプロジェクトを初期化すると、次のようなファイルが展開されます。

your-project/
├── .github/
│   ├── agents/
│   │   ├── speckit.analyze.agent.md
│   │   ├── speckit.checklist.agent.md
│   │   ├── ...
│   │   └── speckit.taskstoissues.agent.md
│   └── prompts/
│       ├── speckit.analyze.prompt.md
│       ├── speckit.checklist.prompt.md
│   │   ├── ...
│       └── speckit.taskstoissues.prompt.md
├── .specify/
│   ├── memory/
│   └── templates/
└── .vscode/
    └── settings.json

実は、ディレクトリ構造からすでに色々なことが見え隠れしています。

  • プロンプトとエージェントの名前が speckit. から始まる
  • 同じような名前のプロンプトファイルとエージェントファイルがセットになっている
  • VS Code の設定も入っている

以降で、Spec Kit が冒頭の 3 つの悩みをどのように解決しているか解説してきます。

良いと思ったプラクティス

1. prompt は agent へのエントリーポイントにする

Spec Kit のプロンプト ファイルは極端に薄い（内容が少ない）です。たとえば plan の プロンプトはこれだけです。

.github/prompts/plan.prompt.md
---
agent: speckit.plan
---

そうです。プロンプトファイルは、"どのエージェントを起動するか" だけを決めて、実際のタスクの実行に必要な定義はエージェント側に全て集約されています。

これは「プロンプトとエージェントの使い分け」の答えの一つとしてとても良いです。プロンプトはエントリーポイント、エージェントはロジックの実体と決めて運用することで、同じようなことが両方に書けてしまう問題を解消します。また、こうして分けておくと、更新箇所がエージェントだけで済みます。

  • プロンプト ファイル: 入口なので、なるべく変えない（変えると導線が壊れる）
  • エージェント ファイル: 中身なので、都度改善する（手順、チェック、ハンドオフ、失敗時の挙動・・・）

ところで、エージェントに実装を寄せるのはなぜでしょうか？公式の見解は無いですが、個人的には以下のメリットがあると感じます。

  1. Coding Agent (GitHub 上) で実行できる
  2. runSubagent で他のエージェントから呼べる
  3. handoffs で次のステップへスムーズに渡せる

特に、最後の点は「迷子」問題にも効きます。Spec Kit のエージェントは、handoffs フロントマターで次に実行すべきステップを提案してくれます。

handoffs: 
  - label: Create Tasks
    agent: speckit.tasks
    prompt: Break the plan into tasks
    send: true
  - label: Create Checklist
    agent: speckit.checklist
    prompt: Create a checklist for the following domain...

2. <namespace>.<name> で名前空間を切る

Spec Kit はプロンプト / エージェントのファイル名が speckit.<command>.[prompt|agent].md に統一されています。これが地味に効きます。

  • plan や review みたいな汎用名を使っても衝突しづらい
  • / を打ったときに候補が speckit でまとまるので視認性が高い
  • 将来 org.<name> や team.<name> みたいな体系を並べても整理しやすい

最近、AI 設定テンプレ管理ツール（openjny/dotgh) を作って運用していたのですが、使いまわしできるエージェントやプロンプトが増えてくると、名前のバッティング問題が起きてしまっていました。名前を変えたり良い感じに重複しないように工夫していたのですが、この namespace アイディアは大きな突破口になると思います。

https://github.com/openjny/dotgh

3. chat.promptFilesRecommendations と handoff でガイドする

VS Code には、チャット開始時におすすめプロンプトを表示する設定があります。Spec Kit はこれを取り入れています。以下は、デフォルトで注入される VS Code の設定の一部です。

settings.json
{
    "chat.promptFilesRecommendations": {
        "speckit.constitution": true,
        "speckit.specify": true,
        "speckit.plan": true,
        "speckit.tasks": true,
        "speckit.implement": true
    }
}

新しいチャットを開いたときに "まずこれから" が提示されるので、README を熟読しなくても始められます。

さらに、最初の一歩の後も迷わせないのが Spec Kit のすごいところです。

前述の通り、Spec Kit のエージェントには handoffs フロントマターで次のステップがディレクションされています。たとえば:

  • /speckit.specify の次は /speckit.plan を提案
  • /speckit.plan の次は /speckit.tasks を提案
  • ...

といった具合です。つまり、入口は chat.promptFilesRecommendations で示し、以降は handoff で繋ぐという設計になっています。ユーザーは "次何すればいいの？" と迷わずに、ワークフロー全体を進められます。

自分の repo に持ち帰るときの最小セット

Spec Kit から "型" だけ持ち帰るなら、最小はこれで良いです。

  • 命名規則: <namespace>.<name>（例: acme.review）→ バッティング回避
  • エージェントに実体を寄せる（手順、チェック、ツール、handoffs）→ 使い分けの明確化 & 再利用性
  • プロンプトは薄く（agent 指定 + description 程度）→ 入口の安定化
  • handoffs で次のステップを提案（handoffs frontmatter）→ ワークフローのガイド
  • chat.promptFilesRecommendations で入口を用意（.vscode/settings.json）→ オンボーディング

まとめ

Spec Kit は Spec-Driven Development を支えるツールですが、GitHub Copilot のプロンプト/エージェント ファイルをどう整理すれば破綻しにくいかという点でも、非常に良い設計になっています。

本記事で紹介した 3 つのプラクティスをおさらいすると、以下の通りです。

  1. 名前空間を切る
  2. プロンプトはエージェントへのエントリーポイント
  3. chat.promptFilesRecommendations と handoff でガイド

どれも「長期運用する」ことを考えると、地味ですが確実に効いてきます。prompt や agent が増えてきたら、ぜひ試してみてください。

脚注

  1. Spec Kit（github/spec-kit）と Spec-Driven Development の概要。https://github.com/github/spec-kit と https://github.com/github/spec-kit/blob/main/spec-driven.md ↩︎

Microsoft (有志)
Microsoft (有志)Publication

メンバーが選んだMicrosoft製品の最新技術情報・知見をお届けします。 ※このPublicationは日本マイクロソフトまたは米Microsoft所属社員による個人の見解であり、所属する組織の公式見解ではありません。 ※Publicationに参加希望の社員は @07JP27までご連絡ください。

Discussion