【実践レポート】Spec Kit + Claude Code GitHub Actionsで実現するAI仕様駆動開発

AIエージェント GitHub Actions 生成AI

本記事でわかること

この記事では、AIエージェント時代の新しい開発手法として注目される「仕様駆動開発」を、 Claude Code GitHub Actions と Spec Kit を使って実際に試した結果をお伝えします。オセロアプリの開発を通じて、従来の開発プロセスとの違いや実際の課題までを解説します。

はじめに

こんにちは。 この度Insight Edgeで1ヶ月間のインターンに参画しております、東京科学大学物質理工学院博士課程2年の石井です。大学院では主に半導体材料をターゲットとした第一原理計算を用いた点欠陥の解析などを行なっております。

今回は、インターン期間中に検討したClaude Code GitHub ActionsとSpec Kitを用いた仕様駆動・AIエージェント駆動開発に関する話をご紹介しようと思います。

背景・課題

ソフトウェア開発は、単一の生成AIによる点的な支援から、複数モデル／エージェントが協調して要件理解・設計・実装・検証を一貫支援する「エージェント駆動型」への移行過程にあります。主要LLMと周辺ツールの高度化により自律実行や運用レベルのコーディングが可能になり、開発者は本質的な課題解決に集中できる環境が整いつつあります。 一方で、活用はまだ局所最適に留まりがちで、プロジェクト／個人間でのばらつき、ならびにAI活用プロセスの可視化・再現性の不足が課題です。具体的には以下が挙げられます。

  • 情報探索や手戻りが散発的に発生しやすい
  • ドキュメントと実装の同期が人手依存で、保守性・説明可能性に揺らぎがある
  • ローカルでのAI活用は進む一方、成果物管理やレビューの基盤（GitHub等）が従来運用のままで、活用過程がログとして残らない/監査できない
  • 組織横断で再利用できるプロンプト・エージェント設計・ワークフローが標準化されていない

目的

そこで今回は、組織プロセスとして定着させるための手段としてGitHub Actionsに組み込み、GitHub上で実行することを目指します。 これにより、

  • 情報探索や手戻りの削減
  • ドキュメントと実装が自然に同期され、プロダクトの保守性が高まる
  • AIエージェントを前提とした開発プロセスが可視化される

が成し遂げられ、チーム開発における開発者体験(Developer Experiense)の質的向上と、 組織ノウハウとしての定着が期待されます。 今回はAIエージェントとして Claude Code を活用します。

GitHub Actionsを用いたSpec Kitで仕様駆動開発を試してみる

仕様駆動開発とは

仕様駆動開発（Spec-Driven Development; SDD）は、AIが直接コードを生成する方式ではなく、まず仕様書（Specification）を定義し、その仕様を根拠としてAIエージェントが開発を進める手法です。

仕様駆動開発のねらいは、即興的なvibe codingで失われがちな合意や根拠を仕様へ明確化し、変更時も仕様差分を基点として安全かつ高速で反復できる状態を実現することです。

仕様駆動開発の応用例として、Amazonが発表したエージェント型AI統合開発環境(IDE)である Kiro も注目されています。Kiroは、自然言語のプロンプトや要求から明確な仕様を起こし、それをもとに要件分解→設計→実装タスク化→テスト生成→コード生成までを支援するものです。

Spec-Kitとは

そして、その仕様駆動開発のワークフローの標準化のためのツールとして注目されているのが Spec Kit です。 Spec Kitは与えた仕様を詳細化して仕様書を作成し、ソフトウェア開発の計画を策定してタスクに分解・実装するためのオープンソースツールキットでGitHubから提供されています。

Claude Code GitHub Actionsについて

また、今回はAIエージェントの活用過程がログとして残らない／監査できないという現状へのアプローチとしてGitHub Actions上で仕様駆動開発を試みます。 そのために今回は、Claude Code GitHub Actionsを活用しました。フローとしてはまずIssueを作成しIssueのコメントで @claude をメンションし、続けて本文を投稿するとその内容をプロンプトとして解釈して返信が返ります。その実装をレビューしてPRを出します。

こちらの 公式サイトのworkflowファイル作成 を参照し、 github/workflows/ 配下へymlファイルを追加しました。

