OpenSpec クイックスタート：インストール、ワークフロー、およびよくある落とし穴

40ページのPRDではなく、差分としての仕様

目次

OpenSpec は、Fission AI によって開発された無料のオープンソース CLI ツールです。このツールにより、コーディングエージェントとの間で、重い仕様駆動開発フレームワークのような段階制の儀式なしに、コードを書き始める前にプレーンな Markdown で変更内容について合意できるようになります。

仕様駆動開発（SDD）を試みる多くのチームが、同じトレードオフに足止めを食らいます。それは、エージェントが推測で進んでしまうのを防ぐのに十分なプロセスを確保しつつ、50行ほどのバグ修正に提案書が必要になるほどの過度なスケルトン（骨組み）を設けないことです。OpenSpec の答えは、「まずシステム全体を文書化する」という直感そのものをスキップし、実際に変更が影響を与える部分のみに対して、毎回全面書き換えを行うのではなく、ADDED（追加）、MODIFIED（変更）、REMOVED（削除）というデルタ（差分）を用いて仕様を書くというものです。

OpenSpec spec-driven development workflow with an AI coding assistant

この変更中心的な設計思想こそが、OpenSpec が SDD ツールのカテゴリ比較 で GitHub Spec Kit、Kiro、Superpowers と一緒に頻繁に登場する理由でもあります。これは、800行にも及ぶ計画フェーズなしにレビュー可能な仕様を得たいと願うチームの第一候補としてよく選ばれているためです。本ガイドでは、CLI のインストール方法、日常で実際に使う4コマンドのワークフロー、ディスク上での変更の姿、そして Reddit や OpenSpec 自身のイシュートラッカーに最もよく見られる質問や不満について解説します。

OpenSpec とは何か？

OpenSpec は、自身の哲学を以下の4行で説明しています。「柔軟であって硬直的でない」「反復的であってウォーターフォール的でない」「簡単であって複雑でない」「グリーンフィールドのみならずブラウンフィールド向けに設計されている」。実践的には、これはロックされたフェーズが存在しないことを意味します。つまり、ツールに依存しない SDD ワークフロー が説明するような「指定 → 計画 → 実装」を厳密な順序で強制されるのではなく、変更プロセスのどの時点でも提案書、仕様、またはタスクリストを編集できます。

OpenSpec での1つの変更は、自身のフォルダ内に最大4つの Markdown アーティファクト（成果物）を生成します。

アーティファクト 目的
proposal.md 変更が存在する理由とその内容について、平たい言葉で説明
specs/ デルタ要件とシナリオ – この変更に対するテスト可能な仕様
design.md 必要な場合の任意の技術的アプローチ
tasks.md エージェントが対応する実装チェックリスト

変更が実装されてアーカイブされると、そのデルタ仕様は openspec/specs/ にマージされ、これがシステムの状態の持続的な現在の説明となります。これは 仕様駆動開発とは何か？ で解説されている「仕様が真実のソースである」という考え方に他なりませんが、一度にすべてを書くのではなく、1つの変更単位でスコープを絞ったものです。

OpenSpec のインストール

OpenSpec は Node.js 製 CLI であるため、マシンには Node 20.19.0 以上が必要です。

node --version

npm を使用して CLI をグローバルにインストールし、PATH に正しく配置されたかを確認します。

npm install -g @fission-ai/openspec@latest
openspec --version

Deno、pnpm、yarn、bun、および nix も、npm よりセットアップに適している場合にインストールパスとしてサポートされています。インストールが完了したら、プロジェクト内で初期化します。

cd your-project
openspec init

openspec init は使用する AI ツールを尋ね、対応するスキルファイルとコマンドファイルを書き出します。OpenSpec は Claude Code、Cursor、GitHub Copilot、Gemini CLI、Codex、Kiro、OpenCode など 30 以上のアシスタントをサポートしています。CI やスクリプトによるセットアップを行う場合は、ピッカー（選択画面）を完全にスキップできます。

