OpenSpec とは:インストール、基本概念、ワークフロー

OpenSpec は軽量な仕様駆動開発(Spec-Driven Development)フレームワークです。あなたと AI コーディングアシスタントの間に「合意」の層を加え、何を作るかを先に書き出し、計画を確認してからコードを書くようにします。要件がチャット履歴にしか残らない状態を避けられます。MIT ライセンスのオープンソースで、30 を超える AI コーディングツールに対応しており、HagiCode 自身のワークフローもこれを基盤にしています。このページは、インストールから最初の一連の変更までの最短ルートです。詳しいガイドは専用サイトで管理しています。

基本概念

OpenSpec は 5 つの考え方でできています。

仕様(specs)が信頼できる唯一の情報源です。 システムが現在どう動くかを記述し、openspec/specs/ にドメイン別に整理され、要件とシナリオで構成されます。
変更(change)は 1 つの作業単位です。 振る舞いを追加、変更、削除するときは openspec/changes/ 配下にフォルダーを作り、その作業の提案、設計、タスク一覧、仕様の修正をまとめます。
差分仕様(delta specs)は変わる部分だけを記述します。 変更の中で仕様全体を書き直さず、ADDED、MODIFIED、REMOVED を書きます。既存システムの修正に強いのはこのためです。
成果物は互いにつながります。 proposal(なぜ)→ specs(何を)→ design(どうやって)→ tasks(手順)→ 実装。これらは関門ではなく補助であり、いつでも戻って直せます。
アーカイブで変更が情報源に戻ります。 作業が終わると差分仕様がメインの仕様に統合され、変更フォルダーは日付付きで changes/archive/ に移動します。

インストール

Node.js 20.19.0 以上が必要です(HagiCode のほかのコンポーネントは 24 以上を推奨しています。Node.js のインストールを参照してください)。

npm install -g @fission-ai/openspec@latest
openspec --version

macOS と Linux では Homebrew も使えます:brew install openspec。pnpm、yarn(1.x)、bun でもグローバルインストールできますが、OpenSpec の実行環境は引き続き Node.js です。

次にプロジェクトのディレクトリへ移動して初期化します。

cd your-project
openspec init

初期化では、使用する AI ツールを尋ねられ、そのツール用のスキルまたはコマンドのファイルが生成されます。質問を省略するには openspec init --tools claude,cursor を使います。ツール ID の一覧は対応ツールにあります。

最初の一連の変更

スラッシュコマンドはターミナルではなく AI アシスタントのチャットに入力します。

/opsx:explore            # まだ固まっていない?AI にコードを読ませて選択肢を検討させる
/opsx:propose add-dark-mode   # 変更フォルダーを作成:proposal、specs、design、tasks
/opsx:apply              # タスク一覧に沿って実装
/opsx:archive            # アーカイブ。差分仕様がメインの仕様に統合される

/opsx:propose は proposal.md、specs/、design.md、tasks.md を含む openspec/changes/add-dark-mode/ を作成します。仕様は特別な構文のない普通の Markdown です。

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

これらは AI が書き、あなたはコードが書かれる前に計画を確認します。デフォルトのプロファイルには propose、explore、apply、update、sync、archive が含まれます。拡張フロー(new、continue、ff、verify、bulk-archive など)は openspec config profile で選択し、openspec update で適用します。

コマンド名はアシスタントによって少し異なります

/opsx:propose が標準の表記です。Cursor と GitHub Copilot では /opsx-propose、Amazon Q では @opsx-propose、Codex では $openspec-propose です。openspec init は選んだツールに合った表記を表示します。

アップグレード

npm install -g @fission-ai/openspec@latest   # パッケージをアップグレード
openspec update                              # 各プロジェクトの AI 指示ファイルを更新

Homebrew でインストールした場合は brew upgrade openspec を使います。

よくある問題

openspec: command not found:npm のグローバルディレクトリが PATH に入っていません。npm prefix -g を実行し、macOS と Linux ではそのディレクトリの bin/ を、Windows ではそのディレクトリ自体を PATH に追加してください。
「Requires Node.js 20.19.0 or higher」:node --version で確認し、アップグレードしてください。
チャットに /opsx:propose が表示されない:ターミナルではなくアシスタントに入力しているか確認し、openspec update でファイルを再生成してからアシスタントを再起動してください。Codex のようにスキルのみの対応ツールでは $openspec-propose の形式を使います。
初期化でお使いのツールが設定されなかった:openspec init をもう一度実行するか、--tools を指定してください。