---
title: "OpenSpecとは？使い方・インストール・/opsxコマンドをv1.14で解説"
url: "https://www.issoh.co.jp/tech/details/11351/"
published: 2026-03-13
updated: 2026-10-16
categories: ["AIエージェント・MCP"]
publisher: "株式会社一創"
---

# OpenSpecとは？使い方・インストール・/opsxコマンドをv1.14で解説

OpenSpecは、AIコーディングツールに実装させる前に「何を作るか」をMarkdownの仕様として合意し、そのまま履歴として残すためのオープンソースのCLIです。この記事では、2026年10月15日公開のv1.14.2を手元にインストールし、`openspec init`から`openspec archive`までを実行した結果をもとに、使い方とつまずきやすい点を整理します。

検索で見つかる解説には、1.0より前の`/openspec:proposal`や`project.md`を前提にしたものがまだ多く残っています。1.0（2026年1月26日）でコマンド体系が作り直されているため、古い手順のまま試すと生成されるファイルが一致しません。

## まとめ：OpenSpecの要点

- OpenSpecはFission-AIが開発するMITライセンスのCLIで、npmパッケージ名は`@fission-ai/openspec`。Node.js 20.19.0以上が必要です。
- 導入は`npm install -g @fission-ai/openspec@latest`のあと、プロジェクト直下で`openspec init`。Claude Code・Cursor・Cline・Codex・OpenCodeなど、v1.14.2では50種のIDを`--tools`で指定できます。
- 既定のcoreプロファイルは`/opsx:propose`・`/opsx:explore`・`/opsx:apply`・`/opsx:update`・`/opsx:sync`・`/opsx:archive`の6コマンドです。スラッシュコマンドはAIツールのチャットで、`openspec validate`などのCLIはターミナルで使います。
- 変更は`openspec/changes/<名前>/`に、proposal・specs・design・tasksとして残ります。archiveするとデルタが`openspec/specs/`へ統合されます。
- `openspec validate`はシナリオが無い要件をエラーにし、SHALL/MUSTが無い要件、500字を超える要件、archiveで引き継がれない節を警告にします。`--strict`を付けると警告でも失敗します。
- 1.0以降はAGENTS.mdとproject.mdを生成しません。プロジェクトの前提は`openspec/config.yaml`の`context`に書きます。

## OpenSpecの位置づけと1.0で変わった設計

### AIとの合意をリポジトリに残す仕様レイヤー

