こんにちは、サイオステクノロジーの遠藤です。
仕様駆動開発(SDD)のフレームワーク OpenSpec のメジャーバージョン 2.0.0 が出ました。普段から OpenSpec を使っているので移行の影響が気になり、1.x の最終版 1.17.0 と 2.0.0 に同じ手順を流して、出力をすべて diff してみました。
要約
- v2 で変わったのは、AI ツール向けファイルの「配り方」だけ。 スラッシュコマンド(
/opsx:*)がなくなり、skills を.agents/skills/の 1 か所にまとめる形になった - CLI・spec の書式・validate・archive は v1 と出力が完全に一致した。 store や workset も 1.17.0 に既にある機能で、v2 で増えたものではない
- 移行は
openspec update1 回で済む。 spec のデータには触れない。ただし手で編集したスキルは「残される」ので片付けが必要
検証のやり方
Docker で v1 用と v2 用の環境を 1 つずつ作り、比較する形で検証を行いました。
| 項目 | 値 |
|---|---|
| ベースイメージ | node:22-slim(両方同じ) |
| v1 | @fission-ai/openspec@1.17.0 |
| v2 | @fission-ai/openspec@2.0.0 |
両方の環境で、次の流れを 1 本のシェルスクリプトにまとめて実行しました。題材は「TODO アプリに期限日を追加する」という小さな change です。
openspec init --tools claude- change を作る → わざとシナリオが欠けた spec を置いて
validate→ 直してvalidate --strict archive(新しい capability の追加)- 既存の spec を変える MODIFIED の change を作って
archive - 作りかけの change を 1 つ残す(あとで移行の検証に使う)
- store / workset / schemas / doctor / context を実行する
- 4 つの AI ツール(Claude Code / Cursor / Codex / GitHub Copilot)向けに
initする
あわせて、全コマンドの --help(2 階層まで、57 ファイル)と、init 直後のファイル一式も保存して diff -r しました。
1. CLI:--help の差分は 1 行だけ
57 本の help を diff した結果、違いはこれだけでした。
# init の --tools の選択肢
- "none", or a comma-separated list of: amazon-q, amp,
+ "none", or a comma-separated list of: amp, antigravity,
コマンドの追加・削除・改名は 1 つもありません。トップレベルのコマンド 24 個はすべて同じで、違いは init --tools から amazon-q が消えたことだけです。
2. init の生成物:スラッシュコマンドがなくなった
一番大きな変化はここです。openspec init --tools claude で生成されるファイルを比べました。

openspec init --tools claude 直後のファイル構成(実際のスナップショットから作成。同じ形のファイルは ×N でまとめて表示)。赤がスラッシュコマンド、緑が共有の skills、青が symlink
v1 はスラッシュコマンドと skills を両方作っていました。 .claude/commands/opsx/propose.md と .claude/skills/openspec-propose/SKILL.md は、frontmatter と言い回しが少し違うだけで、本文はほぼ同じです。同じ指示を 2 つの形式で重複して配っていたことになります。
v2 はスラッシュコマンドを作りません。 skills の実体は .agents/skills/ に置かれ、.claude/skills/ からはシンボリックリンクで参照します。
./.claude/skills/openspec-propose -> ../../.agents/skills/openspec-propose
openspec/ ディレクトリ(config.yaml・specs・changes)は v1 と一字一句同じでした。
4 ツールを併用すると 43 ファイル → 7 ファイル
複数の AI ツールを使うと差がはっきりします。--tools claude,cursor,codex,github-copilot で init しました。

