概念

このガイドでは、OpenSpec の基本概念と、それらがどのように関係するかを説明します。実践的な使い方ははじめにとワークフローを参照してください。

基本理念

OpenSpec は4つの原則を基礎としています。

柔軟であり、硬直しない         — フェーズの関門を設けず、妥当な作業を進める
反復的であり、ウォーターフォールではない — 構築しながら学び、進めながら洗練する
簡単であり、複雑ではない       — 軽量なセットアップと最小限の手続き
既存システムを重視             — 新規開発だけでなく、既存コードベースにも対応

これらの原則が重要な理由

柔軟であり、硬直しない。 従来の仕様システムでは、まず計画し、次に実装し、最後に完了するというフェーズに固定されます。OpenSpec はより柔軟で、作業に合った任意の順序で成果物を作成できます。

反復的であり、ウォーターフォールではない。 要件は変化し、理解は深まります。最初はよいと思えた方法も、コードベースを確認した後では適切でないかもしれません。OpenSpec はこの現実を受け入れます。

簡単であり、複雑ではない。 仕様フレームワークの中には、広範なセットアップ、厳格な形式、重いプロセスを必要とするものがあります。OpenSpec は作業を妨げません。数秒で初期化してすぐに始められ、必要な場合だけカスタマイズできます。

既存システムを重視。 ソフトウェア開発の多くはゼロからの構築ではなく、既存システムの変更です。OpenSpec の差分ベースの方法では、新しいシステムの説明だけでなく、既存の動作に対する変更も簡単に仕様化できます。

全体像

OpenSpec では作業を2つの主要領域に整理します。

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  Source of truth    │◄─────│  Proposed modifications       │   │
│   │  How your system    │ merge│  Each change = one folder     │   │
│   │  currently works    │      │  Contains artifacts + deltas  │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

仕様は真実の情報源であり、現在のシステムの動作を記述します。

変更は提案中の修正であり、マージする準備ができるまで別々のフォルダーに保存されます。

この分離が重要です。複数の変更を競合せずに並行して進められます。メインの仕様に影響する前に変更をレビューできます。変更をアーカイブすると、その差分が真実の情報源に整然とマージされます。

仕様

仕様では、構造化された要件とシナリオを使ってシステムの動作を記述します。

構成

openspec/specs/
├── auth/
│   └── spec.md           # 認証の動作
├── payments/
│   └── spec.md           # 決済処理
├── notifications/
│   └── spec.md           # 通知システム
└── ui/
    └── spec.md           # UI の動作とテーマ

仕様はシステムにとって意味のある論理的なまとまりであるドメインごとに整理します。一般的なパターンは次のとおりです。

機能領域ごと: auth/、payments/、search/
コンポーネントごと: api/、frontend/、workers/
境界づけられたコンテキストごと: ordering/、fulfillment/、inventory/

仕様の形式

仕様には要件が含まれ、各要件にはシナリオがあります。

# 認証の仕様

## Purpose
アプリケーションの認証とセッション管理。

## Requirements

### Requirement: ユーザー認証
システムはログインの成功時に JWT トークンを発行しなければならない。

#### Scenario: 有効な認証情報
- GIVEN 有効な認証情報を持つユーザーがいる
- WHEN ユーザーがログインフォームを送信する
- THEN JWT トークンが返される
- AND ユーザーはダッシュボードにリダイレクトされる

#### Scenario: 無効な認証情報
- GIVEN 無効な認証情報がある
- WHEN ユーザーがログインフォームを送信する
- THEN エラーメッセージが表示される
- AND トークンは発行されない

### Requirement: セッションの期限切れ
システムは、30分間操作がない場合にセッションを期限切れにしなければならない。

#### Scenario: アイドルタイムアウト
- GIVEN 認証済みセッションがある
- WHEN 操作せずに30分が経過する
- THEN セッションが無効になる
- AND ユーザーは再認証しなければならない

主な要素:

