虎の穴ラボの古賀です。主な担当は各プロダクトのセキュリティ対応、アーキテクト検討、フロントエンド設計＆実装です。

最近の推しは「ちいかわ」です。ついに島編（セイレーン編）が映画化決定しましたね。子供や妻と毎週アニメも見てコミックもチェックしつつ、グッズも集めていますがとっても楽しみです。

今回は、「Spec KitとGitHub Copilot Agentで社内ツールを作ってみた〜開発フローをAI製のツールで改善した話〜」というテーマで、実際にSpec Kitを使って社内ツールを開発した際の知見や、GitHub Copilot Agentsとの併用について共有します。

Spec Kitとは、「AIとの協働において、コードを書く前に『仕様（Spec）』を厳密に定義し、それを起点に実装までを自動化・管理する『仕様駆動開発（SDD）』のためのツールキット」です。

↓ 続編はこちら

toranoana-lab.hatenablog.com

1. 開発の背景（なぜツールを作ったか）

所属するチームには、従来からタスク管理の課題がありました。チームではスクラムのスプリントプランニングの時に、上司と複数プロダクトのタスクの割合をすり合わせします。

しかし、複数プロダクトが並行するため、タスク割合を把握しづらいという問題がありました。

従来はMarkdownを都度作成し、Backlogに貼って定例で確認していましたが、これが面倒で見づらいものでした。例えば、以下のようなMarkdownを手動で作っていました。（スクラムの期間は2週間です）

### 定型タスク
|                | 種別  | 予測工数 |     |
| -------------- | :-: | :--: | :-: |
| 休暇・祝日など        |     |  24  |  H  |
| 定例             | MTG |  .5  |

...（他に20個程度）

合計時間：54h
残り時間：80h - 54h = 26h

### プロダクト1
- プロダクト1 見積もり/設計：10h
...

この運用だと、タスク単位のため「プロダクト1とプロダクト2の割合は…？」とパッと見でわからず、2週間ごとの入力や手動計算が手間でした。プロダクトごとに集計するとさらにプランニングの手間が増えてしまうのでやりたくありません。

また、Markdownは簡単に崩れるし、並び順も適当になってしまいます。

そこで、以下の要件を満たすツールを作ることにしました。

工数の合計と残り時間を自動計算する。
CSVやTSVをペーストして入力できる。
過去のスプリントをコピーして新規作成できる。
タスクを共有できる。

正直、スプレッドシートとGoogle Apps Script (以降、GAS)やRedmine等でも良かったんですが、そこまで仕様も難しくなく、最近話題のSpec Kitを試すのにちょうど良さそうだったので、あえてSpec Kitで開発してみました。

2. Spec Kit 導入時の注意点

導入にあたっていくつか注意点（exe版が欲しい！と感じる点）がありました。

1. uv が必須 Pythonのパッケージ管理ツール uv が要求されます。以前は公式ドキュメントに明記されていませんでしたが、必須です。私はずっとpip/venvユーザーだったので、この機会に brew install uv でインストールしました。

2. Python 3.11+ が必須 古いPythonバージョン（例: 3.10以下）ではエラーが発生しました。これも最初はREADMEに記載がなく悩みましたが、macOS標準のPython 3.9やAIでよく使われるPython 3.10では動かないため、新しいバージョンをインストールしました。

3. Spec Kitによるツール開発

システム構成

以前から試したかった、Next.jsなしのReact SPA構成にしました。

フロントエンド： React / TypeScript / Vite / Vitest
バックエンド： TypeScript / Express

Hono、Astro、Remixなども悩みましたが、今回はお試しなので「AIに優しい過去の情報量が多い構成」を選びました。

その代わり古いバージョンややり方のノイズを得やすくなる可能性もあります。

開発フロー

Spec Kitを使った開発は、基本的にチャットベースで進みます。

(1) AIとのチャットで要件定義（specify / clarify）

