Zenn
📋

小規模な既存プロジェクトでSpec Kitを使用し仕様書駆動してみる

に公開
AI
GitHub
開発手法
speckit
tech

はじめに

GitHubが2025年9月にリリースしたSpec Kitは、仕様書駆動開発を支援するツールキットです。多くの記事では新規プロジェクトでの使用例が紹介されていますが、実際の開発現場では既存プロジェクトに機能追加するケースが多いのではないでしょうか。

本記事では、既存プロジェクトでSpec Kitを使って機能追加を行った実体験を紹介します。

Spec Kitとは

Spec KitはGitHubが公開したオープンソースのツールキットで、仕様書駆動開発をAIと組み合わせて効率化します。主な特徴：

  • 自然言語で書かれた仕様書から開発計画を自動生成
  • Claude CodeやGitHub Copilotなどのコーディングエージェントと連携
  • 仕様→計画→実装のワークフローを体系化

既存プロジェクトでの導入

前提条件・インストール

# uvのインストール（macOS）
brew install uv

Spec Kitはuvxを使って実行できます：

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

基本的な使い方との違い

新規プロジェクトでは uvx ... specify init を使いますが、既存プロジェクトでは --here オプションを使用します。

# 新規プロジェクト
uvx --from git+https://github.com/github/spec-kit.git specify init my-new-project

# 既存プロジェクト
uvx --from git+https://github.com/github/spec-kit.git specify init --here

この一点の違いで、既存のプロジェクト構造を保ったまま仕様書駆動開発を導入できます。

Image from Gyazo

ただし、スクリーンショットで確認できるように、既存プロジェクトで --here オプションを使用すると重要な警告が表示されます：

Warning: Current directory is not empty (32 items)
Template files will be merged with existing content and may overwrite existing files
Do you want to continue? [y/N]:

この警告は、Spec Kitのテンプレートファイルが既存ファイルと競合する可能性があることを示しています。既存ファイルが上書きされる可能性があるため、事前のバックアップやgitコミットが必須です。

特に注意が必要なのは以下のファイル名の競合です：

  • spec.md - 既存の仕様書がある場合
  • tasks.md - タスク管理ファイルがある場合
  • CLAUDE.md - Claude関連の設定ファイルがある場合
  • その他のテンプレートファイル

既存プロジェクトで同名のファイルが重要な役割を果たしている場合、上書きによってプロジェクトが破損する危険性があります。導入前に既存ファイル一覧を確認し、競合する可能性のあるファイルは事前にリネームまたはバックアップしておくことを強く推奨します。

実際の導入手順

  1. 既存プロジェクトのルートディレクトリで実行
  2. 対話的に仕様書を作成
  3. 自動的にブランチが作成され、関連ファイルが生成される

生成されるファイル：

  • spec.md - 機能仕様書
  • tasks.md - 実装タスク一覧
  • CLAUDE.md - AIエージェント用の設定

実践：機能追加してみる

個人プロジェクトの既存Webアプリケーションに新しい機能を追加する際にSpec Kitを使用しました。

今回の検証環境

  • プロジェクト規模：個人開発の小〜中規模プロジェクト
  • 既存仕様書：詳細な仕様書はなく、基本的なREADMEのみ
  • コードベース：比較的シンプルな構成

仕様書の作成

自然言語で機能要件を記述するだけで、Spec Kitが構造化された仕様書を生成してくれました。個人プロジェクトという性質上、既存の仕様書が少ないため、Spec Kitが既存コードを分析して適切な実装計画を提案してくれた点が特に有効でした。

実装フロー

  1. 仕様定義 - 追加したい機能を自然言語で記述
/specify "追加したい機能の概要"

自然言語の要求を構造化された仕様書に変換。specs/xxx/spec.mdが生成され、同時にgitブランチも作成される。

  1. 計画生成 - 既存アーキテクチャに適合する実装プランを自動生成
/plan

「何を作るか」を「どうやって作るか」に変換。plan.md、research.md、データモデルなどが生成される。

  1. タスク分解 - 具体的な実装ステップに分解
/tasks

実装計画を具体的な作業単位まで分解。推定工数や依存関係を含むtasks.mdが生成される。

  1. 実装 - AIエージェントと協力して実装
@specs/xxx/plan.md に従って実装を進めて

生成された計画に基づいて、Claude CodeやGitHub Copilotなどのコーディングエージェントを選んで実装。

既存プロジェクトならではのメリット

既存コードとの整合性

新規プロジェクトと異なり、既存のアーキテクチャやコーディング規約を考慮した実装計画が生成されます。これにより、既存システムに自然に溶け込む機能追加が可能でした。

段階的な導入

プロジェクト全体を一度に変更するのではなく、特定の機能追加から始められるため、リスクを最小限に抑えながらSpec Kitの効果を体験できます。

制約と今後の課題

今回は個人プロジェクト（既存仕様書が少ない環境）での検証だったため、以下の点は未検証です：

  • 大規模プロジェクトでの動作
  • 詳細な既存仕様書がある環境での整合性

企業の本格的なプロジェクトでの効果については、さらなる検証が必要と考えています。

まとめ

既存プロジェクトでのSpec Kit使用は、--here オプション一つで簡単に導入できました。特に個人開発や小〜中規模のプロジェクトでは、既存コードベースとの整合性を保ちながら機能追加できる点が大きなメリットでした。

ただし今回は比較的シンプルな環境での検証のため、より複雑な既存プロジェクトでの効果については今後の検証課題です。まだ発展途上のツールですが、適切な環境では積極的に活用していく価値があると感じました。

参考資料

Spec Kitについてより詳しく知りたい方は、以下の記事もご参照ください：

Discussion