核となる概念の概要
OpenSpecは、あなたとAIとの間の軽量な合意レイヤーです。あなたは変更が何をすべきかを記述し、AIが詳細をドラフトします。その後、両者が同じ計画を確認してから、初めてコードが書かれます。このページがそのメンタルモデル全体を一枚の画面にまとめたものです。長文が必要な場合は、Conceptsを参照してください。
このアイデア全体を五つの言葉で表現すると、「先に合意し、自信を持って構築する」です。
5つの考え方
OpenSpecのすべては、これら5つの概念から成り立っています。これらを学ぶことで、残りは詳細となります。
1. Specsが真実であること。 Specは、あなたのシステムが現時点でどのように振る舞うかを記述します。それはopenspec/specs/に存在し、ドメイン（auth/、payments/、ui/など）ごとに整理されています。Specは要件（「システムは30分後にセッションを期限切れにするべきである」）とシナリオ（具体的なGiven/When/Thenの例）で構成されます。Specを、「このソフトウェアは何をするのか？」という問いに対する唯一合意された答えとして考えてください。
2. 変更は一つの作業単位であること。 行動を追加、修正、または削除したい場合、あなたは「変更」を作成します。これはopenspec/changes/内にあるフォルダであり、その作業に関するすべてを一つの場所にまとめています。提案、設計、タスクリスト、そしてSpecの編集が含まれます。変更一つ、フォルダ一つ、機能一つです。
3. Delta specsは世界全体ではなく、何が変化しているかを記述すること。 変更の中では、Spec全体を書き直す必要はありません。小さなデルタ（delta）を記述します。「この要件を追加したADDED」、「あの要件を修正したMODIFIED」、「これを取り除いたREMOVED」。これがOpenSpecがグリーンフィールドなものだけでなく、既存のシステムのエディットに優れている理由です。目的地ではなく、差分（diff）を記述するのです。
4. アーティファクトは互いに積み重ねられること。 変更にはいくつかのドキュメントが含まれ、それらは自然な順序で作成され、それぞれが次のものにフィードバックされます。
text
proposal ──► specs ──► design ──► tasks ──► implement
why what how steps do itいつでもこれらのいずれかを見返すことができます。これらはゲート（門番）ではなくイネーブラー（実現手段）です。（詳細は後述します。）
5. アーカイブは変更を真実の中に戻すこと。 作業が完了したら、その変更をアーカイブします。そのデルタSpecはメインのSpecにマージされ、変更フォルダは日付スタンプ付きでchanges/archive/に移動します。これであなたのSpecは新しい現実を記述し、次の変更の準備が整います。サイクルが閉じます。
構造図
text
┌─────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ ◄───── │ │ │
│ │ source of truth │ merge │ one folder per change │ │
│ │ how things work │ on │ proposal · design · │ │
│ │ today │ archive │ tasks · delta specs │ │
│ └──────────────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘2つのフォルダ。specs/が真実です。changes/が提案中のものです。アーカイブは提案を真実に移行させる行為です。
実際に実行するループ
デフォルトのセットアップでは、あなたの1日は次のようになります。オプションとして事前に考えてみても構いません。その後、一つのコマンドで計画がドラフトされ、それを読み込み調整し、次で構築し、最後でファイルを保管します。
text
/opsx:explore → (オプション) AIと共感的に考える
/opsx:propose add-dark-mode → AIが提案、Spec、設計、タスクをドラフト
(あなたは計画を読み、調整する)
/opsx:apply → AIが構築し、タスクをチェックオフ
/opsx:archive → Specを更新し、変更をアーカイブ迷ったら、まず探索から始めましょう。 /opsx:exploreはリスクのない思考パートナーです。コードを読み込み、選択肢を提示し、いかなるアーティファクトが存在する前でも曖昧なアイデアを具体的な計画に変換します。これは、AIが漠然としたプロンプトから何かを構築してしまうことに対する最良の解毒剤です。すでに何を望んでいるか正確に分かっていますか？/opsx:proposeに直接進んでください。いずれの場合も、探索はデフォルトのプロフィールに含まれているため、常に利用可能です。Explore guideを参照してください。
これらはAIアシスタントのチャットに入力するスラッシュコマンドです。セットアップ（openspec init）はターミナルで行います。この分割が初めての場合は、How Commands Workを先に読むことをお勧めします。これが最も混乱が生じやすい点だからです。
「ゲートではなくイネーブラー」
このフレーズはOpenSpecの至る所に登場するため、平易な言葉で何を意味するか説明します。
従来のSpecプロセスはウォーターフォール（滝）のようなものです。計画を完了し、それから初めて実装が許可され、後戻りは苦痛を伴います。OpenSpecはそれを拒否します。「proposal → specs → design → tasks」という順序は、次に強制されることではなく、次になにが可能になるかを示しています。
設計が間違っていたことに実装中に気づきましたか？design.mdを編集し、続行してください。スコープを縮めるべきだと悟りましたか？提案を更新してください。何もロックされていません。依存関係は、AIが必要なコンテキスト（ベースとなるSpecなしに良いタスクを書くことはできない）を持っているためだけに存在し、あなたを箱の中に閉じ込めるためではありません。
ここでの強みは正直さです。実際の作業は雑然として反復的であり、OpenSpecはその状態を受け入れます。トレードオフは規律です。何もかもがあなたを強制しないため、変更が拡散するのではなく、集中力を保つのはあなたの責任となります。Workflowsガイドにはそのための良い習慣が記載されています。
なぜこの小さなオーバーヘッドの価値があるのか
率直に言って、OpenSpecは一つのステップを追加します。構築する前に短い計画を書くのです。では、それに対して何を得るのでしょうか？
- 問題がコストになる前に、誤った方向に進むのを防ぎます。 1パラグラフの提案での誤解を修正するのは無料です。AIが400行書いた後にそれを修正するのは違います。
- 計画とコードは同じリポジトリ内に保たれます。 半年後でも、そのSpecがシステムがなぜそのように機能するのか（そして次のAIセッションに）教えてくれます。
- 変更はレビュー可能です。 変更フォルダは整然としたパッケージです。提案を読み、デルタをざっと確認し、タスクを確認します。チャット履歴からの考古学的な発掘りは不要です。
- 既存のコードベースに適合します。 デルタのおかげで、すべてを文書化する前に5万行あるアプリへの変更を指定できます。
そして正直なトレードオフについて：本当に些細な1行の修正に対しては、この儀式（ceremony）が報われない可能性があり、それは問題ありません。OpenSpecは軽量であるように設計されていますが、無料ではありません。合意が重要となる箇所でそれを使用してください。AIに曖昧に尋ねたものを自信を持って構築させる場合、それがほとんどの場合に該当します。
次に進むべき場所
- 初めての方ですか？Getting Startedでは最初の変更を完全に解説しています。
- 何を作るべきかまだ決まっていませんか？Explore Firstから始めるのが良いでしょう。
- コマンドがどこで実行されるのか混乱していますか？How Commands Work。
- 上記のすべてについて深いバージョンが必要ですか？Concepts。
- 例を通じて学びたいですか？Examples & Recipes。
- 用語を定義する必要がありますか？Glossary。