仕様駆動開発
AIコーディングエージェントに頼む前に、仕様書を書く
GitHubのSpec Kitは、GitHub自身のオープンソースプロジェクトです。このガイドは独立したもので、GitHubとの提携や承認を受けたものではありません。
AIコーディングエージェントへの不満の多くは、同じ原因にたどり着きます。曖昧な依頼からは曖昧な結果しか返ってこず、自分が本当に欲しかったものは、期待とずれたコードを読んで初めて分かります。仕様書は、この順番を入れ替えます。最初のプロンプトを送る前に、平易な言葉で3つの短いことを書きます。それが何をするものか、誰のためのものか、そして完成したと判断するための具体的なチェックです。コードが書けなくても問題ありません。GitHub自身のリポジトリで管理されているオープンソースのツールキットSpec Kitは、まさにこの習慣を軸に、コーディングエージェント向けの構造化された再現可能な進め方を作っています。専用のコマンドラインツールと、プロジェクトの指針から動くビルドまでをつなぐ名前付きの手順が用意されています。このガイドでは、5分で手書きできる3つの要素からなる仕様書、Spec Kitのワークフローが同じ考え方をどのように個別のコマンドに分けているか、そしてツールキット全体を導入する価値があるのはどんなときか、自分で仕様書を書けば十分なのはどんなときかを扱います。
仕様書とは、コーディングエージェントに何かを作らせる前に書く、短く平易な言葉の依頼書です。何をするか、誰向けか、そして完成したことを確かめる完了条件を書きます。GitHub自身のリポジトリで作られているオープンソースのツールキットSpec Kitは、この習慣を再現可能なワークフローにしたもので、原則の設定、仕様書の作成、計画、計画のタスク分解、実装、収束の確認までをそれぞれ専用のコマンドで進めます。ドキュメントには、AnthropicのClaude CodeやGitHub Copilotなど、接続できるエージェントが挙げられています。ただし、効果を得るのにツールキットは必須ではありません。同じ3つの要素の依頼書を最初のメッセージとして入力すれば、普段使っているどのコーディングエージェントでも機能します。
公開日
無料レッスン · アカウント不要Claudeと出会うなぜClaudeなのか?6 分無料レッスンを始める要点まとめ
- 仕様書とは、最初のプロンプトの前に書く3つのことです。エージェントに何を作らせるか、誰向けか、完成を証明する完了条件です。
- GitHubのSpec Kitは無料のオープンソースツールキットで、リポジトリの記載ではMITライセンスです。この習慣を6つの名前付きコマンドにしています。憲法(constitution)、仕様書、計画、タスク一覧、実装、そして収束の確認です。
- 仕様書の効果を得るのにSpec Kitは必須ではありません。同じ3つの要素の依頼書を最初のメッセージとして入力すれば、Claude Code、OpenAIのCodex、Copilot、AnysphereのCursorなど、どのコーディングエージェントでも使えます。
- Spec Kitのセットアップ用ドキュメントには、接続できるコーディングエージェントが統合キーとともに挙げられています。Claude CodeやGitHub Copilotも含まれ、ほかのエージェントを追加する方法も用意されています。
- 完了条件を省くことは、仕様書が気づかれないまま失敗する最も多い原因です。完了条件がなければ、あなたにもエージェントにも、作業が本当に終わったのか判断できません。
コピーして使える
今日から使えるプロンプト
最初のチャットを始めるための3つの要素の仕様書
これから作ってほしいものの仕様書です。何をするか:Downloadsフォルダ内のファイルを、ファイルの種類ごとに日付付きのサブフォルダへ振り分けるスクリプト。誰向けか:私だけが、ターミナルから手動で実行します。ほかに利用者はいません。完了条件:20個のサンプルファイルを入れたテスト用フォルダで実行すると、すべてのファイルが正しいサブフォルダに振り分けられること、そのフォルダの外には何も触れないこと、1つのコマンドで実行全体を元に戻せること。作り始める前に、必要なことがあれば何でも質問してください。
どう作るかのやり取りをする前に、これを最初のメッセージとして貼り付けてください。
曖昧なアイデアをエージェントに仕様書へ整理してもらう
作りたいものがあるのですが、アイデアはまだ漠然としています。頭の中にあるのはだいたい次のようなものです:ここに大まかなアイデアを1、2文で書いてください。コードを書く前に、質問を重ねて、それが何をするものか、誰向けか、どうなったら完成と言えるかを、3つの短い項目にまとめて私に示せるようにしてください。3つすべてを私がはっきり確認するまで、作り始めないでください。
問題の輪郭は分かっているけれど、細部がまだ固まっていないときに役立ちます。
ビルドを承認する前に完了条件を確認する
実装を始める前に、これが完了したことを証明するために実行するチェックを具体的に挙げてください。何をテストするか、それぞれの期待される結果、何をもって失敗とするかを示してください。このセッションの中では自分で確認できないものが必要なチェックがあれば、後でうまくいくと思い込まず、今伝えてください。
優れたエージェントなら、コードを1行書く前にこれに詳しく答えられるはずです。
基本の習慣
プロンプトの前に仕様書を置く理由
コーディングエージェントに依頼をそのまま打ち込むほうが、先に何かを書き出すより速く感じますし、本当に簡単な作業ならたいていその通りです。問題が起きるのは、解釈が複数ありえる作業です。エージェントはどれか1つを選んでその方向に作り、間違った解釈を選んだと分かるのは、完成したコードを読んでからになります。そこから往復するたびに、仕様書を書く数分よりも多くのコストがかかります。
仕様書は、作業の順番を組み替えます。コードが書かれる前に、平易な言葉で3つのことを書き出します。それが何をするものか、誰のためのものか、そして動作を証明する完了条件です。技術文書ではありません。初対面の有能なアシスタントに残すメモに近いもので、大事な部分を推測させずに済むだけの詳しさがあれば十分です。
これが効く理由は単純です。埋めるべき隙間が減るので、エージェントが自分の思い込みで依頼の空白を埋めなくなります。そしてあなたも、出てきた結果を後から読んで自分の望みを知るのではなく、頼む前にすでに書き出していることになります。
これは特定のツールに限った話ではありません。Claude Code、Codex、Copilot、Cursor、そのほかのコーディングエージェントはどれも、基本的には同じ仕組みで動きます。平易な言葉で指示を入れると、コードとコマンドが出てきます。仕様書は入れるものを変え、それによって返ってくるものも変わります。どのエージェントと話していても同じです。
3つの要素の仕様書
5分で書ける仕様書に入れるもの
短い4つの要素を、平易な言葉で書きます。コードが書ける必要はありません。
何をするか
実装ではなく、振る舞いを1、2文で書きます。「ファイルを種類別に日付付きフォルダへ振り分ける」のように書き、どの関数やライブラリを使うかは書きません。
誰向けか
自分だけが手動で実行するのか。プロジェクトを見たことのない同僚が使うのか。この答えは、機能の説明以上に、実際に何を作る必要があるかを左右することがよくあります。
完了条件のチェック
ビルドが完成したことを証明する、具体的でテストできる条件です。多くの人が省く部分ですが、何か問題が起きたときに最も重要になる部分でもあります。
ガードレール
任意ですが、リスクが現実にあるときは加える価値があります。エージェントが決してしてはいけないこと、たとえば特定のフォルダ以外のファイルに触れる、何かを自動で送信する、といったことです。
そのためのオープンソースの枠組み
GitHubのSpec Kitは仕様書をワークフローにする
GitHubのSpec Kitは、GitHub自身のリポジトリでMITライセンスのもと管理されているオープンソースのツールキットです。AIコーディングエージェントに、その場限りの会話ではなく、構造化された手順、再利用できるテンプレート、記録に残る成果物を与えるために作られています。専用のコマンドラインツールでインストールし、READMEでは、仕様駆動開発、またはエージェントに従わせたい任意の構造化された手順を始めるためのツールキットと説明されています。
プロジェクト自身のドキュメントによると、中核となる仕様駆動のワークフローは、名前の付いた6つのコマンドを順に進めます。プロジェクトの指針を設定するもの、仕様書そのものを書くもの、その仕様書を技術的な計画にするもの、計画を順序付きのタスク一覧に分解するもの、タスクを実行して実際のコードを書くもの、そして最後に結果が仕様書にどれだけ収束したかを確認するものです。プロジェクトの案内では、これらを1つずつ実行し、各結果を確認してから次へ進むこと、そして収束の確認が収束したと報告するまで、実装と収束の確認を繰り返すことが勧められています。作業全体を一度にエージェントへ任せることはしません。
このツールキットには、中核のワークフローに追加できる別の拡張も付いています。これも同じくドキュメントによるもので、特定のバグを評価して修正することを軸にしたコマンド群と、ラフなアイデアを調査と定義に通してから、そもそも作るかどうかを判断することを軸にしたコマンド群があります。
接続できるエージェントについては、Spec Kitのセットアップ用ドキュメントが、インストール時に渡す統合キーとともにいくつかを挙げています。Claude CodeやGitHub Copilotもその中にあり、直接挙げられているもの以外のエージェントを接続する方法は、別のドキュメントで案内されています。ここに書いたものも含め、特定のエージェント一覧はあくまで現時点のスナップショットとして扱ってください。あるツールが今日対応しているかどうかを決めつける前に、Spec Kitの最新のドキュメントを確認してください。
コマンドごとに見るワークフロー
Spec Kitの6つの中核コマンド
プロジェクト自身のREADMEによると、仕様駆動のワークフローはこの6つの手順を順に進み、最後の2つは結果が収束するまで繰り返します。
憲法(constitution)を設定する
この後のすべての作業でエージェントが守るべき、プロジェクト全体の原則を記録するコマンドです。一度書いたものを、以降の作業で使い回します。
仕様書を書く
実際の仕様書を生成するコマンドです。ここまで説明してきた平易な言葉の依頼書と同じものを、その場限りのメッセージではなく、再利用できるファイルとして残します。
アプローチを計画する
仕様書を技術的な計画にするコマンドです。コードが書かれる前にアプローチを決めるので、設計上の判断が実装の中に埋もれません。
タスクに分解する
計画を、具体的で順序付きのタスク一覧に分けるコマンドです。各タスクは、単独で確認できる小ささにします。
実装する
タスク一覧を実行してコードを書くコマンドです。ゼロから始めるのではなく、それまでの手順で得られたすべてを手引きにします。
収束を確認する
結果が仕様書にどれだけ合っているかを確認するコマンドです。プロジェクトの案内では、収束の確認が収束したと報告するまで、実装と収束の確認をセットで繰り返します。
何もインストールしない場合
ツールキットなしで仕様書を手書きする
開発者ではない人が小さなものを1つ作るだけなら、Spec Kitのワークフローをすべて回すのは、作業に対して大げさになることがあります。3つの要素の仕様書だけを、普段使っているエージェントへの最初のメッセージとして入力するだけで、実際の仕事の大部分は片付きます。インストールするものはありません。
仕様書を貼り付けたら、コードを書く前にエージェントから確認の質問をしてもらいましょう。有能なエージェントは不明な点があれば質問します。仕様書があれば、黙って推測して自信満々に間違ったものを作るのではなく、質問するための具体的な材料をエージェントに渡せます。
この素のままの習慣は、持ち運べます。Claude Code、Codex、Copilot、Cursor、そのほかのコーディングエージェントのどれと話していても、同じ3つの要素の依頼書が使えます。特定のツールの機能には何も依存していないからです。インストールするプラグインではなく、身につける習慣です。
つまずきやすいところ
仕様書を台無しにする失敗
次のどれかが紛れ込むと、仕様書の効果は本来より小さくなります。
完了条件がない
完了を確かめる方法がない仕様書は、推測する場所をプロンプトからレビューへ移すだけです。レビューのほうが、気づきにくくなります。
実装の詳細が混ざる
その機能が本当に必要かを決める前に、プログラミング言語や特定のアルゴリズムを指定すると、仕様書が早すぎる設計になってしまいます。
後から書く
すでにあるコードに合わせて書いた仕様書は、作られたものを記録するだけです。自分が一致するように書かれた問題を、見つけることはできません。
1つの仕様書に多くのタスク
複数の実際のタスクを含む仕様書は、本当に重要な1つを埋もれさせます。仕様書は、確認できる1つの作業に絞りましょう。
ツールキットを使うタイミング
素の仕様書か、Spec Kit全体か:選び方
小さなビルドを1つ作るだけなら、3つの要素の素の仕様書をそのままチャットに入力すれば十分で、何かをインストールするより速く済みます。このガイドの例の多くは、まさにそのケースを想定して書かれています。
Spec Kitのセットアップに手間をかける価値が出てくるのは、同じプロジェクトでこれを繰り返すとき、新しい機能ごとに原則が自動で適用されてほしいとき、あるいはバグ修正やアイデア評価の拡張が持つ構造を、毎回自分で作り直さずに使いたいときです。
どちらを選んでも、身につけるべき技術は同じです。コードを1行書く前に、何をするか、誰向けか、どうなったら完了かを言葉にすることです。ツールキットは、その書き出しを一貫して行う作業を自動化するだけで、その習慣が自動化する価値があるほど頻繁に使うものになってから意味を持ちます。
ビルドの前に仕様書を書く練習をする
明確な仕様書を書くこと、そしてAIコーディングエージェントに常時参照されるプロジェクトの指示を与えることは、このガイドで扱うどのツールにも通用するスキルです。Nightschool AIの無料レッスン「プロジェクトの指示ファイル」では、Claude Codeを例にそのやり方を順に説明しています。
よくある質問
ここでいう仕様書とは、具体的に何ですか?
コーディングエージェントに何かを作らせる前に書く、短く平易な言葉の依頼書です。最低限、それが何をするか、誰向けか、完成を証明する完了条件を含みます。技術文書ではなく、コードが書けなくても書けます。
仕様書を書くのに、コードが書ける必要はありますか?
いいえ。仕様書は、実装ではなく、振る舞いと結果を平易な言葉で記述するものです。ツールが何をすべきか、動いているとどう分かるかを書くのにプログラミングの知識は要りません。実際のコードを書くのは、それを作るエージェントです。
GitHubのSpec Kitとは何ですか?
GitHub自身のリポジトリで管理されている、MITライセンスのオープンソースのツールキットです。仕様駆動開発を軸にした、構造化された再現可能な進め方をAIコーディングエージェントに与えます。専用のコマンドラインツールと、プロジェクトの指針から実装、収束の確認までをつなぐ名前付きの6つのコマンドがあります。
Spec Kitはどのコーディングエージェントと使えますか?
セットアップ用ドキュメントによると、インストール時に統合キーでエージェントを接続します。ドキュメントにはClaude CodeやGitHub Copilotなど、いくつかのエージェントがこの形で挙げられており、ほかのエージェントの接続方法は専用のドキュメントで案内されています。特定のツールが対応していると決めつける前に、Spec Kitの最新のドキュメントで完全な一覧を確認してください。
このガイドはGitHubと提携していますか?
いいえ。これは独立した学習用ガイドで、GitHubが公開したものでも、承認したものでもありません。Spec KitとGitHubはGitHub自身のプロジェクトであり商標です。正確に説明するためにだけ名前を挙げています。
仕様書と、単に長いプロンプトとは何が違いますか?
長いプロンプトは、あくまで作業を説明する1つのメッセージです。仕様書は、何をするか、誰向けか、完了条件という3つの具体的な要素を持つ構造化された依頼書で、一度入力して忘れるのではなく、読み、確認し、再利用することを前提にしています。
「完了条件」のチェックとは、具体的に何ですか?
ビルドが完成したことを証明する、テストできる条件です。何を確認するか、各チェックの期待される結果、何をもって失敗とするかを含みます。これがなければ、エージェントが本当にタスクを終えたのか、ただ止まっただけなのかを判断する共通の方法がありません。
この習慣の効果を得るために、Spec Kitをインストールする必要はありますか?
いいえ。同じ3つの要素の仕様書を、Claude Code、Codex、Copilot、Cursorなど、どのコーディングエージェントにも最初のメッセージとして入力すれば、何もインストールせずに効果の大部分が得られます。Spec Kitは、これを頻繁に行うための再現可能な構造であり、行うための必須条件ではありません。
Spec Kitは無料で使えますか?
はい。リポジトリの記載によるとMITライセンスのオープンソースプロジェクトで、無料の専用コマンドラインツールでインストールできます。
Spec Kitの仕様書作成コマンドは、実際に何を生成しますか?
プロジェクト自身のドキュメントによると、仕様書そのものを生成します。このガイド全体で説明してきた平易な言葉の依頼書と同じもので、毎回チャットに新しく入力するのではなく、プロジェクト内に再利用できるファイルとして保存されます。