オセロ対戦アプリを作ってみた

Claude Code GitHub ActionsとSpec Kitを用いた仕様駆動開発のデモンストレーションとして、オセロ対戦アプリを作成しました。

spec-kitの代表コマンドとして以下のようなものがあり、これらを順に実行していくことで仕様駆動開発が実現できます。

  • /specify コマンドから要求を書き仕様書を生成
  • /clarify コマンドで作成した仕様書の未定義箇所の穴埋め
  • /plan コマンドから対応してほしい技術スタックを書き込んで詳細設計書を生成
  • /tasks コマンドを叩くとtask.mdファイルとしてTodoリストが作成
  • /implement コマンドでtask.mdを読み込んでそのタスクを元に実装

これらのコマンドはすべてSpec Kitの初期化時に作成されます。

まずはuvを事前にインストールし、以下を実行します。

uvx --from git+https://github.com/github/spec-kit.git specify init --here

Claude Codeではなく、Geminiでspeckitを使用したい場合は

uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai gemini

のように --ai <使用したいcoding agent> で使用できます。(geminiの場合は.gemini/commands/にtomlファイルが生成されます。)対応しているagentの種類はリポジトリを参照：Spec Kit

そして以下の画像のように、Issueを立ち上げて @claude でClaudeをメンションして雑な要件定義を投げます。

@claude /specify モダンなUIのオセロ対戦アプリを開発してください。CPUとの対戦が可能なアプリとし、CPUとの対戦は「弱い」、「普通」、「強い」の三種類を選べます。

specifyコマンドの実行例

そうすると、上記の要件で未定義で曖昧な箇所を以下のようにリストアップしてくれます。

未定義な項目のリストアップ例

上記の未定義な箇所の埋め合わせは /clarify コマンドで以下のようにPR上でコメントします:

@claude /clarify

1. プレイヤー対プレイヤーのモード: CPU対戦のみ
2. ゲーム履歴の保存: 過去のゲーム結果や統計情報の保存は必要なし
3. サウンドとアニメーション: 駒を置く音、裏返すアニメーション等は必要なし
4. プラットフォーム対応: Webにのみ対応
5. CPU思考時間: 即座に応答すべきか。ただしCPUの処理レベルが高い場合、視覚的な表示や遅延処理が必要
6. ヘルプ機能: 有効な手のヒント表示やアンドゥ機能は必要

これにより曖昧な未定義箇所を穴埋めした仕様書(spec.md)が完成します。 そして、次に実装計画の作成するために /plan コマンドを実行して技術要件の定義や設計、実装手順の策定します。

@claude /plan これを React + TypeScript で実装し、ビルドは Vite、状態管理に Zustand を使用します。スタイリングは Tailwind CSS と shadcn/ui（Radix UIベース）でモダンかつアクセシブルなUIを構築します。盤面描画は解像度に依存しない SVG を基本とし、将来的なアニメ最適化に備えて Canvas 実装も抽象化レイヤーで切り替え可能にします。
CPU思考はUIスレッドをブロックしないよう Web Worker に分離し、アルゴリズムは Minimax + Alpha-Beta を採用（弱=深さ2+簡易ヒューリスティック、普=深さ4、強=反復深化6–8／時間上限10秒）。ハッシュは Zobrist、思考中インジケータとUX用の意図的ディレイはUI側で制御します。
アクセシビリティは ARIA と react-aria に準拠し、レスポンシブ対応・コントラスト基準を満たします。国際化は react-i18next で実装し、チュートリアルは MDX で管理します。
永続化要件は最小のためバックエンドやDBは不要（サーバーレス/静的ホスティング: Vercel または Cloudflare Pages）。任意で設定のみ LocalStorage に保存します。
プロジェクト構成は core/（盤・合法手・反転・評価・探索の純関数）と ui/（表示・操作）、workers/（AI思考）に分離し、仕様の FR 群（合法手表示、無効手の視覚フィードバック、終了判定、難易度選択、思考インジケータ、終了ダイアログ、終了後の新規対局）を満たすタスクに分解して実装します。

そうすることで、技術スタック定義やプロジェクト構造などが書かれた計画文書(plan.md)、技術領域について詳細調査と選定理由を文書化した技術調査文書(research.md)、などを生成してくれます。