要素	目的
`## Purpose`	仕様のドメインを大まかに説明
`### Requirement:`	システムが備えるべき具体的な動作
`#### Scenario:`	要件の動作を示す具体例
SHALL/MUST/SHOULD	要件の強さを示す RFC 2119 キーワード

このように仕様を構成する理由

要件は「何をするか」 を示します。実装方法を指定せずに、システムが何をすべきかを記述します。

シナリオは「どのような場合に」 を示します。検証可能な具体例を提供します。良いシナリオは次のようなものです。

テスト可能（自動テストを作成できる）
正常系と境界ケースの両方をカバーする
Given/When/Then または同様の構造化形式を使う

RFC 2119 キーワード（SHALL、MUST、SHOULD、MAY）は意図を伝えます。

MUST/SHALL — 絶対的な要件
SHOULD — 推奨されるが、例外を認める
MAY — 任意

仕様に含めるもの・含めないもの

仕様は 動作に関する契約 であり、実装計画ではありません。

仕様に含める内容:

ユーザーや下流システムが依存する、観測可能な動作
入力、出力、エラー条件
外部制約（セキュリティ、プライバシー、信頼性、互換性）
テストまたは明示的な検証が可能なシナリオ

仕様に含めない内容:

内部のクラス名や関数名
ライブラリやフレームワークの選択
実装の詳細な手順
詳細な作業計画（design.md または tasks.md に記述）

簡単な判断基準:

外部から見える動作を変えずに実装を変更できるなら、おそらく仕様に含める内容ではありません。

軽量さを保つ: 段階的な厳密さ

OpenSpec は官僚的な手続きを避けることを目指しています。変更を検証できる範囲で、最も軽いレベルを使ってください。

Lite 仕様（既定）:

動作を中心にした短い要件
明確な範囲と対象外事項
いくつかの具体的な受け入れ確認

Full 仕様（高リスク向け）:

チームやリポジトリをまたぐ変更
API/契約の変更、移行、セキュリティ/プライバシー上の懸念
曖昧さが高コストの手戻りにつながる可能性がある変更

ほとんどの変更は Lite モードで十分です。

人間とエージェントの協働

多くのチームでは、人間が検討し、エージェントが成果物を下書きします。想定される流れは次のとおりです。

人間が目的、コンテキスト、制約を提供する。
エージェントがそれを動作中心の要件とシナリオに変換する。
エージェントは実装の詳細を spec.md ではなく design.md と tasks.md に記述する。
実装前に検証し、構成と明確さを確認する。

これによって仕様が人間にとって読みやすく、エージェントにとって一貫したものになります。

変更

change は、システムに対する変更案をフォルダーにまとめたものです。理解と実装に必要な内容がすべて含まれます。

change の構成

openspec/changes/add-dark-mode/
├── proposal.md           # 理由と内容
├── design.md             # 方法（技術的な方針）
├── tasks.md              # 実装チェックリスト
├── .openspec.yaml        # change のメタデータ（任意）: schema、created、skip_specs、retire_capabilities
└── specs/                # Delta specs
    └── ui/
        └── spec.md       # ui/spec.md の変更内容

各 change は自己完結しており、次のものを含みます。

成果物 — 目的、設計、タスクを記録するドキュメント
差分仕様 — 追加、変更、削除する内容の仕様
メタデータ — この change 固有の任意の設定

change をフォルダーにする理由

変更をフォルダーにまとめることには、次の利点があります。

すべてを一か所に。 提案、設計、タスク、仕様を1つの場所に保存するため、あちこち探す必要がありません。
並行作業。 複数の change を競合せずに同時に進められます。fix-auth-bug の作業中に add-dark-mode に取り組めます。
明確な履歴。 アーカイブすると、変更はすべての文脈を保ったまま changes/archive/ に移動します。後から何が変わったかだけでなく、その理由も確認できます。
レビューしやすい。 change フォルダーを開いて提案を読み、設計を確認し、仕様の差分を見るだけです。

