0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code × OpenSpecで始める仕様駆動開発 ― proposal・specs・changesの意味と開発フロー

0
Last updated at Posted at 2026-09-29

はじめに

Claude Code のような AI コーディングエージェントに「いい感じに作って」と頼むと、確かにそれっぽいコードは出てきます。ただ、

  • 会話の途中で要件がブレて、どこまで合意したのか分からなくなる
  • セッションを跨ぐと前回の前提が失われる
  • 「なぜこの実装になったのか」が後から追えない

といった問題にぶつかりがちです。

これを解決するアプローチが 仕様駆動開発(Spec-Driven Development) で、その代表的なツールが OpenSpec です。本記事では、Claude Code と OpenSpec を組み合わせた開発フローを、proposal や changes といった用語の意味を中心に解説します。

本記事は OpenSpec v1.9.0 時点の内容です。OpenSpec は更新が速く、旧バージョン(/openspec:proposal 系のコマンドや AGENTS.md / project.md を使う構成)とは細部が異なります。

OpenSpec とは

OpenSpec は、人間と AI が「何を作るか」を先にファイルで合意してから実装するための軽量なフレームワークです。

ポイントは次の 2 つです。

  1. 仕様(specs)を Markdown でリポジトリに置く:チャット履歴ではなく、Git 管理されたファイルが「真実の情報源」になる
  2. 変更(changes)を仕様への差分として扱う:今の仕様と、これから加える変更を明確に分けて管理する

導入

npm install -g @fission-ai/openspec
cd your-project
openspec init --tools claude

openspec init を実行すると、次のファイルが生成されます。

your-project/
├── .claude/
│   ├── commands/opsx/        # スラッシュコマンド(/opsx:propose など)
│   │   ├── explore.md
│   │   ├── propose.md
│   │   ├── update.md
│   │   ├── apply.md
│   │   ├── sync.md
│   │   └── archive.md
│   └── skills/openspec-*/    # 各コマンドに対応する Skill
└── openspec/
    ├── config.yaml           # プロジェクト設定
    ├── specs/                # 現在の仕様(真実の情報源)
    └── changes/              # 進行中の変更
        └── archive/          # 完了した変更

Claude Code 側には /opsx:* というスラッシュコマンドと Skill がインストールされ、Claude が OpenSpec の CLI を叩きながらファイルを作っていく仕組みになっています。

用語とディレクトリの意味

OpenSpec で一番とっつきにくいのが用語です。ここを押さえると全体像が一気に分かります。

全体像

openspec/
├── config.yaml
├── specs/                          ← 「今、システムがどう振る舞うか」
│   └── user-auth/
│       └── spec.md
└── changes/                        ← 「これから、どう変えるか」
    ├── add-dark-mode/              ← 1つの変更 = 1フォルダ
    │   ├── .openspec.yaml
    │   ├── proposal.md             ← なぜ・何を
    │   ├── design.md               ← どうやって
    │   ├── tasks.md                ← 作業手順
    │   └── specs/                  ← 仕様への差分(delta)
    │       └── ui-theme/
    │           └── spec.md
    └── archive/
        └── 2026-09-01-add-login/   ← 完了した変更

specs/:現在の仕様

「システムが今どう振る舞うべきか」を表す、プロジェクトの正本です。機能のまとまり(OpenSpec では capability と呼びます)ごとにフォルダを切り、spec.md を置きます。

specs/ は直接編集せず、後述する changes を archive したときに更新される、という運用が基本です。

changes/:変更の提案

「これから仕様をこう変えたい」という提案をまとめる場所です。機能追加・仕様変更・機能削除など、1 つの変更ごとに changes/<change-name>/ というフォルダを作ります(名前は add-dark-mode のような kebab-case)。

Git に例えると、specs/ が main ブランチ、changes/<name>/ がフィーチャーブランチ、のようなイメージです。複数の change を並行して進めることもできます。

change フォルダの中には、次の 4 つの artifact(成果物) を順番に作ります。

artifact ファイル 役割 一言でいうと
proposal proposal.md 変更の動機と範囲 なぜ・何を
specs specs/**/spec.md 仕様への差分 何ができるべきか
design design.md 技術的な設計判断 どうやって
tasks tasks.md 実装のチェックリスト どの順で作るか

依存関係は proposal → specs / design → tasks です。openspec status を実行すると、どこまでできているかを確認できます。

$ openspec status --change add-dark-mode
Progress: 0/4 artifacts complete

[ ] proposal
[-] specs (blocked by: proposal)
[-] design (blocked by: proposal)
[-] tasks (blocked by: specs, design)

