GitHub Spec Kitによる業務システム開発実践記録（第3回: Plan・Tasks・Analyzeで実装準備を整える）

はじめに

前回は GitHub Spec Kit を利用して、最初の Spec を作成しました。

前回の記事はこちらです。
GitHub Spec Kitによる業務システム開発実践記録（第2回: 最初のSpecを作成してみる）

前回は /speckit.specify と /speckit.clarify を実行し、質問定義ファイルの取り込みと公開管理機能について仕様を整理しました。

質問定義ファイルの構造や JSON Schema、運用ルール、認可要件、監査ログ要件なども整理し、仕様としてはかなり具体的な状態まで持っていくことができました。

今回はその続きとして、

• /speckit.plan
• /speckit.tasks
• /speckit.analyze

を実行し、実装前の準備を進めていきます。

結論から言うと、このフェーズは前回の Spec 作成や Clarify と比べるとかなり軽量でした。
作業時間も合計で約2時間程度です。

ただし、その短い時間の中で、実装に入る前に気付いておくべき問題点や不足事項を見つけることができました。

Planで実装計画を作成する

前回までの作業で仕様は整理できました。

しかし実際にコードを書くためには、

• どのような構成で実装するのか
• データ構造をどうするのか
• どの Azure サービスを利用するのか
• フォルダ構成をどうするのか

などを決める必要があります。

そこで最初に /speckit.plan を実行しました。

Quick Start などを見ると、Plan 実行時には利用技術を追加で指示する例が紹介されています。
しかし今回は少し状況が異なり、前回作成した Constitution の中で、

• React
• Azure Functions
• Azure Blob Storage
• Azure Entra ID

といった技術選定や設計原則をあらかじめ定義していたので、今回は追加の指示を与えず、そのまま /speckit.plan を実行してみました。

結果として、Constitution の内容を踏まえた計画が自動生成されました。

Planで生成されたドキュメント

Plan を実行すると、思っていたより多くの成果物が生成されました。

中心となるのは plan.md です。

このファイルには、これから作成する機能のアーキテクチャやフォルダ構成、利用する技術スタックなどがまとめられていました。
さらに、それ以外にも複数のドキュメントが生成されました。

まず research.md です。
これは実装を進める際に判断が分かれやすいポイントについて、どのような方針を採用するかを整理したドキュメントでした。

次に data-model.md です。
こちらには主要データの構造が定義されていました。
質問定義ファイルや公開状態など、本機能で扱うエンティティが整理されています。

そして quickstart.md も生成されました。
ファイル名を見ても何のためのドキュメントなのか分かりませんでしたが、読んでみると将来的な受入試験シナリオのような内容になっていました。
実装完了後、どのように動作確認を行うのかが記載されています。

単なる設計資料だけではなく、実装後の検証方法まで先に用意されるのが AI 駆動開発らしいポイントだなと思いました。

Planは二段階構成

生成された plan.md を読んでいると、Phase 0 と Phase 1 という構成になっていることに気付きました。

Phase 0 は設計に入る前の事前調査フェーズです。
不確定要素を潰し、技術的な方向性を確認することが目的になっています。

そして Phase 1 が実際の設計フェーズでした。
ここで各種設計資料やデータモデルを作成する流れになっています。

計画を明示的に作ることで、実装に入る前の抜け漏れを減らそうとしているように見えます。

Copilotにセルフレビューを依頼してみた

Plan を読んだ限りでは特に問題は見当たりませんでした。
しかし、せっかく AI と一緒に進めているので「Plan に不足している内容はないか」を GitHub Copilot に確認してみました。

すると、Plan の生成結果自体には含まれているものの、以前作成したドキュメントに反映されていないというレビュー結果が返ってきました。

つまり Plan の問題ではなく、

• Spec
• Contract
• Constitution

などとの整合性の問題でした。

そこで一部のドキュメントへ修正を加えました。
また、私自身も気になっていた点を確認しました。

例えば、管理画面の画面遷移についてです。
この時点では詳細な画面遷移定義はありませんでした。
今の段階で定義しなくても問題ないのか、それとも設計として整理しておくべきなのかを Copilot と確認しながら進めました。

こうしたセルフレビューを数回繰り返し、実装前の設計として問題ない状態まで整理していきました。

Tasksで実装作業へ分解する

Plan の内容に問題がなくなったところで、今度は /speckit.tasks を実行しました。

ここでは設計内容を具体的な実装作業へ分解していくのですが、 /speckit.tasks 実行後に生成された tasks.md には、タスクは全部で60件近く定義されていました。
Spec Kit は単純にタスク一覧を作るのではなく、まず実装フェーズ全体を複数の段階に分割して整理していました。

最初は Setup フェーズです。ここでは管理画面や Azure Functions、契約定義を利用するための最低限のフォルダ構成やプレースホルダーを作成します。

