OpenSpec 2.0の変更点をv1とdiffで検証してみた

OpenSpec 2.0の変更点をv1とdiffで検証

こんにちは、サイオステクノロジーの遠藤です。

仕様駆動開発(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 update 1 回で済む。 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 です。

  1. openspec init --tools claude
  2. change を作る → わざとシナリオが欠けた spec を置いて validate → 直して validate --strict
  3. archive(新しい capability の追加)
  4. 既存の spec を変える MODIFIED の change を作って archive
  5. 作りかけの change を 1 つ残す(あとで移行の検証に使う)
  6. store / workset / schemas / doctor / context を実行する
  7. 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 つがスキル名にそろいました。

ツールv1v2
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 の)スキルを使い続けます。

移行チェックリスト

  1. v2 をインストールする(specs と changes はそのまま使える)
  2. openspec update --dry-run で、消えるものと増えるものを確認する
  3. openspec update を実行する
  4. 「Kept …」と表示されたスキルとコマンドを .agents/skills/ と見比べ、追記を移してから手で削除する
  5. 手順書やドキュメントの /opsx:* を /openspec-* に書き換える
  6. .agents/ と、シンボリックリンクになった .claude/skills/* をコミットする

まとめ

  • OpenSpec 2.0 は、機能追加というより AI ツール連携ファイルの配り方を変えたメジャーアップデートです。スラッシュコマンドを廃止し、skills を .agents/skills/ にまとめました
  • CLI、spec の書式、validate、archive、store などは 1.17.0 と同じです
  • 移行は openspec update 1 回で済みます。ただし、編集済みスキルの片付けと /opsx:* の書き換えは忘れないようにしましょう

メジャーバージョンアップと聞くと身構えますが、同じ手順を流して diff してみると、変わった箇所はかなり限られていました。移行前に一度 --dry-run で確認してみてください。

参考

ご覧いただきありがとうございます! この投稿はお役に立ちましたか?

役に立った 役に立たなかった

0人がこの投稿は役に立ったと言っています。
エンジニア募集中!

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です