🤖

OpenSpecの導入と開発サイクルの回し方に関して

に公開
AI
Cursor
Codex
spec駆動開発
openspec
tech

はじめに

普段使っているIDEやCLIにspec駆動開発を気軽に導入するためのツールが欲しいと思っていたところ、OpenSpecが良いという話を聞いたので導入して使ってみました。
ブラウンフィールドが得意ということもあって、既存のコードベースに対して改修を加えるというユースケースで簡単にspec駆動で開発する体験が味わえてとても良かったです。
以降で備忘録としてOpenSpecについての概要と、インストールして実際に利用するまでの流れをサクッとまとめておきます。なるべくスパッと必要なところだけを書きます。

以下のリポジトリに書いてあることそのままではあるのですが、良ければご参考にしてください。
https://github.com/Fission-AI/OpenSpec

OpenSpecとは

OpenSpecは「仕様（Spec）ドリブンでAIコーディングアシスタントを動かす」ための軽量ワークフレーム。
初期設定によってリポジトリの内容を分析した後、以下のように仕様の提案、計画のすり合わせ、実行を行う開発サイクルを進めていきます。

  1. Draft Change Proposal — 変更提案の作成
  2. Review & Align — AIと仕様をすり合わせる
  3. Implement Tasks — 合意した仕様をもとに実装する
  4. Archive & Update Specs — 仕様を反映して正式化

これからの実装内容について示した未来のことが書かれたProposalから、実装後に結果どうなったのかをきちんと明文化するArchiveまでを実施することで、AIと人間の対話がmdファイルとして明示的に格納されます。
そのため、AIエージェントが実装を行う際や改修後に参照できる信頼できる情報源としてリポジトリにドキュメントをため込んでいけるのも利点ですね。

OpenSpec のインストールと初期化手順

公式のリポジトリに書かれているもののコピペです。
でもなんだかんだZennとか見ながら手を動かしたくなるの不思議ですよね

前提条件（Prerequisites）

Node.js 20.19.0 以上 が必要です。
バージョン確認コマンド：

node --version

ステップ1：OpenSpec CLI をグローバルにインストール

OpenSpec のコマンドラインツールをシステム全体にインストールします。

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

インストールが完了したら、以下でバージョンを確認できます：

openspec --version

これで CLI のセットアップは完了です。

ステップ2：プロジェクトに OpenSpec を初期化

次に、OpenSpec を使いたいプロジェクトのルートディレクトリへ移動します。

cd my-project

プロジェクト内で初期化を実行します：

openspec init

このコマンドを実行すると、プロジェクト内に openspec/ ディレクトリが作成され、
以下のような構成が自動生成されます：

openspec/
├── specs/ # 仕様ファイル（source of truth）
├── changes/ # 提案や変更内容の格納場所
└── AGENTS.md # AIアシスタント連携仕様

ステップ3：OpenSpecを活用して開発を進める

これで OpenSpec の準備が完了し、
openspec draft コマンドなどを使って提案フローを始めることができます。

Codex には OpenSpec と統合されたコマンドがいくつか用意されています。
これらは Codex を初回起動したときに自動的にインストールされ、
~/.codex/prompts 配下に保存されています。

コマンド 役割 CLI対応コマンド
/openspec-proposal 新しい変更提案（Change Proposal）を作成する /openspec proposal
/openspec-apply 提案を反映し、開発タスクに展開する /openspec-apply
/openspec-archive 完了した提案を正式仕様（specs）に統合する openspec archive

例えば以下のような使い方ですね

  1. 「/openspec-proposal このリポジトリの○○機能のパフォーマンスの改善を行いたい」みたいな感じで指示出し
  2. エージェントと対話して仕様をすり合わせる
  3. /openspec-applyを実行して、仕様を確定し実装に移る
  4. 実装後の内容を見ながら適宜修正依頼、素のAIエージェントでの開発と同じ
  5. 改修が完了後/openspec-archiveで改修内容を確定させ、実装時の内容をspecsとして記録する

Discussion