話題になっていたSpec Kitを今更使ってみる
こんにちは、FLINTERS新卒エンジニアの野崎です。
少し前からチーム内で「Spec Kitが良さそう」という話題が上がるようになりました。仕様駆動開発（Spec-Driven Development ; SDD） をAIで支援するプロンプトが入ったツールキットらしいとのこと。
私も遅ればせながらSpec Kitを使った開発を試してみることにしました。
Spec Kitとは何か？
Spec Kitは、GitHubが公開しているオープンソースのツールキットです。
これは、GitHub CopilotやClaude CodeといったAIコーディングエージェントを使い、仕様を起点にして開発を進める「仕様駆動開発」を支援するために作られています。
導入方法
作業ディレクトリで下記のコマンドを実行してください。
- uvを使う場合
uvx --from git+https://github.com/github/spec-kit.git specify init --here
- brewを使う場合
brew install specify
specify init --here
その後様々な初期設定をすると、.specifyディレクトリが作成され、各種プロンプトが利用可能になります。
Spec Kitを使った開発の流れ
Spec Kitの基本的な開発プロセスは、主に以下のコマンド（プロンプト）で構成されています。
/specify (仕様定義)
ユーザーが「こういう機能を作りたい」という大まかな目的や要件を伝えます。
AIはそれに基づいて、機能仕様書（spec.mdなど）を生成してくれます。また、この段階で作業用のブランチを切ってくれます。
/plan (計画)
生成された仕様書をどう実現するか、使用する技術スタック、アーキテクチャ、API設計などの「技術計画」をAIと策定します。技術計画書（plan.mdなど）が生成されます。
/tasks (タスク分解)
仕様書と技術計画に基づき、実装に必要な作業をAIが具体的なタスクリスト（tasks.md）に分解します。
/implement (実装)
分解されたタスクを一つずつAIに実行させ、コードを生成・実装していきます。
+------------------------------------------+
| 1. /specify (仕様定義) |
| 成果物: spec.md (仕様書) |
+------------------------------------------+
|
V
+------------------------------------------+
| 2. /plan (計画) |
| 成果物: plan.md (技術計画) |
+------------------------------------------+
|
V
+------------------------------------------+
| 3. /tasks (タスク分解) |
| 成果物: tasks.md (タスクリスト) |
+------------------------------------------+
|
V
+------------------------------------------+
| 4. /implement (実装) |
| 成果物: ソースコード (e.g., *.ts, *.py) |
+------------------------------------------+
|
V
+------------------------------------------+
| ✨ 完成コード |
+------------------------------------------+
このように、いきなりコードを書くのではなく、AIと対話しながら「仕様→計画→タスク分解→実装」と段階を踏んでいくことで、AIの「暴走」を防ぎ、より意図に沿った高品質なコード生成を目指すのが特徴です。
コード品質は◎、しかし気になる点もあり
実際にSpec KitをClaude Codeで使い、いくつかの機能実装を試してみました。
良かった点 (Pros)
生成されるコードの品質が非常に高い
まず仕様書を作成し、それをレビューしてから実装に移るため、手戻りが少なく、アウトプットが安定しています。
特に驚いたのは、多少複雑な実装でも、全体の整合性を取ったコードを提案してくれたことです。これは凄い。
気になった点 (Cons)
工程が多い
仕様書作成（/specify） → 計画（/plan）→ タスク分解（/tasks）→ 実装（/impl） と、ステップが細かく分かれています。
覚えれば良いという話ではありますが、どこまでやったか、次はどのコマンドかの管理が手間に感じました。
コンパクションが頻発する
工程が多いため、一つの機能を実装するだけでもAIとのセッションが非常に長くなります。 これにより、古いやり取りを要約・圧縮し始める「コンパクション」が何度も発生しました。
（もちろん、spec-kitの素晴らしい点は、コンパクションが起きても「生成された仕様書」という中間成果物が残るため、それを再度読み込ませれば作業を継続できることです。ただ、毎回それをやるのは少し手間に感じました。）
CLAUDE.md と Subagents で快適化してみる
「工程の多さ」と「コンパクション問題」。この2つの課題を解決するため、Claude Codeの機能を活用することにしました。
- 「工程の多さ」問題 → CLAUDE.md でワークフロー化
- 「コンパクション」問題 → Subagents でコンテキスト分離
以前書いた記事でClaude Code卒業！！などと宣っていましたが、今回はClaude Codeの機能をしっかり使いこなす良い機会です。早速、この2つのアプローチを試してみることにしました。
CLAUDE.mdによるワークフローの自動化
まず、「工程の多さ」と「次に何をすべきか忘れる」問題を解決するため、Claudeのカスタム指示ファイルであるCLAUDE.mdに、Spec Kitの一連の流れを定義しました。
これにより、私がやることは「[チケットプレフィックス]-XXXXX」のようにJIRAのチケット番号を渡すだけになります。 あとは、このCLAUDE.mdが「指揮者」となり、Spec Kitの各コマンドを正しい順番で呼び出してくれます。
実際に使用しているCLAUDE.mdは以下の通りです。
[チケットプレフィックス]-XXXXXの形のJIRAのチケット番号が渡されたら、以下の手順で作業を進めてください。
1. /speckit.specifyで仕様の明確化。（その際、サブエージェント: jira-requirements-analystを使って渡された番号のJIRAチケットの内容を確認してください）
2. /speckit.plan, /speckit.tasksでTODOの作成、作業用ブランチの作成をしてください。(その際、サブエージェント:workflow-coordinatorを使ってください。)
3. 実装が必要な場合、/speckit.implementで実装を進めてください。(その際、サブエージェント:dev-agentを使ってください。)
上記の１ステップずつで、ステップが完了し次第作業した内容について要約し、ユーザーの確認を求めるようにしてください。
- 既にspec.mdがリポジトリに存在している場合、1段階目は完了しているので2段階目から作業してください。
- 既にspec.md、tasks.mdがリポジトリに存在し、作業用のブランチが作成されている場合、2段階目は完了しているので3段階目から作業してください。
ポイントは、spec.mdやtasks.mdの存在をチェックして、途中からでも作業を再開できるロジックを入れている点です。これにより、「どこまでやったっけ？」という管理の手間からも解放されます。
Subagentsによるコンパクションの回避
次に、CLAUDE.mdの定義を見るとわかりますが、各ステップでSubagentsを呼び出しています。
sub-agentは、メインのチャットセッションとはコンテキストを共有しない独立したセッションで動作します。
コンパクションは、同一セッションが長くなることが原因です。 ならば、Spec Kitの各工程、特にコンテキストが肥大化するような重い処理をSubagentsに丸投げすれば、メインセッションは「チケット番号」と「Subagentsへの指示」だけになり、コンパクションを原理的に回避できるはずです。
今回は、Spec Kitの各工程に合わせて、以下の3つのSubagentsを「専門家」として用意しました。
1. JIRA要件分析担当 (jira-requirements-analyst)
先ほど定義したCLAUDE.mdのステップ1（/speckit.specify）で呼ばれるエージェントです。 MCPサーバーに接続し、JIRAチケットの詳細を分析して、仕様書作成のインプットとなる要件定義ファイル（.claude/{ticket-id}.md）を生成します。
---
name: jira-requirements-analyst
description: JIRAのチケット番号が渡された時(デフォルトは[チケットプレフィックス]-XXXXXの形)。specifyの段階でも使いたい。
model: sonnet
---
あなたは[アプリ名]開発チームの要件分析エキスパートです。JIRAチケットを与えられたら：
説明、受入基準、コメント、リンクされた課題を含む完全なチケット詳細をAtlassian MCPサーバー(https://mcp.atlassian.com/v1/sse)に接続し、取得する。
MCPサーバーへの接続時にはユーザーへの確認をする。
... (以下、分析処理の指示)
分析結果は 作業リポジトリの`.claude/{ticket-id}.md` に保存する。
2. ワークフロー調整担当 (workflow-coordinator)
ステップ2（/speckit.plan, /speckit.tasks）で呼ばれるエージェントです。 要件定義ファイルをもとに詳細なTODOを生成します。
---
name: workflow-coordinator
description: 要件からTODOリストを作成。jira-requirements-analystによる要件分析完了後、またはplan, tasksの作業段階で使用。
model: sonnet
tools: bash, write_to_file, read_file
---
(※ TODOリストのタスク分割を行う処理を記述)
3. 実装担当 (dev-agent)
ステップ3（/speckit.implement）で呼ばれるエージェントです。 TODO.mdを読み込み、 「鉄則：既存コードに従ってください」 という厳格な指示のもと、類似実装を調査しながらコーディング、テスト、コミットを行います。
---
name: dev-agent
description: フルスタック実装担当。既存コードを参考に一貫性を保つ。
model: sonnet
tools: read_file, write_to_file, bash, list_directory, search_memory, save_memory
---
(※ 既存コードの調査、実装、テスト、TODO更新、コミットなど、一連の実装作業を担う処理が記述されている)
このように、CLAUDE.mdで全体の流れを管理し、Subagentsがコンテキストを分離した状態で重い処理を実行する、という分業体制を構築しました。 これにより、Spec Kitの「工程の多さ」と「コンパクション問題」を同時に解決できる（はず）です。
（ちなみに、今回はplanとtasksの工程を「計画段階」としてまとめ、workflow-coordinatorという一つのSubagentに任せています。これは、計画とタスク分解の連携が強い方が良いと判断したためですが、このあたりは好みやプロジェクトの特性に応じて、それぞれ独立したSubagentに分けても良いかもしれません。）
感触は良好。次はコストを睨む。
この 「CLAUDE.md（指揮者） + Subagents（専門家）」 によるSpec Kit運用、感触は非常に良いです。
Spec Kitの最大の懸念点だった「工程の多さによる管理コスト」と「コンパクションの頻発」を、CLAUDE.mdのワークフロー化とSubagentによるコンテキスト分離で解消することができました。
これにより、Spec Kitの最大の強みである「品質の高さ」を、ストレスなく享受できるようになったと感じています。
今後の展望
まだこの運用を始めたばかりなので、あくまで「良い感じかも（？）」という段階ですが、今後はさらに一歩進めて、以下のような点を検証していきたいと考えています。
コスト（モデル）比較の検証
Spec Kitという強力な「型（プロンプト）」があるおかげで、もしかしたら使用するモデルのグレードを（例：SonnetからHaikuに）変更しても、十分な品質のコードが生成されるかもしれません。 これが可能になれば、従量課金であるClaude Codeのコスト効率を劇的に改善できる可能性があります。これは是非実験してみたいですね。
チームへの展開
今回作成したSubagent群、特にdev-agentの「鉄則：既存コードに従ってください」という指示のように、Spec Kitのプロンプトは、プロジェクト固有のコーディング規約や設計思想を反映させる「知見の蓄積場所」として非常に優秀だと感じました。 これは、個人としてだけでなく、チームとして導入し、みんなで育てていくのも大いにアリかもしれません。（spec-kitがもともとそう言った思想のもと生まれているのはあります。）
まずはこのSpec Kit + Subagentsの運用を続けてみて、知見を貯めていこうと思います。
Discussion