[公式リポジトリ（Fission-AI/OpenSpec）](https://github.com/Fission-AI/OpenSpec)のREADMEは、要件がチャット履歴にしか無いとAIの出力が予測しにくくなる点を課題に挙げ、コードを書く前に人とAIが仕様で合意するための軽量なレイヤーとしてOpenSpecを位置づけています。成果物はすべてプロジェクト内のMarkdownです。OpenSpec自身はモデルを呼び出さず、仕様の生成や実装は連携先のAIツールが行います。そのためOpenSpec用のAPIキーは要らず、モデルの費用は使っているツール側の契約で決まります。

2026年10月16日時点のGitHubスター数は72,121、npmのダウンロード数は9月13日から10月12日までの30日間で2,919,226でした。リリースはほぼ毎週で、9月30日の1.14.0から10月15日の1.14.2までの約2週間に3回更新されています。

### 1.0のOPSX刷新で廃止されたAGENTS.md・project.md

1.0は変更履歴で「The OPSX Release」と呼ばれる大きな改訂でした。`/openspec:proposal`・`/openspec:apply`・`/openspec:archive`の3コマンドを順に進める方式をやめ、成果物の依存関係をCLIが把握して「次に作れるもの」を示す方式に変わりました。同時に、ツール別の指示ファイル（`CLAUDE.md`・`.cursorrules`・`AGENTS.md`・`project.md`）は生成されなくなっています。

公式の移行ガイドは、受け身のproject.mdはエージェントが読むかどうかが不確実だったと説明しています。代わりに`config.yaml`の`context`が、成果物を作るたびに指示へ組み込まれるようになりました。旧版からの移行手順はFAQの最後の質問にまとめています。

## OpenSpecのインストールとopenspec initの実行結果

### Node.js 20.19.0以上とnpm・Homebrewでの導入

npmのパッケージ情報では`engines`が`node >=20.19.0`です。20系でも20.19より古いと要件を満たしません。先に`node -v`で確認してください。

```
node -v
npm install -g @fission-ai/openspec@latest
openspec --version
# 1.14.2（2026年10月16日時点のlatest）

# npm版の代替：macOS・LinuxではHomebrewも利用可能
# 配布版がnpmと異なる場合があるため、導入後に版を確認
brew install openspec
openspec --version

# 新しい版が出ているかを確かめる（1.14.0で追加）
openspec version --check
```

npmの`next`タグは0.3.0、`beta`タグは1.6.0-beta.1のまま止まっており、どちらも`latest`（1.14.2）より古い版です。`@next`を付けて入れると古い版になるので、通常は`@latest`を指定します。

既定では匿名の利用統計が送られ、初回実行時に止め方が表示されます。止めるには環境変数`OPENSPEC_TELEMETRY=0`を設定するか、`openspec config set telemetry.enabled false`を実行します（CIでは自動で無効）。ただし`OPENSPEC_TELEMETRY=0`の状態で`openspec version --check`を実行すると「Update check disabled.」と返り、更新の有無は確かめられませんでした。

### openspec init –toolsで生成されるファイル

引数なしの`openspec init`は対話形式でツールを選びます。`--tools`を渡すと対話なしで進みます。空のGitリポジトリで`openspec init --tools claude,opencode`を実行すると、次のファイルが作られました。

```
openspec/
├── config.yaml              # schema: spec-driven と記入例のコメント
├── specs/.gitkeep           # 確定した仕様（最初は空）
└── changes/archive/.gitkeep # 完了した変更の保管先
.claude/commands/opsx/       # propose.mdを含む計6本
.claude/skills/openspec-*/   # SKILL.md 6本
.opencode/commands/          # opsx-propose.mdを含む計6本
.opencode/skills/openspec-*/ # SKILL.md 6本
```

終了時には「6 skills and 6 commands」と表示され、残り6つのワークフロー（new・continue・ff・bulk-archive・verify・onboard）は`openspec config profile`で追加できると案内されます。AGENTS.mdやproject.mdは作られません。`--tools`に渡せるIDはv1.14.2のヘルプで50種あり、1.14.0でAmp・Warp・Grok Buildなど10種が加わりました。`windsurf`は`devin`の別名として受け付けられます。`all`を渡すと全部入ります。どのツールにも当てはまらない場合は、AGENTS.md互換ツールが読む`.agents/skills/`に書き出す`agents`を選びます。

### 日本語で成果物を書かせるconfig.yamlの設定

新規プロジェクトなら`openspec init --language Japanese`のように言語を指定できます。v1.14.2で実行すると、`context`に「Language: Japanese」「All artifacts must be written in Japanese.」に続けて「Keep OpenSpec structural headings and SHALL/MUST keywords in English.」が書き込まれました。既存の`config.yaml`がある場合は`context`に直接書きます。公式の[多言語ガイド](https://github.com/Fission-AI/OpenSpec/blob/main/docs/multi-language.md)も、構造見出しとSHALL/MUSTは英語のまま残すよう注意しています（検証がこれらの語に依存するため）。

```
schema: spec-driven

context: |
  言語：日本語
  すべての成果物は日本語で作成してください。
  ただし ## ADDED Requirements などの構造見出しと SHALL/MUST は英語のまま残す。
  Tech stack: TypeScript, Next.js, PostgreSQL

rules:
  tasks:
    - 1タスクは2時間以内に収まる粒度に分ける
```

`rules`は成果物ごとの追加ルールで、proposal・specs・design・tasksそれぞれに箇条書きで指定します。v1.14.2が生成する`config.yaml`のコメントは、`context`にはコードを読めば分かる事実や一般的なプロジェクト文書を入れず、エージェントが推測できない制約だけを書くよう求めています。apply・archiveの進め方への助言は、1.7.0で加わった`operations`に分けて書けます。

CLIの表示やドキュメントまで日本語にしたい場合は、非公式の日本語ローカライズ版[OpenSpec-J](https://github.com/ayumuwall/OpenSpec-J)（npmは`@ayumuwall/openspec`）があります。READMEには「現在の同期元は OpenSpec v1.14.1 です」とあり、生成物だけ日本語にできれば十分なら本家の多言語機能を使うよう案内しています。どちらのパッケージも`openspec`という同じコマンド名を登録するため、同じnpmのグローバル配置先に両方を入れようとすると、通常はコマンド名が競合してEEXISTエラーになります。切り替える場合は、先に既存のパッケージをアンインストールします。成果物を日本語にするのが目的なら、本家の`--language`で足ります。

## /opsxスラッシュコマンドの使い方

### coreプロファイルの6コマンドと実行順

スラッシュコマンドはターミナルではなく、AIツールのチャット欄で実行します。既定のcoreプロファイルで入るのは次の6つです。

| コマンド            | 役割                 | コードを書くか |
| --------------- | ------------------ | ------- |
| `/opsx:explore` | 方針の検討・コード調査        | 書かない    |
| `/opsx:propose` | 変更フォルダと計画一式を作成     | 書かない    |
| `/opsx:apply`   | tasks.mdに沿って実装     | 書く      |
| `/opsx:update`  | 計画の成果物を修正・整合       | 書かない    |
| `/opsx:sync`    | デルタをspecs/へ統合      | 書かない    |
| `/opsx:archive` | 完了した変更をarchive/へ移動 | 書かない    |

基本の流れは`/opsx:propose add-dark-mode`で計画を作り、中身を読んで直してから`/opsx:apply`、完了後に`/opsx:archive`です。1.14.1からは、applyが全タスクにチェックを付け終えてもすぐにarchiveを勧めず、先にレビューするよう促します。`/opsx:sync`は任意で、archiveが未統合のデルタを見つけると統合するか聞いてくれるため、通常は手で呼ぶ必要がありません。長期間かかる変更で、先にspecs/だけ更新しておきたいときに使います。

### /opsx:exploreと/opsx:proposeの使い分け

作るものが決まっているなら`/opsx:propose`から始め、決まっていないなら`/opsx:explore`から入ります。exploreはコードを読んで選択肢を比べる相談役で、コードは書きません。成果物も、こちらが頼むか提案に同意したときにしか作りません。公式のExploreガイドは、要件がはっきりしている作業では「pure overhead」になるので飛ばしてよいと明記しています。判断の基準は、変更の範囲を一文で言い切れるかどうかです。言い切れないならexploreで範囲を固めてからproposeに渡します。

### 拡張ワークフロー6種とopenspec config profile

coreに入っていない6コマンドは、`openspec config profile`で選び、プロジェクトで`openspec update`を実行すると使えるようになります。

| コマンド                 | 使う場面                  |
| -------------------- | --------------------- |
| `/opsx:new`          | フォルダだけ作り、成果物は1つずつ作る   |
| `/opsx:continue`     | 依存関係上、次に作れる成果物を1つ作る   |
| `/opsx:ff`           | 計画の成果物を一度に全部作る        |
| `/opsx:verify`       | 実装と成果物の食い違いを点検        |
| `/opsx:bulk-archive` | 複数の変更をまとめてarchive     |
| `/opsx:onboard`      | 自分のコードで一巡する練習（15〜30分） |

`/opsx:verify`は完全性・正確性・整合性の3観点で点検し、指摘をCRITICAL・WARNING・SUGGESTIONに分けます。ただしarchiveを止めはしません。1.14.2からは、REMOVEDで消す要件の元の文面をspecs/から読み直してからコードを探し、読み直せないときは検証済みにせず報告するようになりました。`/opsx:onboard`は実際のコードベースから小さな改善点を探し、new→proposal→specs→design→tasks→apply→verify→archiveを解説付きで一巡します。初めて触る人は、onboardで計画からarchiveまでを一度通しておくと、各コマンドの役割がつかみやすくなります。

### ツール別の呼び出し表記（Cursor・Cline・OpenCode・Codex）

`/opsx:propose`は正式名で、実際に打つ表記はツールによって違います。`openspec init`の完了メッセージが、選んだツールごとの正しい表記を表示します。v1.14.2で`--tools claude,opencode`を指定したときは、Claude Code向けに`/opsx:propose "your idea"`、OpenCode向けに`/opsx-propose "your idea"`と案内されました。

| ツール                          | 入力する表記              | コマンドの配置先                    |
| ---------------------------- | ------------------- | --------------------------- |
| Claude Code・Gemini CLI・Qoder | `/opsx:propose`     | `.claude/commands/opsx/` など |
| Cursor・GitHub Copilot（IDE）   | `/opsx-propose`     | `.cursor/commands/` など      |
| Cline                        | `/opsx-propose`     | `.clinerules/workflows/`    |
| OpenCode                     | `/opsx-propose`     | `.opencode/commands/`       |
| Codex                        | `$openspec-propose` | スキルのみ（`.agents/skills/`）    |
| Amazon Q Developer           | `@opsx-propose`     | `.amazonq/prompts/`         |

OpenCodeでは、コマンドが`.opencode/commands/`に、スキルが`.opencode/skills/`に入ります。OpenCode本体の導入やモデル設定は[OpenCodeとは？2.0の変更点・インストール・設定・無料モデルを解説【2026年10月】](/tech/details/10369/)で扱っています。GitHub Copilotのプロンプトファイルが使えるのはIDE拡張（VS Code・JetBrains・Visual Studio）だけで、Copilot CLIでは使えないと公式が注記しています。Clineではワークフローが`.clinerules/workflows/`に入るため、[.clinerulesとは？書き方・配置場所とCline v4.1での読み込み仕様](/tech/details/6033/)で説明しているルールファイルと同じ階層に並びます。

## ターミナルで使うopenspec CLIコマンド一覧

AIツールのチャットで打つ`/opsx:*`とは別に、ターミナルの`openspec`コマンドがあります。こちらはAIを介さず、ファイルの生成・状態確認・検証・統合を行います。v1.14.2の`openspec --help`から、日常的に使うものを抜き出しました。

| コマンド                            | 用途                         |
| ------------------------------- | -------------------------- |
| `openspec init`                 | 初期化・ツール別ファイルの生成            |
| `openspec update`               | スキルとコマンドのファイルを作り直す         |
| `openspec version --check`      | インストール済みの版と更新の有無           |
| `openspec list`                 | 進行中の変更の一覧（`--specs`で仕様）    |
| `openspec list --archived`      | archive済みの変更の一覧（1.14.0〜）   |
| `openspec view`                 | 仕様と変更のダッシュボード              |
| `openspec new change <名前>`      | 空の変更フォルダを作る                |
| `openspec status --change <名前>` | 成果物の完了状況                   |
| `openspec show <名前>`            | 変更・仕様の中身を表示（`--json`可）     |
| `openspec validate`             | 変更・仕様の検証（`--all --strict`） |
| `openspec archive <名前>`         | specs/へ統合しarchive/へ移す      |
| `openspec config profile`       | 拡張ワークフローの選択                |
| `openspec schema fork`          | 既定スキーマを複製して独自化             |

このほか、複数リポジトリの計画を扱う`store`、ルートの健全性を見る`doctor`、AIツールが呼び出す`instructions`などがあります。`openspec view`は1.14.0から変更ごとにどの成果物が完了・作成可能・ブロック中かを表示し、1.14.1からはarchive済みの変更を数えなくなりました。過去の変更を探すときは`openspec list --archived`を使います。

## changesフォルダとデルタスペックの書き方

### proposal・specs・design・tasksの依存関係

既定のスキーマ`spec-driven`では、1つの変更が4つの成果物を持ち、作る順番に依存関係があります。`openspec new change add-2fa`で空の変更を作り、`openspec status`を実行すると次のように表示されました。

```
$ openspec status --change add-2fa
Change: add-2fa
Schema: spec-driven
Progress: 0/4 artifacts complete

[ ] proposal
[-] specs (blocked by: proposal)
[-] design (blocked by: proposal)
[-] tasks (blocked by: specs, design)

Next: openspec instructions proposal --change "add-2fa" --json
```

proposal.mdには「なぜ」と影響範囲、specs/には振る舞いの要件、design.mdには技術的な判断、tasks.mdにはチェックボックス付きの作業一覧を書きます。proposalのテンプレートは、変更ごとに新規か既存かを問わずcapabilityを1つ以上宣言するよう求めます。仕様上の振る舞いが変わらないリファクタリングや文書修正だけの変更は、変更フォルダの`.openspec.yaml`に`skip_specs: true`を書いて明示的に外します。

### ADDED・MODIFIED・REMOVED・RENAMEDの書式

変更フォルダのspecs/には、システム全体の仕様ではなく差分（デルタ）だけを書きます。見出しは`## ADDED Requirements`・`## MODIFIED Requirements`・`## REMOVED Requirements`・`## RENAMED Requirements`の4種です。既存のログインに二要素認証を足す例では、`openspec/changes/add-2fa/specs/auth-2fa/spec.md`に次の内容を書きます。

```
## Purpose
2FAを有効にしたユーザーに、パスワードに加えてTOTPコードの入力を求め、パスワード漏えい時の不正ログインを防ぐ。

## ADDED Requirements

### Requirement: TOTP verification at login
2FAを有効にしたユーザーは、パスワードの後にTOTPコードを入力しなければならない（SHALL）。

#### Scenario: Valid code
- **GIVEN** 2FAを有効にしたユーザーがパスワード認証を完了している
- **WHEN** そのユーザーが正しいTOTPコードを送信する
- **THEN** セッションが作成される
```

要件は`### Requirement:`、シナリオは`#### Scenario:`という見出しの階層で判別されます。シナリオの見出しを`###`にしたり箇条書きにしたりすると、パーサーはシナリオとして認識しません。`## Purpose`は新しいcapabilityにだけ書く節で、テンプレートは50字以上の1〜2文を求めています。

既存の要件を変えるMODIFIEDは、差分ではなく要件ブロック全体の置き換えとして扱われます。シナリオを1つ足したいだけでも、既存のシナリオをすべて書き写す必要があります。省略するとvalidateが「omits scenario(s) the current spec still has」というエラーを返し、archiveも既存シナリオの削除を拒みます。

### archiveでspecs/へ統合される流れ

デルタを持つ変更に`openspec archive add-2fa --yes`を実行すると、「+ 1 added」のように統合の内訳が表示され、`openspec/specs/auth-2fa/spec.md`が作られて、変更フォルダは`openspec/changes/archive/2026-10-16-add-2fa/`のように日付付きで移ります。デルタに`## Purpose`を書いておくと、その文がそのまま仕様の目的になりました。書かずにarchiveすると「TBD – created by archiving change add-2fa. Update Purpose after archive.」が入るので、後から書き足す手間が残ります。

`--yes`は確認を省くオプションです。CIやAIエージェントなど、プロンプトに答えられない環境では必須になります。1.14.0からは、specs/への統合が止まる条件を検出したときにarchiveも止まるようになり、仕様が更新されないまま変更だけがarchiveへ移る事故が防がれています。

## openspec validateで失敗する記述ミス（v1.14.2で実測）

仕様をCIで守るなら`openspec validate`の判定基準を知っておく必要があります。同じ要件を書き換えながら判定と終了コードを確かめました。下の4行目から7行目は1.14系で加わった検査です。

| 書き方                    | 通常             | `--strict`   |
| ---------------------- | -------------- | ------------ |
| シナリオなし                 | ERROR・終了コード1   | ERROR・終了コード1 |
| 英語で小文字のmustのみ          | WARNING・終了コード0 | 失敗・終了コード1    |
| 日本語のみ（SHALL/MUSTなし）    | WARNING・終了コード0 | 失敗・終了コード1    |
| 要件の本文が500字超            | WARNING・終了コード0 | 失敗・終了コード1    |
| デルタに`## Notes`など別の節    | WARNING・終了コード0 | 失敗・終了コード1    |
| 最初の`## `より前に地の文        | WARNING・終了コード0 | 失敗・終了コード1    |
| `.openspec.yaml`に未知のキー | WARNING・終了コード0 | 失敗・終了コード1    |
| MODIFIEDで既存シナリオを省略     | ERROR・終了コード1   | ERROR・終了コード1 |
| シナリオあり・SHALLを含む        | valid・終了コード0   | valid・終了コード0 |

SHALL/MUSTの警告文は「should contain SHALL or MUST (RFC 2119 best practice for English specs)」です。小文字のmustは数えられず、日本語だけで書いた要件も同じ警告を受けます。「〜しなければならない（SHALL）」のように英語の語を1つ添えれば、日本語のまま`--strict`を通せました。

500字の警告（1.14.1から）は、例や境界条件をシナリオへ移すか、1要件1振る舞いに分けるよう促します。`## Notes`や先頭の地の文の警告（1.14.2から）は、archiveしたときにその部分がspecs/へ引き継がれず消えることを知らせるものです。補足はproposal.mdかdesign.mdに書きます。

`.openspec.yaml`の未知キーの警告（1.14.0から）には注意が要ります。設計を飛ばすつもりで`skip_design: true`と書いたところ、警告文は「skip\_design is not a supported key; only skip\_specs exists」と返しました。以前の版ではこうしたキーが黙って無視されていたため、効いていない設定に気付けませんでした。チケット番号など自分用の情報を持たせたい場合は、1.14.2から`x-jiraKey: PROJ-12`のように`x-`で始まるキーにすれば警告が出ず、`--strict`も通りました。

```
# プルリクエストのCIで全件を厳格に検証する
openspec validate --all --strict --concurrency 12

# パースされたデルタの中身を確かめる
openspec show add-2fa --json --deltas-only
```

変更履歴によると、以前は`openspec/`の無いディレクトリで`validate --all`を実行すると空の結果のまま終了コード0になっていました。現在は失敗するよう直されています。古い版を固定しているCIでは、作業ディレクトリの指定漏れが素通りしていないか確認してください。逆に1.14系へ上げると上の警告が増えるため、`--strict`のCIが急に落ちることがあります。版を上げるPRで一度`validate --all --strict`を通しておくと安全です。

## CLIのopenspec updateと/opsx:updateの違い

名前が同じ2つの「update」は、対象がまったく違います。

- **ターミナルの`openspec update`**：CLIを更新したあと、各プロジェクトのスキルとコマンドのファイルを、今のプロファイルと配布形式で作り直します。プロファイルを変えたときもこれで反映します。
- **チャットの`/opsx:update`**：進行中の変更の成果物（proposal・design・tasksなど）を修正し、互いの矛盾を解消します。コードは触りません。1.6.0で追加されました。

CLIの`openspec update`は、インストール済みのCLIに入っているテンプレートからファイルを作ります。古いCLIのままでは、新しい版で追加されたワークフローや改善されたスキルの指示は入りません。そのため、パッケージを先に上げてから各プロジェクトで`openspec update`を実行します。

```
openspec version --check                     # 更新があるか確認
npm install -g @fission-ai/openspec@latest   # Homebrewなら brew upgrade openspec
cd your-project
openspec update
```

`/opsx:update`で直すか新しい変更を切るかは、公式ワークフローガイドの基準に従います。意図が同じで範囲が狭まるだけなら修正で済ませます。範囲が別の作業に広がった場合や、元の変更がそれ単体で完了扱いにできる場合は、新しい変更に分けます。

## チームでの運用：Git・PRレビューとarchiveの時期

### OpenSpecはGitを操作しない前提でのPRの組み方

公式のチーム運用ガイドは「OpenSpec doesn’t touch git」を唯一のルールとして挙げています。コミットもブランチ作成もしないので、`openspec/`フォルダは他のソースと同じように自分でコミットします。推奨されている流れは、ブランチを切って`/opsx:propose`で計画を作り、読んで直してから`/opsx:apply`し、デルタとコードを同じPRに入れる形です。レビュー担当はproposal.md→specs/のデルタ→コード差分の順に読みます。方針への異論をコードの差分ではなく計画の段階で出せるのが、この順序の利点です。

### proposal・specs・tasksのレビュー観点

AIが書いた計画をそのまま通すと、OpenSpecを入れた意味がなくなります。公式の[Reviewing a Changeガイド](https://github.com/Fission-AI/OpenSpec/blob/main/docs/reviewing-changes.md)は、レビューの時点を`/opsx:propose`の直後（コードを書く前）と実装後の`/opsx:verify`の2回に絞り、前者を「最も効果が大きく、最も飛ばされる」レビューと位置づけています。読む順番は、間違いがあれば最も早く止められる順です。

- **proposal.md**：頼んだ問題と少し違う問題を解いていないか、範囲が勝手に広がっていないか。テーマ切り替えを頼んだのに認証にも手を入れている、といった混入をここで止めます。ここが違えば先を読まずに直します。
- **specs/のデルタ**：レビューの中心です。テスターに渡せる具体的なSHALL/MUSTになっているか、シナリオがその要件を確かめる内容になっているか。ガイドが最も価値があるとするのは「書かれていないもの」に気付くことです。AIは言われたことを忠実に書くので、言い忘れた境界条件（権限が無い・入力が不正・時間切れなど）は人が足します。
- **design.md**：大きな変更のときだけ読みます。テンプレートには「Non-Goals」と「Decisions」の節があり、やらないことと採らなかった案が書かれているかを見ます。
- **tasks.md**：どの要件にも対応しないタスクや、判断を隠した「機能を実装する」だけの巨大なタスクが無いか。粒度の基準は`config.yaml`の`rules.tasks`に書いておけば、次の計画から反映されます。

直し方は、Markdownを自分で書き換えるか、「認証の変更は範囲外なので外して」のようにAIへ指示して作り直させるかのどちらかです。MODIFIEDで既存シナリオが消えていないか、SHALL/MUSTが抜けていないかといった形式面は`openspec validate`に任せ、人は中身に集中します。

### archiveの実行時期：マージ後とPR内の比較

archiveはspecs/を書き換えるので、チームでは時期をそろえます。公式の推奨はPRのマージ後で、実際に出荷した変更だけがspecs/に入ります。小さなチームなら同じPR内でarchiveしてもかまいませんが、specs/とコードの差分が混ざってPRが読みにくくなります。別々の変更フォルダは互いに干渉しません。ただし同じ変更フォルダを複数人で編集すれば通常のファイルと同じく衝突し、別々の変更が同じ要件を書き換えた場合はarchive時にspecs/で競合を解消することになります。

### 既存プロジェクトとマルチリポジトリでの使い方

既存のコードベースでは、既存機能の仕様をまとめて後から書かないよう公式が注意しています。変更しないコードの仕様は、現実とずれていくためです。specs/は空に近い状態から始まり、変更をarchiveするたびに触った部分だけが厚くなります。モノレポならルートに`openspec/`を1つ置けば足ります。複数リポジトリにまたがる計画は、1.5.0でベータ提供が始まった「Stores」で専用リポジトリに切り出せます。1.14.2からは`openspec/`や`openspec/specs`をシンボリックリンクにしてもarchiveできるため、共有のドキュメントリポジトリへ仕様を置く構成も取れます。

## Spec Kit・Kiroとの違い

ここでは仕様駆動開発（SDD）を支援するOpenSpec・Spec Kit・Kiroを、導入形態と成果物の違いで比較します。OpenSpecは既存のAIツールに足すCLIです。Spec KitもCLIですが、成果物の工程が長めです。Kiroは仕様機能をIDEそのものに組み込んでいます。

| 項目      | OpenSpec                    | Spec Kit                     | Kiro                      |
| ------- | --------------------------- | ---------------------------- | ------------------------- |
| 提供元     | Fission-AI                  | GitHub                       | AWS                       |
| 形態      | Node.js製CLI                 | Python製CLI（uv）               | IDE・CLI・Web               |
| 前提      | Node.js 20.19.0以上           | Python 3.11以上                | Kiro本体                    |
| 主な成果物   | proposal・specs・design・tasks | constitution・spec・plan・tasks | requirements・design・tasks |
| 既存仕様の扱い | デルタで差分だけ記述                  | 機能ごとに仕様を作成                   | 機能ごとに仕様を作成                |

OpenSpecの強みは、既存コードへの変更をデルタで小さく書けることです。不具合修正や項目追加が中心で、既存仕様への変更をデルタとして管理したいブラウンフィールド案件なら、OpenSpecが第一候補です。新規プロダクトの立ち上げでプロジェクト原則から固めたいならSpec Kitの`/speckit-constitution`が合い、IDEごと乗り換えてよいならKiroが候補になります。なおOpenSpecは`--tools kiro`でKiro向けのファイルも書き出せるので、Kiroの上でOpenSpecを使う構成も取れます。

5製品の選び方は[仕様駆動開発ツール比較｜Spec Kit・Kiro・cc-sdd・OpenSpec・Tesslの違いと選び方](/tech/details/8732/)で比較しています。個別の手順は[Spec Kit（GitHub）とは？仕様駆動開発の使い方・インストール・コマンドを徹底解説](/tech/details/9805/)と[Kiroとは？AWS製の仕様駆動AI IDEの特徴・料金・使い方を解説【2026年版】](/tech/details/7963/)を参照してください。

## OpenSpecが向かないケース

OpenSpecは万能ではありません。2026年7月には、RevCommの開発チームが「[OpenSpec やめます](https://tech.revcomm.co.jp/why-we-stopped-using-openspec)」という記事で導入を取りやめた理由を公開しています。挙げられた理由は、プレゼンテーション層はドメイン層より「変化しやすく、頻繁に Spec の見直しが必要となってしまう」こと、エージェントが生成した文章が「やや冗長になりがち」なこと、archiveに履歴が溜まることで「古いドキュメントを参照してしまい、却ってコード生成の精度が低下してしまうというデメリットが発生する懸念」でした。

この指摘は、OpenSpecが向く条件を裏から示しています。次のどれかに当てはまるなら、導入を見送るか範囲を絞ってください。

- **画面の見た目が頻繁に変わる変更**：UIの細部を要件にすると、仕様の書き直しが実装より重くなります。仕様にするのは入力検証や権限など、変わりにくい振る舞いだけにします。
- **過去の計画を参照させたくないリポジトリ**：archive済みの変更も`openspec/changes/archive/`に残り続けます。現行のspecs/と過去の計画をAIが混同しないよう、参照範囲を指示で区別する手間がかかります。
- **振る舞いが変わらない小さな修正**：依存パッケージの更新や設定値の変更のうち、仕様上の振る舞いが変わらないものは、proposalを書く手間のほうが大きくなります。`skip_specs: true`で外すか、OpenSpecを通さずに直します。認証やAPIの挙動が変わる更新は、この例外に入れません。

逆に、ドメインロジックやAPIの振る舞いのように「何が正しいか」を後から説明する必要がある変更では、archiveされたデルタが判断の記録として残ります。仕様駆動開発そのものの考え方は[仕様駆動開発（SDD）とは？従来手法との違いとSpec Kitで試す手順【2026年10月】](/tech/details/8740/)で整理しています。

## OpenSpecに関するよくある質問

### OpenSpecは無料で使えますか？

MITライセンスのオープンソースで、本体は無料です。OpenSpecはモデルを呼ばないのでAPIキーも不要です。ただし仕様の生成や実装はClaude CodeやCursorなどのAIツールが行うため、有料プランや課金対象のモデルを使う場合は、その利用料金が別途かかります。

### 既存のプロジェクトにも導入できますか？

できます。プロジェクトのルートで`openspec init`を実行するだけで、既存のコードには手を加えません。公式は既存機能の仕様を一括で書かず、これから行う小さな変更1件から始めるよう勧めています。

### Cline・OpenCode・Codexでも使えますか？

使えます。`openspec init --tools cline,opencode,codex`のように指定します。表記はツールごとに違い、ClineとOpenCodeは`/opsx-propose`、Codexはスキルとして`$openspec-propose`で呼び出します。Cline自体の導入は[Clineとは？VS Code拡張とCLIの使い方・料金・自動承認設定を実装目線で解説](/tech/details/17387/)を参照してください。

### TDD（テスト駆動開発）と組み合わせられますか？

既定のspec-drivenスキーマにテスト計画の成果物はありません。代わりに、シナリオのWHEN/THENをそのままテストケースに写す運用ができます。公式ドキュメントのコミュニティスキーマ一覧には、TDDの規律とレビュー工程を組み込んだ`anvil`も載っています（proposal→specs→design→review→test-plan→tasks→apply→verify）。スキーマは`openspec schema fork`で既定を複製して独自に作ることもできます。

### 旧版の/openspec:proposalやAGENTS.mdはどうなりましたか？

1.0で廃止され、`/opsx:*`のコマンドとスキルに置き換わりました。旧版のプロジェクトで`openspec init`か`openspec update`を実行すると、古いファイルの片付けを案内されます。旧コマンドファイルや`openspec/AGENTS.md`は削除対象ですが、ルートの`CLAUDE.md`・`AGENTS.md`などはOpenSpecの管理ブロックだけが除去され、独自の記述は残ります。削除対象のファイルに追記した内容は先に控えておきます。`project.md`だけは自動で消えないので、中身を`config.yaml`の`context`へ移してください。1.14.0からは、`openspec init`がproject.mdからconfig.yamlへの移行をAIに手伝わせる手順を案内します。

## 関連記事

- [仕様駆動開発ツール比較｜Spec Kit・Kiro・cc-sdd・OpenSpec・Tesslの違いと選び方](/tech/details/8732/)
- [Spec Kit（GitHub）とは？仕様駆動開発の使い方・インストール・コマンドを徹底解説](/tech/details/9805/)
- [Kiroとは？AWS製の仕様駆動AI IDEの特徴・料金・使い方を解説【2026年版】](/tech/details/7963/)
- [EARS記法とは？読み方と5つの基本型の書き方を日本語例文で解説【Kiro対応】](/tech/details/11489/)
- [ハーネスエンジニアリングとは？Spec・Context・Harnessの三層で組む設計と実装](/tech/details/11691/)

---

出典: [OpenSpecとは？使い方・インストール・/opsxコマンドをv1.14で解説](<https://www.issoh.co.jp/tech/details/11351/>)（株式会社一創）