仕様駆動開発の始め方：GitHub Spec Kit・KiroでAI実装を進める

文書を増やすことが目的ではありません。必要なのは、創業者が意図しない振る舞いを指摘でき、エンジニアが設計案を検討でき、レビュアーがマージに必要な検証結果を判断できる、簡潔な合意です。

初めて試すなら、普段使っているリポジトリの中から、範囲を絞れる機能を選びます。エクスポート、承認ルール、通知設定などで試すほうが、アプリケーション全体の仕様をエージェントに書かせるよりも、この手法の効果が見えやすくなります。

仕様駆動開発とは？

AIエージェントを使う仕様駆動開発（スペック駆動開発）では、期待する振る舞いを記述してレビューし、その内容を計画、タスク作成、実装、検証のよりどころにします。 仕様には「何が起きるべきか、その理由は何か」を書きます。計画には「既存のアプリケーションでどう実現するか」を書き、タスクでは、その計画を確認可能な作業に分けます。

AIが登場する以前から、振る舞い駆動開発のように、仕様を実行可能なテストとして扱う関連手法がありました。その考え方はこのワークフローとも両立します。ただし、Markdownで書いた仕様そのものが実行可能なテストになるわけではありません。CucumberのBDDドキュメント。

実務上の変化は、コーディングエージェントが実装の各段階でこれらの文書を読み込めるようになったことです。GitHub Spec Kitは、エージェントの作業を整理するオープンソースのツールキットで、手持ちのエージェントに開発プロセスを組み合わせられます。AWSのコーディング環境であるKiroは、仕様に基づくワークフローを製品に組み込んでいます。どちらを使っても、顧客にどのような体験を提供するかは自分たちで決める必要があります。

ドキュメントの確認日：2026年10月13日。 以下のコマンド名、ファイルパス、機能は、確認時点のGitHub、Kiro、Anthropic、OpenAIのドキュメントに基づきます。後半の機能実装例は説明用のもので、本番導入の実績や、生産性を測定した試験結果を示すものではありません。

開発者にとっては、実装対象を小さく保てることが利点です。エージェントには、機能の周辺まで設計し直すのではなく、既存のアプリケーションを再利用させます。運用担当者や創業者にとっては、重要なレビューを早い段階で行えます。エクスポートボタンを確認する前に、誰がデータをエクスポートできるかを決めるのです。導入を判断する人にとっては、この手法を採用するために開発者全員を新しいエディタへ移す必要がない点も重要です。まず今あるエージェントで始め、文書の維持が課題になった段階で、管理を支える仕組みに投資できます。

仕様駆動開発の進め方：仕様から実装まで

文書は役割ごとに分けておきます。それぞれが答える問いは違うからです。アーキテクチャ図では未決定のプロダクトルールは決まりませんし、タスクリストだけでは機能が動くことを証明できません。

振る舞いを決める責任は、創業者またはプロダクトオーナーが持ちます。設計がシステムに適合するかを判断する責任は、エンジニアリングリードが持ちます。エージェントはどちらの草案も作れますが、文章が流暢だからといって、判断が正しい証拠にはなりません。

仕様駆動開発のツールは、必要な仕組みの量で選ぶ

どこで連携がうまくいかなくなるかを基準に、ツールを選びます。GitHub Spec Kitは、既存のエージェントを使いながら、リポジトリで繰り返し使えるプロセスを整えたい場合に向いています。Kiroは、要件、設計、タスク実行をコーディング環境の中で扱いたい開発者に向いています。最初の機能で試す場合や、すでにレビューの習慣が定着しているチームなら、通常のファイルで十分です。

GitHub Spec Kitのコマンドと確認するファイル

GitHub Spec Kitが提供するのは、再利用できる指示、テンプレート、補助スクリプトです。実際の作業は、選択したコーディングエージェントが行います。現在のREADMEは、プロジェクトの原則を定め、機能を仕様化し、計画を立て、タスクを作成して実装し、最後に未対応の箇所を確認する、という基本の流れを明示しています。

現在のREADMEでは、Python 3.11以降、Pythonパッケージインストーラーのuv、対応するエージェントが必要とされています。セットアップ例で使われているのは、GitHubのコーディングアシスタントであるGitHub Copilotです。ターミナルで次を実行します。

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

続いて、そのディレクトリでコーディングエージェントを起動します。ワークフローの各指示はエージェントのチャットで実行し、出力をレビューしてから次へ進みます。これらはシェルコマンドではありません。

