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

「仕様は差分で記述し、40ページのPRDにしない」

目次

Fission AI の OpenSpec は、Fission AI が提供する無料のオープンソース CLI ツールです。重い仕様が駆動するフレームワークのような段階的な手順を省きながら、コードを書く前に、あなたとコーディングエージェントがプレーンな Markdown 形式の変更内容について合意できるよう支援します。

Spec-Driven Development（仕様駆動開発）に挑むチームの多くが、同じトレードオフにぶつかっています。エージェントが推測で実装することを防ぐのに十分なプロセスはあるが、50行のバグ修正に提案書が必要になるほどの骨格は不要、というバランスです。OpenSpec の答えは、「まずシステム全体を文書化する」という発想を完全に捨て、変更が実際に触れる部分のみに対して仕様を書くことです。毎回すべてを書き換えるのではなく、ADDED、MODIFIED、REMOVED のデルタ（差分）形式を使用します。

AI コーディングアシスタントを用いた OpenSpec の仕様駆動開発ワークフロー

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

OpenSpec とは？

OpenSpec の独自哲学は、以下の4つの言葉で表現されます。柔軟であって硬直的でない、反復的であってウォーターフォールではない、シンプルであって複雑ではない、グリーンフィールドだけでなくブラウンフィールド（既存のコードベース）のために作られたもの。実践的には、ロックされたフェーズが存在しないことを意味します。ツール非依存の SDD ワークフローで説明されているような、厳密な順序での「仕様定義→計画→実装」の流れに縛られるのではなく、変更の任意の時点で提案書、仕様、タスクリストを編集できます。

OpenSpec における1つの「変更」は、専用のフォルダ内で最大4つの Markdown 成果物を生成します。

成果物 目的
proposal.md 変更が存在する理由と、変更する内容（平易な言葉で）
specs/ デルタ（差分）要件とシナリオ – この変更に対するテスト可能な仕様
design.md 必要に応じて用意する技術的アプローチ
tasks.md エージェントが処理する実装チェックリスト

変更が実装され、アーカイブされると、その仕様差分は openspec/specs/ にマージされます。これがシステムの中核的かつ現在の状態を記述するものとなり、「仕様を真の源（Source of Truth）とする」という考え方を、一度にすべてを書くのではなく、1つの変更単位でスコープを限定して適用します。この考え方は Spec-Driven Development とは？ でも解説されています。

OpenSpec のインストール

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

node --version

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

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

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

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 Issues、そして r/cursor、r/RooCode、r/opencodeCLI などの Reddit スレでも繰り返し現れる問題です。

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

「AI が必要以上に仕様を生成する。」 長めのレビュー記事で最もよく引用される不満です：エージェントは30分の機能を800行の仕様に変換しがちです。OpenSpec は規律を強制するために、すべてのリクエストに注入される context: フィールドを 50KB に制限しますが、仕様差分自体にはハードリミットがありません。したがって、生成された仕様を実際に効いている部分にまでトリムすることは、ツールが強制するのではなく、自分自身が維持しなければならない習慣です。

「2つの変更が同じ要件に触れ、片方が静かに相手のシナリオを削除した。」 これは実際にドキュメント化されたエッジケースです：アーカイブは、要件名をキーとしたブロック全体の置換として MODIFIED デルタを適用するため、進行中の2つの変更が同じ要件を変更する場合、2つ目のアーカイブが1つ目のシナリオを警告なしで上書きしていました。現在のバージョンでは、変更の仕様をまず更新するよう知らせるドリフトチェックが追加され、アーカイブが中止されます – ただし、同じ領域で複数の変更を並行して実行する場合、この失敗モードが存在することを認識しておくと依然として価値があります。

「実際にどの 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週間で削除する使い捨てのプロトタイプにはスキップしてください。

「エージェントが、すでに拒否した何かを再提案しないようにするには？」 /opsx:archive には拒否された変更専用のステータスがなく、アイデアがすでに調査され却下されたことを将来の提案に伝えるものがありません。エージェントが再提案する前にアーカイブを検索するための decision.md パターンと設定ルールについては、OpenSpec Rejected Proposals: A Decision Memory Conventionを参照してください。

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

適している場合：

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

あまり適していない場合：

  • 1行のバグ修正や使い捨てのプロトタイプ。提案・レビュー手順のコストが節約を上回るとき。
  • Spec Kit のようなより重く、より指示的な構造、または Kiro のような AWS ネイティブの IDE 統合エクスペリエンスが必要なチーム – どのツールが勝るかについては ツール比較の意思決定フレームワークを参照してください。
  • 現状のクロスリポジトリ機能（OpenSpec のベータ stores 機能を試す意思がある場合を除く）。これにより計画は独自の共有リポジトリに移動し、複数のコードベースとエージェントが同じ計画を読み取れます。
  • 特定機能が仕様に値するかどうかまだ決めていない人 – OpenSpec は構造がオーバーヘッドに見合うとすでに決めた後で初めて役立つため、まず Spec-Driven Development vs Vibe Coding をお読みください。

結論

OpenSpec の賭けは、Spec-Driven Development のほとんどの痛みが、コードが存在する前に計画について合意するという根本的なアイデアではなく、儀式（セレモニー）から来ている、ということです。完全な書き換えではなくデルタ、ロックされたフェーズなし、そしてブラウンフィールドファーストのワークフローにより、自分たちがゼロから構築しなかったコードベースでの導入は、Spec Kit や Kiro より明らかに軽くなります。トレードオフも実際にあります – 規律なしには仕様の肥大化は真実のリスクであり、1つの要件への同時変更を巡る競合処理は依然として成熟の途中であり、エコシステムは GitHub 自身のツールよりも若い。1つの実際のプロジェクトにインストールし、explore-propose-apply-archive の小さな変更を最初から最後まで実行して、その軽い儀式が実際のワークロードに見合うかどうかをそこから判断してください。

参考リンク

購読する

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