2026 Spec Kit 完全ガイド：インストールから AI 実装まで、Windows・macOS・Linux の仕様駆動開発

GitHub が保守する Spec Kit は、仕様駆動開発をインストールできる CLI と、エージェントが呼び出す一組のスキルに落とし込む。PyPI のパッケージ名は specify-cli、ソースは github/spec-kit である。Cursor、Claude Code、GitHub Copilot、Codex の代わりにはならない。これらのエージェントに、観察できる振る舞いを先に書き、技術選定をその次にし、リポジトリの変更を最後にする、という順序を守らせる道具だ。2026 年 11 月時点で Windows は PowerShell スクリプトを直接使う。先に WSL を入れる必要はない。この記事が扱うのはインストール、ディレクトリ、コマンドの順序だけだ。仕様がコードより先でなければならない理由は 仕様駆動開発の完全ガイド を読む。スキルファイルの置き場所は Agent Skills の案内 を読む。

「看板を作って」が、すでに間違った始まりである理由

古いやり方と新しいやり方の衝突は具体的だ。古いやり方はセッション優先である。目的も技術スタックもディレクトリ構成も、一度のチャットに詰め込む。エージェントは推測しながらファイルを変える。マシンか人が変わると、その文脈は消える。新しいやり方は成果物優先である。原則は .specify/memory/constitution.md に書く。振る舞いとその理由は specs/<feature>/spec.md に書く。技術スタックは plan.md まで待つ。実行順序は tasks.md まで待つ。今の機能は .specify/feature.json が指すディレクトリであり、前回の会話の記憶ではない。

2026 年にこれが態度の問題ではなくインストールの問題になった理由は三つある。第一に、呼び出しの綴りがエージェントで分かれる。Cursor、Claude Code、Copilot の既定スキルモードは /speckit-specify だ。Codex は $speckit-specify だ。ドキュメントのドット表記は参照用の書き方にすぎない。第二に、uv と pipx の両方で入れると specify が二つ残る。PATH の古い方が --integration を拒否する。第三に、任意の git 拡張は番号付きブランチを作れるが、git checkout 自体は現在の機能を切り替えない。三つとも、プロダクトコードの一行目より前に起きる。

Spec Kit が仕様駆動の作業をどう層に分けるか

九つのスラッシュスキルを、同じ層のチェックリストとして扱わない。それらは三種類の成果物に着地し、合法な経路は二つだけだ。

原則の層はリポジトリにつき一度である。/speckit-constitution は品質、テスト、権限、体験の硬い制約を残し、後の各ステップはそのファイルを物差しにする。機能の層は機能につき一度である。/speckit-specify が答えるのは、利用者が観察できることと、なぜそれが必要かだけだ。/speckit-clarify は曖昧な点を問い、答えを仕様へ書き戻す。実装の層で初めてフレームワークやディレクトリが許される。/speckit-plan は計画、調査、データモデル、契約を出す。/speckit-tasks は計画を依存順のタスクに割り、並列できるものに [P] を付ける。/speckit-implement はその順でファイルを変える。/speckit-converge はコードと成果物を突き合わせ、足りないタスクを足し、Converged と報告するまで繰り返す。

途中に品質の門が二つある。「コードが終わった」と混同しない。/speckit-checklist が作るのは、レビュー担当が持つ要求品質の一覧だ。チェックは要求が明確だという意味であり、機能が実装されたという意味ではない。/speckit-analyze は読み取り専用で、spec.md、plan.md、tasks.md の衝突を報告し、リポジトリは変えない。組み込みの checklists/requirements.md は specify と clarify が保守する。カスタムの一覧はレビュー担当の持ち物だ。implement は未チェックなら止まって尋ねる。代わりにチェックは付けない。

短い経路は、境界がすでに明確な小さい変更に合う。specify、plan、tasks、implement、converge の順だ。完全な経路は、出荷する機能に合う。constitution はプロジェクトで一度行い、その後に specify、clarify、plan、checklist、tasks、analyze、implement、converge と進む。欠陥は公式の bug-fixing クイックスタートへ。まだ作る価値を判断しているアイデアは idea assessment へ。どちらも、この仕様駆動の経路の前提手順ではない。

Windows、macOS、Linux へのインストール

共通の前提は Python 3.11 以上、git 拡張を有効にするときだけの Git、そして実際にコードを書くエージェントである。永続インストールには uv を使う。端末が走らせるのは CLI だけだ。スラッシュスキルはエージェントのチャットで呼ぶ。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

入れたあとに見るのは二つだ。specify version は、そのコマンドが動き、バージョンを表示することだけを証明する。バイナリが PyPI 由来か GitHub 由来かは証明しない。specify self check は読み取り専用で、新しいリリースがあるかを伝え、インストールは変えない。ドキュメントの例は v0.12.11 のように先頭に v が付くタグだ。ソースを版固定するなら uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z とし、v は外さない。PyPI の固定は uv tool install specify-cli==X.Y.Z だ。更新は最初に使った道具で行う。uv tool install --force specify-cli、pipx install --force specify-cli、または pip install --upgrade specify-cli である。

