本文へスキップ
hdknr blog
戻る

OpenSpec とは? 仕様駆動開発の使い方・/openspec-* スキルと Spec Kit・Kiro との違い

更新日:

2026-11-13 更新: OpenSpec v2.0.0(2026 年 11 月 11 日リリース)で /opsx:* のスラッシュコマンドが廃止され、/openspec-* のスキルに置き換わった。使い方・インストール方法・対応ツール・比較表を最新の情報に合わせて書き直し、仕様の差分(delta spec)と v1.x からの移行の節を追加した。

はじめに

「AIにコードを書かせるのは得意になったが、完成品が要件とずれていて全部作り直しになった」——そんな経験はないだろうか。

Vibe coding(感覚的なプロンプトだけでAIにコーディングさせるスタイル)は手軽な反面、AIとの認識齟齬が後から発覚してリワークが発生するリスクをはらんでいる。

OpenSpec は、その問題を「仕様駆動開発(SDD: Spec-Driven Development)」で解消するフレームワークだ。2025 年 8 月にリポジトリが公開されてから急速に普及し、2026 年 11 月時点で GitHub のスターは 7 万を超えている。

要点は次の 3 つ。

Vibe Codingの落とし穴

AIコーディングアシスタントは非常に強力だが、要件がチャット履歴の中にしか存在しない場合、出力は予測不能になりやすい。よくある失敗パターンは次のとおり。

OpenSpecはこれを「コードを書く前にAIと仕様に合意する」プロセスを導入することで防ぐ。

OpenSpecとは

OpenSpecは、AIコーディングアシスタント向けの軽量な仕様レイヤーを提供するフレームワーク。プロジェクトに openspec/ ディレクトリを作り、変更ごとに proposal・specs・design・tasks の4つのアーティファクトを生成・管理する。

設計哲学:

→ fluid not rigid      (柔軟、固定フェーズなし)
→ iterative not waterfall (反復的、ウォーターフォールではない)
→ easy not complex     (シンプル)
→ built for brownfield not just greenfield (新規だけでなく既存プロジェクトにも対応)
→ scalable from personal projects to enterprises

OpenSpec の使い方:/openspec-* スキルと基本の流れ

OpenSpec は、AI コーディングアシスタントに追加する スキル(エージェントが呼び出せる手順書のようなもの)で動作する。v2.0.0 からはスキルが .agents/skills/ に置かれる。

どのスキルを入れるかは「プロファイル」で切り替える。既定の core プロファイルで使えるのは次の 6 つだ(詳細は Skills)。

スキル役割
/openspec-explore変更として提案する前に、アイデアを検討する
/openspec-propose変更を提案し、4 つのアーティファクト(proposal・specs・design・tasks)をまとめて生成する
/openspec-apply-change提案した変更のタスクを実装する
/openspec-update-changeアーティファクトを修正する
/openspec-sync-specsアーカイブせずに、変更の仕様を openspec/specs/ に反映する
/openspec-archive-change完了した変更をアーカイブに移す

Codex では / の代わりに $openspec-propose のように呼ぶ。

基本の 3 ステップ

流れは、提案 → 実装 → アーカイブの 3 ステップ。エージェントのチャット欄で、次の順に実行する。

/openspec-propose add-dark-mode
/openspec-apply-change
/openspec-archive-change

/openspec-propose で作りたいものを伝えると、openspec/changes/add-dark-mode/ に次のファイルが作られる。人間はそれをレビューして合意した上で実装に進む。

ファイル内容
proposal.mdなぜやるか、何が変わるか
specs/要件とシナリオ(変更分)
design.md技術的アプローチ
tasks.md実装チェックリスト

アーカイブすると、変更のフォルダは openspec/changes/archive/YYYY-MM-DD-<変更名>/ に移る。同時に、変更分の仕様が openspec/specs/ の仕様に統合される。

追加のスキルとプロファイル

既定の 6 つのほかに、次のようなスキルもある。

これらは既定では入っていない。プロファイルで選んでから、各プロジェクトでスキルを入れ直す。

openspec config profile   # 使うスキルを選ぶ
openspec update           # 各プロジェクトでスキルを入れ直す

仕様の差分(delta spec)

specs/ に書くのは、仕様全体ではなく 変更分(差分) だ。追加・変更・削除・名前の変更を見出しで分けて書く。次は書式を示すための例(文面は説明用に作ったもの)。

## ADDED Requirements

### Requirement: Theme selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: User toggles dark mode
- **WHEN** the user selects dark mode
- **THEN** the interface switches to the dark theme