openspec init --tools claude,cursor   # 特定のツールを設定
openspec init --tools all             # 対応するすべてのツール
openspec init --tools none            # openspec/ 構造のみ、ツールファイルなし

その後、IDE を再起動して、新しく書き出されたスキルとコマンドを読み込むようにしてください。もしアシスタントにインストール全体を行わせたい場合は、OpenSpec にセットアッププロンプトが付属しており、Claude Code や他のエージェントに貼り付けられます。これにより、インストールが実行され、openspec init が実行され、設定された内容が報告されます。

コアワークフロー: Explore, Propose, Apply, Archive

初日にほぼ全員が戸惑う唯一のことがあります。openspec コマンドはターミナルで実行されますが、/opsx: コマンドは AI アシスタントのチャットウィンドウで実行されることです。「対話モード」のようなものを起動する必要はありません – チャットでスラッシュコマンドを入力するのが開始方法です。

flowchart LR A["/opsx:explore (任意)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs merged| E["openspec/specs/"]
  • /opsx:explore はリスクのない思考のパートナーです。コードベースの関連部分を読み、選択肢を提示し、ディスクに何を書き込む前に計画を練ります – 意気込みのあるエージェントが自信満々に間違ったものを作り上げてしまうのを防ぐため、特に習慣として身に着ける価値があります。
  • /opsx:propose <name> は openspec/changes/<name>/ を作成し、提案書、デルタ仕様、任意の設計、タスクリストを一度に草案します。ここでは、実装が始まる前に計画をレビューします。
  • /opsx:apply はタスクリストを順に対応し、進行するにつれて項目にチェックを入れます。進捗はチャット履歴だけでなくファイル内に記録されるため、コンテキストウィンドウをクリアしたり、新しいセッションを開始したりしても、/opsx:apply が中断した位置から正確に再開できます。
  • /opsx:archive は完了した変更を openspec/changes/archive/YYYY-MM-DD-<name>/ にファイリングし、そのデルタ仕様を正規の openspec/specs/ ツリーにマージします。

デフォルトの core プロファイルでは、これら4つのコマンドに加えて update と sync がインストールされます。拡張プロファイルでは、一度にすべてを作成するのではなく、1つのアーティファクトずつ作成したいチーム向けに new、continue、ff、verify、bulk-archive、onboard が追加されます – openspec config profile の後で openspec update を実行して切り替えます。

各ツールは、カスタム指示の読み込み方法に応じて同じコマンドを異なるスペルで表示します。Claude Code では /opsx:propose、Cursor や GitHub Copilot では /opsx-propose、Amazon Q では @opsx-propose、Codex では $openspec-propose です。openspec init は選択したツールの正確な形式を出力するため、「コマンドを入力したのに何も起こらなかった」ときの最速の解決策は、推測するのではなく、その出力されたヒントを再読することです。

ディスク上での変更の姿

openspec/changes/add-dark-mode/ 配下の 변경フォルダには、通常、次のような提案書、デルタ仕様、タスクリストが含まれます。

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

この ADDED/MODIFIED/REMOVED のデルタ形式は、1つのフィールド変更のために仕様ファイル全体を書き換えるのを OpenSpec が回避できるメカニズムです。また、OpenSpec がグリーンフィールド第一ではなく、明示的にブラウンフィールド第一である理由でもあります。アプリケーション全体を文書化してから価値を得る必要はなく、各実際の変更が関与するスライス（部分）のみを文書化すればよく、openspec/specs/ は通常の作業を数ヶ月行っていくことで自然に埋まっていきます。

ターミナルから離れずにその状態を確認するための便利な CLI コマンド：

openspec list                 # アクティブな変更
openspec show add-dark-mode   # 変更のアーティファクトを表示
openspec validate --all       # プロジェクト全体の仕様フォーマットをチェック
openspec view                 # 対話的なダッシュボード

openspec/ フォルダ全体を git にコミットしてください。アクティブな変更とアーカイブは、マージ後に削除するスクラッチパッドではなく、システムが何を行い、なぜ変更されたかについての持続的かつバージョン管理された記録になることを意図しています。

既存コードベースでの OpenSpec の導入

実際のプロジェクトで OpenSpec を評価するチームからの最も一般的な懸念は、「私のアプリは 8 万行の古物です、まずすべて仕様化する必要がありますか？」という類いのものです。必要ありません。OpenSpec 自身のガイダンスはこれについて率直です。今週すでに構築予定だった小さく現実に存在するものを選び、これから触る領域で /opsx:explore を実行してエージェントにまずどのように動作しているかをマップさせ、それからそのスライスのみでスコープを絞った変更を /opsx:propose します。

すでに Notion や Confluence に PRD、SRS 文書、設計ドキュメントが保管されている場合は、それらを探索のための素材として扱い、仕様に一括変換するものとは見なさないでください。関連するセクションを /opsx:explore セッションに貼り付け、エージェントがそこから焦点の当てられたデルタを形作らせましょう。40ページの PRD の機械的な一括変換は、6ヶ月後に誰も信用しない仕様を生み出す傾向があります。実際の变更に直接飛び込むのではなく、ガイド付きで説明付きの初回実行を望むチームには、拡張コマンド /opsx:onboard がコードベースをスキャンして小さく安全な改善を見つけ、それに対する完全なループを案内します。

よくある質問と問題

これらは、OpenSpec の Discord、GitHub イシュー、および r/cursor、r/RooCode、r/opencodeCLI などの subreddit における Reddit のスレッドに繰り返し現れる問題です。

「スラッシュコマンドを入力したが何も起こらない。」 ほぼ常に以下のいずれかです：アシスタントのチャットではなくターミナルで入力した、openspec init 実行以来 IDE を再起動していない、CLI バージョンが古すぎて openspec update がすべて最新と報告するが新しいワークフローファイルを書き出さない。openspec update を実行し、IDE を再起動し、スキルフォルダが存在することを確認します（Claude Code の場合は .claude/skills/openspec-*、またはサポートツールのリストにあるそのツールの同等フォルダ）。

「AI が必要なものよりもはるかに多くの仕様を生成する。」 これは長いレビュー記事で最も引用される不満です：エージェントが30分の機能を800行の仕様に転換しかねません。OpenSpec は規律を強制するため、すべてのリクエストに注入される context: フィールドを50KBに制限していますが、デルタ仕様自体には厳密な制限がないため、生成された仕様を実際に重要（load-bearing）なものにまで削減することは、ツールが強制するものではなく、自分で維持しなければならない習慣です。

「2つの変更が同じ要件に触れ、片方のシナリオが黙って消えた。」 これは実在し、文書化されたエッジケースです：アーカイブは MODIFIED デルタを要件名をキーとした全体ブロックの置換として適用するため、進行中の2つの変更が同じ要件を変更する場合、2番目をアーカイブすると警告なしに最初のシナリオを上書きしてしまうことが以前はありました。現在のバージョンではドリフトチェックが追加され、アーカイブを中断してまず変更の仕様を更新するように促しますが、同じ領域で複数の変更を並行して実行する場合は、この障害モードが存在することを知っておく価値があります。

「実際にどの AI モデルを使うべきか？」 OpenSpec 自身のドキュメントは、計画と実装の両方で高い推論能力を持つモデルを推奨しています – Opus クラスと Codex クラスのモデルが特に言及されています – また、実装前にコンテキストウィンドウをクリアすることを推奨しています。なぜなら、クリーンなコンテキストは、長く蓄積されたセッションよりも測定可能なほど良い結果を生むためです。

「Spec Kit、Kiro、Superpowers、または BMAD とどう違うのか？」 これは Reddit で最も頻繁に寄せられる質問であり、正直な答えは「プロセスの重さ」です。OpenSpec 自身の README はこの比較を直接的にフレームワークしています：Spec Kit は徹底しているが重く、Markdown が多く硬直的なフェーズゲートがある。Kiro は強力だが AWS の IDE と Claude モデルにロックされる。OpenSpec は、その事前構造の一部を、自由に反復でき、すでに開いているアシスタントと作業できる能力と交換します。Spec Kit、Kiro、Claude Code スキル、BMAD-METHOD、および Superpowers に対する完全な分析については、専用の SDD ツール比較 を参照してください。

「AI は本当に自分で書いた仕様を守っているか？」 いつもではありません。これは OpenSpec 固有ではなく、SDD ツール全般における文書化された問題です – 大きなコンテキストウィンドウは、エージェントがそのすべての部分に均等に注意を払っていることを意味しません。/opsx:verify コマンドは、自分の仕様と矛盾する生成コードを検出するために特に存在しており、盲目的に実装を信頼するのではなく、自明でないものすべてに対して実行する価値があります。

「1行の修正にこれが必要か？」 必要ありません。OpenSpec 自身の FAQ もそう述べています：合意が重要な場所、つまり自明でない、複数ファイルにまたがる作業で使用し、タイプミス修正や1週間で削除する使い捨てのプロトタイプにはスキップしてください。

OpenSpec が適している場合と適さない場合

適している場合：

  • 事前に関連システム全体を文書化することなく、レビュー可能な仕様を得たいブラウンフィールドのコードベース。
  • Spec Kit よりも軽い儀式を望みながらも、コードの前に書かれた計画を得たい個人開発者や小規模チーム。
  • 複数ファイルにまたがる作業、スキーマ変更、またはジュニアエンジニアが短かい設計ドキュメントを合理的に求めるであろうもの。
  • プルリクエストで計画をレビューすることをすでにコミットしているチーム – デルタ仕様は変更点のみを説明するため、クリーンに差分表示できます。

適さない場合（弱い適合）：

  • 1行のバグ修正や使い捨てのプロトタイプ、提案-レビューステップが節約するコストより高くなる場合。
  • Spec Kit のより重く指示的な構造、または Kiro のような AWS ネイティブで IDE 統合された体験を必要とするチーム – 各ツールの勝利領域については ツール比較内の意思決定フレームワーク を参照してください。
  • 現在のところリポジトリ間をまたぐ機能、ただし OpenSpec のベータ版 stores 機能を試すことを惜しまない場合は別です。これは計画を独自の共有リポジトリに移行し、複数のコードベースとエージェントが同じ計画を読めるようにします。
  • 特定の機能が仕様の価値があるかどうかまだ決定していない人 – OpenSpec は、すでに構造がオーバーヘッドに見合うと決定した後にのみ役立つため、まず 仕様駆動開発 vs 雰囲気コーディング をお読みください。

結論

OpenSpec の賭けは、仕様駆動開発の多くの苦痛は、基礎的な「コードが存在する前に計画で合意する」という考えではなく、儀式から来るとしていることです。全面書き換えではなくデルタ、ロックされたフェーズなし、ブラウンフィールド第一のワークフローにより、ゼロから構築していないコードベースでの採用において、Spec Kit や Kiro よりも著しく軽量です。トレードオフも実際に存在します – 規律なしには仕様の肥大化は真のリスクであり、1つの要件に対する同時変更まわりの競合処理はまだ成熟の途上にあり、エコシステムは GitHub 自身のツールよりは若い。1つの実際のプロジェクトにインストールし、小さな変更を explore-propose-apply-archive でエンドツーエンドで実行し、それから、より軽い儀式が実際の作業量に見合っているかどうかを判断してください。

有用なリンク

購読する

システム、インフラ、AIエンジニアリングの新記事をお届けします。