すでにコードがあるリポジトリを、汚れた作業ツリーの上で初期化しない。先にコミットかバックアップを取り、その後で specify init --here --force --non-interactive --integration claude を実行する。--force は、テンプレートが既存ファイルへ合流することを承知した、という意味だけだ。キーボードのない CI には --non-interactive が要る。無いと初期化は矢印キーのメニューで止まる。エージェントの実行ファイルが別のマシンにあるときは --ignore-agent-tools を足し、手元のバイナリ検査を飛ばす。非対話の既定統合は Copilot だ。別の --integration を書かない限り、そうなる。

統合キーは推測しない。Cursor は cursor-agent であり、cursor ではない。ほかによく使うのは claude、copilot、gemini、pi、omp、codebuddy だ。対話端末は --integration を省くと選択を求める。スクリプトやパイプは明示しなければならない。

specify version が古い番号を出したら、先に which specify でパスを見る。0.1 系が残っていると --integration は No such option: --integration になり、古い --ai は No matching release asset found になる。これはネットワークの故障ではなく、PATH の先頭が別のインストールを指しているサインだ。消すのは使っていない方だけで、更新は最初の道具に --force か --upgrade を付けて行う。二つの道具を交互に入れると、また二つに戻る。

九つのコマンド。どこで呼び、何を変えてよいか、誰向けか

次の二つの表は列を揃えてある。本当の差は入口と実行境界であり、モデル名ではない。

場面で短い経路か完全な経路かを選ぶ

実例は、一台のマシンに留まる付箋ボードだ。アップロードはしない。第一期にパスワードはない。あらかじめ決めた三人。プロジェクトの下に四列。未着手、進行中、確認待ち、完了。カードはドラッグで列を変える。コメントを編集できるのは書いた本人だけだ。specify にはこの振る舞いと理由だけを書く。plan で初めて「ローカルの SQLite、リモート API は無し」と書く。データベースを specify に入れると、最初の技術的な勘が、誰も挑戦できない要求になる。

チャットに貼る specify は、次の粒度で止める。三人の固定メンバーがプロジェクトを開き、四列のあいだでカードをドラッグする。コメントの編集と削除は著者だけができる。起動時にパスワードは聞かない。ファイルの保存先、フレームワーク、テーブル名は書かない。それらを書いた瞬間、仕様は計画を先取りしている。plan に進んでから、保存はローカルの SQLite、画面は単一ページ、ネットワークへは出さない、と技術を固定する。

初期化の直後にディスク上で確認するファイルは、記事の中で名前を出したものと一致する。原則は .specify/memory/constitution.md。現在の機能は .specify/feature.json が指す。Windows ならスクリプトは .specify/scripts/powershell/、macOS と Linux なら .specify/scripts/bash/、--script py なら .specify/scripts/python/ だ。specify のあと機能ディレクトリに spec.md があり、plan のあと plan.md と調査メモ、データモデル、契約が並ぶ。tasks のあと tasks.md があり、並列可能な行だけが [P] を持つ。この並びを飛ばして implement を呼ぶと、エージェントは欠落を推測で埋める。それが、チャット一発に戻る道だ。

Cursor でスキルが見えないときは、端末ではなくチャットのスラッシュを確認する。ファイルは .cursor/skills/speckit-specify/SKILL.md にあるはずだ。Claude Code なら .claude/skills/、Copilot の既定なら .github/skills/ だ。点号の /speckit.specify を打って無反応でも、インストール失敗とは限らない。綴りが参照記法のままになっている。

エージェント、スクリプト種別、隔離したマシンを揃える

すでに Cursor でこのリポジトリを書いているなら、cursor-agent とそのマシンのスクリプト種別を使う。Windows は ps、macOS と Linux は sh だ。初期化のあと、チャットでは短い経路か完全な経路かを一段ずつ呼ぶ。次のスキルの前に成果物を読む。九つを一つのプロンプトに貼らない。

主に Claude Code を使うなら、統合キーは claude だ。スキルの説明が文脈を圧迫するときは、初期化に --integration-options="--no-model-invocation" を付け、中核コマンドは /speckit-specify と打ったときだけ走るようにする。Copilot はそのまま既定のスキル配置でよい。古いエージェントファイルが欲しいときだけ --commands を足す。

implement はファイルを変え、コマンドを実行する。本番の鍵が入ったノート PC で最初の一周をしない。リポジトリをリモート Mac に置き、差分を読んでから戻す。ノードの頼み方は Mac mini のレンタル、予算は 料金 を見る。仕様に macOS のビルドや署名が含まれるなら、その段階は実機のノードで走らせ、OpenClaw のクラウド自動化 で日常のノート PC から分ける。インストールが失敗したら、Spec Kit を疑う前に ヘルプセンター の接続とシステム要件を確認する。