成果物

成果物は、change 内で作業を導くドキュメントです。

成果物の流れ

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   理由            内容           方法          手順
 + 範囲        変更内容       アプローチ     やること

成果物は互いに積み重なります。それぞれの成果物が次のものにコンテキストを与えます。

成果物の種類

提案（`proposal.md`）

提案では、目的、範囲、方針を大まかに記録します。

# 提案: ダークモードの追加

## Intent
夜間利用時の目の負担を軽減し、システム設定に合わせるため、
ユーザーからダークモードの追加が求められています。

## Scope
対象:
- 設定画面のテーマ切り替え
- システム設定の検出
- localStorage への設定保存

対象外:
- カスタムカラーテーマ（今後の作業）
- ページごとのテーマ上書き

## 方針
テーマには CSS カスタムプロパティを使い、状態管理には React context を使います。
初回読み込み時にシステム設定を検出し、手動での上書きも可能にします。

提案を更新するタイミング:

範囲が変わった（縮小または拡大した）
目的が明確になった（問題をより深く理解できた）
方針が根本的に変わった

仕様（`specs/` 以下の差分仕様）

差分仕様は、現在の仕様に対して 何が変わるか を記述します。下記の差分仕様を参照してください。

設計（`design.md`）

設計では、技術的な方針 と アーキテクチャ上の判断 を記録します。

# 設計: ダークモードの追加

## Technical Approach
prop drilling を避けるため、テーマの状態は React Context で管理します。
CSS カスタムプロパティを使えば、クラスを切り替えずに実行時にテーマを変更できます。

## Architecture Decisions

### 判断: Redux ではなく Context
次の理由から、テーマの状態管理に React Context を使います。
- 単純な2値状態（ライト/ダーク）
- 複雑な状態遷移がない
- Redux 依存関係を追加せずに済む

### 判断: CSS カスタムプロパティ
CSS-in-JS ではなく CSS 変数を使う理由:
- 既存のスタイルシートで使える
- 実行時のオーバーヘッドがない
- ブラウザー標準の仕組みである

## Data Flow
```
ThemeProvider（context）
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS 変数（:root に適用）
```

## ファイルの変更
- `src/contexts/ThemeContext.tsx`（新規）
- `src/components/ThemeToggle.tsx`（新規）
- `src/styles/globals.css`（変更）

設計を更新するタイミング:

実装により方針がうまくいかないと分かった
より良い解決策が見つかった
依存関係や制約が変わった

タスク（`tasks.md`）

タスクは 実装チェックリスト であり、チェックボックス付きの具体的な手順です。

# タスク

## 1. テーマの基盤
- [ ] 1.1 ライト/ダーク状態を持つ ThemeContext を作成する
- [ ] 1.2 色の CSS カスタムプロパティを追加する
- [ ] 1.3 localStorage への保存を実装する
- [ ] 1.4 システム設定の検出を追加する

## 2. UI コンポーネント
- [ ] 2.1 ThemeToggle コンポーネントを作成する
- [ ] 2.2 設定ページに切り替えを追加する
- [ ] 2.3 簡易切り替えを含めるよう Header を更新する

## 3. スタイル
- [ ] 3.1 ダークテーマのカラーパレットを定義する
- [ ] 3.2 CSS 変数を使うようコンポーネントを更新する
- [ ] 3.3 アクセシビリティのコントラスト比をテストする

タスク作成のベストプラクティス:

関連するタスクを見出しの下にまとめる
階層的な番号（1.1、1.2 など）を使う
1回のセッションで完了できる大きさにする
各タスクの検証方法（テスト、コマンド、または観測可能な結果）を記載する
各グループに必要なテストとドキュメントは、そのグループに含める。最後にまとめて対応するグループを作らない
完了したタスクにチェックを付ける

差分仕様

