はじめに
憲法(Constitution)を定めたら、次は仕様書です。/speckit.specify は、「何を作りたいか」を AI に伝えると、対話を通じて要件を整理し、spec.md を生成・更新してくれるコマンドです。
ここで一番のポイントは、実装の詳細ではなく「どんなユーザー体験を提供したいか」「どんなビジネスルールがあるか」を書く ことです。「仕様書」と聞くと具体的なクラス名やライブラリ名を書きたくなりますが、この段階ではそうではなく、ユーザー目線でどういうサービスにしたいか を書いていきます。技術選定はもっと後の工程(計画)で行います。
このシリーズでは、これまでに「Spec Kit の仕組み」「Constitution の設定」を扱いました。あわせて読むと、導入から実践まで一続きでつかめます。
この記事で分かること
-
/speckit.specifyが何をするコマンドか分かる - 仕様に「書くこと」と「書かないこと」の線引きが分かる
- 生成される
specs/001-.../spec.mdの構成(ユーザーストーリー・エッジケース・成功基準など)が読める - 同時に作られる
checklistsが何のためのものか分かる - 憲法の指示が効いていないとき(英語で返るなど)の見直し方が分かる
第1章:/speckit.specify の位置づけと「書くこと」
仕様書づくりは、憲法の次、計画(plan)の前に位置する工程です。
この段階で書くのは「What(何を)」と「Why(なぜ)」です。「How(どう実装するか)」は書きません。ここを混同すると、まだ決めるべきでない技術の話が仕様に紛れ込み、後工程がぶれます。
図の左側(ユーザー目線)に集中するのが、良い仕様書の第一歩です。
第2章:プロンプトを書いて実行する
エディタに戻り、Copilot チャットのエージェント選択から speckit.specify を選びます。今回は人事管理システムの最初の機能として、社員一覧画面 を作ります。
単に「社員一覧画面を作りたい」でも動きますが、その画面の目的や役割 を軽く添えておくと、AI が意図をつかみやすくなります。たとえば次のような形です。
社員一覧画面を作りたいです。
この画面を見れば、どんな社員がいるか、それぞれの役割・役職・年齢・勤続年数など、
多くの情報が分かるようにしてください。
この画面はトップ画面(ログイン後に最初に表示される画面)になります。
このプロンプトを入力して実行します。
第3章:生成された仕様書を読む
生成が完了すると、specs というディレクトリができ、その中に採番されたフォルダが作られます。今回は 001-employee-list という名前になりました。仕様書を増やしていくと、次は 002-... というように番号が増えていきます(この番号は Git ブランチにも対応します)。
ファイル構成はおおむね次のようになります。
人事管理システム/
└── specs/
└── 001-employee-list/
├── spec.md # 仕様書
└── checklists/
└── requirements.md # 仕様の品質チェックリスト
spec.md の中身
spec.md には、ブランチ名・日付・ステータスといったメタ情報に続いて、次のような要素が書かれます。
- ユーザーストーリー / ユーザーシナリオ:技術的な話ではなく、「システムにログインするとトップ画面で社員一覧が見られる」といった、どう使われるかの概要
- エッジケース:めったに起きないが起こり得るケース。たとえば社員数が1000名を超えたときのパフォーマンス、同姓同名の扱い、退職者の扱いなど
- 非機能要件:スマホ対応など、機能そのもの以外の要件
- 成功基準(success criteria):結果的にどんな挙動をすれば「うまく実装できた」と言えるか
ユーザーストーリーは、独立してテストできる価値の単位として優先度(P1・P2 など)付きで整理されることもあります。ざっと読んで違和感がなければ、次に進んで大丈夫です。
checklists/requirements.md の役割
spec.md と一緒に、checklists フォルダに品質チェック用のファイルも作られます。これは仕様書の 質(完全性・明確性)を評価するチェックリスト です。最初に定めたプロジェクトの検証条件を満たせているかを確認していく位置づけで、検証が済むと完了として記録されます。
このチェックリストは、いわば「英語(自然言語)に対するユニットテスト」です。実装後の QA テストではなく、実装を始める前に「要件がちゃんと書けているか」を検証するためのものだと理解しておくと迷いません。ファイル名や項目はバージョンによって変わり得ます。
生成される要素を整理すると、次のとおりです。
まとめ:仕様書づくりチェックリスト
-
/speckit.specifyは「何を作るか」を伝えてspec.mdを作るコマンドだと理解した - 実装詳細(クラス名など)ではなく、ユーザー体験・ビジネスルール(What / Why)を書いた
- 画面の目的や役割を軽く添えて、AI が意図をつかめるようにした
-
生成物が
specs/001-<機能名>/spec.mdに採番されて作られることを確認した -
spec.mdのユーザーストーリー・エッジケース・成功基準をざっと読んだ -
checklistsは要件の品質チェック(QA ではない)だと理解した - 憲法の指示が効いていないと気づいたら、憲法に戻って指示を強化する流れを知っている
仕様書ができたら、いよいよ「何を作るか」から「どう作るか」へ移ります。次回は、この仕様書から計画(plan)へ落とし込む工程を進めていきます。