OpenSpec

クイックスタート ​

あなたの最初の変更。アイデアからアーカイブまで、新規プロジェクトでも既存プロジェクトでも。

始める前に、あなたのマシンにCLIがインストールされ（インストール）、プロジェクトでOpenSpecが初期化されている必要があります（プロジェクトのセットアップ）。

空のプロジェクトから始める ​

スタックや完全なアーキテクチャを決めずに開始できます。プロジェクトフォルダでOpenSpecを初期化し、エージェントに選択肢を検討してもらいましょう。AIチャットで:

text
タスクトラッカーをゼロから構築するのを手伝ってください。まだスタックを選んでいません。選択肢を比較しながら、最初に作る機能を決めたいです。

最初の変更に必要なものを決め、後のアーキテクチャの選択はオープンにしておきます。エージェントにその変更を提案してもらい、以下の手順に従ってください。プロジェクトが成長するにつれて、アーキテクチャを見直すこともできます。

ループの概観 ​

すべての変更は同じ5つのステップを通ります: エージェントとアイデアを煮詰め、計画をドラフトし、コードが存在する前にその計画を修正し、エージェントが計画に基づいて構築し、アーカイブによって出荷内容で仕様が更新されます。

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

以下のプロンプトはすべて、コードを依頼するのと同じAIチャットで送ります。例はツールを問わない平易な言葉で示しています。スキルを直接呼び出すこともできますが、その構文はツールにより異なります（対応ツール）。

ステップ1: 探索 ​

計画を依頼する前に、エージェントとアイデアをしっかり考えましょう。AIチャットで:

text
このアプリでレート制限をどのように動作させるべきか、一緒に検討してください。

探索は思考のモードです。エージェントはコードベースを調査し、重要な質問を投げかけ、選択肢をスケッチし、前提に挑戦します。コードを書くことは一切なく、決定事項を書き留めるように頼んだり、エージェントが提案してきたときに承諾しない限り、それ以外の出力はありません。結果はより明確なアイデアです。

問題に必要なだけここにとどまり、形が整ったら引き継ぎます:

text
今議論した変更を提案してください。

この一文で提案ステップが開始され、確定した内容がすべて引き継がれます。ステップ2の最初のプロンプトはスキップしてください。

ステップ2: 提案 ​

提案はアイデアをレビュー可能な計画に変えます。探索から来た場合は既に開始されています。変更が頭の中で明確な状態で最初から始める場合は、直接依頼します。AIチャットで:

text
レート制限を追加する変更を提案してください。

エージェントは必要なことを尋ね、次のような変更フォルダを作成します:

openspec/changes/add-rate-limiting/
├── proposal.md    理由と何を変えるか
├── specs/         テスト可能な要件として「完了」を定義
├── design.md      技術的な決定（変更が必要な場合のみ）
└── tasks.md       実装チェックリスト

コードはまだありません。提案は計画で止まります。

ステップ3: 計画のレビューと修正 ​

まだ何も構築されていない言葉の段階で計画を修正しましょう。以下の順で読んでください:

  • proposal.md: これは正しい問題を、適切なサイズで扱っているか？
  • specs/: 最も価値のある読み物です。これらの要件をもって完了と見なせますか？
  • tasks.md: タスクは仕様をカバーし、余計なものはないか？

修正するには、どちらの方法でも構いません:

  • 自分でファイルを編集します。成果物はプレーンなMarkdownであり、ファイル自体が計画です。
  • エージェントに何が間違っているか伝えます（「未認証のケースが仕様から抜けている」）。エージェントが成果物を修正します。

ステップ4: 適用 ​

適用は計画をコードに変えます。実装はクリーンなコンテキストウィンドウで行ったほうがうまくいくため、新しいチャットセッションを開始します。AIチャットで:

text
add-rate-limiting変更を適用してください。

エージェントは変更フォルダを読み込み、tasks.md に従って作業を進め、各タスクが完了するたびにチェックを入れます。

  • 中断されたり、コンテキストが不足した場合？ 新しいセッションを開き、再度適用を依頼します。最初の未チェックのタスクから再開します。
  • 計画が間違っていたことが判明した場合？ 成果物を修正して（ステップ3のいずれかの方法で）、適用を続けます。
  • 進捗は tasks.md のチェックボックスで管理されます。隠れた状態はありません。

ステップ5: アーカイブ ​

アーカイブは2つのことを行います: 変更の要件でメインの仕様を更新し、変更フォルダをアーカイブフォルダ（/openspec/changes/archive/*）に移動します。

tasks.md のすべてのチェックボックスがチェックされたら、AIチャットで:

text
add-rate-limiting変更をアーカイブしてください。

アーカイブが何をするかを追ってみましょう:

file-steps
## The finished change
> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## Requirements land in specs/
> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## The folder moves to archive/
> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs describe the system as built
> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Gitは別の関心事です。変更フォルダをコードと一緒にコミットするだけで、ワークフローの他の部分は何も変わりません。

アーカイブされた変更の保持または削除 ​

openspec/changes/archive/ には、完了した各変更の提案、設計、タスク、差分が保持されます。上記のアーカイブフローでは、差分はすでに openspec/specs/ を更新しています。

  • 変更フォルダ全体を保持する 場合、現在のチェックアウトに自己完結的な記録を残したいときにそうします。
  • アーカイブされた変更の specs/ フォルダを削除する 場合、仕様履歴をGitで管理する場合に削除します。先にアーカイブをコミットし、その後 openspec/changes/archive/<change>/specs/ を削除します。提案、設計、タスクはチェックアウトに残ります。openspec validate --archived はタスク完了をチェックするだけで、適用された差分は見ないので、引き続き動作します。
  • 変更フォルダ全体を削除する のは、その提案、設計、タスク履歴がチェックアウトに不要になった場合のみです。現在の仕様は変わりませんが、openspec validate --archived やチェックアウト内の検索にはその変更は含まれなくなります。

WARNING

削除されたファイルをGit履歴に残したい場合は、アーカイブのコミットをリポジトリ履歴に保持してください。アーカイブとクリーンアップのコミットを squash すると、その中間スナップショットが失われます。

OpenSpecはアーカイブされた変更を自動的に削除したり、保持期間の設定を提供したりしません。

さらに詳しく ​

  • 差分仕様: 差分仕様での振る舞い変更の記述方法。
  • プロファイル: コアセットを超えたオプションのワークフロー（アーカイブ前の検証、インクリメンタルな計画）。

詳細ガイド ​

まだ執筆されていません; 追加予定のガイド:

  • プロトタイプファースト: 仕様の前にコードを試作し、その試作から学んだことを提案に反映させる。
  • 反復的な構築: 大きな提案ではなく、一連の小さな変更の連続。
  • 実装済みの変更を修正する: 適用後に計画を再度動かす必要があるが、変更はまだマージもアーカイブもされていない場合。