差分仕様は、OpenSpec が既存システムの開発で機能するための重要な概念です。仕様全体を書き直すのではなく、何が変わるか を記述します。

形式

# Auth の差分

## ADDED Requirements

### Requirement: 二要素認証
システムは TOTP ベースの二要素認証に対応しなければならない。

#### Scenario: 2FA の登録
- GIVEN 2FA を有効にしていないユーザーがいる
- WHEN ユーザーが設定で 2FA を有効にする
- THEN 認証アプリのセットアップ用 QR コードが表示される
- AND 有効化前にコードによる確認が必要となる

#### Scenario: 2FA でログイン
- GIVEN 2FA が有効なユーザーがいる
- WHEN ユーザーが有効な認証情報を送信する
- THEN OTP チャレンジが表示される
- AND 有効な OTP の入力後にのみログインが完了する

## MODIFIED Requirements

### Requirement: セッションの期限切れ
システムは、15分間操作がない場合にセッションを期限切れにしなければならない。
(変更前: 30分)

#### Scenario: アイドルタイムアウト
- GIVEN 認証済みのセッションがある
- WHEN 操作せずに15分が経過する
- THEN セッションが無効になる

## REMOVED Requirements

### Requirement: ログイン状態を保持
(2FA に移行するため非推奨。ユーザーはセッションごとに再認証する。)

差分の節

節	意味	アーカイブ時の処理
`## ADDED Requirements`	新しい動作	メイン仕様に追加
`## MODIFIED Requirements`	変更された動作	既存要件を置き換える
`## REMOVED Requirements`	廃止する動作	メイン仕様から削除。最後の要件を削除すると機能が廃止され、その change に `retire_capabilities: true` が指定されている場合は仕様ファイルも削除される
`## Purpose`	新しい機能の目的	作成するメイン仕様の Purpose に設定。仕様がすでにある場合は無視

仕様全体ではなく差分を使う理由

明確さ。 差分には変更点が正確に示されます。仕様全体を読む場合、現在のバージョンと頭の中で比較する必要があります。

競合の回避。 異なる要件を変更する限り、2つの change が同じ仕様ファイルを扱っても競合しません。

効率的なレビュー。 レビュアーは変更箇所を確認し、変更されていない文脈を読み込まずに済みます。重要な点に集中できます。

既存システムとの相性。 作業のほとんどは既存の動作を変更することです。差分によって、変更を後付けではなく中心的に扱えます。

スキーマ

スキーマでは、ワークフローの成果物の種類と依存関係を定義します。

スキーマの仕組み

name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # 依存関係なし。最初に作成可能

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # 作成前に proposal が必要

  - id: design
    generates: design.md
    requires: [proposal]      # specs と並行して作成可能

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # specs と design の両方が先に必要

