たねやつの木

Photographs, Keyboards and Programming

GitHubの新ツールspec-kitを実際に動かしてできたことと、注意点など

AI gemini/gemma プログラミング

こんにちは、たねやつです。

GitHubが開発したAIエージェント向けのフレームワーク「spec-kit」が面白そうだったので、実際に触ってみて簡単なTODOアプリの仕様を作成してみました。 今回はその手順と使ってみた感想をまとめていきます。

この記事でできること

  • spec-kitの基本的な使い方（初期化、仕様作成、タスク分割）がわかる
  • spec-kitを使った開発フローの雰囲気を知る

事前に必要なもの

  • Python環境
  • Gemini CLIなどのAI搭載CLIツール

spec-kitとは

spec-kitは、自然言語で書かれた要件から仕様書を生成し、開発タスクを計画・実行するためのAIエージェントフレームワークです。 GitHubによって開発されており、開発の初期段階における仕様の明確化やタスクの洗い出しを効率化することを目的としています。

試してみる

公式ドキュメントの手順通りに進めて、簡単なTODOアプリを作成してみます。

プロジェクトの初期化

まず、uvxコマンドを使ってプロジェクトを初期化します。

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

すると、使用したいCLIツールを選択するプロンプトが表示されます。今回はgemini-cliを選択しました。

初期化が完了すると、プロジェクトディレクトリと初期ファイルが生成されます。 CONSTITUTION.mdというファイルがあり、ここにはプロジェクトにおける普遍的なルール（例えば「対話やファイル作成はすべて日本語で行う」など）を記述しておくことで、spec-kitの振る舞いを制御できるようです。

仕様書の作成

次に、/specifyコマンドを使って作成したいアプリケーションの概要を伝えます。

/specify CRUD操作が可能なシンプルなTODOアプリを作成して

このコマンドを実行すると、spec-kitが内部で処理を行い、spec/spec.mdというファイルに仕様書を生成してくれます。 以下が実際に生成された仕様書の一部です。

# Feature Specification: Simple TODO App with CRUD

**Feature Branch**: `001-crud-todo`  
**Created**: 2025-09-04  
**Status**: Draft  
**Input**: User description: "CRUD操作が可能なシンプルなTODOアプリを作成して"

## Execution Flow (main)
1. Parse user description from Input
   → If empty: ERROR "No feature description provided"
2. Extract key concepts from description
   → Identify: actors, actions, data, constraints
3. For each unclear aspect:
   → Mark with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
   → If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
   → Each requirement must be testable
   → Mark ambiguous requirements
6. Identify Key Entities (if data involved)
7. Run Review Checklist
   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
   → If implementation details found: ERROR "Remove tech details"
8. Return: SUCCESS (spec ready for planning)

---
(中略)
---

## User Scenarios & Testing *(mandatory)*

### Primary User Story
A user can add, view, edit, and delete their tasks in a TODO list.

### Acceptance Scenarios
1. **Given** the TODO list is empty, **When** a user adds a new task "Buy milk", **Then** the task "Buy milk" should appear in the list.
2. **Given** a task "Buy milk" exists, **When** a user marks it as complete, **Then** the task should be shown as completed.
3. **Given** a task "Buy milk" exists, **When** a user deletes it, **Then** the task should be removed from the list.
4. **Given** a task "Buy milk" exists, **When** a user edits it to "Buy almond milk", **Then** the task should be updated to "Buy almond milk".

### Edge Cases
- What happens when a user tries to add an empty task?
- What happens when a user tries to edit a non-existent task?

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST allow users to create a new task with a title and a status (e.g., pending, completed).
- **FR-002**: System MUST display the list of all tasks.
- **FR-003**: System MUST allow users to update the title and status of an existing task.
- **FR-004**: System MUST allow users to delete a task.
- **FR-005**: System MUST persist the tasks.

### Key Entities *(include if feature involves data)*
- **Task**: Represents a single TODO item. Attributes: id, title, status.

ユーザーシナリオや機能要件が自動で定義されており、非常に詳細です。

実装計画の作成

次に、/planコマンドで技術スタックを指示します。