v1 は .claude/ .cursor/ .github/ .agents/ に、ツールごとに skills とコマンド(Copilot は prompts)をコピーしていました。v2 は .agents/skills/ だけで、.cursor/ と .github/ は作りません。どのツールがこの共有コピーを使うかは、.agents/skills/.openspec-target という一覧ファイルに書かれています。
claude own-files
codex
cursor
github-copilot
呼び出し名がツール間で統一された
v1 では、同じ「propose」でもツールごとに呼び出し方が違いました。v2 では Claude Code・Cursor・Copilot の 3 つがスキル名にそろいました。
| ツール | v1 | v2 |
|---|---|---|
| Claude Code | /opsx:propose | /openspec-propose |
| Cursor / GitHub Copilot | /opsx-propose | /openspec-propose |
| Codex | $openspec-propose | $openspec-propose(変更なし) |
Codex はもともとスキル形式だったので変わりません。チームの手順書に /opsx:propose と書いてある場合は、書き換えが必要です。
delivery 設定は無視されるようになった
v1 には、配り方を選ぶ delivery という設定がありました。既定値は両方を配る both です。
# v1
$ openspec config set delivery commands → 6 commands in .claude/
$ openspec config set delivery skills → 6 skills in .claude/
v2 では、値を設定しても無視されます。
# v2
$ openspec config set delivery commands
Note: delivery no longer changes anything; OpenSpec 2.0 installs skills only.
3. spec・validate・archive は何も変わっていない
シナリオの各ステップの出力を diff したところ、validate --json の所要時間(durationMs)以外はすべて一致しました。
| 観点 | 挙動(v1 / v2 共通) |
|---|---|
| change の構成 | proposal → specs / design → tasks(schema spec-driven) |
| delta の書式 | ## ADDED / MODIFIED / REMOVED / RENAMED Requirements、### Requirement:、#### Scenario: |
| シナリオが欠けた spec | ✗ [ERROR] … must include at least one scenario(終了コード 1) |
| 対話できない環境(非TTY)での archive | 確認の入力を読めずに失敗する(安全側)。--yes を付ければ実行される |
| MODIFIED の反映 | 要件ブロックを丸ごと置き換える |
v1 で書いた spec や change は、v2 でもそのまま使えます。
4. store / workset は v2 の新機能ではない
v2 のヘルプには store や workset が並んでいるので新機能に見えますが、1.17.0 にも同じコマンドがあり、出力も一致しました。 せっかくなので中身も紹介します。
store:spec 置き場をコードのリポジトリから独立させる
store は、openspec/(specs と changes)だけを持つ独立したリポジトリです。マシンに id で登録しておくと、どのディレクトリからでも --store <id> で操作できます。
openspec store setup team-specs --path ~/openspec/team-specs # 作成して登録(既定で git init も)
openspec new change shared-glossary --store team-specs # store 側に change を作る
openspec list --store team-specs
フロントエンドとバックエンドでリポジトリが分かれていて、仕様を 1 か所で管理したい場合や、チームで spec 専用のリポジトリを共有したい場合に使えそうです。ほかの Git リポジトリの中には作れない(Store setup path is inside another Git repository)点だけ注意してください。
workset:自分用の「作業フォルダの組み合わせ」を保存する
workset は、いつも一緒に開くフォルダに名前を付けて保存し、エディタや AI エージェントのセッションでまとめて開く機能です。help には「purely local」とあり、自分のマシンの中だけで完結します。
openspec workset create ragstd --member app=~/repos/app --member specs=~/openspec/team-specs
openspec workset open ragstd
今回の検証で実行したのは workset list だけなので、create と open の挙動は別の機会に確かめます。
5. v1 / v2 共通のハマりどころ
バージョンとは関係ありませんが、検証中に踏んだものを 3 つ挙げます。
archive --yes は未完了のタスクがあっても止まらない。 タスクが 0/3 でも、警告が出るだけで archive されます。CI などで --yes を付けるなら、事前に openspec list でタスクの状況を確認したほうが安全です。
Warning: 3 incomplete task(s) found. Continuing due to --yes flag.
Purpose に「TODO」という単語があると、未記入扱いされる。 validate --strict は、Purpose に TBD や TODO が残っていると「未記入(placeholder)のまま」と判定します。TODO アプリの spec で「TODO に期限日を持たせ…」と書いたところ、これに引っかかりました。単語を「タスク」に言い換えると通ります。
⚠ [WARNING] overview: Purpose section is still a placeholder rather than a Purpose anyone wrote
「50 文字以上」は文字数で数えられる。 Purpose や Why が 50 文字未満だと「短すぎる」と警告されます。日本語だと 45 文字程度でも十分な情報量になりがちですが、それでも警告が出ます。また Why の警告は validate --strict では出ず、archive のときにだけ出ました。
6. v1 のプロジェクトを v2 に移行する
v1 でシナリオを流したプロジェクト(archive 済みの spec が 1 つ、作りかけの change が 1 つ)を v2 の環境にコピーして、v2 の CLI で扱ってみました。
何もしなくても読める
list / status / show / validate / doctor はすべて正常に動きました。データの移行は不要です。 ただし .claude/ の中身は v1 のままで、/opsx:* のコマンドも残っています。CLI がこれらを自動で書き換えることはありません。
openspec update で v2 の形にする
--dry-run を付けると、何が変わるかを事前に確認できます(--json 付きなら機械可読な形で出ます)。
$ openspec update --dry-run .
26 file(s) would change:
add .agents/skills/openspec-propose/SKILL.md (openspec)
delete .claude/commands/opsx/propose.md (claude)
add .claude/skills/openspec-propose (claude)
delete .claude/skills/openspec-propose/SKILL.md (claude)
...
実行すると、次のように更新されます。
$ openspec update .
Updating 1 tool(s): claude (1.17.0 → 2.0.0)
Replaced 6 unchanged skill copies in tool folders with the one shared copy in .agents/skills.
Removed: 6 command files (OpenSpec 2.0 installs skills only)
openspec/(specs と changes)には一切変更がなかった(git diffが空)- もう一度実行すると
All 1 tool(s) up to dateとなり、何度実行しても結果は同じ - v1 で作りかけだった change は、v2 で validate からタスク完了、archive まで通った
- 4 ツールのプロジェクトでは、18 個のスキルのコピーが共有の 1 部にまとまり、18 個のコマンドが削除された。
.cursor/と.github/はディレクトリごと消えた
手で編集したファイルは「残される」
業務では、生成されたスキルに独自のルールを書き足しているケースもあると思います。そこで、編集済みのスキルとコマンドがある状態で update してみました。