コマンド名の表記の違いには注意が必要です。READMEはCopilotのデフォルトのスキル構文である/speckit-specifyを使っています。詳細なコマンドリファレンスは、ドット区切りの/speckit.specifyです。Codexのスキル連携では$speckit-specifyを使います。導入した連携に対応する構文を使ってください。記号を置き換えて使うことはできません。連携リファレンス。

これらの名称と役割は、GitHubのAgentic SDDリファレンスに基づきます。Clarify、checklist、analyzeは、追加の品質確認の工程です。constitutionはプロジェクトで継続的に守るルールを定めるものなので、小さな機能を追加するたびに書き直すものではありません。

エクスポートの例なら、specifyへの指示に、誰がエクスポートできるか、どのレコードを対象とするか、ファイルの内容、失敗時の振る舞いを含めます。既存の技術スタックやリポジトリ上の制約は、計画の段階で伝えます。受け入れテストは明示的に要求してください。tasksコマンドのドキュメントでは、テストは要求された場合に生成するとされています。タスクリストが生成されたというだけでは、適切なテストが含まれている証拠にはなりません。

レビューするファイルは次のとおりです。

• .specify/memory/constitution.md：プロジェクトの原則。constitutionのテンプレート。
• specs/<feature-directory>/spec.md：機能の振る舞い。機能のディレクトリは通常specs/配下に置かれ、ディレクトリ名は生成または設定されます。specifyのテンプレート。
• 機能ディレクトリ内のplan.mdとtasks.md：実装設計と作業の分解。計画時にはresearch.md、data-model.md、quickstart.mdも生成され、該当する外部インターフェースにはcontracts/が使われます。planのテンプレート、tasksのリファレンス。

実装後、convergeはコードベースを仕様、計画、タスクと照合します。未対応の箇所があればtasks.mdに作業を追加しますが、コード自体を修正するわけではありません。追加された作業を実装してから、再度確認します。「Converged」という結果はレビューの参考になりますが、テストや承認の代わりにはなりません。

既存のアプリケーションについては、GitHubの導入ガイドでは、元の状態を保存したうえで、その場で初期化する手順を案内しています。コマンドはspecify init --here --force --integration <key>で、<key>をclaudeやcodexなど、ドキュメントに記載された連携キーに置き換えます。ガイドには、--forceが競合する管理対象ファイルを置き換える場合があるという注意もあります。実行後の差分をレビューしてください。次の変更を仕様化する前に、アプリケーション全体の仕様を再構築する必要はありません。

限界： Spec Kitは文書間の矛盾を見つけられても、すべての文書で一貫している誤った業務ルールはそのまま受け入れ得ます。追加されるファイルの維持に見合う価値が生まれるのは、複数の人やセッションが同じ合意を必要とするときです。

Kiroで進める仕様駆動開発：Specs・Steering・Hooks

Kiroは、機能の意図、継続的に適用するプロジェクトの指針、自動実行する処理を分けています。今回の機能にはSpecs、リポジトリ全体の規約にはSteering、繰り返し行うチェックにはHooksを使います。

KiroのコードエディタであるIDEでは、Specsの下にある**+をクリックするか、チャットでSpecを選びます。続いてFeature**、Requirements-Firstを選択します。要件をレビューしてから、技術設計とタスク分解を承認します。生成された機能ディレクトリには、.kiro/specs/<feature-name>/requirements.md、design.md、tasks.mdが入ります。内容をレビューした後、タスクの画面から実行します。KiroのSpecsドキュメント。

Kiroは、Easy Approach to Requirements Syntaxの略であるEARSを使い、条件と、そのときシステムが取るべき振る舞いを表現します。今回の例なら、「メンバーがエクスポートを要求した場合、システムはその要求を拒否し、エクスポートファイルを返さないこと」と書けます。ここまで具体的なら、テストに落とし込めます。Feature Specs。

KiroにはDesign-FirstとQuick Specもあります。Design-Firstは技術設計から始めます。Quick Specは途中の承認を挟まずに文書を作成します。エージェントが意図を繰り返し取り違えることに困っている創業者なら、Requirements-Firstを選び、レビューの機会を活用してください。レビューを省くと、問題の解決に必要な工程そのものがなくなってしまいます。

Steeringは、.kiro/steering/配下のMarkdownを通じて、継続的に使うコンテキストを提供します。基礎となるファイルはproduct.md、tech.md、structure.mdで、それぞれプロダクト、技術スタック、リポジトリの構成を扱います。IDEのGenerate Steering Docsで、この初期コンテキストを作成できます。リポジトリの実態と照合してレビューしてください。「既存のメンバーシップ認可ポリシーを再利用する」のように複数の機能へ適用するルールはここに置き、「エクスポートできるのはオーナーだけ」のようなルールはエクスポートの仕様に書きます。Steeringのドキュメント。

