GitHub Spec Kitによる業務システム開発実践記録（第5回: Feature Specの前にAIへ渡すべきコンテキスト）
前回の記事では、GitHub Spec Kitを利用した仕様策定から実装、テストまでの流れについて紹介しました。
その後も引き続き業務システム開発への適用を進めていましたが、ここにきて少し考え方を見直した方が良いのではないかと感じています。
今回の記事は「このやり方で成功した」という話ではありません。
実際に開発を進める中で感じた課題をCopilotやClaudeと議論した結果、「今後はこう進めた方が良いのではないか」という考えにたどり着いたので、その内容を整理しておこうと思います。
まだ実際にこの進め方でプロジェクトを完走した訳ではありませんが、少なくとも現時点ではかなり筋が良さそうに感じており、この後記載の内容で進めるように方向転換しようと思っています。
Spec Kitの流儀通りに進めていて感じた違和感
これまで私はSpec Kitの考え方に従い、機能単位でSpecを作成しながら開発を進めていました。
顧客管理、契約管理、ライセンス管理、レポートといった単位でFeature Specを作り、それぞれについてPlanやTasksを生成しながら実装する流れです。
このやり方は個々の機能を作り込むという意味では非常に優秀でした。
仕様が明文化されるためAIも迷いにくく、受入条件に沿った実装を行ってくれます。
これまでの記事でも紹介してきた通り、仕様から実装までを一貫して支援してくれる点については非常に大きな効果を実感しています。
しかし開発が進むにつれて少しずつ違和感を覚えるようになりました。
個々の画面や機能は着実に出来上がっていくのですが、システム全体として見ると完成形がなかなか見えてこないのです。
顧客管理画面はある、契約管理画面もある、レポート画面もある、しかしそれらがどのように接続され、ユーザーがどのような流れで利用するのかが実装としてなかなか見えてこないことに焦りを感じていました。
特に画面遷移を実装しようとしたタイミングでこの問題を強く感じるようになりました。
個々のFeature Specは存在するものの、機能同士の接続がAIに指示しても思うように実装されず、完成形を確認できる状態までなかなか持っていけなかったのです。
さらに困ったのはお客様への説明です。
お客様が知りたいのは機能一覧ではなく、システムを利用したときの完成イメージです。
ログインしてからどのような画面遷移で業務を行い、最終的にどのような価値が得られるのかをモックを見ながら理解したいはずです。
しかしFeature Specだけを中心に進めていると、モックで説明するということが難しくなります。
開発者である私自身も、何をどうしたら機能間がうまく結合されていくのかが見えず、個別機能は進んでいるのに完成へ向かっている実感が薄く、進捗が計れなくなっていました。
全体設計を作っていなかった訳ではない
システム開発に携わっている方であれば当然だと思いますが、業務システム開発では最初に全体像を整理します。
機能要件一覧を作り、業務フローを整理し、画面構成を検討し、画面遷移を設計します。
お客様へ提案するための資料も作りますし、システム構成図も描きます。
私自身もそれらは最初から作っていました。
つまり、システム全体像が存在していなかった訳ではありません。
問題は、その全体像がPowerPointの中に閉じ込められていたことでした。
お客様向け説明資料にはシステム概要もありますし、画面一覧もあります。
画面イメージもあれば、大まかな画面遷移やシステム構成図もあります。
人間が見る資料としては十分に機能していました。
しかし実際にSpec Kitを利用して開発を始めると、それらの情報はほとんど参照されなくなります。
AIへ渡していたのはFeature Specだけでした。
人間であれば必要になったときにPowerPointを見返しながら開発できます。
しかしAIは毎回Feature Specを中心に解釈して実装を進めます。
その結果、個々の機能は綺麗に出来上がる一方で、システム全体としての一貫性や完成イメージが徐々に弱くなっていくのではないか。
今振り返ると、今回感じていた違和感の原因はそこにあったように思います。
CopilotやClaudeとの議論で見えてきたこと
この問題についてCopilotやClaudeとも議論してみました。
最初はVision Specを作るべきなのか、Architecture Specを作るべきなのか、といった話から始まったのですが、議論を重ねるうちに少しずつ整理されてきました。※Vision Spec、Architecture Spec、この後出てくるSystem Shell Specについては後述します
そこで見えてきたのは、従来から作っている全体設計資料を、AIが利用できる形へ変換する工程が必要なのではないかという考え方です。
これまでは、
| |
という流れでした。
しかし本来は、
| |
という流れにした方が良いのではないかと考えるようになりました。
つまりPowerPointを作ることが重要なのではなく、その内容をAIが参照できる共通知識へ変換することが重要だったという話です。
Constitutionには何を書くべきなのか
最初はArchitecture Specの中にシステム構成や技術方針をまとめようと考えていました。
しかしCopilotやClaudeと議論を続ける中で、これはConstitutionに入れるべき内容とArchitecture Specに入れるべき内容を分けて考える方が自然ではないかと思うようになりました。
例えば、
「マルチテナントであること」
「認証はEntra IDを利用すること」
「Azure Nativeを前提とすること」
「FrontendはNext.jsを利用すること」
「Infrastructure as CodeはBicepで管理すること」
といった内容は、システムの構成図ではなくプロジェクト全体の原則です。
これらはFeatureによって変わるものではありません。
つまり、どう作るかよりも、このプロジェクトでは何を守るかに近い内容です。
Spec KitのConstitutionはまさにこういったプロジェクト全体のルールを管理するために存在しているように感じています。
そのため、PowerPointの中に存在するシステム方針や技術方針は、最初にConstitutionへ反映しておくべきなのではないかという考えに至りました。
Vision Specはお客様向け資料をAIが読める形へ変換する
一方でVision Specの役割は少し異なります。
ここでは実装の話をするのではなく、システム全体の目的や利用者、業務フロー、機能一覧、画面一覧、画面遷移といった内容を整理します。
イメージとしては、お客様向け説明資料の内容をMarkdownとして再構成し、AIが継続的に参照できるようにするものです。
お客様へ説明する際にはPowerPointの方が断然分かりやすいですが、AIと開発を進めるのであれば、それをVision Specとして構造化しておく方が扱いやすいのは当然のこと。
個人的には、PowerPointからVision Specを生成するという流れがかなり相性が良いのではないかと考えています。
Architecture Specはシステム構造の説明書
Architecture Specには、Constitutionでは扱わないシステム構造そのものを記載します。
システム構成図やデータモデル、ドメインモデル、サービス間の境界、主要エンティティの関係などがここに入ります。
例えば、
「TenantとUserがどのような関係にあるのか」
「LicenseやSubscriptionがどのように紐付くのか」
「システム内のドメインはどのように分割されるのか」
といった内容です。
私は最初、この辺りもConstitutionへ書くのかと思っていましたが、よく考えるとこういった設計は将来的に変更される可能性があります。
一方でConstitutionはプロジェクト全体の原則として長期間維持されます。
そのため、Constitutionは原則、Architecture Specは設計、という分担の方がしっくりきています。
System Shell Specは最初の実装対象
もう一つ面白かったのがSystem Shell Specという考え方です。
これまで私は機能ごとの開発を優先していました。
しかし今振り返ると、最初に作るべきだったのは機能ではなくシステム全体の骨格だったと感じています。
ログイン画面があり、共通レイアウトがあり、サイドメニューがあり、ダッシュボードがあり、主要な画面へ遷移できる状態を先に作る。
中身の機能はまだ存在しなくても構わない。
そうすることで、開発のかなり早い段階からシステム全体を実際に操作しながら確認できるようになります。
お客様にも説明しやすくなりますし、開発者自身も完成イメージを共有しやすくなります。
そしてこのSystem Shellこそが、最初にSpec Kitで実装対象として扱うFeatureになるのではないかと思っています。
この後、試してみたい進め方
現時点では、次のような流れが良いのではないかと考えており、今のプロジェクトについては一から開発しなおそうと思っています。
今舵を切ればまだ間に合うので！
まずお客様向けのPowerPoint資料を作る。
その内容からプロジェクト原則をConstitutionへ落とし込み、システム全体像をVision Specとして整理する。
その後、システム構造をArchitecture Specとしてまとめ、System Shell Specによってシステムの骨格を実装する。
そして最後に各機能をFeature Specとして分解していく。
これは決して新しい考え方ではなく、むしろ従来のシステム開発で当たり前に行っていた全体設計を、AI駆動開発の世界へ持ち込もうとしているだけです。
違うのは、人間のためだけに全体設計を作るのではなく、AIも利用できる形で管理しようとしている点です。
これまでは「良いFeature Specを書くこと」に意識が向いていました。
しかしその前に、「AIがシステム全体を理解できる状態を作ること」が重要になるのではないかという気がしています。
まだ仮説の段階ではありますが、実際にこの進め方を試しながら、Constitution、Vision Spec、Architecture Spec、System Shell Specがどの程度有効に機能するのか検証していきたいと思います。
続きのブログで報告していきますね。