編集した内容が上書きされないのは安心です。ただし、残された .claude/skills/openspec-explore/ はシンボリックリンクではなく、v1 版の実体のままです。自分の追記を取り込んで手で削除するまで、Claude Code は古い(1.17.0 の)スキルを使い続けます。
移行チェックリスト
- v2 をインストールする(specs と changes はそのまま使える)
openspec update --dry-runで、消えるものと増えるものを確認するopenspec updateを実行する- 「Kept …」と表示されたスキルとコマンドを
.agents/skills/と見比べ、追記を移してから手で削除する - 手順書やドキュメントの
/opsx:*を/openspec-*に書き換える .agents/と、シンボリックリンクになった.claude/skills/*をコミットする
まとめ
- OpenSpec 2.0 は、機能追加というより AI ツール連携ファイルの配り方を変えたメジャーアップデートです。スラッシュコマンドを廃止し、skills を
.agents/skills/にまとめました - CLI、spec の書式、validate、archive、store などは 1.17.0 と同じです
- 移行は
openspec update1 回で済みます。ただし、編集済みスキルの片付けと/opsx:*の書き換えは忘れないようにしましょう
メジャーバージョンアップと聞くと身構えますが、同じ手順を流して diff してみると、変わった箇所はかなり限られていました。移行前に一度 --dry-run で確認してみてください。
参考
- OpenSpec 2.0.0 リリースノート(GitHub Releases) — skills の
.agents /skills/への集約と/opsx:*の廃止についての公式説明 - OpenSpec(GitHub リポジトリ)
- OpenSpec CHANGELOG
- @fission-ai/openspec(npm)