まず、「従来のMarkdown」や「ツールの要件」のメモ書きをSpec Kitに渡し、/speckit.specify コマンドで要件を整理します。次に /speckit.clarify を実行すると、AIが気づきにくい曖昧な点を質問形式で潰してくれます。

一度に5個程度質問されるので、これを必要無くなるまで繰り返します。

(2) 計画と品質チェック（plan / checklist）

/speckit.plan で技術的な手法や言語・フレームワークを提示します。続いて /speckit.checklist を実行します。これは品質チェックのリストを生成してくれるもので、品質的にどれを重視するべきか（UX、パフォーマンス、エッジケースなど）を確認してくれます。

(3) タスク分解と分析（tasks / analyze）

/speckit.tasks で開発タスクをリスト化します。その後に /speckit.analyze を実行するのがポイントです。

タスクの抜け漏れ、整合性、曖昧な表現、カバレッジ不足、表記揺れ、重複などの修正案を出してくれます。

(4) 実装（implement）

最後に /speckit.implement で実装を開始します。注意点として、次のステップに進むか、コマンドの実行確認などで頻繁に確認を求められ、何度も途中で停止します。

エラーになったら前まで戻って再指示するか、やり直しで進める必要があります。

完成したもの

実際に完成したツールの画面がこちらです。UIはWCAG 2.2に準拠を指示したのでWCAG 2.2に準拠したよくあるUIっぽい感じになっています。

4. 開発結果（良かった点・微妙な点）

良かった点

Spec Kit（とCopilot）が、ほぼバグのないアプリをフルスクラッチで一気に作ってくれました。

多機能なアプリが爆速で完成:
- UIには工数割合がわかるグラフが追加され、いい感じに仕上がりました！
- 前スプリントのデータをコピーする機能や、メモ書きからの自動入力機能も実装されました。
- 休暇やフレックスタイムを考慮した工数自動計算も可能です。
品質への配慮:
- ユニットテストも作成済みです。
- 「WCAG 2.2に準拠して」と補足することで、見えにくい文字色や曖昧なUIが出にくくなりました。
柔軟な指示への対応:
- 「将来的にOSSにしたいので、柔軟な設定ができる設定画面を作って」という適当で曖昧な指示でも、良い感じの設定画面が生成されました。

微妙な点・課題

便利な反面、課題もありました。

ロジックのブラックボックス化（バイブコーディングの弊害）:
- 生成されたコードのロジックを私が全く把握しておらず、他人が作ったプロジェクトの改修を指示している感覚に陥ります。気軽に私で修正できる感じではなくなったのでかわりにAIで修正もしています。
- Reactコンポーネントの作りが多様で読みづらく、自分で作るより記憶に残らないため、AIを使わない改修が億劫になります。プログラミングの腕は落ちそうでスキルの維持には工夫が必要かもしれません。
デグレ・不具合の発生:
- 仕様を修正・機能追加すると、指示に関係ない箇所も仕様書に合わせようとして修正が入り、特に数値計算系でデグレが頻発しました。
- 画面の編集項目はあるのにDB保存処理がない、といったBackend/DB間の不整合もありました。
UI/UXとロジックの不整合:
- ダーク/ライトテーマ切り替えでの視認性問題や、円グラフの崩れなどが発生しました。HTML/CSSとロジックの整合はまだ難しいようです。
Yesを入力しないと先に進まない:
- /speckit.implement 中は数分おきに回答を求めてくるので、いつの間にか作業が止まっていることがあります。
- VSCode設定の "chat.notifyWindowOnConfirmation": true を設定しておくと、ウィンドウがアクティブになるのでオススメですが完璧ではありません。Claude Codeのhooksの方が優秀です。

5. GitHub Copilot Agents との併用

Spec Kitで作成した仕様書は別のエージェントでも使えます。そこで、「仕様の作成（Spec Kit）」と「仕様に則った開発（GitHub Copilot Agents）」を分離するアプローチを試しました。

