コア概念の概要

OpenSpec は、あなたと AI の間で合意を形成するための軽量なレイヤーです。 変更で実現したいことを書き出し、AI が詳細を下書きし、双方で同じ計画を確認してから、初めてコードを書きます。このページでは、全体の考え方を一画面で説明します。詳しくは概念を参照してください。

考え方をひとことで表すと、まず合意し、自信を持って構築するです。

5つの考え方

OpenSpec は5つの概念を基礎にしています。これらを理解すれば、あとは詳細です。

1. 仕様が真実を表す。 仕様は、システムが 現在どのように動作するか を記述します。openspec/specs/ に置かれ、ドメイン（auth/、payments/、ui/ など）ごとに整理されます。仕様は要件（「システムは30分後にセッションを期限切れにしなければならない」など）とシナリオ（具体的な Given/When/Then の例）で構成されます。「このソフトウェアは何をするのか」に対する、合意済みの唯一の答えだと考えてください。

2. 変更はひとまとまりの作業。 動作を追加、変更、削除したいときは change を作成します。openspec/changes/ 内のフォルダーに、その作業に関するすべてをまとめます。提案、設計、タスクリスト、仕様の変更を一か所に置きます。1つの変更、1つのフォルダー、1つの機能です。

3. 差分仕様は、システム全体ではなく変更点を記述する。 change の中で仕様全体を書き直す必要はありません。ADDED（追加）、MODIFIED（変更）、REMOVED（削除）で小さな差分を記述します。これにより OpenSpec は、新規開発だけでなく既存システムの変更にも適しています。最終形ではなく差分を記述します。

4. 成果物は順につながる。 change には複数のドキュメントが含まれ、自然な順序で作成され、それぞれが次の成果物の材料になります。

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

どの成果物もいつでも見直せます。これらは次へ進むための助けであり、進行を妨げる関門ではありません（詳しくは後述します）。

5. アーカイブによって変更が真実に反映される。 作業が終わったら change をアーカイブします。差分仕様がメインの仕様にマージされ、change フォルダーは日付を付けて changes/archive/ に移動します。仕様が新しい状態を表すようになり、次の変更に取りかかれます。これでサイクルが完了します。

全体像

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ 真実の情報源     │ で     │ 変更ごとに1フォルダー   │    │
│   │ 現在の動作       │アーカイブ│ 提案・設計・タスク・    │    │
│   │                  │  時に統合│ 差分仕様               │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

フォルダーは2つです。specs/ は現在の真実、changes/ は提案中の内容です。アーカイブすると、提案が真実に反映されます。

実際に使うワークフロー

既定の設定では、次のように進めます。必要なら先に考えを整理し、コマンドで計画を下書きします。計画を確認してから次のコマンドで実装し、最後にアーカイブします。

/opsx:explore                   →  (任意) 先に AI と考えを整理
/opsx:propose add-dark-mode     →  AI が提案、仕様、設計、タスクを下書き
        (計画を読んで調整)
/opsx:apply                     →  AI が実装し、完了タスクにチェック
/opsx:archive                   →  仕様を更新し、change をアーカイブ

迷ったら、まず explore から始めましょう。 /opsx:explore はリスクなしで相談できる相手です。コードを読み、選択肢を整理し、コードを書く前に曖昧なアイデアを具体的な計画にします。曖昧な指示から AI が何かを作ってしまうのを防ぐのに最適です。作りたいものが明確なら、すぐに /opsx:propose を実行してください。explore は既定のプロファイルに含まれるため、いつでも使えます。Explore ガイドを参照してください。

これらは AI アシスタントのチャットで入力するスラッシュコマンドです。セットアップ（openspec init）はターミナルで行います。この違いに馴染みがなければ、よくある混乱の原因なので、まずコマンドの実行方法を読んでください。

「助けであり、関門ではない」

OpenSpec ではこの表現がよく使われます。ここでは平易な言葉で説明します。

従来の仕様策定プロセスはウォーターフォール型です。計画を終えて から 実装に進み、前の段階に戻るのは困難です。OpenSpec はその考え方を採りません。proposal → specs → design → tasks という順序は、次に 可能になること を示すものであり、次に 必ず行うこと を強制するものではありません。

実装中に設計の誤りに気付いたら、design.md を編集して続けます。範囲を縮小すべきだと分かったら、提案を更新します。何も固定されません。依存関係は、AI が必要な文脈を得られるようにするためだけのものです（仕様を基にしなければ適切なタスクを書けません）。あなたを縛るためではありません。

この仕組みの利点は、実際の作業が複雑で反復的であることを正直に認め、それを許容する点です。一方で規律も必要です。先へ進むことを強制されないため、change が肥大化しないよう、範囲を保つのはあなたの役割です。ワークフローガイドでは、そのためのよい習慣を紹介しています。

少しの手間をかける価値

率直に言えば、OpenSpec では手順が1つ増えます。実装前に短い計画を書く必要があります。その対価として得られるものは何でしょうか。

• 手戻りが大きくなる前に誤りを見つけられます。 1段落の提案にある誤解なら、無料で直せます。AI が400行のコードを書いた後ではそうはいきません。
• 計画とコードを同じリポジトリに保管できます。 6か月後も仕様を見れば、システムがそのように動く理由を（次の AI セッションも）理解できます。
• 変更をレビューできます。 change フォルダーには提案、差分、タスクが整理されています。チャット履歴を掘り起こす必要はありません。
• 既存のコードベースにも適用できます。 差分を使えば、5万行のアプリ全体を先に文書化せずに変更を仕様化できます。

正直なところ、本当に些細な1行修正では、この手順に見合う効果がない場合もあります。それで問題ありません。OpenSpec は軽量に設計されていますが、手間がゼロではありません。曖昧な指示でも自信満々に実装する AI と作業すると、合意が重要な場面はたいていの作業に当てはまると分かるでしょう。

次に読むページ

• 初めての方は、はじめにで最初の変更を一通り体験できます。
• まだ何を作るか決まっていないなら、まず Exploreから始めてください。
• コマンドの実行場所が分からない場合は、コマンドの実行方法を参照してください。
• 上記の内容を詳しく知りたい場合は、概念を読んでください。
• 例から学ぶには、例とレシピを参照してください。
• 用語の定義は用語集にあります。