背景
OpenSpecは、コードを書く前に「何を作るか」をproposalやspecとして書き、それをもとにClaude Codeなどのエージェントに実装させる、仕様駆動開発(Spec-Driven Development)のためのCLIツールです。openspec initでプロジェクトに導入すると、propose(計画を書く)→apply(実装する)→archive(確定してspecに反映する)という一連のワークフローが使えるようになります。
OpenSpecを4月から使用してまして、当時のバージョンは1.3系で、そのまま固定してずっと使ってたんですが、最近ふと見たら現在は1.13.1になってました。結構アップデート内容が多かったので調べてみて、その内容をここに書きます。
普段やってた作業は、/opsx:proposeで仕様、実装内容、タスクを生成して、/opsx:applyで実装、終わったら/opsx:archiveで確定、という流れです。この記事もその流れに沿って、4月時点と今でどう変わったかを見ていきます。
変更点まとめ
GitHubのReleasesとCHANGELOGを1.3.1から1.13.1までで影響が大きいものだけを以下の表にしました。
構造・体験
| バージョン | 変更点 |
|---|---|
| v1.5.0 | Stores導入(ベータ)。複数プロジェクトでspecを共有するための仕組み。それまでは1つのgitリポジトリに1つのopenspec/フォルダを置くだけで、リポジトリをまたいでspecを共有する統一的な方法がなかった。Storesは「単独のOpenSpecリポジトリ」をマシンに登録しておき、複数プロジェクトから--store <id>で参照できるようにする仕組み |
| v1.7.0 |
openspec config set defaultStore <id>を設定すると、--storeを毎回書かなくてもそのマシンのコマンドが自動的にそのStoreを見るようになった |
| v1.6.0 |
/opsx:update追加。proposalやtasksなどの計画だけを直したくなったときに使うコマンド。実装に入る前でも、実装が始まった後でも呼べる。 |
| v1.11.0 |
openspec status --all追加。動いているchangeをまとめて一覧できるようになった |
Claude Code関連
| バージョン | 変更点 |
|---|---|
| v1.8.0 | AGENTS.md対応の.agents/skills/共有ツリーが追加。AGENTS.mdに対応したツールなら、共通の場所に置いたskillを複数のツールから読み込めるようになった |
| v1.11.0〜v1.13.1 | Explore mode(実装前にアイデアを整理する、読み取り専用の相談モード)の確認が厳密になった。以前は質問に答えただけで「書き込んでいい」と解釈されることがあったが、今はファイルを書く前に必ず「作ってもいいか」を明示的に聞き、別のメッセージでyesと言われるまで書かない |
セキュリティ(v1.13.1)
| 修正内容 |
|---|
config.yaml経由でagent instructionにコードを混入させる攻撃を防げるようになった |
その他
| バージョン | 変更点 |
|---|---|
| v1.8.0, v1.13.1 | タスクの完了判定が厳密になった。ネストしたチェックボックスや+/1./1)マーカーも正しくカウントするようになり、完了表示なのに未完了タスクが隠れてる、という事故を防げる |
| v1.9.0〜 |
openspec validate(specファイルの書き方が正しいかを見るコマンドで)で、scenario(要件ごとのWHEN/THENの動作例)の抜け落ちを検知できるようになった。archiveも内部で同じチェックをしているが、v1.9.0からはopenspec validateを単体で実行するだけでも、specを書いた直後(proposeの段階)にその場で気づける。以前はこのチェックがなく、archive時に気づかないままscenarioが消えることがあった |
実際にpropose→apply→archiveがどう変わったか
表だけだとピンとこないので、実際に4月の1.3.1と今の1.13.1、両方で同じ変更(商品データをCSVで出力する機能を追加する)をpropose→apply→archiveまで通してみました。同じことをやって、どこがどう変わったか比較します。
propose
v1.3.1時点のopenspec-proposeテンプレート(propose.ts / v1.3.1)には、こう書いてありました。
I'll create a change with artifacts:
- proposal.md (what & why)
- design.md (how)
- tasks.md (implementation steps)
design.mdが問答無用で必須になっていました。小さい変更でも「design.mdはこのケースなら書かなくていい」という判断はスキル側になく、openspec statusで見てもdesignは常にtasksの前提条件でした。
今の1.13.1(propose.ts / v1.13.1)では、design.mdの扱いが変わっています。
When to include design.md (create only if any apply):
- Cross-cutting change (multiple services/modules) or new architectural pattern
- New external dependency or significant data model changes
- Security, performance, or migration complexity
- Ambiguity that benefits from technical decisions before coding
「このくらいの変更ならdesign.md書かなくていい」という判断基準がスキル自体に組み込まれています。実際、今回のCSVエクスポートくらいの変更ならdesign.mdなしでもopenspec validateは普通に通りました。
もう1つ、proposalのテンプレート自体も変わっています。v1.3.1のテンプレートは## Whyからいきなり始まっていましたが、1.13.1では# Proposalという見出しから始まるようになりました。単体のMarkdownファイルとして見たときに、見出しレベルがちゃんと1から始まる形に整理されたということです。
apply
apply側は指示の骨格自体はそこまで変わっていませんが、ガードレールが増えています。v1.3.1(apply-change.ts / v1.3.1)はこれだけでした。
**Pause if:**
- Task is unclear → ask for clarification
- Implementation reveals a design issue → suggest updating artifacts
- Error or blocker encountered → report and wait for guidance
- User interrupts
1.13.1(apply-change.ts / v1.13.1)だとここに1行増えています。
- A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
要は「specに書いてないことをこっそりやったり、specに書いてあることをこっそり削ったりせず、必ずユーザーに聞け」というガードレールが増えました。例えば実装中に「CSVの区切り文字も選べるようにしたほうがいいかも」と思いついても、黙って実装するのではなく「これはspecにない追加のスコープですが、やりますか?」と一度確認を挟む、というイメージです。エージェントが空気を読んで勝手にスコープを縮めたり広げたりするのを防ぐ意図だと思います。
archive
v1.3.1のopenspec-archive-changeテンプレート(archive-change.ts / v1.3.1)は、こう指示していました。
5. **Perform the archive**
Create the archive directory if it doesn't exist:
```bash
mkdir -p openspec/changes/archive
```
Generate target name using current date: `YYYY-MM-DD-<change-name>`
...
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
Claude自身にmkdirとmvをやらせて、delta specをmainのspecに反映する作業もsubagentに委任する、かなりエージェント任せの手順でした。実際に1.3.1環境で同じCSVエクスポートのchangeをarchiveすると、あっさりこう終わります。
一方、今の1.13.1(archive-change.ts / v1.13.1)はopenspec archiveコマンド1つがdelta specの解析・main specへの反映・検証まで全部やってくれます。同じ変更をarchiveすると、こうなりました。
carried Purpose is under 50 charactersという警告が出ています。このPurposeという欄自体、v1.3.1のspecテンプレートには存在していません。1.3.1のspecテンプレートは## ADDED Requirementsから始まっていて、## Purposeセクションがそもそもありません。1.13.1になって「このcapabilityは何のためにあるか」を50文字以上で書く欄が追加され、短すぎると--strictで警告が出るようになりました。
参考: セットアップの出力
openspec initの出力自体も見た目が違います。v1.3.1だとこうなります。
「4 skills and 4 commands」です。今の1.13.1だとこうなります。
「6 skills and 6 commands」に増えていて、増えた2つはsyncとupdateです。
-
sync(openspec-sync-specs、v1.4.0〜): archiveせずに、delta specだけ先にmain specへ反映したいときに使う。changeはまだ進行中のまま、specの内容だけ先に本体へ取り込める -
update(openspec-update-change、v1.6.0〜): 上の表で紹介した/opsx:updateのこと。実装が進んでいる途中でも計画(proposal/tasks)だけ直したいときに手動で呼ぶ
まとめ
OpenSpecはこうして少しずつアップデートが入っているので、随時見直してアップデートしていくのも作業効率の面でおすすめです。



