はじめに
こんにちは。アプリケーションサービス本部ディベロップメントサービス3課の北出です。
前々から概要は知っていたものの、最近になってようやく仕様駆動開発をちゃんと理解しようと思い、情報を集めていました。
仕様駆動開発とGitHub Spec Kit (以下 Spec Kit) は密接な関係にありますが、いざSpec Kitを使おうと思ってもそもそもどういう仕組みで動いているのかがわからないものをあまり使う気にはならなかったため、今回 Spec Kit がやっていることの中身を少し調べてみたので共有しようと思います。
仕様駆動開発とSpec Kit
これらについてはブログが数多くあるので詳しくは書きませんが、自分の中では大雑把に以下の理解です。
- 仕様駆動開発
- 実装前にコーディング前に詳細な機能仕様書を定義・明文化し、そのドキュメントに基づいてAIや人間が実装・テストを行う開発手法
- Spec Kit
- GitHubがオープンソースで公開した仕様駆動開発のためのツールキット
自分のなかでポイントかな～と思っていることとして、仕様駆動開発はあくまで開発手法であり、必ずしもAIを使わないといけないということはなく、Spec Kit はAIを使って仕様駆動開発するためのあくまでツールであるということです。
当たり前のことかと思いますが、「仕様駆動開発するぞ → Spec Kit を使わないといけない」わけではないということです。
Spec Kit はどのプロジェクトにもマッチする万能なツールというわけではないと思うので、仕様駆動開発をちゃんと理解して、 Spec Kit をベースにカスタムしてプロジェクトに合った仕様書やプロンプトを作成できるというのが理想の状態かと思っています。
とはいえもちろん Spec Kit は仕様駆動開発の汎用ツールではあると思うので、理解したうえで自分なりにカスタマイズできればいいなと思っています。
Spec Kit の初期設定
Spec Kit を理解するために、今回は Spec Kit が作成するファイル群を紐解こうかと思います。
Spec Kit のインストール手順などは探せばあると思うので省きます。
まずは specify init <プロジェクト名> でプロジェクトを作成します。AIエージェントは Amazon Q Developer CLI を選択し、スクリプトは sh を選択しました。
すると、以下のメッセージが出て複数のファイルが作成されます。
╭────────────────────────────────────────────────────────── Next Steps ──────────────────────────────────────────────────────────╮ │ │ │ 1. Go to the project folder: cd <プロジェクト名> │ │ 2. Start using slash commands with your AI agent: │ │ 2.1 /speckit.constitution - Establish project principles │ │ 2.2 /speckit.specify - Create baseline specification │ │ 2.3 /speckit.plan - Create implementation plan │ │ 2.4 /speckit.tasks - Generate actionable tasks │ │ 2.5 /speckit.implement - Execute implementation │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭───────────────────────────────────────────────────── Enhancement Commands ─────────────────────────────────────────────────────╮ │ │ │ Optional commands that you can use for your specs (improve quality & confidence) │ │ │ │ ○ /speckit.clarify (optional) - Ask structured questions to de-risk ambiguous areas before planning (run before │ │ /speckit.plan if used) │ │ ○ /speckit.analyze (optional) - Cross-artifact consistency & alignment report (after /speckit.tasks, before │ │ /speckit.implement) │ │ ○ /speckit.checklist (optional) - Generate quality checklists to validate requirements completeness, clarity, and │ │ consistency (after /speckit.plan) │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
作成されるファイルは以下になります。
<プロジェクト名>
├─.amazonq
│ └── prompts
│ ├── speckit.analyze.md
│ ├── speckit.checklist.md
│ ├── speckit.clarify.md
│ ├── speckit.constitution.md
│ ├── speckit.implement.md
│ ├── speckit.plan.md
│ ├── speckit.specify.md
│ ├── speckit.tasks.md
│ └── speckit.taskstoissues.md
└─.specify
├── scripts
│ └── bash
│ ├── check-prerequisites.sh
│ ├── common.sh
│ ├── create-new-feature.sh
│ ├── setup-plan.sh
│ └── update-agent-context.sh
└── templates
├── agent-file-template.md
├── checklist-template.md
├── constitution-template.md
├── plan-template.md
├── spec-template.md
└── tasks-template.md
Next Step にあるように、Spec KitのコマンドはAIエージェント内（今回は q chat 内) で実行することになります。
※Spec KitがAmazon Q Developer CLI をサポートしているので q chat と書いていますが、実際は kiro-cli chat になります。 q chat は kiro-cli chat でやっていると読み替えてください。 Kiro CLI で Spec Kit を使う場合はSpec Kit が .amazonq/ に作るファイルから .kiro/ にコピーする必要があります。
ただし、q chat 内では / (スラッシュ) ではなく、かわりに「@」を使うことでspeckitが起動します。
AIエージェント内での実行
q chat 内で @speckit.constitution <プロジェクト憲章の内容> とすると、プロジェクト憲章を作成してくれます。
Spec Kitにおけるプロジェクト憲章はAIに対してプロジェクトの目的や工程を共有するもので、実際のプロジェクト憲章とは違う印象です。
プロジェクトを一貫した原則になるので、Spec Kit のプロジェクト憲章に AWS CDK を使うであったり、テスト駆動開発であったりの技術的な要素も入れてもいいかもしれないです。
@speckit がspeckitのコマンドなんだと思うかもしれませんが、厳密にはそうではありません。
q chat における「@」はプロンプトライブラリに保存されたプロンプトを呼び出すコマンドになります。
参考 (Kiro CLI のドキュメント)
ですので、@speckit.constitution は .amazonq/prompts/speckit.constitution.md をプロンプトにしているだけという話であり、難しいスクリプトなどの実行などはしていません。
つまり、これらのプロンプトを理解できればSpec Kit をおおむね理解できたということにならないかと思っています。
.amazonq/prompts にあるプロンプトライブラリや、プロンプトが参照する.specify/ ディレクトリ配下のテンプレートファイルを日本語化したものを以下の GitHub に保管したので読み解いていきます。
まずは ステップ2.1 で呼び出している .amazonq/prompts/speckit.constitution.md を見ていきます。
プロンプトの理解
speckit.constitution
「ユーザー入力」にて、 ユーザー入力を引数として受け取っています。
「実行フロー」では .specify/memory/constitution.md を読み込んだり書き込んだりするような指示が書かれています。
「2. プレースホルダーの値を収集/導出」で * ユーザー入力（会話）が値を提供する場合、それを使用 * それ以外の場合、既存のリポジトリコンテキスト（README、ドキュメント、埋め込まれている場合は以前の憲法バージョン）から推測
とあるように、おそらく@specifyコマンドですべての文章を打たず、別で作ったマークダウンファイルへのパスをわたすなどでも見てくれそうです。
「4.一貫性伝播チェックリスト」では、仕様書や計画書などとの一貫性もチェックするように指示されています。
フォーマットなども明確に指示されています。
フローが明確で、プログラムを自然言語で書いているような印象を受け、ここまで詳細に書くことでAIエージェントが意図した通りに動いてくれるのかと思いました。
speckit.specify
ユーザーが与えた機能説明に対して、仕様書と仕様品質チェックリストを作るように指示されています。
「4.実行フロー」では、仕様を作成するための具体的な手順が書かれています。
実行フローの3. にて、以下の場合のみ「要明確化」のマークをするように書かれています。
■ 選択が機能スコープやユーザー体験に大きく影響する ■ 異なる影響を持つ複数の合理的な解釈が存在する ■ 合理的なデフォルトが存在しない
これらに該当しなければ深堀りはされないということになるので、AIの解釈にだいぶ依存しそうな気がします。
speckit.clarify.md
specify で作成した機能仕様に不明確な部分がないかを特定し、明確化するためのフェーズになります。
前提条件チェックにて、「リポジトリルートから .specify/scripts/bash/check-prerequisites.sh --json --paths-only を実行」とあり、スクリプトを実行する指示をしています。
このスクリプトは以下のパスが出力されるようです。
- REPO_ROOT: リポジトリのルートディレクトリ
- BRANCH: 現在のブランチ名
- FEATURE_DIR: フィーチャーディレクトリ
- FEATURE_SPEC: 仕様書（Feature Spec）のパス
- IMPL_PLAN: 実装計画書（Plan）のパス
TASKS: タスクリスト（Tasks）のパス
現在の仕様ファイルを読み込む 以降では、仕様を明確にするための詳細なフローが設けられています
speckit.plan.md
このフェーズでは実装計画をして、設計成果物を作成します。
ここでは、.specify/scripts/bash/setup-plan.sh --json を実行するような指示があります。このスクリプトの出力は以下になるようです。
- FEATURE_SPEC: 仕様書のパス
- IMPL_PLAN: 実装計画書のパス（今回作成されたファイル）
- SPECS_DIR: フィーチャーディレクトリのパス
- BRANCH: 現在のブランチ名
- HAS_GIT: Gitリポジトリかどうかのフラグ
既に作成したプロジェクト憲章と.specify/templates/plan-template.md をみて、実装計画を作成します。
plan-template.md の中身を見ると、技術コンテキストやプロジェクト構造が用意されています。
一部書き換えるなら
ここまで序盤部分を読んでみましたが、例えばプロジェクト向けに一部書き換えるなら以下が思い浮かびました。
.specify/docs ディレクトリを作成し、プロジェクト開始までのお客様とのやり取りや議事録などをマークダウンにして入れておきます。
その状態で、.amazonq/prompts/speckit.specify.md 実行フローに以下のような文章を追加します。
`.specify/docs` を読み込み、プロジェクトの補足情報を解析し機能説明に追加する
@specify コマンドですべての情報を整理していれるのは大変なので、このようにプロンプトを修正することでよりプロジェクト理解してもらえそうな気がします。
まとめ
まだほんの一部ですが、Spec Kit の中身を見てみました。
中身を見ると、Spec Kit がやっていることは言ってしまえばすごくちゃんとしたプロンプトをAIに与えているだけということなので、決してまねできないことはないと思います。
仕様駆動開発で効率よく開発はしたいけど、Spec Kit が微妙に手が届いていない部分や、定められた進め方が合わないというエンジニアやプロジェクトは多そうなので、これらをベースに現在の開発にうまく生成AIを取り込んでいけたらと思います。