見出しは ## ADDED Requirements・## MODIFIED Requirements・## REMOVED Requirements・## RENAMED Requirements を使う。要件には少なくとも 1 つの #### Scenario: が必要で、openspec validate で形式を確かめられる。

既存のコードに手を入れる変更でも変わる部分だけを書けばよいので、既存プロジェクト(brownfield)にも導入しやすい。

インストールと初期化

インストールスクリプトを使えば、Node.js がなくても入れられる(Installation)。

# macOS / Linux(スタンドアロン版)
curl -fsSL https://openspec.dev/cli/install.sh | sh

# npm で入れる場合(Node.js 22.12.0 以上が必要)
npm install -g @fission-ai/openspec@latest

# プロジェクトディレクトリで初期化
cd your-project
openspec init

Windows は PowerShell の irm https://openspec.dev/cli/install.ps1 | iex で入れられる。Homebrew(brew install openspec)・pnpm・yarn・bun・Nix にも対応している。

初期化したら、エージェントで /openspec-propose <作りたいもの> を実行する。

v1.x(/opsx:*)からの移行

v1.x では /opsx:propose・/opsx:apply・/opsx:archive のようなスラッシュコマンドを使っていた。v2.0.0 でこれらは廃止され、/openspec-propose・/openspec-apply-change・/openspec-archive-change などのスキルに置き換わった。

v1.x から使っているプロジェクトでは、openspec update を実行する。古いバージョンが作ったファイルが整理され、新しいスキルに入れ替わる。

テレメトリの無効化

OpenSpec は、匿名の利用統計(コマンド名とバージョンのみ)を収集する。openspec config set telemetry.enabled false か、環境変数 OPENSPEC_TELEMETRY=0 で無効にできる。

対応ツール(Claude Code・Codex・Cursor など)

README では「30 種類以上」とされ、対応ツールの一覧には 40 を超えるツールが並んでいる。主なものは以下のとおり。

README では、計画と実装の両方に高推論モデル(Codex 5.5 と Opus 4.7)を推奨している。

Spec Kit・Kiro との違い

OpenSpecSpec Kit (GitHub)Kiro (AWS)
形態既存のエージェントに追加する既存のエージェントに追加する専用の AI 開発環境(IDE・CLI・Web など)
導入インストールスクリプト 1 行か npmPython 3.11 以上と uv / pipxKiro 自体をインストール
進め方提案 → 実装 → アーカイブ(固定フェーズなし)原則 → 仕様 → 計画 → タスク → 実装要件 → 設計 → タスク → 実装(承認を省く Quick Spec もある)
使えるエージェント30 種類以上(一覧では 40 超)40 種類以上—(専用環境)
モデルエージェントに依存エージェントに依存Kiro が提供するモデル(Claude・OpenAI・オープンウェイトなど)

OpenSpec の README は、Spec Kit を「徹底しているが重い(厳格なフェーズゲート、大量の Markdown、Python のセットアップ)」と評している。Kiro については「強力だが IDE に縛られ、Claude のモデルに限られる」とする。ただし 2026 年 11 月時点の Kiro は、CLI や Web からも使え、Claude 以外のモデルも選べる。OpenSpec 自身による比較なので、割り引いて読むとよい。

そのうえで筆者の見立てを言えば、OpenSpec の強みは「軽量さ」と「ツールの自由度」だ。固定フェーズがなく、変更を差分で扱うので、既存プロジェクトにも導入しやすい。

Kiro の機能と料金の詳細は「Kiro とは? AWS の仕様駆動 AI IDE の Spec・Steering・Hooks と料金プラン」、Spec Kit のコマンドと原則(constitution)は「GitHub Spec Kit とは? 仕様駆動開発のコマンド・constitution と Kiro との違い」を参照。MCP サーバーとして動き、仕様の承認をダッシュボードで記録する「Spec Workflow MCP」という選択肢もある。

Kiro の機能と料金の詳細は「Kiro とは? AWS の仕様駆動 AI IDE の Spec・Steering・Hooks と料金プラン」を参照。

コンテキストエンジニアリングの標準化

OpenSpecが注目されるもう一つの理由が、コンテキストエンジニアリングの標準化だ。

AIコーディングアシスタントが失敗する根本原因の多くは「コンテキスト管理の失敗」にある。長いセッションで仕様が揮発したり、複数ファイルの変更で前提が食い違ったりする。

