Spec Kitを日本語化して試してみる
はじめに
GitHubから「Spec Kit」という開発ツールが登場しました。これは、AIと相談しながらアプリの設計図をしっかり固めることで、開発の手戻りをなくし、コーディングの精度をグッと上げてくれるツールです。
なんですが、Spec kitは日本語に対応していないため、そのまま使うと仕様もタスクリストもAIとのコミュニケーションも英語でほとんど理解できませんでした。
なので一部日本語化して試してみます。
Spec Kitってなに？
Spec Kitは、仕様駆動開発という、新しい開発スタイルを実現するための道具箱（ツールキット）です。
一番のポイントは、AIとの対話で作る実行可能な設計図（仕様書）を開発のど真ん中に置くこと。これまでの開発でよくあった「設計書とコードがだんだんズレていく…」という悩みを、解決してくれるようです。
Spec Kitでできること
Spec Kitは、以下のような機能（カスタムコマンド）を追加します。
1. 仕様書（設計図）の作成 (/specify)
/specifyコマンドを使い、作りたいもののアイデアを自然言語で伝えるだけで、AIが対話しながら構造化された仕様書を作成してくれます。これにより、関係者間の認識のズレや、要件の抜け漏れを防ぎます。
プロンプト例:
/specify Webブラウザで遊べるシンプルなインベーダーゲームを作りたい。
2. 実装計画の策定 (/plan)
/planコマンドを使い、完成した仕様書と使用したい技術スタックを基に、AIが具体的な実装計画を立ててくれます。どのようなファイル構成にするか、どういったテストを行うかといった、技術的な意思決定をサポートします。
プロンプト例:
/plan HTMLとCSS, JavaScriptだけで作ってほしい。描画にはCanvasを使いたい。
3. 具体的なタスクへの分解 (/tasks)
/tasksコマンドを使い、策定された実装計画を、エンジニアがすぐに着手できるレベルの具体的なタスクリストにまで分解します。これにより、開発者は次に何をすべきか迷うことなく、効率的に作業を進めることができます。このコマンドは引数が不要で、単体で実行します。
プロンプト例:
/tasks
Spec Kitを日本語化してインベーダーゲームを作ってみよう
簡単なインベーダーゲーム開発を例に、一連の流れを説明します。
動作環境
Spec Kitを動かすには、以下の環境が必要です。
※この記事では、AIエージェントとして Gemini CLI を使用することを前提に進めます。
- OS: Linux, macOS, または Windows（WSL2環境）
- Python: バージョン 3.11 以降
- uv: 高速なPythonパッケージ管理ツール
- Gemini CLI: Google製のAIエージェント
必要なツールのインストール
「動作環境」のツールがまだPCに入っていない場合は、ここで準備します。
Gemini CLI
Google製のAIエージェントです。詳しいインストール方法は、こちらの記事を参考にセットアップを進めてください。
Python
Gemini CLIやuvの動作に必要です。Python公式サイトからご自身のOSに合ったインストーラーをダウンロードし、実行してください。
その際、「Add Python to PATH」のチェックを入れると、後の手順がスムーズになります。
uv
高速なPythonパッケージ管理ツールです。Pythonをインストールした後、ターミナル（コマンドプロンプト）で以下のコマンドを実行してインストールします。
pip install uv
Spec Kitプロジェクトの初期化
プロジェクトの初期化には以下のコマンドを使用します。
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
<PROJECT_NAME> の部分に、作成したいプロジェクト名（ディレクトリ名）を指定します。
https://github.com/github/spec-kit.gitの部分は、利用したいリポジトリURLに置き換えることもできます。
uvx --from git+https://github.com/username/repo.git specify init <PROJECT_NAME>
今回はインベーダーゲームの作成をするので、
uvx --from git+https://github.com/github/spec-kit.git specify init invaders-game
と入力します。
すると以下のようなインストール画面が表示されますので、今回はGemini CLIを選択してインストールします。
これで指定した名前でプロジェクトディレクトリが作成され、その中に specs, templates といったファイルやフォルダが自動で生成されます。
これで、開発を始める準備が整いましたので、生成されたディレクトリに移動してください。
cd invaders-game
Spec Kitの日本語化
Spec Kitは、そのままだと基本的に英語でAIとやり取りをします。日本語でよりスムーズに使うためにAIへの指示が書かれたいくつかのファイルを編集します。
Spec Kitの操作はカスタムコマンドのため、Gemini CLIの場合、プロジェクトのルートディレクトリ直下の.gemini/commands/にspecify.toml、plan.toml、tasks.tomlが生成されています。
それぞれのファイルを開くと以下のような箇所がありますので、
prompt = """
この下の行に日本語でやりとりするための指示を追加します。
prompt = """
ファイル生成やユーザーとのコミュニケーションはすべて日本語で行ってください。
このように各カスタムコマンドファイルのプロンプトの最初に指示を追記しておくことで、AIからの出力も日本語になり、その後の開発がグッと楽になります。
STEP 1：仕様を決める (/specify)
準備ができたら、AIエージェントのチャット画面を開き、/specify コマンドを使って作りたいゲームの概要を伝えます。
ここで重要なのは、Spec Kitはあなたの思考を読み取って書かれていないことまで補完してくれる魔法のツールではありません。
ここで伝える仕様を曖昧にしてしまうと曖昧な仕様しか作成されませんので、必ず詳細な内容を伝えてください。
今回はインベーダーゲームの作成をするため、ゲームの仕様を伝えます。
プロンプト例：
/specify Webブラウザで遊べるシンプルなインベーダーゲームを作りたい。
以下ゲームの仕様になります。
画面の中央やや上方に、縦5段 横11列の、計55のインベーダーが現れます。
インベーダーは隊列状態でまとまって横移動しながら、端にたどり着く度に一段下がり、下がり終えると進行方向を逆方向に変えて再び移動しはじめます。
これを繰り返すことによって、段々と下に降りてきます。
インベーダーが画面最下部のプレイヤーの位置まで降りてきたら、自陣が占領されたことになり、残機があってもゲームオーバーとなります。
それまでにインベーダーを全滅させればクリアとなります。
自陣に関しては、ビーム砲（自機）が一門、画面の下段に表示されます。
ビーム砲は左右にしか動けず、弾を撃つ場合でも1発限定で、しかも自分が撃った飛翔中の弾がどこかに着弾するまでは、次の弾が撃てません。
ビーム砲の上にはいくつかトーチカ（防御壁のようなもの）があり、ビーム砲を敵の攻撃から護る役割を最初は果たしています。
トーチカはインベーダーからの攻撃を受けた場合も、またビーム砲がトーチカ下方からビームを撃った場合も、少しずつ破損してゆき、さらには降りてきたインベーダーが触れることでも削られてしまいます。
プレーヤーは、トーチカの下に入ってインベーダーからの攻撃を避けたり、そこから出てインベーダーを攻撃する。
画面がスクロールすることはなく、インベーダーやビーム砲が画面からはみ出すことなどはありません。
インベーダーを撃墜した際の得点は一番上の段が30点、その下の2段が20点、その下の2段が10点です。
逆に敵インベーダーからの攻撃でビーム砲が被弾した場合、ミスとなりビーム砲を1門失う。
インベーダーは撃墜され数が減るにつれ、徐々に移動速度が速くなっていきます。
インベーダーが最下段まで降りてしまうと、占領されたということでビーム砲は破壊されてしまい、ゲーム終了となり「GAME OVER」の文字が表示されます。
この指示を基に、ゲームのルールや登場要素を定義した仕様書としてspecsディレクトリにspec.mdが生成されます。
# Feature Specification: Webブラウザで遊べるシンプルなインベーダーゲーム
**Feature Branch**: `001-web-5-11`
**Created**: 2025-09-09
**Status**: Draft
**Input**: User description: "Webブラウザで遊べるシンプルなインベーダーゲームを作りたい。 以下ゲームの仕様になります。 画面の中央やや上方に、縦5段 横11列の、計55のインベーダーが現れます。 インベーダーは隊列状態でまとまって横移動しながら、端にたどり着く度に一段下がり、下がり終えると進行方向を逆方向に変えて再び移動しはじめます。 これを繰り返すことによって、段々と下に降りてきます。 インベーダーが画面最下部のプレイヤーの位置まで降りてきたら、自陣が占領されたことになり、残機があってもゲームオーバーとなります。 それまでにインベーダーを全滅させればクリアとなります。 自陣に関しては、ビーム砲（自機）が一門、画面の下段に表示されます。 ビーム砲は左右にしか動けず、弾を撃つ場合でも1発限定で、しかも自分が撃った飛翔中の弾がどこかに着弾するまでは、次の弾が撃てません。 ビーム砲の上にはいくつかトーチカ（防御壁のようなもの）があり、ビーム砲を敵の攻撃から護る役割を最初は果たしています。 トーチカはインベーダーからの攻撃を受けた場合も、またビーム砲がトーチカ下方からビームを撃った場合も、少しずつ破損してゆき、さらには降りてきたインベーダーが触れることでも削られてしまいます。 プレーヤーは、トーチカの下に入ってインベーダーからの攻撃を避けたり、そこから出てインベーダーを攻撃する。 画面がスクロールすることはなく、インベーダーやビーム砲が画面からはみ出すことなどはありません。 インベーダーを撃墜した際の得点は一番上の段が30点、その下の2段が20点、その下の2段が10点です。 逆に敵インベーダーからの攻撃でビーム砲が被弾した場合、ミスとなりビーム砲を1門失う。 インベーダーは撃墜され数が減るにつれ、徐々に移動速度が速くなっていきます。 インベーダーが最下段まで降りてしまうと、占領されたということでビーム砲は破壊されてしまい、ゲーム終了となり「GAME OVER」の文字が表示されます。"
---
## ⚡ Quick Guidelines
- ✅ Focus on WHAT users need and WHY
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
- 👥 Written for business stakeholders, not developers
### Section Requirements
- **Mandatory sections**: Must be completed for every feature
- **Optional sections**: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
---
## User Scenarios & Testing *(mandatory)*
### Primary User Story
プレイヤーはビーム砲を左右に操作し、画面上部から隊列を組んで迫ってくるインベーダーを撃墜する。プレイヤーは、インベーダーからの攻撃を避けるために、遮蔽物であるトーチカを戦略的に利用する。全てのインベーダーを撃墜すればステージクリアとなる。インベーダーが画面最下部まで到達すると、自陣が占領されゲームオーバーとなる。
### Acceptance Scenarios
1. **Given** ゲームが開始される, **When** プレイヤーが左右の入力を行う, **Then** ビーム砲が画面下部で左右に移動する。
2. **Given** ビーム砲から弾が発射されていない, **When** プレイヤーが射撃入力を行う, **Then** ビーム砲から弾が1発発射される。
3. **Given** プレイヤーの弾がインベーダーに命中する, **When** 弾が着弾する, **Then** インベーダーが消滅し、対応するスコアが加算される。
4. **Given** インベーダーの数が減少する, **When** インベーダーが撃墜される, **Then** 残りのインベーダーの移動速度が上昇する。
5. **Given** インベーダーの弾がビーム砲に命中する, **When** 弾が着弾する, **Then** ビーム砲が破壊され、残機が1つ減少する。
6. **Given** 全てのインベーダーが撃墜される, **When** 最後のインベーダーが消滅する, **Then** ゲームクリアメッセージが表示される。
7. **Given** インベーダーの隊列が画面最下部に到達する, **When** インベーダーが防衛ラインを越える, **Then** ゲームオーバーメッセージが表示される。
### Edge Cases
- プレイヤーの弾が飛翔中に、追加で弾を発射しようとするとどうなるか？ -> 新しい弾は発射されない。
- プレイヤーの弾がトーチカに当たるとどうなるか？ -> トーチカが損傷する。
- インベーダーがトーチカに接触するとどうなるか？ -> トーチカが削られる。
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: システムは、55体のインベーダーを5行11列の隊列で画面中央上部に表示しなければならない。
- **FR-002**: システムは、インベーダーの隊列を一体として左右に移動させ、画面の端に到達するたびに一段下げ、移動方向を反転させなければならない。
- **FR-003**: システムは、インベーダーの数が減少するにつれて、その移動速度を段階的に上昇させなければならない。
- **FR-004**: システムは、プレイヤーが操作するビーム砲を画面下部に1門表示しなければならない。
- **FR-005**: ビーム砲は、画面の水平方向（左右）にのみ移動できなければならない。
- **FR-006**: ビーム砲は、一度に1発の弾しか発射できず、その弾が画面上から消える（着弾または画面外）まで次の弾を発射できないようにしなければならない。
- **FR-007**: システムは、ビーム砲とインベーダーの間に、防御壁として機能する複数のトーチカを配置しなければならない。
- **FR-008**: トーチкаは、インベーダーの弾、プレイヤーの弾、またはインベーダー自身との接触によって、少しずつ破壊されなければならない。
- **FR-009**: インベーダーを撃墜した際のスコアは、最上段が30点、上から2段目と3段目が20点、4段目と5段目が10点として加算されなければならない。
- **FR-010**: インベーダーからの攻撃がビーム砲に命中した場合、プレイヤーの残機を1つ減らし、ミスとして処理しなければならない。
- **FR-011**: 画面上の全てのインベーダーを撃墜した場合、システムはゲームクリア状態に移行しなければならない。
- **FR-012**: インベーダーのいずれかが画面最下部に到達した場合、システムは残機に関わらずゲームオーバー状態に移行し、「GAME OVER」という文字を表示しなければならない。
- **FR-013**: ゲームのプレイ領域は単一の画面に限定され、スクロールしてはならない。
### Key Entities *(include if feature involves data)*
- **インベーダー (Invader)**: 状態（位置[x, y], 生存状態）、種類（点数を決定）、移動速度、隊列情報を持つ。
- **ビーム砲 (PlayerCannon)**: 状態（位置[x], 残機数）、弾の状態（発射中か否か）を持つ。
- **弾 (Bullet)**: 状態（位置[x, y], 飛翔中か否か）、発射元（プレイヤーかインベーダーか）を持つ。
- **トーチカ (Bunker)**: 状態（位置[x, y], 破壊度/耐久値）を持つ。
- **ゲーム状態 (GameState)**: 現在のスコア、ゲームのステータス（プレイ中, クリア, ゲームオーバー）を管理する。
---
## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*
### Content Quality
- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed
### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Scope is clearly bounded
- [ ] Dependencies and assumptions identified
---
## Execution Status
*Updated by main() during processing*
- [ ] User description parsed
- [ ] Key concepts extracted
- [ ] Ambiguities marked
- [ ] User scenarios defined
- [ ] Requirements generated
- [ ] Entities identified
- [ ] Review checklist passed
---
（まだ一部英語が残っていますが）日本語で仕様の作成ができました。
STEP 2：計画を立てる (/plan)
次に、/plan コマンドで、ゲームをどのような技術で作るかを指示します。
プロンプト例：
/plan HTMLとJavascriptで作る。ゲーム画面の描画にはCANVAS要素を使用する。
指定された技術スタックに基づき、ファイル構成や、各ファイルがどのような役割を持つかの実装計画としてspecsディレクトリにplan.md、research.md、quickstart.md、data-model.mdなどが生成されます。
STEP 3：タスクに分解する (/tasks)
次に/tasks コマンドで、具体的な開発タスクのリストを作成します。
プロンプト例：
/tasks
計画書を基に、開発者がすぐ着手できる順番でタスクリストとしてspecsディレクトリにtasks.mdが生成されます。
# Tasks: Webブラウザで遊べるシンプルなインベーダーゲーム
**Input**: Design documents from `/specs/001-web-5-11/`
**Prerequisites**: plan.md, research.md, data-model.md, quickstart.md
## Format: `[ID] [P?] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- Include exact file paths in descriptions
## Path Conventions
- Paths shown below assume the single project structure defined in `plan.md`.
## Phase 1: Setup
- [ ] T001: `index.html` ファイルを作成し、`quickstart.md` に記載されている基本的なHTML構造を記述する。
- [ ] T002: `style.css` ファイルを作成し、`quickstart.md` に記載されている基本的なCSSスタイルを記述する。
- [ ] T003: `src` ディレクトリを作成する。
- [ ] T004: `src/main.js` ファイルを作成し、Canvasのコンテキストを取得して黒で塗りつぶす初期コードを記述する。
## Phase 2: Core Model Implementation
- [ ] T005: [P] `src/player.js` ファイルを作成し、`data-model.md` に基づいて `Player` クラスの基本構造（コンストラクタとプロパティ）を定義する。
- [ ] T006: [P] `src/invader.js` ファイルを作成し、`data-model.md` に基づいて `Invader` クラスの基本構造を定義する。
- [ ] T007: [P] `src/bullet.js` ファイルを作成し、`data-model.md` に基づいて `Bullet` クラスの基本構造を定義する。
- [ ] T008: [P] `src/bunker.js` ファイルを作成し、`data-model.md` に基づいて `Bunker` クラスの基本構造を定義する。
## Phase 3: Game Logic Implementation
- [ ] T009: `src/game.js` ファイルを作成し、`GameState` を管理する `Game` クラスを定義する。このクラスは、プレイヤー、インベーダーの配列、弾の配列などを保持する。
- [ ] T010: `src/main.js` で `Game` クラスのインスタンスを作成し、`requestAnimationFrame` を使用した基本的なゲームループを開始する。
- [ ] T011: `Player` クラスに、Canvasに自身を描画する `draw(ctx)` メソッドを実装する。
- [ ] T012: `Invader` クラスに、`draw(ctx)` メソッドを実装する。
- [ ] T013: `Bullet` クラスに、`draw(ctx)` メソッドを実装する。
- [ ] T014: `Game` クラスのゲームループ内で、すべてのゲームオブジェクト（プレイヤー、インベーダー）を描画する処理を追加する。
- [ ] T015: `index.html` に `script` タグを追加して、作成した `player.js`, `invader.js`, `bullet.js`, `bunker.js`, `game.js` を読み込むようにする。
## Phase 4: Interaction and Dynamics
- [ ] T016: `main.js` でキーボードイベントリスナー（`keydown`, `keyup`）をセットアップし、プレイヤーの左右の移動を制御する。
- [ ] T017: `Player` クラスに、キー入力に応じて位置を更新する `update()` メソッドを実装する。
- [ ] T018: `main.js` で `Spacebar` キーによる射撃イベントを処理し、`Player` クラスに `shoot()` メソッドを実装して新しい `Bullet` を生成する。
- [ ] T019: `Game` クラスに、インベーダーの隊列全体を左右に動かし、端に達したら下に移動させる `updateInvaders()` メソッドを実装する。
- [ ] T020: `Game` クラスのゲームループで、すべての弾の位置を更新する `updateBullets()` メソッドを実装する。
## Phase 5: Collision Detection and Game Rules
- [ ] T021: `Game` クラスに、プレイヤーの弾とインベーダーの衝突を検出するロジックを実装する。衝突した場合、インベーダーと弾を非アクティブにし、スコアを加算する。
- [ ] T022: `Game` クラスに、インベーダーの弾（ランダムに発射）とプレイヤーの衝突を検出するロジックを実装する。衝突した場合、プレイヤーの残機を減らす。
- [ ] T023: `Bunker` クラスに、弾との衝突を検出し、衝突した部分の `damageState` を更新するロジックと、それに応じて自身を描画する `draw(ctx)` メソッドを実装する。
- [ ] T024: `Game` クラスに、ゲームオーバー（インベーダーが最下段に到達、または残機が0）とゲームクリア（すべてのインベーダーを撃墜）の条件を判定するロジックを実装する。
- [ ] T025: 画面にスコア、残機数、ゲームオーバー/クリアメッセージを表示するUI描画処理を実装する。
## Dependencies
- **Phase 1** (T001-T004) must be completed before all other phases.
- **Phase 2** (T005-T008) can be done in parallel but must be completed before Phase 3.
- **T009** and **T010** block most of Phase 4 and 5.
- **T015** must be done after all class files from Phase 2 are created.
## Parallel Example
# Phase 2 tasks can be executed in parallel:
Task: "T005 [P] `src/player.js` ファイルを作成し、`data-model.md` に基づいて `Player` クラスの基本構造（コンストラクタとプロパティ）を定義する。"
Task: "T006 [P] `src/invader.js` ファイルを作成し、`data-model.md` に基づいて `Invader` クラスの基本構造を定義する。"
Task: "T007 [P] `src/bullet.js` ファイルを作成し、`data-model.md` に基づいて `Bullet` クラスの基本構造を定義する。"
Task: "T008 [P] `src/bunker.js` ファイルを作成し、`data-model.md` に基づいて `Bunker` クラスの基本構造を定義する。"
これで計画に基づいた実行可能なタスクリストが生成されました。
こちらも（まだ一部英語が残っていますが）日本語でのタスクリストが作成され、どんなタスクがあるのか理解できるようになりました。
STEP 4：実装する
最後にタスクリストに従って開発をします。
タスクリストに従って開発をしてください
この指示を最後に後は自動でタスクリストに従ってどんどん開発を進めてくれます。
もちろん途中のコミュニケーションは日本語で対応してくれます。
ここから先は自動で進めてくれるとはいえ、それなりに時間がかかりますので、適宜AIへの許可を出しつつコーヒーでも飲みながら待機しましょう。
STEP 5：完成
だいたい30分後くらいに完成しました。
ではさっそくインベーダーゲームで遊んでみます。
ちゃんと遊べるインベーダーゲームができましたね。
さいごに
そのままのSpec Kitでは仕様書、実装計画、タスクリスト、AIとのコミュニケーションがすべて英語だったためあまり理解ができなかったのですが、日本語化することでスムーズに開発が進んでいることが確認できました。
今までのバイブコーディングでは、なんとなく開発できてはいるものの、実際にはうまく動作しないという問題が稀にありましたが、それが解消されたように感じます。
が、まだ完全ではないですね。
もちろんAIのコーディング能力がまだ足りていないところがあるというのもありますが、一番は仕様や指示が曖昧だったことだと思うので、Spec Kitによりそこが明確になることで、ネックだったところの一つが解消されそうです。
今後のバイブコーディングはこのような仕様駆動開発が中心となっていくのではないでしょうか。
参考文献
Discussion