OpenSpec 超入門

• 概要
• 環境
• インストール
• 初期化
• project.md の編集
• 提案書の作成
• 検証する
• コードを生成する
• 動作確認
• アーカイブする
• 最後に
• 参考サイト

概要

OpenSpec は簡単に言えば Markdown (仕様書) を作成するだけでアプリが開発できてしまうツールです
今までは特にフォーマットもなくプロンプトに命令していましたがそれを定型化したツールになります
今回は簡単なブラウザのタイマーアプリを OpenSpec を使って作ってみました

環境

• Ubuntu 24.04
• node 22.21.0
• openspec 0.13.0
• code-server v4.104.3

インストール

• npm install -g @fission-ai/openspec@latest

初期化

まずはプロジェクトを初期化します

• openspec init

 ????   ?????   ??????  ??  ??   ?????  ?????   ??????   ?????
??  ??  ??  ??  ??      ??? ??  ??      ??  ??  ??      ??
??  ??  ?????   ?????   ?? ???   ????   ?????   ?????   ??
??  ??  ??      ??      ??  ??      ??  ??      ??      ??
 ????   ??      ??????  ??  ??  ?????   ??      ??????   ?????

Welcome to OpenSpec!

Step 1/3

Configure your OpenSpec tooling
Let's get your AI assistants connected so they understand OpenSpec.

Press Enter to continue.

次に使用するLLMを選択します

Step 2/3

Which natively supported AI tools do you use?
Use ↑/↓ to move ・ Space to toggle ・ Enter selects highlighted tool and reviews.

    Natively supported providers (? OpenSpec custom slash commands available)
? ○ Auggie (Augment CLI)
  ○ Claude Code
  ○ Cline
  ○ CodeBuddy Code (CLI)
  ○ Crush
  ○ Cursor
  ○ Factory Droid
  ○ OpenCode
  ○ Kilo Code
  ○ Windsurf
  ○ Codex
  ○ GitHub Copilot
  ○ Amazon Q Developer

    Other tools (use Universal AGENTS.md for Amp, VS Code, GitHub Copilot, …)
  ○ Universal AGENTS.md (always available)

Selected configuration:
  - No natively supported providers selected

今回は Github Copilot を使います

Step 3/3

Review selections
Press Enter to confirm or Backspace to adjust.

? GitHub Copilot

これで初期化が完了です

? GitHub Copilot
? OpenSpec structure created
? AI tools configured

? OpenSpec initialized successfully!

Tool summary:
? Root AGENTS.md stub created for other assistants
? Created: GitHub Copilot
? Skipped: Auggie, Claude Code, Cline, CodeBuddy Code, Crush, Cursor, Factory Droid, OpenCode, Kilo Code, Windsurf, Codex, and Amazon Q Developer

Use `openspec update` to refresh shared OpenSpec instructions in the future.

Next steps - Copy these prompts to GitHub Copilot:
────────────────────────────────────────────────────────────
1. Populate your project context:
   "Please read openspec/project.md and help me fill it out
    with details about my project, tech stack, and conventions"

2. Create your first change proposal:
   "I want to add [YOUR FEATURE HERE]. Please create an
    OpenSpec change proposal for this feature"

3. Learn the OpenSpec workflow:
   "Please explain the OpenSpec workflow from openspec/AGENTS.md
    and how I should work with you on this project"
────────────────────────────────────────────────────────────

project.md

の編集

ここにどんなアプリを作成したいか概要を記載ます とりあえず参考サイトにもあるブラウザで動かくタイマアプリを作成してみます Project Conventions の欄はとりあえず不要なので削除しています

• vim openspec/project.md

# Project Context

## Purpose
家庭や業務用キッチンで使用できるシンプルで視認性の高いタイマーを、Web ブラウザー経由で提供します。

- 1分、3分、5分を設定するためのボタンを配置します。ボタンを押すと、その時間からカウントダウンが開始されます。
- カウントダウン中は、残り時間を目立つように表示します。
- カウントダウン中に再度ボタンを押すと、タイマーがリセットされ、新たなカウントダウンが開始されます。

## Tech Stack
- HTML5
- JavaScript（ES6）
- CSS3

提案書の作成

code-server の Github Copilot のチャット欄に /openspec-proposal コマンドを入力します

• /openspec-proposal UIを作成する

すると必要な Markdown ファイルを changes 配下に作成してくれます

ls -lR openspec/changes/ui-timer/
openspec/changes/ui-timer/:
total 12
-rw-r--r-- 1 devops docker  374 Nov  4 13:57 proposal.md
drwxr-xr-x 3 devops docker 4096 Nov  4 13:57 specs
-rw-r--r-- 1 devops docker  341 Nov  4 13:57 tasks.md

openspec/changes/ui-timer/specs:
total 4
drwxr-xr-x 2 devops docker 4096 Nov  4 13:57 timer-ui

openspec/changes/ui-timer/specs/timer-ui:
total 4
-rw-r--r-- 1 devops docker 810 Nov  4 13:57 spec.md

作成されたファイルの中身を確認して仕様に間違いがないか確認しましょう 変更は Copilot Chat にお願いしてもいいですし手動で書き換えても OK です 問題なければ Keep してファイルを保存しましょう

検証する

チャット欄に「検証して」と入力すると勝手に openspec validate コマンドを実行してくれます 内部的には openspec validate ui-timer --strict を実行しています

生成された Markdown に不備があると以下のようにエラーが表示されます ちなみにエラーがよくわからなくても「修正してください」と命令し再度「検証してください」と命令すればそれだけで修正できます

code-server が openspec コマンドを実行できない場合は PATH を確認するか PATH に通っているけど実行できない場合は sudo systemctl restart code-server@USER で再起動しましょう

コードを生成する

あとは /openspec-apply を Copilot Chat に入力すればコードを生成してくれます 各種 html や js が作成されたのが確認できます 内容を確認し問題なければ Keep しましょう

動作確認

これもチャットに「動作確認して」と依頼すればブラウザでアプリを開いて動作確認してくれます

Web アプリがない場合は Python で簡易用のアプリも起動してくれます

アーカイブする

アプリの挙動が問題なければアーカイブします チャット欄に /openspec-archive を入力しましょう すると生成されたコードは archive 配下に移動します

以後アプリに修正を入れたい場合は再度提案を作成し修正するようにしましょう そうすることで changes/archive 配下に日付ごとにディレクトリが作成され提案ごとに履歴管理することができるようになります

最後に

OpenSpec に入門してみました 基本は Markdown を書くだけで開発していく感じです 今まではプロンプトに自分なりの質問やテンプレートを使って質問していたのが完全に形式化したのが OpenSpec かなと思います

新規系は簡単に導入できそうですが既存のアプリにこれを導入するとなるとかなり大変そうです

参考サイト

• https://gigazine.net/news/20251026-openspec/
• https://github.com/Fission-AI/OpenSpeca