成果物は依存関係グラフを形成します。

                    proposal
                   (ルートノード)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (必要:                       (必要:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (必要:
                specs, design)

依存関係は、助けであり関門ではありません。 次に必ず作る成果物ではなく、作成可能なものを示します。不要なら design を省略できます。specs と design はどちらも proposal のみに依存するため、どちらを先に作成してもかまいません。

組み込みスキーマ

spec-driven (default)

仕様駆動開発の標準ワークフローです。

proposal → specs → design → tasks → implement

最適な用途: 実装前に仕様について合意したい、ほとんどの機能開発。

カスタムスキーマ

チームのワークフローに合わせてカスタムスキーマを作成します。

# 新規作成
openspec schema init research-first

# 既存スキーマをフォーク
openspec schema fork spec-driven research-first

カスタムスキーマの例:

name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # 先に調査する

  - id: proposal
    generates: proposal.md
    requires: [research]   # 調査結果を踏まえて提案

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # specs/design を省略し、tasks に進む

カスタムスキーマの作成と使用の詳細は、カスタマイズを参照してください。

アーカイブ

アーカイブでは、差分仕様をメイン仕様にマージして change を完了し、履歴として保存します。

アーカイブ時の処理

アーカイブ前:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ merge
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


アーカイブ後:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # 2FA 要件を含む
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # 履歴として保存
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

アーカイブの手順

差分をマージする。 差分仕様の各節（ADDED/MODIFIED/REMOVED）を対応するメイン仕様に適用します。
アーカイブに移動する。 change フォルダーは、時系列に並べるための日付プレフィックスを付けて changes/archive/ に移動します。
コンテキストを保持する。 すべての成果物がアーカイブにそのまま残ります。後から変更の理由をいつでも確認できます。

アーカイブが重要な理由

整理された状態。 作業中の change（changes/）には進行中の作業のみが表示されます。完了した作業は別の場所に移動します。

監査証跡。 アーカイブでは各 change のすべての文脈が保持されます。変更内容だけでなく、理由を説明する提案、方法を説明する設計、実施した作業を示すタスクも残ります。

仕様の進化。 change のアーカイブに伴って仕様が自然に充実します。アーカイブごとに差分がマージされ、時間をかけて包括的な仕様が形成されます。

全体のつながり

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC の流れ                                  │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. change を  │  /opsx:propose (core) または /opsx:new (expanded)       │
│   │     開始       │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. 成果物を   │  /opsx:ff または /opsx:continue (expanded workflow)    │
│   │     作成       │  proposal → specs → design → tasks を作成               │
│   │                │  (スキーマの依存関係に基づく)                           │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. タスクを   │  /opsx:apply                                            │
│   │     実装       │  タスクを進め、完了したらチェック                        │
│   │                │◄──── 学びに合わせて成果物を更新                          │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. 作業を     │  /opsx:verify (任意)                                    │
│   │     検証       │  実装が仕様に一致するか確認                              │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. change を  │────►│  差分仕様をメイン仕様にマージ                 │    │
│   │     アーカイブ │     │  change フォルダーを archive/ に移動           │    │
│   └────────────────┘     │  仕様が更新後の真実の情報源になる             │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

好循環:

仕様が現在の動作を記述する
change が差分として修正を提案する
実装によって変更が実現する
アーカイブが差分を仕様にマージする
仕様が新しい動作を記述する
次の change が更新済みの仕様を基礎にする

用語集

用語	定義
Artifact（成果物）	change 内のドキュメント（提案、設計、タスク、差分仕様など）
Archive（アーカイブ）	change を完了し、その差分をメイン仕様にマージするプロセス
Change（変更）	成果物とともにフォルダーにまとめられた、システムへの変更案
Delta spec（差分仕様）	現在の仕様に対する変更（ADDED/MODIFIED/REMOVED）を記述した仕様
Domain（ドメイン）	仕様を論理的にまとめたもの（例: `auth/`、`payments/`）
Requirement（要件）	システムが備えるべき具体的な動作
Scenario（シナリオ）	要件の具体例。通常は Given/When/Then 形式で記述
Schema（スキーマ）	成果物の種類とその依存関係の定義
Spec（仕様）	要件とシナリオを含み、システムの動作を記述する仕様書
Source of truth（真実の情報源）	現在の合意済みの動作を含む `openspec/specs/` ディレクトリ

次の手順

はじめに — 実践的な最初の手順
ワークフロー — よくあるパターンとその使い分け
コマンド — コマンドの完全なリファレンス
カスタマイズ — カスタムスキーマの作成とプロジェクトの設定

HagiCode

HagiCode は構造化ワークフロー、マルチエージェント実行、Hero Dungeon ビューを備えたエージェント型コーディングワークスペースです。

よりスマートで速く、楽しいエージェント型ワークフローで、使いやすいソフトウェアを形にします。

Smart構造化ワークフローは意図をアイデアから変更のリリースまで実行可能な道筋にします。
Efficientマルチエージェントのワークフローで調査、実装、レビューを並行して進めます。
FunHero Dungeon により長時間のコーディングを視覚的で協力的な体験にします。

HagiCode を見る