Hooksは、イベントの発生時にシェルコマンドやエージェントへのプロンプトを実行します。現在のプロジェクト用フックファイルは.kiro/hooks/<id>.jsonに置かれ、PostFileSaveはドキュメントに記載されたトリガーです。対象を絞ったフックなら、関連ソースの変更時に既存のエクスポートテストを実行できます。変更案を自動チェックする継続的インテグレーションにも同じチェックを残し、ローカルのフックだけで実行する状態にしないでください。Kiroの現在の機能対応表では、HooksはIDEとCLIで利用でき、WebとMobileでは利用できません。Hooksのドキュメント。

限界： 自動生成された要件は、誰も承認していない前提を正式なルールにしてしまうことがあります。設計に進む前に、権限、結果が空の場合、失敗時の振る舞いをレビューしてください。仕様モードは作業を整理してくれますが、プロダクトに関する判断を補ってくれるわけではありません。

Claude Codeで仕様駆動開発を始める

AnthropicのコーディングエージェントであるClaude Codeでは、機能の仕様書とPlan Modeを使ってこのプロセスを進められます。手法を試すために、仕様管理のフレームワークを導入する必要はありません。

specs/workspace-export/spec.mdを自分で作成するか、エージェントが書いた草案をレビューします。続いて、計画モードでターミナルセッションを開始します。

claude --permission-mode plan

Claudeにそのファイルを読み、エクスポートに関係する既存コードを調べ、受け入れ基準に対応する実装計画を提案するよう依頼します。実装を承認する前に、未解決の問いと、実行予定の具体的なチェックを提示させます。

Plan Modeは、調査して方針を提案するためのモードです。ただしAnthropicは、権限チェックをバイパスできる対話型ターミナルセッションでは、計画モードの編集制限が適用されないという例外を記載しています。承認前の編集を確実に制限したい場合は、バイパスを有効にせずに開始してください。権限モードのドキュメント。

提案をレビューしたら、合意した方針をspecs/workspace-export/plan.mdに、チェックリストをtasks.mdに保存してから、実装を許可します。これらのパスは本記事で提案する置き方であり、Plan Modeが自動作成を保証するファイルではありません。操作と承認後の移行については、Claude CodeのPlan Modeガイドで解説しています。

リポジトリで継続的に使う指示は、チーム向けメモリガイドを参考にCLAUDE.mdへ置き、機能固有の振る舞いは仕様書に書きます。そうしないと、一時的なエクスポート要件が恒久的な指示になり、無関係な作業にまで影響しかねません。

限界： 会話の中だけに残した計画は、見失ったり、その後の作業と食い違ったりしやすくなります。ファイルに保存するだけでも不十分で、後続の実装とレビューで明示的に参照して初めて役立ちます。

Codexでも同じ仕様書をPlan Modeで使う

OpenAIのコーディングエージェントであるCodexでも、同じように少ない手間で作業を引き継げます。処理を実行していないCLIチャットで/planを入力すると計画を開始でき、同じ入力に依頼内容を続けて書くこともできます。公式コマンドドキュメント。

例えば、次のように依頼します。「specs/workspace-export/spec.mdを読んでください。既存のメンバーシップポリシー、タスクのクエリ、テストを調べ、すべての要件を満たす最小限の実装計画を提案してください。実装前に決める必要がある事項を挙げてください。」

計画をレビューして合意したファイルを保存したら、Codexにタスクの実装を依頼し、要件とテストを対応付けた完了報告も求めます。継続的に使うリポジトリの指示にはAGENTS.mdを使い、/initでそのひな形を作成できます。初期環境については、Codex CLIのセットアップガイドで解説しています。

OpenAIも、長期にわたる作業で仕様、計画、進捗をMarkdownに残す方法を紹介しています。後のセッションで合意内容を読み直せることが、その利点です。限界： Plan Modeだけでは、別ファイルの機能仕様を最新に保てません。仕様の更新を変更レビューに組み込んでください。OpenAIが紹介するワークフロー。

仕様駆動開発の実例：ワークスペースのCSVエクスポート

CSVエクスポートは、レコードをカンマ区切りの値としてダウンロードする小さな機能です。この例を使うと、先に振る舞いを決めることが、複数ファイルにまたがる手戻りをどう防ぐかが分かります。「CSVエクスポートを追加して」だけでは、ユーザーのロール、データの範囲、ページネーション、ファイル形式をエージェントが推測することになります。見栄えのよいボタンができても、そうした判断がすべて間違っている可能性があります。