/plan フロントエンドはNuxt.jsとTailwandCSSで作成してください。データの保存にはLocalStrageを使用してください。

これを実行すると、tasks.mdというファイルが生成され、開発に必要なタスクが一覧化されます。

# Implementation Tasks for Simple TODO App

## Phase 1: Project Setup

- [ ] T001: Initialize a new Nuxt.js 3 project.
  - File: `.`
  - Command: `npx nuxi init <project-name>`
- [ ] T002: Install Tailwind CSS and configure it for the project.
  - File: `tailwind.config.js`, `nuxt.config.ts`
  - Command: `npm install -D tailwindcss @nuxtjs/tailwindcss postcss autoprefixer`
- [ ] T003: Create basic project structure (pages, components, store).
  - File: `src/pages/`, `src/components/`, `src/store/`
  - Command: `mkdir -p src/pages src/components src/store`

## Phase 2: Core TODO Logic (LocalStorage & State Management)

- [ ] T004 [P]: Define Task interface/type.
  - File: `src/types/todo.d.ts`
  - Command: Create file with Task interface.
- ...

ここまで来たら、あとは/tasksコマンドでタスクの整理を行い、T001から進めてのように指示を出すことで、実際の開発作業を進めていくことになります。

使ってみた感想

実際に spec-kit を触ってみて、その思想やポテンシャルを強く感じました。良かった点と、今後さらに期待したい点をまとめてみます。

良かった点 (Pros)

  • 思考の壁打ち相手になる仕様書生成 /specify コマンドで曖昧な要件を投げかけるだけで、ユーザーシナリオや機能要件まで洗い出してくれるのは非常に強力です。自分一人で考えていると漏れてしまいがちな観点をAIが提示してくれるため、要件定義の解像度を上げるための優れた「壁打ち相手」になると感じました。

  • タスクの標準化と属人性の排除 /plan コマンドによって、仕様書から具体的な開発タスクリストが生成される点も素晴らしいです。これにより、開発者が「まず何から手をつけるべきか」を悩む時間が減り、すぐに実装に取り掛かれます。また、誰がプロジェクトを開始しても同じ構造のタスクが生成されるため、作業の属人化を防ぎ、チーム開発における透明性の向上にも繋がるでしょう。

  • 構造化された開発フロー 「要件定義 (specify) → 技術計画 (plan) → 実装 (tasks)」という一貫したフローがフレームワークとして提供されているため、プロジェクトの見通しが非常に良くなります。この構造に従うことで、個人の思いつきや場当たり的な開発ではなく、計画に基づいた体系的な開発プロセスを自然と実践できるのが大きなメリットです。

今後の期待と要望 (Cons & Wishes)

  • 日本語対応と国際化(i18n) CONSTITUTION.md で日本語利用を指示しても、現状では仕様書などが英語で生成されます。ドキュメントはチームの共通言語となるため、今後のアップデートでの国際化対応に期待。

  • 既存プロジェクトへの導入支援 現状のフローは新規プロジェクトの立ち上げ (init) が基本となっています。しかし、開発途中の既存プロジェクトに後から spec-kit を導入したいケースも多いはずです。既存のコードベースを解析して自動で spec.md や tasks.md の草案を生成してくれるような import 機能があれば、活用の幅が大きく広がると思います。

  • GUI/Web UIによる可視化 CLIは強力ですが、非エンジニアも巻き込んで仕様を確認・合意形成する上では、グラフィカルなインターフェースが有効です。Web UI上で仕様書を閲覧・編集したり、タスクの進捗をカンバン形式で管理したりできると、プロジェクト全体の可視性が高まり、より多くのユーザーにとって使いやすいツールになる気がします。

最後に

今回はGitHub製のAIエージェントフレームワーク「spec-kit」を試してみました。 単なるコード生成AIとは一線を画し、開発の上流工程である「仕様定義」と「計画」に焦点を当てている点が非常に興味深いです。自然言語から開発の初期段階を体系化・自動化してくれるこのツールは、個人開発からチーム開発まで、幅広いシーンで生産性を向上させる大きなポテンシャルを秘めていると感じました。

まだ発展途上のツールですが、今後の進化が非常に楽しみです。