バグ修正や機能追加は、GitHub Copilot Agentsへ丸投げします。VSCodeのチャットや、GitHubのIssueから依頼が可能です。特にIssueで依頼を残したい時や、長文のMarkdown指示や画像やエラーログがある時にIssueからの依頼が便利です。

良かった点

Issueで履歴が残る: Spec Kitのローカル履歴と違い、PRで作業が残るため管理が簡単です。
作業の並行化: AIに任せている間に人間は別の作業（メインプロダクトの調査など）を進められます。Spec Kitのように何度も「Yes」を確認されることもありません。

微妙な点・課題

再指示の限界: @Copilot で再指示できますが、3〜4回繰り返すとかなり頭が悪い状態になります。そうなったらマージして別のPRにするか、Issueを立て直した方が早いです。
完了まで遅い: 20分〜40分ほどかかります。GitHub Actions（GHA）上でテストや静的解析まで実施しているためと思われます。余裕を持って並行作業を前提にするのが良さそうです。

まとめ

Spec Kitは新規開発において非常に効率的で、初期MVPの開発を楽にしてくれます。考えることが多い新規開発で、選択肢を提案してくれるのはとても強力です。一方で既存開発の場合、Spec Kitは質問が多く手間がかかるため、GitHub Copilot Agentsや他のエージェントの方が効率が良いと感じました。

今回作った社内タスク管理ツールもチームで使われており、以前より見やすく入力も楽になったので結果オーライです。（スプレッドシート＋GASでも良かった説はあります…が、Spec Kitを試したかったということで。）

ちなみに、GitHub Copilot Chatのモデルは「Auto」固定で使っています。モデルを選ぶ手間がなく便利です。

ありがとうございました！

↓ 続編はこちら

toranoana-lab.hatenablog.com

付録

付録1：セットアップの補足

Spec Kitを使うには、uv と python 3.11+ の準備が必要です。準備ができれば以下のコマンドを実行します。

uv tool install specify-cli
uv tool update-shell

これでインストールは完了です ✅。シェルを再起動して specify コマンドを実行し、Specifyのロゴが出ることを確認してください。

付録2：プロジェクト初期化の補足

プロジェクトの初期化コマンド specify init についての注意点です。このコマンドは、利用するAIエージェントの分だけ繰り返す必要があります。

specify init .  --ai copilot  # GitHub Copilot追加
specify init .  --ai claude   # Claude Code追加

オプションなしで実行しても後から選べます。既存プロジェクトの場合は specify init . 、新規の場合は specify init <プロジェクト名> とします。

実行後、以下のようなファイル群が追加されます。

.github/prompts: speckitコマンドのプロンプトファイル
.specify/scripts: speckitのスクリプト
.specify/templates: speckitコマンドのテンプレート
.specify/memory/constitution.md: プロジェクト固有のルール
spec/案件名: 案件ごとの仕様フォルダ

付録3：仕様構築の補足

仕様構築は、基本的に以下の5つのコマンドを順に進めていきます。

/speckit.constitution：非機能要件の検討
/speckit.specify：要件定義（実行後に新規ブランチと /specs/{ブランチ名} フォルダが作成される）
/speckit.plan：基本設計
/speckit.tasks：タスク細分化
/speckit.implement：実装開始

チャットの応答は遅いため、要件や仕様は事前にメモ書きレベルでも整理しておくと、そのまま貼り付けできて効率が良いです。コマンドはGitHub Copilotのチャット画面に候補が表示されるので、覚える必要はありません。

また、以下のオプションコマンドを活用すると品質が向上します。

/speckit.clarify：曖昧な部分を明確にするための質問をしてくれます。/speckit.plan の前に実行します。
/speckit.checklist：品質チェックリストを生成します。/speckit.plan の後に実行します。
/speckit.analyze：タスクの抜け漏れや整合性を分析します。/speckit.tasks の後に実行します。

採用情報

虎の穴ラボでは一緒に働く仲間を募集中です！
この記事を読んで、興味を持っていただけた方はぜひ弊社の採用情報をご覧ください。
toranoana-lab.co.jp