OpenSpecは変更ごとに openspec/changes/<feature>/ 以下にアーティファクトを整理することで、AIが常に正しい文脈で作業できる環境を維持する。「コンテキストを毎回クリアしてから実装を開始する」というベストプラクティスも公式に推奨されている。

既存の「docs/ に仕様書を書かせてからレビュー → 実装」運用との比較

OpenSpec を導入していなくても、すでに 「docs/ フォルダに mkdocs などで仕様書を書かせ、人間がレビューしてから実装に入る」 運用をしている開発者は多い。これは Spec-Driven Development の原則そのものであり、本質的には正しい方向を向いている。

ではそのうえで OpenSpec を使う意味はあるのか。両者を比較すると、現状方式で解きにくい「2つの本質的な問題」が見えてくる。

問題docs/ + mkdocs 方式OpenSpec の解
why / what / how / do の混在1つの仕様書に動機・要件・設計・タスクが混ざりがちproposal.md / specs/ / design.md / tasks.md で物理分離
AIのコンテキスト戦略が手動「どの docs を読ませるか」を毎回人間が判断変更ごとのフォルダにアーティファクトがまとまる(README は実装前のコンテキストのクリアも推奨)

補足: 「変更履歴」は git で足りる

docs/ を git 管理している場合、変更履歴自体は commit log・PR description・issue で十分に残る。OpenSpec の archive/ が git に対して優位なのは、(1) 機能単位の物理隔離(PR と機能は必ずしも 1:1 ではない)、(2) AI から読みやすい固定パスにアーティファクトが置かれる、(3) 完了時点のスナップショットが上書きされない、の3点に絞られる。「変更履歴を残すため」を OpenSpec 採用の主理由にするのは弱い。

docs/ + mkdocs 方式の強み

逆に現状方式にも、OpenSpec にはない強みがある。

OpenSpec が効いてくる閾値

逆に言えば、次の状況に達したときに OpenSpec の導入価値が跳ね上がる。

  1. 複数機能を並行開発するようになったとき — docs/ がフラットだと AI が読むべき範囲を絞れないが、changes/<feature>/ は機能単位で物理隔離される
  2. AI に実装を任せる比率が増えたとき — tasks.md のチェックリストで進捗が機械可読になり、/openspec-apply-change で一気通貫の自動実装が可能になる
  3. why/what/how/do を1ファイルに書き散らかして AI が混乱し始めたとき — 4アーティファクト分離は単なる整理整頓ではなく、AI のコンテキスト窓を節約する仕組みとして効く

折衷案: docs/ 上で OpenSpec の構造だけ真似る

OpenSpec を全採用しなくても、「変更単位で隔離する」「tasks.md でチェックリスト化する」 の2点だけ docs/ 配下に取り込むと、現状方式の弱点が8割埋まる。

docs/
├── changes/
│   ├── 2026-05-26-add-dark-mode/
│   │   ├── proposal.md   # なぜやるか
│   │   ├── design.md     # 技術的アプローチ
│   │   └── tasks.md      # 実装チェックリスト
│   └── archive/
│       └── 2026-04-10-add-search/
└── specs/                # 最新の正(specs はここに集約)

つまり「OpenSpec をフレームワークとして導入する」より、「OpenSpec の構造を mkdocs 上で真似る」 ほうが、すでに docs/ 運用が回っているプロジェクトには合っている。OpenSpec を導入するかどうかの判断は「フレームワークを入れるか」ではなく、「変更単位の隔離と why/what/how/do の物理分離を、自分のプロジェクトに取り込むか」で考えるとよい。

実践例: docs-structure.md + GitHub Issue で初期化する

mkdocs ベースで開発を始めるとき、リポジトリ作成直後の典型的なフローはこうなる。

  1. main ブランチで PLAN.md にプロジェクトの目的・手段・要件を記載
  2. リポジトリルートに docs-structure.md を置いてルールを定義
  3. GitHub Issue は「docs-structure.md に従って docs/ を作って」と一行で立てる
  4. AI コーディングアシスタントに着手させる

ポイントは「規約はリポジトリに、依頼は短く」。Issue にルール全文を毎回コピペするのではなく、リポジトリ内の固定ファイルとして外出しする。これは CLAUDE.md / AGENTS.md と同じパターンで、

という利点がある。

① リポジトリルートに置く docs-structure.md

# docs-structure.md — 仕様書ディレクトリの規約

このリポジトリの `docs/` は mkdocs + 以下のルールで運用する。
新規プロジェクト初期化時、および新機能追加時はこのファイルに従うこと。