proposal.md:なぜ、何を変えるのか

変更の土台となるドキュメントです。実装方法(How)ではなく、動機(Why)と範囲(What) に集中して書きます。

## Why
夜間の利用者から「画面がまぶしい」という声が多く、離脱の一因になっている。

## What Changes
- ダークモードを追加する
- OS の設定に追従する自動切り替えを追加する
- ヘッダーに手動切り替えトグルを追加する

## Capabilities

### New Capabilities
- `ui-theme`: 画面テーマ(ライト/ダーク)の切り替え

### Modified Capabilities
- `user-settings`: テーマ設定の保存を追加

## Impact
- 全コンポーネントの色指定(CSS 変数化が必要)
- ユーザー設定 API

特に重要なのが Capabilities セクションです。ここに挙げた capability ごとに、次の specs/ で差分ファイルを作ることになります。proposal と specs をつなぐ「契約」の役割を持っています。

changes/<name>/specs/:仕様の差分(delta spec)

ここが OpenSpec の核心です。change 内の specs/ には、仕様全体ではなく「差分」だけを書きます。

## ADDED Requirements

### Requirement: テーマの自動切り替え
システムは OS のカラースキーム設定に応じてテーマを切り替えなければならない(SHALL)。

#### Scenario: OS がダークモードの場合
- **WHEN** ユーザーの OS がダークモードに設定されている
- **THEN** 初回表示時にダークテーマが適用される

#### Scenario: ユーザーが手動で選択済みの場合
- **WHEN** ユーザーが過去にライトテーマを手動選択している
- **THEN** OS の設定に関わらずライトテーマが適用される

差分は次の 4 種類の見出しで表現します。

見出し 意味 注意点
## ADDED Requirements 要件の追加
## MODIFIED Requirements 要件の変更 変更後の全文を書く
## REMOVED Requirements 要件の削除 Reason(理由)と Migration(移行方法)が必須
## RENAMED Requirements 名前の変更のみ FROM: / TO: 形式で書く

各要件は ### Requirement: で始め、#### Scenario: に WHEN / THEN 形式で具体的な振る舞いを書きます。シナリオはそのままテストケースの素になります。

spec はあくまで振る舞いの契約です。クラス名、ライブラリの選定、実装手順などは書きません。「実装を変えても外から見た振る舞いが変わらないなら、それは spec に書くことではない」が判断基準です。

design.md:どうやって作るか

技術的な設計判断とその理由を書きます。小さな変更なら省略されることもあります。

## Context
現状、色は各コンポーネントにハードコードされている。

## Goals / Non-Goals
**Goals:** CSS 変数によるテーマ切り替え
**Non-Goals:** ユーザー独自のカスタムテーマ

## Decisions
- `prefers-color-scheme` と `data-theme` 属性を併用する
  - 代替案:CSS-in-JS のテーマプロバイダ → バンドルサイズ増のため不採用

## Risks / Trade-offs
- 既存コンポーネントの色の置き換え漏れ

「なぜこの設計にしたのか」が残るので、後から見返したときに非常に役立ちます。

tasks.md:実装のチェックリスト

実装をどの順番で進めるかを、チェックボックス付きのリストにします。

## 1. 基盤
- [ ] 1.1 カラートークンを CSS 変数として定義する
- [ ] 1.2 テーマ切り替えロジックを実装する

## 2. UI
- [ ] 2.1 ヘッダーにトグルを追加する
- [ ] 2.2 既存コンポーネントの色指定を CSS 変数に置き換える

## 3. テスト
- [ ] 3.1 各シナリオに対応するテストを追加する

Claude Code は実装中にこのチェックボックスを [x] に更新していくので、進捗がファイル上で見えます。セッションが途切れても、続きから再開できます。

archive/:完了した変更

実装が終わった change は changes/archive/YYYY-MM-DD-<name>/ に移動します。このとき、delta spec の内容が openspec/specs/ の正本に反映されます。

つまり archive とは、**「変更を仕様の正本に取り込み、その経緯を履歴として残す」**操作です。

config.yaml:プロジェクトの前提

AI が artifact を作るときに参照するプロジェクト共通の設定です。

schema: spec-driven

context: |
  Tech stack: TypeScript, Next.js, Supabase
  コミットメッセージは Conventional Commits
  ドキュメントは日本語で書く

rules:
  proposal:
    - 必ず Non-goals を含める
  tasks:
    - 1タスクは最大2時間程度に分割する

技術スタックや規約を書いておくと、生成される proposal や tasks の質が大きく上がります。最初に必ず設定しておきたいファイルです。

Claude Code での開発フロー