続いて Foundational フェーズがあります。
ここでは認可、監査ログ、相関 ID、質問定義のドメインモデル、Blob Storage へのアクセス、エラー契約、多言語対応といった全ユーザーストーリー共通の基盤部分を実装します。
このフェーズは後続の実装を進めるための前提条件として位置付けられていました。

その後はユーザーストーリー単位でタスクが整理されていました。

User Story 1 では質問定義ファイルの取り込み機能を実装します。インポート API、上書き判定、実行状態管理、監査ログ、管理画面、エラーパネル、多言語対応などが対象です。

User Story 2 では質問定義の公開状態や回答可否状態の切り替え機能を実装します。公開状態切替 API や回答移行処理、確認ダイアログなどが含まれていました。

User Story 3 では利用者が回答できる条件を制御する機能を実装します。公開状態かつ回答許可状態の質問定義だけを利用できるようにするための API や画面制御が整理されていました。

最後に Polish フェーズがあり、API 契約書の更新、運用ルールとの整合確認、受入テストシナリオの実施、多言語対応の確認、アクセシビリティ対応、README や ADR の更新などがまとめられていました。

一般的な開発作業でも WBS を作って作業を分解して順番に作業を進めていきますが、Spec Kit も同様に作業を分解して進めていくようになっていました。

内容としても特に違和感はなく、実装フェーズへ進むための十分な粒度になっていると感じました。

Analyzeで最後の整合性チェックを行う

続いて /speckit.analyze を実行しました。

個人的には、このフェーズが一番興味深かったです。

Analyze は単に設計レビューをするのではありません。
Constitution、Spec、Plan、Tasks といった主要ドキュメント全体を横断的に確認します。

例えば、

• Constitution に定義した原則と矛盾していないか
• Spec に定義した要求が Tasks に落ちているか
• 仕様上の抜け漏れはないか

といった観点でチェックが行われます。

実際に実行するといくつか指摘が出ました。

• FR-024
• FR-025
• FR-026
• 多言語対応（i18n）
• FR-021 に関する UI 案内
• SC-003 の測定条件

などについて補強が必要という指摘です。

指摘内容を確認し、必要だと思ったものは反映しました。
このあたりは人間同士の設計レビューでも出てきそうな内容で、GitHub Copilot が自分で気づいたものや私の指摘によって気づいたものなど、色々ありました。
一つ一つの対応について、AI が Constitution や Spec、Tasks から読み直して確認してくれるため、かなり網羅的にチェックされている印象を受けました。

そうやって、恐らく6回程度 analyze と修正を繰り返して、実装へ進める段階まで到達しました。

実装工数を聞いてみた

Analyze が終わった段階で「このまま実装するとどれぐらい時間がかかるのだろう」と思い、GitHub Copilot に聞いてみました。
すると回答は予想より大きなものでした。

60タスクを一気に実行する場合、実装だけで約3〜8時間。
さらに人間によるレビューを含めると約2日。
という見積りでした。

さすがに Implement を指示してそんなにも長い時間処理させ続けて、大量に生成されたコードを一気にレビューするのは非現実的だと思い、一回の作業単位を小さくさせたいと考えました。

そこで「もっと小さな単位に分割し、人間レビューをしやすくできないか」と相談してみました。

60タスクを6つのWaveへ分割する

その結果、Copilot から別案が提示されました。

60タスクを6つの Wave に分割し、各 Wave 完了後に人間がレビューを行うという方式です。

私はこの案を採用しました。

最終的には以下のような構成になりました。

Wave別の実装時間

実装のみの合計時間は約5.8〜11.5時間という試算になりました。
さらに各 Wave ごとにレビュー時間を見積もると、全体では約8〜15時間程度になりそうです。

もちろん実際にやってみなければ分かりません。
ただ、少なくとも「一気に全部実装する」よりも、「小さく実装して小さくレビューする」方が、AI 駆動開発には向いているように感じています。

ここまでの作業時間

今回の作業時間は約2時間でした。

前回の Spec 作成までが約10.5時間だったので、ここまでの累計作業時間は約12.5時間になります。

クレジット消費は約600程度で、ここまでの累計が約1,350程度になります。

前回の Spec 作成や Clarify と比べると、作業そのものはかなり軽量でした。

しかし、

• 実装計画の作成
• データモデルの整理
• 実装タスクへの分解
• ドキュメント間の整合性チェック
• 実装順序の最適化

まで進めることができました。

ここまでで、質問定義ファイルの取り込みと公開管理機能の実装前に必要な準備はほぼ完了した状態になっています。

次回予告

次回はいよいよ /speckit.implement を実行し、質問定義ファイルの取り込みと公開管理機能のコード実装へ入ります。

今回整理した Wave 単位で実装を進めながら、

• AI がどこまで自律的に実装できるのか
• 人間はどのタイミングでレビューするべきなのか
• 実際の作業時間はどれくらいになるのか

を確認していきたいと思います。

また引き続き作業時間やクレジット消費量も記録しながら、140人日と見積もられたシステムを AI 駆動開発でどこまで実現できるのかを追いかけていきたいと思います。