以下は、既存のタスク管理アプリケーションを題材にした説明用の例です。パス、要件ID、テスト案は学習のために示すもので、本記事のために実際のリポジトリでテストやマージを行ったという意味ではありません。

1ページの仕様書に振る舞いをまとめる

次の内容を機能のspec.mdとして保存するか、同じ振る舞いの要件をKiroのrequirements.mdに記載します。

R2に含まれる判断に注目してください。「条件に一致するすべての結果」と「表示中のページ」は別物です。実装前にこれを決めれば、クエリとテストの計画にすぐ反映できます。デモを見てから決めると、両方をやり直すことになりかねません。

R4では、具体例を使って決める必要のある事項を、意図的に明記しています。仕様を承認する前に、表計算ソフトの数式として扱われる入力への対応を決め、具体例を記録します。「安全にエクスポートする」とだけ書くと、エージェントが代わりに方針を選ぶことになります。

計画：既存のアプリケーションに組み込む

計画では、既存のセッションとメンバーシップポリシーを再利用し、タスク一覧のフィルターロジックを切り出すか再利用して、一覧のレスポンスを変えずにエクスポート用レスポンスを追加します。エクスポートは、サーバーの認可チェックを通る経路にします。認証済みのメンバーシップからワークスペースへのアクセス権を判断し、その範囲内で要求されたフィルターを適用します。

リポジトリに既存のCSVシリアライザーがあれば、それを選びます。コンテンツとダウンロード用のヘッダー、フィールドを安全に出力する方針、エラー時の振る舞い、テストを明記します。ボタンの追加には、アプリケーションで使われている読み込み中とエラーの状態表示を使います。

想定する結果件数が、既存のリクエスト処理とメモリの制約に収まるかも、計画段階で確認します。全件エクスポートが収まらない場合は、機能の責任者にこの矛盾を戻します。出力範囲を制限するか、バックグラウンド処理を別の開発範囲として定めるかを決めます。エージェントが無断で上限を作ったり、R6に反してジョブの仕組みを追加したりしてはいけません。

タスク：変更ごとに検証できる形にする

レビュアーが内容を把握できる作業に、計画を分解します。

1. 既存のタスク一覧の振る舞いと共通のフィルタールールを、回帰チェックにまとめます。
2. オーナー、メンバー、オーナー権限を取り消されたユーザー、別のワークスペースについて、リクエストの認可テストを追加します。
3. 合意したフィールドの扱いに従って、対象範囲を限定したクエリとCSVレスポンスを実装します。
4. エクスポートの操作部、読み込み中の状態、失敗時の表示を追加します。
5. 受け入れチェックを完了し、機能の範囲外の変更がないか差分を確認します。

これは今回の例に合わせたタスク分解です。ツールキットが別のリストを生成しても、合意した内容を網羅しているかで判断してください。

TypeScriptアプリケーションなら、レビュー対象となる変更には、認可、フィルタリング、レスポンスを担うserver/exports/tasks.ts、操作を担うui/tasks/ExportButton.tsx、受け入れケースを確認するtests/task-export.test.tsなどが考えられます。いずれも説明用のパスであり、フレームワークの必須規約ではありません。新たなキューワーカーやデータベースのマイグレーションが含まれていれば、スコープ変更の兆候です。マージ前に解決する必要があります。

受け入れ基準をマージの判断につなげる

エージェントが編集したファイルの一覧ではなく、振る舞いを確かめた証拠を求めます。プルリクエストの説明では、要件を次のようなチェックと対応付けます。

レビュアーは、これらのチェックを仕様と照合し、認可とクエリのコードを確認して、プロジェクトで通常使うレビュー環境で合意したユーザーフローを試します。エージェントが実装とテストの両方を書いた場合は、期待結果を独立に検討してください。テストもコードと同じ誤った前提を、忠実に確認している可能性があります。

例えば、レビューでエンドポイントが現在のページしか読み込んでいないと分かったとします。オーナーが引き続き全件を望むなら、R2は変えずにクエリを修正し、そのページの先にも一致するレコードがあるテストを追加します。オーナーが対象範囲を変えるなら、承認前にR2、計画、テストをまとめて更新します。

検証結果が合意内容を満たしたら、機能をマージします。 レビュー済みの仕様、最終的な計画、完了したタスクの記録、実装、テストを同じプルリクエストに含めます。承認したスコープ変更もそこに記録します。マージ後は、仕様を現行の合意として維持するか、過去の機能開発記録であると明示します。古い仕様が現在も正しいように見える状態で放置すると、次の混乱を招きます。

