spec-kitが合わなかったので、チケット駆動向けにちょうどいい感じのプロセスを作った
概要
spec-kit は仕様駆動開発で高い評価をされていると思いますが、自分の用途だと想定している開発の進め方が少し違いました。そこで、チケット粒度の課題に合わせて、プラン作成からレビュー、実装後の検証までを git に残しながら回せる Agents 群を作ってみたら、単発の Plan モードより抜けを減らしやすくなりました。それを紹介します。
「spec-kitは便利は便利なんだけど、今の作業だと必要以上にドキュメントを書いている気がする」とか「specとplanで同じ事を書いているだけな気がする」と感じるような開発をしている人は、もしかして使ってみると合うかもしれません！
最初に結論まとめ
- チケットの課題を設計して確実に実装したいという目的の場合、spec-kit は自分の使い方には合わなかった
- 自分の使い方に合わせて、ドキュメントをgitに保存しつつ作成とチェックを対にした、エージェント群を作ってみた
- 作成したのは次のgitリポジトリにある
.github/agents/*.agent.mdで、GitHub Copilot のVSCode/VS版やCLIで使う想定のもの。だいぶ実用的に使えている
検討の背景
仕様駆動開発の spec-kit を試してみたのですが、手元で普段やっているような、継続的な製品開発の中で新機能や障害修正を1件ずつ解決していくチケット駆動開発的な使い方だと、重すぎると感じています。spec-kitはそういう開発も想定しているとは思いますが、私はいまいち上手く組み合わせられませんでした。
それなら GitHub Copilot の Plan モードが選択肢になりそうなので試しましたが、これも少し弱かったです。単発でプランを出して人間が見るだけだと見落としが残りやすく、しかもgitへドキュメントをコミットしていく想定では無くセッション内保存なので、一手間かけて保存しないと途中で直した履歴やレビューの過程がgit管理で残らないという問題がありました。
さらに、Plan を作っても「その Plan を満たす実装になっているか」を機械的に確認する仕組みがありません。spec-kit より軽いのは良いのですが、その分だけ抜けやミスは実際に増えやすいと感じました。
チケット駆動に寄せた中間の仕組みとして、GitHub Copilot向けAgentsを作成した
そこで、その中間になる仕組みを自分で作りました。GitHub Copilot で Plan First 開発を回すための Agents を、.github/agents/ に置く形です。
狙いは、Plan モードの軽さは残しつつ、チケット単位の課題解決で必要になる「履歴」「レビュー」「実装抜けの検証」を足すことです。spec-kit を無理にチケット駆動へ寄せるより、この形の方が今のところかなり扱いやすいです。
使う流れ
まず plan-generation.agent.md でプランを作ります。これは Plan モードに近い役割ですが、リポジトリ上のファイルとして保存する前提にしています。この中で、ブラックボックスのテスト観点を作る integration-test-design.agent.md に書かれている内容も行うように指示しています。（必須のサブエージェント扱いというわけではなく、単に指示を書いているだけです）
ちなみに runtime-evidence.agent.md も行う指示が入っていますが、これは少し別の目的のものです。別の記事 で紹介しました。
次に plan-review.agent.md でそのプランをレビューします。実際、LLM に一発で作らせたプランは見落としがそこそこ出るので、このレビュー段階はかなり効いています。ちなみにこれは経験則ですが、作成を Claude 系、レビューを GPT 系にすると相性が良いと感じています。
その後は通常のエージェントで実装します。
実装が終わったら、integration-test-verification-implementation.agent.md で、事前に作ったブラックボックスのテスト観点をチェックリストにして、それぞれが UnitTest、手動確認、スキップ理由、または未実装差分として説明できているかを検証します。（テスト観点の同等のE2Eテストを目指すという事ではなく、抜けが無いかのチェックです）
ここで抜けが出た場合は、coverage-gap-resolution.agent.md で埋めます。実際に多いのは、「UnitTest 用のスタブはあるが、本物の実装が足りない」というパターンで、この検証を入れるとかなり拾えます。
注意点として、いずれもgitのワークスペース上に作成するように指示を書いていますが、gitにコミットする事は明示していません。必要に応じて手動でコミットする想定です。
実際に効いたポイント
一番効いたのは、各段階の成果物を git に残せることです。Plan モードだけだと途中経過が流れやすいのですが、ファイルとしてコミットできる形にすると、レビューや修正の履歴を追いやすくなりました。
もう1つ効いたのは、作成だけで終わらせず、対になるレビューと検証を入れたことです。プラン生成、レビュー、実装、観点ベースの検証、ギャップ解消まで分けると、単発生成でそのまま進めるより明らかに抜けを潰しやすいです。
実例
実際に使ってみた例としては、例えば次のリポジトリです。
zipファイルをAzure Blob Storageからダウンロードする機能を追加する、という課題でこのプロセスを回して、動作するものができました。ドキュメントとしては次のものです。
プランを作るだけではなく、それが実装されたかのチェックがちゃんと行われています。（チェック結果として残項目が有りますが、このときの目的としては重要な点ではなかったのでそのまま通しました）
まとめ
今のところ、チケット単位で「この課題を漏れなく解決してほしい」というケースでは、このやり方は上手く機能しています。用途に合わせて使い分けて上手くやっていくのが良さそうです。
Discussion