次に、plan.mdで定めた実装手順をベースに、それをタスクに落とし込む /tasks コマンドを実行します。その結果、一連の全ての実装タスクをtasks.mdに作成してくれます。

@claude /tasks

最後に /implement コマンドで実装します。以下のように「並列で実装できるタスクは並列で実装して」のようなプロンプトを追加で入れると、tasks.mdのタスクの中で並列に実装可能と判断したタスクを並列で実装してくれるようになります。

@claude /implement 並列で実装できるタスクは並列で実装して。

全ての実装が完了後、軽微な修正であればそのままClaudeにメンションして修正させることができます。大きな追加実装であれば新たに /specify コマンドで追加機能の要件を定義して上記のフローを実行します。 以下は実際に出来たオセロ対戦アプリの画面の一部です。

作成したオセロの画面

Issue連携とSub-issueの活用

GitHubを活用した開発では、Issueに書かれた要求を起点として開発するIssue駆動開発（チケット駆動開発）が一般的です。 そこで今回は、Issueを起点に作業を計画し、必要に応じてsub-issue機能も活用するため、 /create-sub-issue コマンドを新たに作成しました。このコマンドは親issueを細分化してsub-issueを作成する機能を持ち、実際は以下のフローになります。

  1. 親Issueを立てる
  2. 親Issueのスレッドでまずは大まかな作業計画を立てて、親Issueに紐づくブランチ(親ブランチ)でspec.mdを作成し、mainブランチターゲットでPRを作成（親PR）
  3. 親PR上でspec.mdのレビューをし、親PR上でplan.md、tasks.mdを続けて作成
  4. /create-sub-issue コマンドでtasks.mdの内容を参照し、sub-issue作成の指示を出してsub-issueを作成
  5. sub-issueの作業内容は、親ブランチを起点として作成し、PR作成時にも親ブランチをtargetに設定

作成されるsub-issueには以下のルールが適用されます：

  • タイトルに親issue番号と連番を付与
  • 最大6個まで作成可能
  • Github MCPの機能でissueの作成と親子関係を自動化

コマンドの内容は以下(create-sub-issue.md)：

---
description: 親Issueを細分化してsub-issueを作成するコマンド。以下のsub-issueの作成ルールに従ってsub-issueを作成してください。
---


#### **タスクの進め方**

元の大きなタスク（親Issue）を、いくつかの小さな作業（sub-issue）に分けて進めていきましょう。

### **1. タスクの分割**

まず、元のタスク（親Issue）の内容をよく読んで理解し、それを具体的な作業に分解します。分解した作業は、新しいタスク（sub-issue）として登録してください。

* **作成方法**: Github MCPの `sub_issue_write` という機能を使ってsub-issueを作成してください。
* **個数**: 作成するsub-issueは**6個まで**にしましょう。


### **2. sub-issueのタイトルルール**

作成するsub-issueのタイトルは、以下のルールに従ってください。

* **フォーマット**: タイトルの先頭に `[親Issue番号-連番]` を付けます。
* **例**: 親Issueの番号が「123」で、最初の作業なら `[123-1] 〇〇の実装` のようになります。
* **連番**: 連番は、作業を進める順番（優先度が高い順）に `1` から振ってください。


### **3. タスクの親子関係を設定**

Github MCPの `sub_issue_write` という機能を使って、元の親Issueと、新しく作成したsub-issueを関連付けます。これにより、タスクの全体像が分かりやすくなります。


### **4. 作業用ブランチの準備**

最後に、**親Issue用のブランチ**を1つ作成し、変更が何もない状態で構わないので、一度プッシュしてください。

##### **なぜこれが必要？**
この親ブランチを基準点（出発点）として、各sub-issueの作業用ブランチを作成したり、作業完了後のプルリクエストの送り先に指定したりするために必要です。

