GitHub Spec Kitによる業務システム開発実践記録（第2回: 最初のSpecを作成してみる）

はじめに

前回は GitHub Spec Kit の環境構築を行い、プロジェクト全体の原則となる Constitution を作成しました。

前回の記事はこちらです。
GitHub Spec Kitによる業務システム開発実践記録（第1回: 環境構築とConstitution作成）

前回の記事の最後で「次は Spec を作る」と書いたのですが、実際に作業を始めてみると、ここが想像以上に重要な工程でした。

従来のシステム開発であれば、要件定義書や基本設計書を作成し、その中に複数の機能をまとめて記載することが少なくありません。

しかし Spec Kit では考え方が少し異なります。

最初私は「質問書アプリ全体を1つの spec.md にまとめれば良いのではと思うものの、それでは spec.md が肥大化しすぎて読みづらくなるのでは」と考えていました。

GitHub Copilot と相談しながら進める中で、Spec はできるだけ1機能に絞って作成した方が良いというアドバイスを受けました。

やはり機能ごとなど一定の粒度で spec.md を分割した方が読み手もそうですが管理も楽ですし、それによって GitHub Copilot もコード生成時のブレが減らせるのではないかと思います。

今回は、最初の Spec をどのように作成したのか、そしてその過程で何を考えたのかについて記録したいと思います。

まずは機能を分割する

今回開発している質問書アプリには複数の機能があります。

大きく分類すると、

• 管理者が行う質問登録・公開管理機能
• ユーザーが質問へ回答する機能

の2つに分かれます。

もちろん実際にはこれ以外にも認証機能や監査ログ機能、回答内容のエクスポート機能などが存在します。

しかし、いきなり全体を仕様化しようとすると spec.md が非常に大きくなってしまいます。
そこで GitHub Copilot と相談した結果、まずは管理者向けの機能から着手することにしました。

さらに管理者機能の中でも「質問定義ファイルをシステムへ取り込み、公開状態を管理する機能」だけを対象に最初の Spec を作成することにしました。

結果として最初に作成した Spec は、

1

001-question-definition-visibility

という機能になりました。

なぜこの機能から始めたのか

この機能を最初に選んだ理由は単純です。
質問書アプリ全体の中で最も重要な機能だからです。

今回のシステムでは、質問書そのものを JSON ファイルとして管理します。
管理者は毎年作成した質問定義ファイルを Azure Storage 上へ配置し、その内容をシステムへ取り込みます。
利用者は、その公開された質問定義に基づいて回答を行います。

つまり、この質問定義管理機能が存在しなければ、利用者向けの回答機能も成立しません。

また前回の記事でも書いた通り、今回のシステムでは Configuration Driven な設計を採用しています。

質問項目をコードではなく設定データとして管理することがプロジェクトの重要な原則になっています。

そのため最初に仕様化すべきなのは利用者向け画面ではなく、質問定義そのものを管理するための機能だと判断しました。

最初の Spec を作成する

最初に GitHub Copilot へ伝えたのは非常にシンプルな内容でした。

1
2
3
4
5
6

/spec.specify 
 管理者が質問定義JSONをAzure上ストレージへ配置し、
 管理画面からロードして認識。
 毎年1つ利用。
 管理者は表示/非表示を切替可能。
 表示時のみユーザー回答可能。

これだけです。(実際には1行の指示として書いています)

従来の要件定義書と比較すると、かなり粒度の粗い内容だと思います。

しかし Spec Kit では、まず大まかな要求を入力し、その後 Copilot との対話の中で曖昧な部分を明確にしていく流れになっています。

実際に /speckit.specify を実行すると、spec.md や requirements チェックリストが生成され、仕様のたたき台が作られました。

ここからが本格的な仕様検討の始まりです。

曖昧だった部分を一つずつ潰していく

Spec Kit によって最初に生成された仕様は、指示文を元にしたものではありますが、細かい点まで GitHub Copilot が考えて作成してくれていました。 そちらをベースに仕様作成を進めていくと、思っていた以上に決めなければならないことが次々に出てきました。

例えば最初に議論になったのは、同じ年度の質問定義を再度取り込む場合の扱いです。

当初生成された仕様では、同年度の定義が存在する場合はエラーとして拒否する形になっていました。
しかし運用を考えると、質問定義を修正して再度取り込むケースは十分に考えられます。

そこで「管理者へ確認を求めたうえで上書きを許可する」という形へ修正しました。