ここからは、実際に Claude Code で 1 つの機能を開発する流れを見ていきます。

/opsx:explore  →  /opsx:propose  →  レビュー・/opsx:update  →  /opsx:apply  →  /opsx:archive
  (相談)         (計画を作る)      (計画を詰める)          (実装)        (仕様に反映)

Step 1. /opsx:explore ― アイデアを整理する(任意)

/opsx:explore ダークモード対応したいけど、どこから手をつけるべき?

考えるためのモードです。Claude はコードベースを調べたり、選択肢を比較したりしますが、コードは書きません。要件がまだ固まっていないときに使います。

Step 2. /opsx:propose ― change を作る

/opsx:propose ダークモードを追加したい。OS設定に追従しつつ手動でも切り替えられるように

Claude が openspec/changes/add-dark-mode/ を作成し、proposal → specs → design → tasks を一気に生成します。

このコマンドは計画だけを行い、実装には進みません。人間がレビューする時間が確保されている点が重要です。

Step 3. レビューと /opsx:update ― 計画を詰める

生成された artifact を読み、気になる点を修正します。

/opsx:update 手動切り替えはヘッダーではなく設定画面に置きたい

/opsx:update を使うと、proposal・specs・design・tasks の整合性を保ったまままとめて修正してくれます。

あわせて CLI で検証しておくと安心です。

openspec validate add-dark-mode --strict   # フォーマットや必須項目のチェック
openspec show add-dark-mode                # 内容の確認

このレビューが最も大事な工程です。 実装前の段階で認識のズレを潰せるので、「作ってもらったけど思ってたのと違う」という手戻りが大きく減ります。

Step 4. /opsx:apply ― 実装する

/opsx:apply add-dark-mode

Claude が tasks.md を上から順に実装し、完了したタスクにチェックを付けていきます。proposal・specs・design を読み込んだうえで実装するため、途中で要件がブレにくくなります。

セッションが切れても、もう一度 /opsx:apply を実行すれば未完了のタスクから再開できます。

Step 5. /opsx:archive ― 仕様に反映して完了

/opsx:archive add-dark-mode

実装とテストが終わったら archive します。

  1. delta spec の内容を openspec/specs/ にマージする(openspec/specs/ui-theme/spec.md が新規作成されるなど)
  2. change フォルダを changes/archive/2026-09-26-add-dark-mode/ に移動する

これで「今の仕様」が最新になり、次の change はこの仕様を前提に作られます。

/opsx:sync を使うと、archive せずに delta spec だけを先に specs/ へ反映できます。長期間の change で、途中の仕様を他の change と共有したいときに便利です。

よく使う CLI コマンド

スラッシュコマンドの裏では、OpenSpec の CLI が動いています。人間が状況を確認するときにも便利です。

コマンド 用途
openspec list 進行中の change 一覧
openspec list --specs spec 一覧
openspec view 対話型ダッシュボード
openspec show <name> change / spec の内容表示
openspec status --change <name> artifact の進捗
openspec validate <name> --strict フォーマット検証
openspec archive <name> change の archive
openspec update 指示ファイルを最新版に更新

運用のコツ

  • config.yaml の context は最初に書く:技術スタックや規約を書くだけで、生成物の質が大きく変わります
  • 1 change = 1 つの目的:「ダークモード追加」と「ログイン改善」を 1 つの change に混ぜない
  • 振る舞いが変わらない変更は specs を作らない:リファクタやツール整備だけの change は、.openspec.yaml に skip_specs: true を設定します(archive --skip-specs でも可)
  • change フォルダも Git にコミットする:PR に proposal と spec の差分が載るので、レビュアーが「何のための変更か」を理解しやすくなります
  • 既存プロジェクトでは、触る部分から spec を書く:最初から全機能の spec を揃える必要はありません。変更のたびに少しずつ specs/ が育っていきます

まとめ

用語 意味
specs/ 今のシステムの振る舞い(正本)
changes/<name>/ これから加える 1 つの変更
proposal.md なぜ・何を変えるのか
delta spec 仕様への差分(ADDED / MODIFIED / REMOVED / RENAMED)
design.md どうやって作るか、設計判断の理由
tasks.md 実装のチェックリスト
archive 差分を正本にマージし、履歴として残す

OpenSpec を使うと、Claude Code との開発が「チャットでのその場のやり取り」から「ファイルで合意して、合意どおりに作る」プロセスに変わります。特に「propose → レビュー → apply」の流れで、実装前に人間が計画を確認できる点が大きな価値です。

AI に任せる範囲が広がるほど、「何を作るか」を明確にしておく重要性は増していきます。ぜひ試してみてください。

参考

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?