## ディレクトリ構造

```text
docs/
├── index.md           # PLAN.md の要約を載せる
├── specs/             # 合意済みの「最新の正」を集約
│   └── .gitkeep
└── changes/
    ├── _template/     # 新規 change 作成時にコピーする雛形
    │   ├── proposal.md
    │   ├── design.md
    │   └── tasks.md
    ├── archive/       # 実装完了した change の保管先
    │   └── .gitkeep
    └── .gitkeep
```

## アーティファクトの責務

| ファイル | 役割 | 書く内容 |
|---|---|---|
| `proposal.md` | Why | 背景・課題、提案する変更、スコープ外、関連 issue/PR |
| `design.md` | How | 採用するアプローチ、代替案と却下理由、依存・前提、影響範囲 |
| `tasks.md` | Do | 実装チェックリスト(`- [ ]` 形式、機械可読) |
| `specs/` 配下 | What(最新の正) | 合意済みの要件・仕様 |

1ファイル内で why/how/do を混在させない。

## 運用フロー

1. 新機能を追加するときは `docs/changes/YYYY-MM-DD-<feature>/` を作り、`_template/` からコピーする
2. **proposal → design → tasks の順で人間がレビュー**してから実装に入る
3. 実装完了後、当該ディレクトリを `docs/changes/archive/` に移送し、`docs/specs/` を更新する
4. AI に作業させるときは **「該当 change のディレクトリだけ」をコンテキストに入れる**(他の change のファイルは読ませない)
5. `docs/specs/` は常に「最新の正」のみを置く。履歴は archive と git に任せる

## 初期化時の受け入れ条件

- [ ] `pip install mkdocs mkdocs-material` の手順が README にある
- [ ] `mkdocs.yml` がプロジェクト直下にある
- [ ] `mkdocs serve` でローカル閲覧できる
- [ ] `docs/specs/` `docs/changes/` `docs/changes/archive/` `docs/changes/_template/` が初期化されている
- [ ] `_template/` に proposal.md / design.md / tasks.md が配置されている
- [ ] (任意) `mkdocs build --strict` が CI に組み込まれている

## なぜこの構造にするのか

- **変更単位の物理隔離** — 並行開発で AI が読むべき範囲が `docs/changes/<feature>/` に絞られる
- **why/what/how/do の分離** — 1ファイル混在による AI の混乱を防ぐ
- **コンテキスト戦略の標準化** — 「change ディレクトリだけ読ませる」が運用ルールとして明文化される
- 履歴は git の commit log・PR・issue で十分残るため、archive は AI から読みやすい位置に固定する目的に絞る

② GitHub Issue 本文(短縮版)

## 課題
`docs-structure.md` のルールに従って、`docs/` 以下に mkdocs で仕様書を作ってください。

## 前提
- `PLAN.md` にプロジェクトの目的・手段・要件は記載済み
- main ブランチで作業

## 完了条件
- [ ] `docs-structure.md` の「初期化時の受け入れ条件」をすべて満たしている
- [ ] PR を出す

Issue はこれだけ。後続の「機能 X を追加」系の Issue も「docs-structure.md に従って docs/changes/YYYY-MM-DD-feature-x/ を作って」の一行で発注できる。

注意点

この形にしておくと、プロジェクトが育っても OpenSpec を導入するかどうかは選択肢として残しつつ、AI コーディング時代の最低限の構造は最初から確保できる。

まとめ

ポイント内容
課題Vibe codingでは要件齟齬が後から発覚しやすい
解決策仕様書(proposal/specs/design/tasks)を先に合意してから実装
ツールOpenSpec (@fission-ai/openspec)
対応環境Claude Code・Codex・Cursor・Kiro など 30 種類以上(一覧では 40 超)
使い方/openspec-propose → /openspec-apply-change → /openspec-archive-change
v2.0.0 の変更/opsx:* から /openspec-* スキルへ(v1.x からは openspec update で移行)
導入コストインストールスクリプトか npm install -g @fission-ai/openspec で即日導入可能

仕様書を先に書く。それだけでAIの出力品質が桁違いに変わる。OpenSpecはこの単純な原則をツールとして具体化したプロジェクトだ。AIコーディングを本格的に活用したい開発者にとって、試す価値は十分にある。



前の記事
「言語税」対策として CLAUDE.md を英語化する — 日本語境界を残したまま prompt caching を効かせる部分英語化パターン
次の記事
Claude Code × TradingView — MCPサーバーでチャートを「会話で動かす」時代へ