OpenSpecで仕様駆動開発を始める

OpenSpecは、AIエージェントと「仕様」を共有しながら開発を進めるための仕様駆動開発（Spec-Driven Development）の仕組みです。実装前に変更内容を仕様として明文化することで、AIの出力のブレを抑え、レビュー可能な開発を実現します。

この記事でわかること

• 仕様駆動開発の考え方
• OpenSpecの基本的なワークフロー
• 提案（proposal）の書き方
• 仕様から実装へつなげる流れ

前提知識

• Claude Code などのエージェントの基本操作
• Git とプルリクエストの流れ
• Markdown の基本記法

仕様駆動開発とは

仕様駆動開発は、「まず何を作るかを仕様として書き、それに沿って実装する」進め方です。AIエージェントに丸投げするのではなく、合意した仕様を基準にすることで、意図と成果物のズレを防ぎます。

OpenSpecのワークフロー

基本の流れは次の4段階です。

1. 変更したい内容を「提案」として記述する
2. 提案をレビューして合意する
3. 合意済みの仕様に沿って実装する
4. 完了後、変更をアーカイブして仕様に取り込む（/opsx:archive または openspec archive）

提案の段階で議論を済ませるため、実装での手戻りが起きにくくなります。

提案を作る

OpenSpecでは、変更提案を openspec/changes/<変更名>/ に置きます。

openspec new change user-rate-limit

作成された openspec/changes/user-rate-limit/ に proposal.md を置き、変更の理由（Why）と内容（What Changes）を記述します（AI エージェントのチャットで /opsx:propose を使えば下書きを生成できます）。

## Why
ログインAPIに過剰なリクエストを防ぐレート制限を追加する。

## What Changes
- 同一IPからの試行回数を制限する
- 上限超過時は429を返す

仕様を検証する

記述した提案が整合しているかを確認します。なお、検証を通すには specs/<capability>/spec.md に ## ADDED Requirements などのデルタ（各要件に #### Scenario: を1つ以上）が必要です。

openspec validate user-rate-limit

問題がなければ、チームやAIエージェントと内容を共有してレビューします。

実装に落とし込む

合意した提案をエージェントに渡すと、仕様という明確な基準のもとで実装を進められます。実装後は提案を確定済みの仕様として取り込み、次の変更の土台にします。

よくある失敗

• 提案を書かずにいきなり実装を依頼してしまう
• 提案の範囲が曖昧で何を作るか定まらない
• レビューを省略して仕様の合意を飛ばす
• 実装後に仕様を更新せず、記録と実体が乖離する

まとめ

OpenSpecは、仕様を中心に据えることで、AIの出力を予測しやすくするフレームワークです。提案を書き、合意し、実装するという流れを守るだけで、手戻りの少ない開発になります。まずは小さな変更で一連のサイクルを体験してみましょう。

※ コマンド例は 2026年10月時点の OpenSpec（v1.15.0）のドキュメントに基づいています。