このような内容は要件資料には書かれていません。
実際に仕様を作ってみて初めて見えてくる論点でした。

なお、spec.md への反映は、GitHub Copilot と対話する中で自動的に更新されるため、自分で spec.md を変更することは一切ありませんでした。

JSON の形式も仕様に含めた

作業を進める中で、もう一つ気になったことがありました。
それは質問定義 JSON の形式です。

最初の仕様では「質問定義 JSON を取り込む」ということしか決まっていませんでした。

しかし考えてみると、

• JSON はどのような構造なのか
• 必須項目は何か
• 条件分岐はどう表現するのか
• 同年度判定は何で行うのか

といった内容が決まっていなければ実装できません。

そこで Copilot と相談したところ「JSON Schema を定義して契約として扱う方が良い」という提案を受けました。
この判断はきっとこの後の実装に効いてくるものと思われます。

仕様だけではなく、

• JSON Schema
• 運用ルール
• エラー定義
• サンプルファイル

まで含めて管理することで、実装者が迷う余地を減らすことができます。

Spec だけでは足りなかった

ここで面白かったのは、Spec から派生する成果物が増えていったことです。

当初は spec.md だけ作れば十分だと思っていました。

しかし実際には、

• question-definition.schema.json
• operation-rules.md
• validation-errors.md
• README.md
• サンプルJSON

といった文書も作成しています。

さらに 2023 年度の実際の質問書をサンプル JSON として変換し、スキーマに適合しているかも確認しました。

従来の開発であれば設計書の付録に書かれていたような内容ですが、Spec Kit では仕様の一部として明示的に管理していく考え方になります。

なお、公式文書を全部読んだわけではありませんが、クイックスタートを見ただけではこういった補足ドキュメントについては触れられていないため、これは実際に触ってみて得た成果になります。

Clarify で見えてきたこと

仕様策定が一通り終わった段階で、今度は /speckit.clarify を実行しました。

これは仕様の曖昧な部分や矛盾を検出するための工程です。

このコマンドを実行すると、GitHub Copilot が仕様の矛盾点やあいまいな個所を探し、仕様を具体化するための質問をしてきます。
この質問に順に応えていくことで、あいまい部分が排除されて仕様がより具体的になります。

ここで改めて質問された内容を見ると、実装よりも運用に近い内容が多かったのが印象的でした。

例えば、

• 同一年に複数の定義を保持できるのか
• 公開切り替え時に既存回答はどうするのか
• 更改切り替え時、回答移行が失敗した際に扱いはどうするのか

といった内容です。

特に回答移行については「既存回答を新しい質問定義へ自動移行する」という方針を選択しました。

さらに「移行できない回答が1件でも存在した場合は切替全体を失敗にする」というルールも決めています。

このあたりは実装を始めてから考えると手戻りになりやすい部分です。
仕様段階で整理できたのは大きな収穫でした。

認可や監査ログも早い段階で整理した

Clarify を進めていく中で、認証や監査ログの仕様も追加しました。

例えば管理者機能については、

• administrator ロールを持つユーザーのみ利用可能
• role クレームで判定
• 権限不足時はアクセス拒否

という内容を仕様へ反映しています。

また、監査ログについても、

• 誰が
• いつ
• 何を
• 成功したのか失敗したのか

を記録することを要件化しました。

ログに関する要件も仕様の中に盛り込むことで、実装段階でのブレを減らすことができるだろうと思います。

仕様策定にかかった時間

今回の作業時間は、

• Spec 作成と仕様検討で約4時間
• Clarify 実行後の調整で約1時間

でした。

合計すると約5時間です。

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

もちろんまだコードはなにも書いていません。

しかし、

• 質問定義の管理方式
• JSON Schema
• 運用ルール
• 認可
• 監査ログ
• 回答移行方針

まで整理できています。

従来の開発であれば、この段階の検討にもかなりの時間を使っていたと思います。

少なくとも現時点では、AI と対話しながら仕様を整理することで、要件定義や設計初期フェーズの生産性は向上しているように感じています。

次回予告

次回はいよいよ /speckit.plan を実行し、今回作成した仕様をどのように実装へ落とし込むのかを整理していきます。

今回作成した Spec は管理者向けの質問定義管理機能でした。

次は、この仕様を実現するために、

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

をどのように組み合わせるのか、アーキテクチャや実装方針を検討していく予定です。

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