こちらの記事は カケハシ Advent Calendar 2025 の 16日目の記事になります。
はじめに
Pocket Musubiチームでソフトウェアエンジニアをしている牧野です。
私たちのチームでは、既存システムへの機能追加のプロジェクトにおいて仕様駆動開発（Specification-Driven Development）を行っています。
本記事では、ツールの導入検討から実際の運用、チーム全体での学習プロセスまでを具体的に紹介します。
仕様駆動開発とは
仕様駆動開発は、仕様書(spec)を起点として開発を進める手法です。仕様書をSingle Source of Truth（信頼できる唯一の情報源）として扱い、そこから一貫性のある成果物(設計書、タスクリスト、コード等))を導出することで、仕様と実装の乖離を防ぎます。
AIを活用したコーディングが一般的になる中で、この仕様駆動開発の考え方が改めて注目されています。kiroやSpecKit、OpenSpec等のツールは、仕様書から設計やタスクリスト、実装コードまでをAIエージェントが自動生成する機能を提供しており、人間は仕様の定義とレビューに集中できるようになります。
ツール選定
ツールの候補としてSpecKitとOpenSpecの2つを比較検討しました。 それぞれのツールで仕様書やタスクリストの作成、実装を小さく試しつつ、最終的にOpenSpecを選択しました。主な理由は以下になります。
1. 既存仕様と変更内容の分離管理機能
OpenSpecは、ベースとなる既存仕様・設計と、新規開発による変更差分を明確に分けて管理する機能を提供しています。実際のユーザーストーリーを対象に両ツールを試したところ、既存システムへの改修を前提とした今回のケースでは、OpenSpecが生成するタスクリストやコード成果物のほうが期待に近いものでした。
2. 機能とドキュメントのシンプルさ
SpecKitは多機能である一方、必須コマンドだけでも複数あり、生成される中間成果物の数も多く、ワークフロー全体を把握するのに時間がかかります。一方OpenSpecは、提供するコマンドや生成されるドキュメントの種類が絞られており、ワークフローがシンプルです。初めて仕様駆動開発ツールを導入するチームにとって、覚えるべきことが少ないのは大きなメリットでした。
チームとしての学習コストの低さや導入ハードルの低さの観点からも、OpenSpecの利用がより効果的と判断しました。
プロジェクトのディレクトリ構成
私たちのシステムは複数のリポジトリに分かれたマルチリポジトリ構成をとっています。今回の機能開発ではnativeアプリとそのバックエンド、webの管理画面とそのバックエンド等に改修を加える必要があり、変更対象のリポジトリが6つありました。
仕様駆動開発では仕様書をSingle Source of Truthとして扱うことを基本原則としています。これを実現し、かつチームとして管理できるようにするため、プロジェクトのコンテキストを一元管理するリポジトリ内で必要なファイルを管理するようにしています。
project-root/ ├── .claude/ # カスタムコマンド、スキル ├── docs/ # AIエージェントに渡すドキュメント類 ├── openspec/ # OpenSpecが管理する仕様書や設計書 ├── repositories/ # 変更対象のGitリポジトリ (サブモジュールで取り込み) │ ├── foo.git │ ├── bar.git │ └── .... ...
変更対象のリポジトリはGitのサブモジュールとして取り込む構成にしています。このプロジェクトディレクトリには仕様書だけでなく、チームで作ったClaude Codeのカスタムスラッシュコマンドやエージェントスキルも含めています。
導入初期：モブプロによる全員での学習
チームメンバー全員が仕様駆動開発ツールを使うのがはじめてだったため、最初の数日はエンジニア4人全員によるモブプロを実施しました。1つのユーザーストーリーを対象に、OpenSpecのセットアップから仕様書、設計書の作成、実装完了までを全員で進めました。
モブプロでは、ツールの使い方だけでなく、プロンプトの書き方やツール特有の癖、期待される出力の精度などを共通認識にすることを目指しました。一人ひとりが個別に学習すると、「これで合っているのか？」という不安や些細なエラーでの躓きが発生しがちなため、全員で失敗や試行錯誤を共有することで、チームとしての共通知を早期に形成できました。
結果として、以降のユーザーストーリーでは各自が独立してタスクを消化できる状態になりました。
実際の運用フロー
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#e1f5ff','primaryTextColor':'#000','primaryBorderColor':'#0288d1','lineColor':'#0288d1','secondaryColor':'#fff3e0','tertiaryColor':'#f5f5f5'}}}%%
graph TB
subgraph AI["🤖 AIエージェント"]
A1["`仕様書/設計書/タスクリストの作成`"]
A3[コーディング]
A4[最終成果物レビュー]
end
subgraph Human["👤 人間"]
H0[外部設計・仕様の洗い出し]
H1["`仕様書や設計書の作成要求
(/openspec:proposal)`"]
H2["`設計書やタスクリストの調整`"]
H3["`実装の要求
(/openspec:apply)`"]
H4[レビュー]
H5{修正必要?}
H6[最終成果物レビュー]
end
H0 --> H1
H1 --> A1
A1 --> H2
H2 --> H3
H3 --> A3
A3 --> H4
H4 --> H5
H5 -->|Yes| A3
H5 -->|No| A4
A4 --> H6
H6 --> End([完了])
style AI fill:#e1f5ff,stroke:#0288d1,stroke-width:2px
style Human fill:#fff3e0,stroke:#f57c00,stroke-width:2px
style End fill:#4caf50,stroke:#2e7d32,color:#fff
私たちのチームではスクラム開発を行っており、バックログリファインメントで各ユーザーストーリーの仕様を詳細化しています。リファインメントの場で明らかになった仕様を元に、proposal コマンドで仕様書、設計書、タスクリストの草案を作成します。
生成された成果物をざっとレビューし、実装できる状態になったら apply コマンドを実行してAIエージェントが実装を行います。このとき、タスクリストを元に一括で実装するのではなく、人間がレビューや作業をコントロールしやすい小さな粒度で漸進的に進めています。
今回の開発では複数のGitリポジトリにまたがる変更が必要なため、タスクリストの作業をリポジトリごとに分けて出力するようにAIエージェント向けのルールファイルを調整しています。
その後は人間が確認し、必要に応じて修正要求するサイクルを繰り返します。
チームラーニングの仕組み
チーム全体でツールを利用し改善していくため、AIエージェントとのやり取りを振り返りやすくする仕組みを作りました。Claude Codeのカスタムスラッシュコマンドとエージェントスキルを使い、入出力をログとして記録できるようにしています。
たとえばエージェントスキルでは、「このやり取りを保存しておいて」と入力するだけで、人間の入力内容、AIのアクション（調査したファイルや実行したコマンド）、最終的な出力がログファイルに記録されます。
私たちのチームではデイリースクラム後に「2次会」という場を設けており、その日の作業についてのすり合わせや相談を同期的に行っています。ここで仕様駆動開発ツールを使ううえでの課題や良かった点を頻繁に共有し、高頻度に改善サイクルを回しています。
運用してみての気づき、工夫していること
チームとして運用をする中で気づいたことや工夫についていくつか共有いたします。
中間成果物の評価はほどほどにする
OpenSpecは、変更内容と既存コードを元に仕様書や設計書、タスクリストを生成します。生成される中間成果物の量は多く、すべてを丁寧にレビューしようとするとかなりの時間がかかります。
最終的な作業内容はタスクリストで表現され、コードとして実装されます。そのため、生成された設計書のレビューに必要以上の時間を使わず、実装後のコードレビューに重点をおくようにしています。中間成果物は方向性の確認程度にとどめ、実装されたコードで最終的な品質を担保する方針としています。
specファイルの鮮度を保つ
実装を進める中で、当初想定していなかった仕様が見つかることがあります。こうした仕様もspecファイルに反映させ、仕様書を常に最新の状態に保つことを意識しています。
複数人で開発を進めると、specファイルの変更がコンフリクトしやすくなります。これを避けるため、仕様書や設計書に変更があった場合は、実装を待たずにすぐにmainブランチにマージするようにしています。こうすることで、コンフリクトのリスクを小さく保ちながら、仕様書を常に最新の状態で共有できるようになりました。
specファイルを元にしたテストケースの作成
私たちのチームにはQAチームがあり、ユーザーストーリーごとにテストケースの作成とテスト実施を行っています。
OpenSpecが生成するspecファイルは、シナリオごとに「WHEN (条件) → THEN (結果) → AND (追加条件/結果)」という形式で記載されています。この構造がテストケース作成と相性が良く、specファイルを入力情報としてテストケース（csv形式）を作成する取り組みを実際に試しています。仕様書がテストの起点としても機能することで、仕様とテストの一貫性を保ちやすくなると期待しています。
まとめ
チームへの導入から約3週間が経ちました。元々予定していたスケジュールから前倒しで開発を進められており、短期的な観点ではありますが、開発生産性が向上している実感があります。
自前でプロンプトを都度作成してAIに指示する方法と比べると、OpenSpecのようなツールを使うことで、コンテキストをより正確に渡せ、出力も期待に近いものになりやすいと感じています。ツールが提供するワークフローに乗ることで、チーム全体で一貫した開発プロセスを共有できる点も大きなメリットです。
今回紹介したのはまだ導入初期の取り組みですが、今後も運用を続ける中で新たな気づきや改善点が出てくると思います。仕様駆動開発ツールの導入を検討している方の参考になれば幸いです。