権限やページネーションの前提が実装全体に広がる前に決めておくことに、この手法の価値があります。マージ後も、仕様、テスト、コードに同じ判断を残せます。

仕様駆動開発には何がかかり、どんなときに見合うのか

この手法にかかるのは、レビューと維持の時間、そして草案作成や実装に使うエージェントの稼働です。Spec Kitはオープンソースですが、接続するコーディングエージェントにはそれぞれの利用条件があります。通常のMarkdownファイルなら仕様ツールの追加サブスクリプションは不要ですが、モデルの利用まで無料になるわけではありません。

Kiroの標準商用料金では、適用される税金を除き、Freeは月額$0で50クレジット、Proは1ユーザーあたり月額$20で1,000クレジットです。したがってProを4契約すると、追加クレジットと税金を除いて4 × $20 = 月額$80になります。これは契約数に応じた料金の計算であり、完成させられる機能の数を予測するものではありません。Kiroの公式料金ページ。

追加購入のクレジットは1クレジットあたり$0.04です。Kiroによると、仕様の調整、タスクの実行、エージェントフックの実行でクレジットを消費し、複雑な仕様タスクでは1クレジットを超える場合があります。実際の作業負荷を観察せずに、「クレジット数」を「完成した機能数」に換算できる根拠はありません。Kiroのクレジットの定義。

採算の判断基準は明確です。仕様化、レビュー、維持に追加でかかるコストが、それによって避けられる作り直しのコストを下回ることです。自分たちのプロセスで、そのコストを記録してください。文書が増えても、判断をコードレビューまで先送りする状況が変わらなければ、その負担に見合う価値は生まれていません。

過大評価されている点は？どこからがやりすぎか

「十分に詳しい文書があれば、エージェントは安定して正しく実装できる」という期待は過大です。仕様自体が間違っていることも、実装が仕様を無視することも、テストが仕様と同じ誤った前提を繰り返すこともあります。

区別すべきなのは、明記した意図と実装で担保する振る舞いです。「メンバーはエクスポートできない」という要件を書き、そのルールをサーバー側のチェックとテストで支えます。要件のチェックリストが確認するのは記述内容であり、アプリケーションを実行するわけではありません。両者を同じものと捉えると、根拠のない安心感につながります。

文書と実装のずれも問題になります。開発者が権限の振る舞いを変えてコードだけを更新すると、次のエージェントが古い仕様に合わせてアプリケーションを「修正」してしまうかもしれません。振る舞いを変えるときは関連する合意の更新を必須にするか、その合意をアーカイブしたと明示します。継続的に参照するコンテキストは、正確さを保ってこそ役立ちます。

今すぐ取り入れるべきなのは、エージェントが権限、エッジケース、連携、受け入れ基準を繰り返し見落とす場合です。曖昧な点が複数のコンポーネントやレビュアーにまたがる機能で、このワークフローを使います。

正式な仕様書を作るのは待ったほうがよいのは、そもそも誰かがその機能を欲しがっているか、まだ探っている段階です。先に使い捨てのプロトタイプを作るか、未知の点を調べます。未検証のアイデアに立派な仕様書を用意すると、誤った投資判断まで確定したように感じてしまうことがあります。

小さな修正は小さなまま扱います。 誤字、既存のスタイルに沿った調整、明確な回帰テストがある局所的なバグなど、意図が明白で変更範囲も狭い場合です。期待する振る舞いを示し、それを検証すればよいのです。constitution、計画、タスクの一式を回すと、その変更に必要な以上の手間がかかることがあります。

判断の基準はコードの行数ではありません。何もしなければ、エージェントが重要な前提をいくつ自分で決めることになるかです。

仕様駆動開発を最初の1週間で試す

すでにバックログにある小さな機能を選びます。対象外の事項と失敗時のケースも含めて、振る舞いを1ページの仕様にまとめ、責任者の承認を得ます。現在のエージェントの計画モード、またはSpec KitやKiroの対応するフローを使い、リポジトリの実態に基づく計画を提案させます。

実装前に、未解決の問いをレビューします。要件と結び付いたタスクリストを求めます。プルリクエストでは、同じ合意に照らして検証結果を確認し、変わった決定事項を記録します。プロセスの重さは、曖昧さを解消するために必要な範囲にとどめます。

AIを使った開発と運用の実践的な方法は、ニュースレターでお届けします。