残りの作業を全部やり直させる五つの誤り

1. specify にフレームワークとデータベースを書く。 技術スタックは plan の持ち物だ。仕様が「このライブラリ必須」と言うと、clarify と analyze はその選択を弁護する時間になる。
2. 端末に /speckit-specify と打つ。 スラッシュスキルはエージェントのチャットにしか無い。端末が走らせるのは specify 自身だ。
3. ドキュメントのドット表記を Cursor に貼る。 Cursor のスキルは /speckit-specify だ。ドットは参照用の書き方である。
4. uv と pipx の両方に入れる。 古い 0.1.x は No such option: --integration を出すか、--ai で No matching release asset found を出す。どれを消すか決める前に which specify を見る。
5. git checkout を機能の切り替え器にする。 変えるのは .specify/feature.json か SPECIFY_FEATURE_DIRECTORY だ。ブランチを変えただけでは、コマンドは前の機能ディレクトリを向いたままになる。

七つの手順

1. uv と specify-cli を入れる。specify version と specify self check を実行し、PATH 上のバイナリが一つだと確認する。
2. OS に合わせて --script を、実際に使うエージェントに合わせて --integration を選び、specify init する。既存リポジトリは先にコミットし、--here --force を足す。
3. エージェントのチャットで /speckit-constitution を一度だけ走らせる。原則だけを書く。入力は検証する。コメントを編集できるのは著者だけ。第一期はアップロードしない。
4. /speckit-specify で付箋ボードの振る舞いと理由を書く。出荷するなら続けて /speckit-clarify を走らせ、ドラッグ、権限、空のプロジェクトの三つを問い終える。
5. 仕様が安定してから /speckit-plan。その後に checklist、tasks、analyze。analyze が衝突を報告したら、源の成果物を直す。implement の中で継ぎ当たらない。
6. 隔離した Mac かきれいなディレクトリで /speckit-implement を走らせる。タスクが多いなら段階に分ける。tasks.md を一度に飲み込まない。
7. /speckit-converge を、Converged と報告するまで走らせる。その後に差分を読む。仕様の外のファイルが無いか、秘密がリポジトリに書かれていないか。

インストールを決める質問

Spec Kit と Cursor でチャットする違いは何か

チャットの記録はそのセッションに残る。人かマシンが変わると消える。Spec Kit は原則、仕様、計画、タスクをリポジトリの Markdown にする。今の機能は .specify/feature.json のディレクトリであり、前回のスレッドの記憶ではない。

コマンドは /speckit-specify か /speckit.specify か

Cursor、Claude Code、GitHub Copilot の既定スキルモードはハイフン形を、エージェントのチャットで使う。端末には打たない。Codex のスキルモードは $speckit-specify だ。ドキュメントのドット表記は参照用であり、Cursor に貼らない。

Windows では先に WSL が必要か

不要だ。2026 年の Spec Kit は Windows で PowerShell が既定である。初期化時に --script ps を付ける。macOS と Linux の既定は bash で、--script sh に当たる。

uv と pipx の両方に入れてよいか

入れない。specify が二つ残る。PATH の先頭にある古い方が --integration を拒否するか、No matching release asset found を出す。更新は最初の道具で、--force か --upgrade を付ける。

git checkout は現在の機能を切り替えるか

切り替えない。現在の機能は .specify/feature.json だ。SPECIFY_FEATURE_DIRECTORY で上書きできる。任意の git 拡張は番号付きブランチを作るが、チェックアウトだけではこの状態は変わらない。

正しいコマンドを入れてから、エージェントにリポジトリを触らせる

Spec Kit の価値はスラッシュが一つ増えることではない。「仕様、次に計画、最後にファイル変更」が、ほかの人がレビューできるリポジトリ内のファイルになることにある。Windows は PowerShell、macOS と Linux は bash、Cursor は cursor-agent とハイフンのスキルを使う。小さい変更は短い経路、出荷する機能は完全な経路、implement は隔離したノードで走らせる。次の一歩はプロンプトをさらに集めることではない。specify version を実行し、目の前のバイナリが今入れたものだと確認する。番号が期待と違うなら、スキルを打つ前に PATH を直す。スキル名を打ち始めるのは、バージョンと統合キーとスクリプト種別の三つが、今のマシンと一致してからだ。一致していないまま implement を呼ぶと、古い CLI が作ったディレクトリと新しいスキルが混ざり、どの成果物が正なのかを後から分けられなくなる。分けられなくなった状態で converge を繰り返しても、報告書の Converged は「今のファイルを追認した」だけであり、仕様が先だったことの証明にはならない。証明になるのは、spec.md の日付が plan.md より前で、plan.md が最初のコード差分より前だという順序だけだ。

関連記事

• 仕様駆動開発の完全ガイド：方法論のほう →
• Agent Skills の入れ方と選び方 →
• OpenClaw とリモート Mac の自動化 →