また、デフォルトのClaude Code GitHub Actionsではsub-issueを作成する権限がないため、親Issueに紐付けてsub-issueを作成するにはGitHub MCPを使用しました。.github/workflows/ 内のymlファイルのClaude Code GitHub Actionsの設定にclaude_argsとして以下のMCP周りの権限を追記します。

          claude_args: |
            --mcp-config .github/mcp-servers.json
            --allowedTools \
              Bash, Write, Edit, MultiEdit, Read, LS, Glob, Grep, WebFetch\
              mcp__github__create_branch,\
              mcp__github__issue_read,\
              mcp__github__issue_write,\
              mcp__github__sub_issue_write,\
              mcp__github__list_sub_issues,\
              mcp__github__create_pull_request,\
              mcp__github__get_pull_request,\
              mcp__github__get_pull_request_diff,\
              mcp__github__pull_request_read,\
              mcp__github__update_pull_request,\
              mcp__github__create_pending_pull_request_review,\
              mcp__github__add_comment_to_pending_review,\
              mcp__github__submit_pending_pull_request_review

また上記に含まれる .github/mcp-servers.json の設定は以下のようにしました。

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_TOKEN}" }
    }
  }
}

これにより、tasks.md作成後に

@claude /create-sub-issue

とコメントすることで、親Issueに紐付いたsub-issueが作成されます。実装はそれぞれのsub-issue内で実装コマンドをコメントしてClaudeに実装してもらいます。 こうすることで、Issue駆動な仕様駆動開発も実現可能です。

作成されたsub-issueの例

問題点と所感

仕様駆動開発を試行錯誤しながら試していく中で、以下のような課題点やトラブルシューティングに直面しましたので一例として紹介します。

テスト駆動開発の無視

Spec Kitではテスト駆動開発（TDD）を標準としています。 しかし、オセロ対戦アプリの実装では、下図のとおりテストコードが作成されないケースもありました。 原因は、 /implement コマンドでtasks.mdのタスクを実装する際に、テスト実装の優先度が低く設定されているためと考えられます。

TDDがスキップされた例

これを解決するための暫定アプローチとして、CLAUDE.mdに以下のような記述を追加することで、テスト駆動開発を厳守させるようにしました。

CLAUDE.md:

# 原則

- すべての変更は TDD（Red→Green→Refactor） を厳守する。

    1. Red: テスト作成 → 失敗を確認 → テストのみコミット

    2. Green: 実装作成 → すべてのテストを通す → 実装のみコミット（テストは変更禁止）

    3. Refactor: ふるまい不変の範囲でリファクタ → 実装のみコミット（テストは原則変更禁止）

- テストの改変は原則禁止。ただし、誤仕様または明白な不具合の場合に限り、tests-fix サブタスクとして別PRで扱う。

- モック実装・ハードコードは禁止（テスト過適合を避ける）。必要なら最小限のテストダブルを使用し、ケース拡張で過適合を検出。

- sub-issueのタスクとしてファイルを作成・編集する場合、mainブランチではなく、親Issueのブランチから分岐してブランチを作成してください。
- PRを作成する場合も、mainブランチではなく、親Issueのブランチに対して作成してください。
- 仕様の明確化のために質問・確認事項はまとめて質問してください。断片的に質問を繰り返すことは避けてください。

- 全ての会話の応答や文章の作成には日本語で出力してください。
- markdownファイルへの記述も基本的に日本語で行なってください。

自分は上記のCLAUDE.mdを編集することにより、TDDの強制を改めて行いました。一方でSpec Kitのコマンドを活用するのであれば、 /constitution <instruction> コマンドを実行して開発ツールや開発スタイル、コーディング規約などを指定することによりTDDを指定するのも良いかもしれません。またチーム開発の際は、チーム規約の追加も /constitution コマンドで指定しておくとSpek Kitのコマンドをさらに活用できると考えられます。1

まとめ

本記事では、Claude Code GitHub ActionsとSpec Kitを組み合わせることで、仕様駆動・エージェント駆動開発を試してみました。また、Issue/sub-issueとも組み合わせることで、Issue駆動な開発も実現できました。この手法により、ターミナルを開いて自分でコードを書かなくともGitHubのブラウザ上でのコメントによる操作のみで、上記のようなアプリが開発できたのは非常に感慨深かったです。 本記事で扱ったような内容が、現場に寄り添った提供方法の一案として検討していければ幸いです。

参考資料

  1. SpecKitでどこまでできる？コストはどれくらい？ https://speakerdeck.com/leveragestech/speckitdedokomadedekiru-kosutohadorekurai↩