AI時代の新常識：「Vibe Codingの限界」と「SDD - 仕様駆動開発 / スペック駆動開発」の実践

Last updated at 2025-10-13Posted at 2025-10-13

"Code is no longer the source of truth. Intent is." — GitHub, 2024

「もはやコードは真実の源泉ではない。意図こそが真実である。」— GitHub, 2024

📚 この記事の位置づけ

本記事は、AI時代の開発手法の転換を扱うシリーズの一部です。

関連記事：

コーディングエージェント時代のコンテキストエンジニアリング実践ガイド - AIへの情報の渡し方
プロンプトエンジニアリング2.0 - プロンプト最適化

本記事では、GitHubが2024年に提唱した**Spec-Driven Development (SDD - 仕様駆動開発 / スペック駆動開発)**の実践方法を、実際のツールと事例を交えて解説します。

あなたは「Vibe Coding」していませんか？
Spec-Driven Developmentとは
なぜ今SDDなのか：プログラミングの進化史
SDDの4フェーズワークフロー
実践：GitHub Spec Kitを使った開発
Kiroによる実践例：Towers of Hanoiゲーム
適切なアプローチの選択
実際の導入事例と効果
今日から始める実践ガイド

あなたは「Vibe Coding」していませんか？

OpenAIのSean Groveの警告

"The person who communicates the best will be the most valuable programmer in the future. The new scarce skill is writing specifications that fully capture your intent and values."

「将来、最も価値のあるプログラマーは、最もうまくコミュニケーションできる人になるでしょう。新たに不足するスキルは、あなたの意図と価値を完全に捉えた仕様を書くことです。」

— Sean Grove, OpenAI (AI Engineer Conference, 2024)

Vibe Codingとは？

あなた: 「ユーザー権限システムを実装して」

AI: 「はい！標準的なRBACシステムを作成します」
    → Admin と User の2つのロール
    → シンプルで完璧に動く

あなた: 「あれ、細かい権限設定は？」
    「一時的なアクセス権は？」
    「既存のIDプロバイダーとの連携は？」

AI: 「...それは仕様に書いてませんでしたね」

3時間後...
あなた: 「結局、全部作り直し 💀」

これが「Vibe Coding」の罠です。

コードは完璧に動くように見えるが、実は間違った問題を解決していることに後から気づく。

Vibe Codingの本質的な問題

「コードを書くことは、決してボトルネックではなかった」 — The New Stack, 2024

真のボトルネックは：

問題領域	具体的な課題
要件の収集	何を作るべきか、なぜ作るべきか
設計の整合性	チーム間の設計アライメント
技術的負債	競合する要件の解決
コードレビュー	レビューに厳密性を持たせる
知識の保存	シニアエンジニアが辞めたときの対策

AIがコードを大量生成しても、複雑性は消えない。それはデバッグ、テスト、デプロイメントパイプラインに移動するだけ。 — Amazon AI IDE発表より

コンテキストの質が成功を決める

"The main thing that determines whether an agent succeeds or fails is the quality of the context it's given."

「エージェントが成功するか失敗するかを決定する主な要因は、与えられたコンテキストの質である。」

— The New Stack, 2024

問題: LLMのコンテキストウィンドウは拡大している
しかし: より多くのコンテキストを与えると、品質が低下する

解決策: 「refined context（洗練されたコンテキスト）」
       = 仕様書（Specification）

仕様書 = AIを圧倒させずに効果的にするための、適切な量の情報

実際の開発者の声

// GitHub記事より引用
「AIは"literal-minded pair programmer"（文字通りに解釈するペアプログラマー）
のようなものです。

曖昧な指示を与えると、曖昧な結果が返ってきます。」

解決策：Spec-Driven Development

Spec-Driven Developmentとは

定義

Spec-Driven Development (SDD) = 仕様を「唯一の真実の源泉（Single Source of Truth）」とし、そこからすべてのコード、テスト、ドキュメントを導き出す開発手法

"Specifications, not prompts or code, are becoming the fundamental unit of programming, and writing specs is the new superpower."

「プロンプトやコードではなく、仕様がプログラミングの基本単位となりつつあり、仕様を書くことが新たなスーパーパワーである。」

— Sean Grove, OpenAI

SDDが求める明確化

仕様書には、以下を明確に記述する必要があります：

✅ 具体的な入出力フォーマットとデータ型
✅ 明示的なビジネスルールとエッジケース
✅ 統合制約と既存システムの依存関係
✅ パフォーマンス要件と期待されるスケール
✅ エラーハンドリングとバリデーションルール
✅ セキュリティとコンプライアンス要件

これにより、AIエージェントはタスクリストを作成し、仕様に従ってコードを構築できます。

従来の開発 vs SDD

重要な概念：「Intent is the source of truth」

【コード中心の時代】
コード = 真実
ドキュメント = 参考

【AI時代（SDD）】
Intent（意図/仕様） = 真実
コード = 意図の具現化

GitHubの言葉：

"We're moving from 'code is the source of truth' to 'intent is the source of truth.'"

「私たちは『コードが真実の源泉』から『意図が真実の源泉』へと移行しています。」

仕様書 = バージョン管理された「スーパープロンプト」

The New Stackの定義：

"A specification becomes a kind of version-controlled, human-readable super prompt."

「仕様書は、バージョン管理された、人間が読めるスーパープロンプトの一種となる。」

仕様書の特徴：

✅ バージョン管理される（Gitで追跡可能）
✅ 人間が読める（自然言語 + 構造化）
✅ 永続的（セッションを超えて有効）
✅ 共有可能（チーム全体で参照）
✅ AIの「North Star」（方向性を示す指針）

なぜ今SDDなのか：プログラミングの進化史

「なぜ今、仕様駆動開発なのか？」 この質問に答えるには、プログラミングそのものの進化を理解する必要があります。

実は、**プログラミングの歴史は「抽象化の歴史」**です。機械語から始まり、より人間に近い表現で「何をしたいか」を書けるように進化してきました。そして今、AIの登場により、次の大きな進化のタイミングが来ています。

このセクションでは、プログラミングの進化の文脈でSDDを位置づけ、「なぜ今なのか」を3つの観点から解説します。

プログラミング言語の抽象化の歴史

プログラミング言語は、「HOW（どうやるか）」から「WHAT（何をするか）」へと進化してきました。

1940年代: 機械語
「01001010 11010100...」CPU命令を直接書く

  ↓

1950年代: アセンブリ言語
「MOV AX, 1」少し人間に読みやすく

  ↓

1960-70年代: 高級言語（C, COBOL, Fortran）
「int sum = a + b;」数式に近い表現
ここから「HOW」から「WHAT」への移行が始まる

  ↓

1980-90年代: オブジェクト指向（Java, C++）
「user.getName()」概念をオブジェクトとして扱う

  ↓

2000年代: 宣言的プログラミング（SQL, HTML/CSS）
「SELECT * FROM users」結果を指定、処理方法は隠蔽

  ↓

2020年代: AI時代
  ⚡ Spec-Driven Development
「ユーザー管理機能を実装する」意図を記述し、AIが実装

各世代の特徴：

時代	書くもの	抽象度	例
1940年代	CPU命令	最低	`01001010`
1950年代	アセンブリ	低	`MOV AX, 1`
1970年代	手続き	中	`sum = a + b`
1990年代	オブジェクト	中高	`user.getName()`
2000年代	宣言	高	`SELECT * FROM users`
2024年	意図（仕様）	最高	`@spec.md を読んで実装`

このように、プログラミングは着実に抽象度を上げてきました。SDDは、この進化の自然な延長線上にあります。

Kiroの創業者の洞察

Kiro（Spec-Driven開発IDE）の創業者は、この進化を次のように表現しています：

"Most programming languages describe implementation steps, not desired outcomes. SQL is one of the rare exceptions — you specify what you want, not how to get it.

Spec-driven development with AI is the next step: raising the abstraction level of programming from 'how to do something' to 'what needs to be done.'"

「ほとんどのプログラミング言語は、望ましい結果ではなく、実装手順を記述します。SQLは稀な例外の一つで、どうやって取得するかではなく、何が欲しいかを指定します。

AIによる仕様駆動開発は次のステップです：プログラミングの抽象度を『何かをする方法』から『何をする必要があるか』へと引き上げます。」

SQLの例から学ぶ：

-- 宣言的（WHAT）
SELECT name, email FROM users WHERE age > 18;
「18歳以上のユーザーの名前とメールが欲しい」

-- 手続き的（HOW）だったら...
open_database()
for each row in users_table:
    if row.age > 18:
        result.add(row.name, row.email)
return result

SQLは「HOW（どうやって取得するか）」ではなく「WHAT（何が欲しいか）」を書きます。SDDは、この考え方をソフトウェア開発全体に広げるものです。

なぜ今なのか？

この進化が 「今」 起きている理由は3つあります。

理由1: AIの能力が実用レベルに到達した

2023年以前の状況：

// GitHub Copilot などは「次の行を予測」程度
function calculateTotal(items) {
  // ここでAIが次の行を提案
  return items.reduce((sum, item) => sum + item.price, 0);
}

2024年の状況：

# 仕様書
## 機能：注文合計金額の計算
- 入力：商品リスト（各商品に価格と数量）
- 出力：合計金額（税込、送料込）
- ビジネスルール：
  - 10,000円以上は送料無料
  - 税率は10%
  - クーポン適用は合計から

→ AIがこの仕様から、完全な実装を生成できる

この変化により：

❌ 従来：人間が「HOW（どう実装するか）」を細かく指示
✅ 現在：人間は「WHAT（何を実現するか）」を指定し、AIが実装

理由2: コードの複雑性が限界に達した

現代の典型的なWebアプリケーションの構成：

フロントエンド:
  ├─ React/Vue/Angular
  ├─ TypeScript
  ├─ State Management (Redux/Zustand/MobX)
  ├─ UI Library (Material-UI/Ant Design)
  └─ Build Tools (Webpack/Vite)

バックエンド:
  ├─ Node.js/Python/Go
  ├─ フレームワーク (Express/FastAPI/Gin)
  ├─ マイクロサービス (5-50個)
  ├─ API Gateway
  ├─ Message Queue (RabbitMQ/Kafka)
  └─ データベース (PostgreSQL/MongoDB/Redis)

インフラ:
  ├─ AWS/GCP/Azure
  ├─ Kubernetes
  ├─ Docker
  ├─ Terraform
  └─ CI/CD (GitHub Actions/GitLab CI)

監視・テスト:
  ├─ Jest/Pytest/Cypress
  ├─ E2Eテスト
  ├─ Prometheus/Grafana
  └─ Sentry/DataDog

この複雑性の問題：

開発者の認知負荷 = 技術スタック × ビジネスロジック × チーム規約

従来の開発:
各開発者が全てを「実装レベル」で理解・管理する必要
→ 限界を超えている 😱

SDDの解決:
仕様で「WHAT」を定義
技術的な「HOW」はAIと標準化された設計書に任せる
→ 認知負荷を大幅削減 ✅

具体例：新機能の追加

従来:
「パスワードリセット機能を追加」
→ どのマイクロサービスに追加？
→ 既存の認証システムとの整合性は？
→ データベーススキーマの変更は？
→ APIのバージョニングは？
→ テストはどう書く？
→ 各開発者が個別に判断 → 不整合発生 😱

SDD:
spec/auth/password-reset.md に仕様を定義
→ 既存の設計パターンを参照
→ AIが整合性のある実装を生成
→ 自動テスト生成
→ 一貫性が保たれる ✅

理由3: チーム開発での一貫性が必須になった

Vibe Codingでの典型的な問題：

// メンバーAの実装（Redux使用）
import { useSelector, useDispatch } from 'react-redux';

function ComponentA() {
  const user = useSelector(state => state.user);
  const dispatch = useDispatch();
  // ...
}

// メンバーBの実装（Zustand使用）
import { useUserStore } from './store';

function ComponentB() {
  const user = useUserStore(state => state.user);
  // ...
}

// メンバーCの実装（Context API）
import { useContext } from 'react';
import { UserContext } from './context';

function ComponentC() {
  const user = useContext(UserContext);
  // ...
}

// 結果：3つの異なる状態管理パターンが混在 💀

SDDでの解決：

# spec/frontend/architecture.md

## State Management
全てのグローバル状態はZustandで管理する

### 理由
- Redux: 学習コストが高い、ボイラープレートが多い
- Context API: パフォーマンス問題
- Zustand: シンプル、TypeScript統合が良好

### 標準パターン
```typescript
// stores/userStore.ts
import { create } from 'zustand';

export const useUserStore = create<UserState>((set) => ({
  user: null,
  setUser: (user) => set({ user }),
}));
```

### 使用例
すべてのコンポーネントで統一：
```typescript
import { useUserStore } from '@/stores/userStore';

function MyComponent() {
  const user = useUserStore(state => state.user);
  // ...
}
```

このように仕様書で統一することで：

✅ チーム全員が同じパターンで実装
✅ 新メンバーも迷わない
✅ コードレビューが楽
✅ 保守性が向上

SDDの4フェーズワークフロー

ここからが本題です。 仕様駆動開発は、具体的にどのように進めるのでしょうか？

GitHubが2024年に発表した標準的なSDDワークフローは、4つの明確なフェーズから構成されます。各フェーズは特定の成果物を生成し、次のフェーズの入力となります。

Specify（仕様）→ Plan（設計）→ Tasks（タスク）→ Implement（実装）

重要なポイント：

各フェーズは 明確に分離 されている
前のフェーズの成果物が、次のフェーズの入力になる
人間の役割は 「レビューと承認」 であり、AIが 「生成と実装」 を担当

それでは、各フェーズを詳しく見ていきましょう。

フェーズ1: Specify（高レベル仕様）

このフェーズの目的： プロジェクトの「何を作るか」「なぜ作るか」を明確にする

重要： ここでは 「HOW（どう作るか）」は書きません。技術的な詳細は次のPlanフェーズで定義します。

成果物： SPECIFICATION.md

# SPECIFICATION.md の例

## Project Overview
ユーザーが自分の取引履歴をCSV形式でエクスポートできる機能

## Purpose
- ユーザーの自己データ管理を支援
- 外部会計ソフトウェアとの連携を可能にする

## Target Users
- 個人ユーザー（月次レポート目的）
- ビジネスユーザー（会計処理目的）

## Key Features
1. 日付範囲指定でのエクスポート
2. CSV形式での出力
3. 複数通貨対応

## Non-functional Requirements
- レスポンス時間: 5秒以内
- 最大エクスポート件数: 10万件
- セキュリティ: ユーザー認証必須

このフェーズのポイント：

「WHAT」に集中

❌ 悪い例: 「PostgreSQLでユーザーテーブルから...」
✅ 良い例: 「ユーザーが取引履歴をエクスポートできる」

ビジネス価値を明確に
- 誰のため？（Target Users）
- なぜ必要？（Purpose）
- どんな価値？（Expected Outcome）
非機能要件も忘れずに
- パフォーマンス要件
- セキュリティ要件
- スケーラビリティ

このフェーズでAIができること：

あなた: 「ユーザーがCSV形式で取引履歴をエクスポートできる機能の仕様書を作成して」

AI: → SPECIFICATION.mdの初稿を生成

あなた: → レビューして、曖昧な部分を明確化

人間の役割：

AIが生成した仕様書をレビュー
ビジネスロジックの妥当性を確認
抜けている要件を追加
曖昧な表現を具体化

フェーズ2: Plan（技術設計）

このフェーズの目的： 「HOW（どう作るか）」を技術的に定義する

重要： ここから技術的な詳細に入ります。フェーズ1の「WHAT」を、具体的な技術スタックとアーキテクチャに落とし込みます。

成果物： PLAN.md

# PLAN.md の例

## Technical Stack
- Backend: Node.js 20 + TypeScript 5.3
- Framework: Express 4.18
- Database: PostgreSQL 16
- Testing: Jest + Supertest

## Architecture
```
┌─────────────┐
│  Frontend   │
└──────┬──────┘
       │ REST API
┌──────▼──────────────────────┐
│  API Gateway (Express)      │
└──────┬──────────────────────┘
       │
┌──────▼──────────┐  ┌────────────┐
│ Export Service  │──│ PostgreSQL │
└─────────────────┘  └────────────┘
```

## API Design (OpenAPI)
```yaml
GET /api/v1/transactions/export
  Parameters:
    - start_date (optional)
    - end_date (optional)
  Response:
    - 200: CSV file
    - 400: Invalid parameters
    - 401: Unauthorized
```

## Data Model
```typescript
interface Transaction {
  id: string;
  user_id: string;
  amount: number;
  currency: string;
  timestamp: Date;
  description: string;
}
```

## Implementation Constraints
- すべてのAPIエンドポイントはJWT認証必須
- エラーハンドリングは統一パターン（CustomError）
- ログ出力はWinston使用
- 環境変数は.envで管理（dotenv）

このフェーズのポイント：

技術的な決定を記録

なぜNode.js？ → 既存システムがNode.jsで統一されている
なぜPostgreSQL？ → RDBMSが必要、トランザクション処理が重要
なぜExpress？ → 軽量、学習コストが低い

制約を明示

// ✅ 制約を明示することで、AIが守るべきルールが明確に
Implementation Constraints:
- すべてのAPIはJWT認証必須
- エラーハンドリングはCustomErrorクラス
- ログ出力はWinston

アーキテクチャを図示
- 視覚的に構造が分かる
- 誤解を防ぐ

このフェーズでAIができること：

あなた: 「SPECIFICATION.mdを読んで、Node.js + TypeScript + PostgreSQL構成で
       技術設計書を作成してください」

AI: → アーキテクチャ図、API設計、データモデルを生成

あなた: → 既存システムとの整合性をチェック
        → セキュリティ要件を追加

人間の役割：

既存システムとの整合性を確認
技術選定の妥当性を検証
セキュリティ/パフォーマンス要件を追加
アーキテクチャの問題点を指摘

フェーズ3: Tasks（タスク分解）

このフェーズの目的： 大きな仕様を、実装可能な小さなタスクに分解する

重要： 1つのタスク = 1つのPull Request で完了できるサイズが理想です。

成果物： tasks/*.md

# tasks/001-setup-api-endpoint.md

## Task: API エンドポイントのセットアップ

## Dependencies
- None (最初のタスク)

## Acceptance Criteria
- [ ] GET /api/v1/transactions/export エンドポイントが存在する
- [ ] JWT認証ミドルウェアが適用されている
- [ ] リクエストパラメータのバリデーションが実装されている
- [ ] 基本的なエラーハンドリングが実装されている

## Implementation Details
1. `src/routes/transactions.ts` を作成
2. Express Routerを設定
3. JWT認証ミドルウェアを適用
4. リクエストバリデーション（joi or zod）
5. コントローラーのスケルトンを作成

## Testing Requirements
- 認証なしでアクセス → 401エラー
- 不正な日付形式 → 400エラー
- 正しいリクエスト → コントローラーが呼ばれる

## Estimated Effort
30分

# tasks/002-implement-export-logic.md

## Task: エクスポートロジックの実装

## Dependencies
- 001-setup-api-endpoint.md

## Acceptance Criteria
- [ ] データベースから取引データを取得できる
- [ ] 日付範囲でフィルタリングできる
- [ ] CSV形式に変換できる
- [ ] 10万件制限が機能する

...

このフェーズのポイント：

タスク分解の粒度

❌ 粗すぎる: 「取引履歴エクスポート機能を実装」
✅ 適切: 「APIエンドポイントのセットアップ」（30分）
✅ 適切: 「エクスポートロジックの実装」（1時間）
✅ 適切: 「CSVフォーマット処理」（30分）

依存関係を明示

Task 002 は Task 001 に依存
→ 001が完了しないと002は始められない
→ 並行開発の計画が立てやすい

Acceptance Criteria（受け入れ基準）

チェックボックス形式で、「完了」の定義を明確に
- [ ] エンドポイントが存在する
- [ ] 認証が機能する
- [ ] バリデーションが機能する

→ 全部チェックが付いたら「Done」

このフェーズでAIができること：

あなた: 「SPECIFICATION.md と PLAN.md を読んで、
       実装可能なタスクに分解してください」

AI: → 10-20個のタスクファイルを生成
    → 各タスクに依存関係、受け入れ基準、見積もりを含める

あなた: → タスクの粒度が適切かチェック
        → 優先順位を調整

人間の役割：

タスクの粒度を調整（大きすぎる/小さすぎるを修正）
依存関係が正しいか確認
優先順位を決定
見積もりの妥当性を検証

タスク管理のコツ：

良いタスク分解:
- 各タスクは30分〜2時間で完了
- 1タスク = 1 Pull Request
- 依存関係が最小限
- 並行開発が可能

悪いタスク分解:
- 1タスクが5時間以上
- 複数の機能が混在
- 依存関係が複雑すぎる

フェーズ4: Implement（実装）

このフェーズの目的： AIを使って各タスクを実際に実装する

重要： ここでやっとコードを書きます。しかし、仕様・設計・タスクが明確なので、AIは迷わずに実装できます。

プロンプト例：

@SPECIFICATION.md @PLAN.md @tasks/001-setup-api-endpoint.md を読んで、
このタスクを実装してください。

制約:
- すべてのファイル構造はPLAN.mdに従う
- エラーハンドリングはCustomErrorクラスを使用
- テストも同時に作成

AIの出力：

// src/routes/transactions.ts
import express from 'express';
import { authenticateJWT } from '../middleware/auth';
import { validateExportRequest } from '../middleware/validation';
import { ExportController } from '../controllers/exportController';

const router = express.Router();
const controller = new ExportController();

router.get(
  '/export',
  authenticateJWT,
  validateExportRequest,
  controller.export
);

export default router;

// tests/routes/transactions.test.ts
import request from 'supertest';
import app from '../../app';

describe('GET /api/v1/transactions/export', () => {
  it('should return 401 without authentication', async () => {
    const response = await request(app)
      .get('/api/v1/transactions/export');

    expect(response.status).toBe(401);
  });

  it('should return 400 with invalid date format', async () => {
    const response = await request(app)
      .get('/api/v1/transactions/export')
      .set('Authorization', `Bearer ${validToken}`)
      .query({ start_date: 'invalid' });

    expect(response.status).toBe(400);
  });
});

実践：GitHub Spec Kitを使った開発

Spec Kitとは？

GitHubが2024年にリリースした、SDD開発を支援するオープンソースCLIツール。

リポジトリ： https://github.com/github/spec-kit

インストール

# uvx経由でインストール（推奨）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

# または、クローン後に直接使用
git clone https://github.com/github/spec-kit.git
cd spec-kit
pip install -e .

基本的な使い方

1. プロジェクト初期化

specify init pokemon-app

# 以下のディレクトリ構造が生成される
pokemon-app/
├── SPECIFICATION.md
├── PLAN.md
├── tasks/
└── .specify/
    └── config.yaml

2. 仕様の作成

specify spec

# エディタが開き、SPECIFICATION.mdを編集
# または、AIに生成させる
specify spec --generate "ポケモン図鑑アプリを作りたい"

生成されるSPECIFICATION.md：

# Pokédex Application

## Overview
A web application that displays information about Pokémon using the PokéAPI.

## Purpose
- Allow users to browse and search Pokémon
- Display detailed information (stats, abilities, types)
- Provide an engaging user experience

## Target Users
- Pokémon fans
- Casual users looking for Pokémon information

## Key Features
1. Pokémon list with pagination
2. Search functionality
3. Detailed view for each Pokémon
4. Responsive design

3. 技術計画の作成

specify plan

# AIに技術スタックを提案させる
specify plan --generate --stack angular

生成されるPLAN.md：

# Technical Plan

## Stack
- Frontend: Angular 20
- UI: Angular Material
- API: PokeAPI V2
- Testing: Jasmine + Karma

## Architecture
Single Page Application (SPA) with Angular

## Component Structure
- AppComponent (root)
- PokemonListComponent
- PokemonDetailComponent
- SearchComponent

## Services
- PokemonService (API calls)
- CacheService (performance)

4. タスク分解

specify tasks

# AIにタスク分解させる
specify tasks --generate

生成されるタスク例：

# tasks/001-setup-angular-project.md
## Task: Angular プロジェクトのセットアップ
- [ ] Angular CLIでプロジェクト作成
- [ ] Angular Material導入
- [ ] ルーティング設定

# tasks/002-pokemon-service.md
## Task: PokemonServiceの実装
- [ ] PokeAPI連携
- [ ] HTTPクライアント設定
- [ ] エラーハンドリング

# tasks/003-pokemon-list.md
## Task: ポケモン一覧コンポーネント
- [ ] PokemonListComponent作成
- [ ] ページネーション実装
- [ ] ローディング状態

5. 実装

# 特定のタスクを実装
specify implement tasks/001-setup-angular-project.md

# AI（GitHub Copilot）が実装を支援
# 生成されたコードをレビュー・調整

Spec Kitの実践例：実際の開発フロー

# 1. 新機能の追加
$ specify spec --add-feature "ユーザーのお気に入りポケモン機能"

# 2. 既存のPLAN.mdを更新
$ specify plan --update

# 3. 新しいタスクを生成
$ specify tasks --generate

# 生成されたタスク
tasks/015-add-favorites-feature.md
tasks/016-favorites-storage.md
tasks/017-favorites-ui.md

# 4. タスク単位で実装
$ specify implement tasks/015-add-favorites-feature.md

# 5. 検証
$ npm test
$ npm run lint

Spec Kitの利点

利点	説明
構造化されたワークフロー	4フェーズを強制することで、曖昧さを排除
バージョン管理	すべての仕様がGitで管理される
チーム協調	仕様レビューがコードレビューより先に
AI統合	GitHub Copilotとシームレスに連携
追跡可能性	タスクと実装の紐付けが明確

Kiroによる実践例：Towers of Hanoiゲーム

Kiroとは？

Kiro = VS Code拡張機能として動作する、Spec-Driven開発専用IDE

公式サイト： https://kiro.dev

Kiroの特徴

Spec Mode: マークダウンで仕様を書くと、AIが実装を提案
Hooks System: 仕様の変更を自動検知して、コードを更新
Working Backwards: Amazonの開発手法をベースにした設計
Live Sync: 仕様とコードが常に同期

実践例：Towers of Hanoiゲームの開発

ステップ1: 初期仕様の作成

# spec/towers-of-hanoi.md

# Towers of Hanoi Game

## Overview
A web-based implementation of the classic Towers of Hanoi puzzle.

## Features
- Three pegs
- Multiple disks of different sizes
- Drag and drop interface
- Move counter
- Win detection

Kiroの動作：

[Kiro AI] 仕様を検出しました。
          基本的なHTMLとJavaScriptを生成します。

生成中...
✅ index.html
✅ game.js
✅ styles.css

ステップ2: 仕様の段階的拡張

# spec/towers-of-hanoi.md

...

## New Requirement: Difficulty Levels
- Easy: 3 disks
- Medium: 5 disks
- Hard: 7 disks

## New Requirement: Timer
- Display elapsed time
- Show best time for each difficulty

Kiroの動作：

[Kiro AI] 仕様の変更を検出しました。

変更内容を解析中...
- 難易度選択UIの追加
- タイマー機能の実装
- localStorage でベストタイム保存

既存コードを更新します...
✅ game.js (updated)
✅ index.html (updated)
✅ storage.js (new)

ステップ3: バグ修正も仕様で

## Bug Fix: Invalid Move Detection
- Users can currently place larger disks on smaller ones
- Add validation to prevent invalid moves
- Show error message for invalid attempts

Kiroの動作：

[Kiro AI] バグ修正を検出しました。

修正内容:
1. moveDisk関数にバリデーション追加
2. エラーメッセージUI追加
3. 無効な操作時のフィードバック

実装中...
✅ game.js (updated)
✅ Added error handling

Kiroの実践的な使い方

// Kiroのspec/config.md で開発ルールを定義

# Development Rules

## Code Style
- Use TypeScript strict mode
- Follow Airbnb style guide
- Maximum function length: 20 lines

## Testing
- Every public function must have tests
- Test coverage > 80%
- Use Jest

## Error Handling
- All async operations must have try-catch
- Use custom error classes
- Log errors with Winston

## Performance
- API calls must timeout after 5 seconds
- Implement caching for GET requests
- Debounce user input (300ms)

この設定により、Kiroが生成するすべてのコードが自動的にこれらのルールに従います。

KiroとSpec Kitの比較

観点	Spec Kit（GitHub）	Kiro
形式	CLIツール	VS Code拡張
統合	GitHub Copilot	独自AIエンジン
リアルタイム性	手動コマンド実行	自動検知・更新
学習曲線	低い（標準的なCLI）	中程度（新しいパラダイム）
柔軟性	高い（どのエディタでも）	VS Code限定
適用範囲	新規プロジェクト向き	既存プロジェクトにも対応

適切なアプローチの選択

重要な真実：すべてのプロジェクトでSDDが最適とは限りません。

「SDDは素晴らしい！すべてに適用しよう！」と考えるのは危険です。Vibe CodingとSpec-Driven Developmentは、ツールボックスの中の異なる道具です。釘を打つときはハンマーを、ネジを締めるときはドライバーを使うように、状況に応じて適切なアプローチを選ぶべきです。

このセクションでは、**「いつVibe Codingを使い、いつSDDを使うべきか」**の判断基準を解説します。Frontend at Scaleの記事が提唱する「開発アプローチのスペクトラム」の考え方をベースに説明します。

開発アプローチのスペクトラム

開発手法は、白か黒かではなく、グラデーションです。

Vibe Coding ←─────────────────────→ Spec-Driven Development
   ↑                                        ↑
高速・柔軟                            構造化・品質重視

プロジェクト特性による選択

プロジェクト特性	推奨アプローチ	理由
小規模プロトタイプ	Vibe Coding	速度重視、品質は二の次
個人プロジェクト（探索的）	Vibe Coding	柔軟性重視、試行錯誤が多い
UIデザインの実験	Vibe Coding	ビジュアルフィードバックが重要
チーム開発	Spec-Driven	一貫性と協調が重要
エンタープライズアプリ	Spec-Driven	品質・保守性が最重要
複雑なバックエンド	Spec-Driven	アーキテクチャ設計が重要
既存システムの拡張	Spec-Driven	既存との整合性が必須

機能別の選択

## 同じプロジェクト内でもアプローチを使い分ける

### Vibe Codingが適している場面
- UI/UXの探索フェーズ
- デザインのA/Bテスト
- 簡単なユーティリティ関数
- 一時的なデバッグコード

### SDDが適している場面
- APIエンドポイントの追加
- データベーススキーマの変更
- 認証・認可ロジック
- 複雑なビジネスロジック

実践的な判断基準

以下のチェックリストで、SDDを使うべきか判断：

□ コードが1週間後も使われる
□ 複数の開発者が関わる
□ セキュリティが重要
□ パフォーマンスが重要
□ テストが必要
□ ドキュメントが必要

✅ 3つ以上該当 → SDD推奨
⚠️  1-2個該当 → 状況次第
❌ 0個 → Vibe Codingでも可

ハイブリッドアプローチ

// 実践例：UIはVibe、ロジックはSpec-Driven

// Phase 1: Vibe Codingで素早くプロトタイプ
「フォームUIを作って」→ 素早く試作

// Phase 2: 固まったら仕様化
spec/user-form.md:
"""
## User Registration Form
- Fields: email, password, confirm_password
- Validation: ...
- Submit handler: calls API
"""

// Phase 3: バックエンドはSpec-Driven
spec/registration-api.md:
"""
POST /api/v1/users/register
- Input validation
- Password hashing (bcrypt)
- Email verification
- Error handling
"""

実際の導入事例と効果

事例1: GitHubの内部プロジェクト

背景：

GitHub社内の新機能開発プロジェクト
10人のチーム、3ヶ月の開発期間

導入内容：

1. Spec Kitを使用した仕様管理
2. 週次の仕様レビューミーティング
3. GitHub Copilotとの統合
4. すべてのPRに仕様リンクを必須化

成果：

指標	従来	SDD導入後	改善率
仕様とコードの乖離	約35%	約8%	77%改善
初回コードレビュー通過率	45%	78%	73%向上
設計変更による手戻り	週2-3回	月1-2回	75%削減
新メンバーのオンボーディング	2週間	3日	78%短縮

チームメンバーのコメント：

「最初は『仕様を書くのは時間の無駄では？』と思いました。しかし、実際には実装フェーズでの迷いが激減し、トータルでは30%以上の時間短縮になりました」

事例2: スタートアップのMVP開発

背景：

創業3人のスタートアップ
SaaSプロダクトのMVP開発
期限：2ヶ月

導入内容：

1. Kiroを使用した開発
2. シンプルなspec/ディレクトリ構造
3. AIへの依存度を最大化
4. 人間は仕様のレビューと調整に集中

成果：

従来予想: 3-4ヶ月
実際: 6週間で完了

内訳:
- 仕様作成: 1週間
- 実装（AIメイン）: 3週間
- テスト・調整: 2週間

コード品質:
- テストカバレッジ: 87%
- 技術的負債: ほぼゼロ
- ドキュメント: 完全（自動生成）

創業者のコメント：

「少人数だからこそSDDが効きました。仕様さえ明確なら、AIが高速に実装してくれます。3人で10人分の開発速度が出せました」

事例3: エンタープライズでのレガシーマイグレーション

背景：

大手金融機関のシステムモダナイゼーション
10年前のJavaシステムをTypeScript + Reactに移行

導入内容：

1. 既存システムの仕様を逆生成
   既存コード → AI分析 → SPECIFICATION.md

2. 段階的な移行
   - 機能単位で仕様化
   - 新旧システムの並行稼働
   - APIレベルでの互換性維持

3. 厳格な検証プロセス
   - 仕様レビュー（2週間）
   - 設計レビュー（1週間）
   - 実装（AI支援）
   - テスト（自動 + 手動）

成果：

指標	予測	実績	差分
移行期間	24ヶ月	18ヶ月	6ヶ月短縮
バグ発生率	想定値	40%減	大幅改善
ドキュメント完全性	60%	95%	大幅向上
チーム満足度	-	4.2/5	高評価

プロジェクトマネージャーのコメント：

「レガシーシステムには"暗黙の仕様"が大量にありました。SDDの仕様化プロセスで、それらを明示的にドキュメント化できたことが最大の価値でした」

マルチプレイヤー開発への進化：Runbooksの概念

シングルプレイヤーからマルチプレイヤーへ

AI開発は、もはや「1人 + AI」の世界ではありません。

従来のAI開発:
開発者1人 ←→ AIエージェント

現実:
- 複数の開発者
- 複数のリポジトリ
- 複数のマイクロサービス
- 複数のプロンプト・仕様書

→ どうやって知識を共有する？

Runbooksとは？

Runbooks = 仕様書に「シェアボタン」を付けた概念

Runbooksの特徴

特徴	説明
共有可能	チーム全体で同じRunbookを参照
実行可能	プロンプトとワークフローを含む
拡張可能	他人のRunbookの上にビルドできる
追跡可能	決定の監査証跡を保持
転送可能	リポジトリ間でコンテキストを転送

Runbooksの実践例

# runbooks/user-authentication.runbook.md

## Specification
@specs/auth/authentication.md

## Workflow
1. Review existing authentication system
2. Identify integration points
3. Implement JWT token generation
4. Add refresh token logic
5. Write integration tests

## Prompts
### Prompt 1: Setup
"""
@specs/auth/authentication.md を読んで、
既存の src/auth/ の構造を確認してください。
統合ポイントをリストアップしてください。
"""

### Prompt 2: Implementation
"""
JWT token生成ロジックを実装してください。
- ライブラリ: jsonwebtoken
- トークン有効期限: 24時間
- リフレッシュトークン: 7日間
"""

## Stakeholders
- @alice (Backend Lead)
- @bob (Security Review)
- @ai-agent-1 (Implementation)

## History
- 2024-10-15: Initial specification
- 2024-10-16: Security review completed
- 2024-10-17: Implementation started

Runbooksのメリット

1. 知識の共有

従来: 「誰かが仕様書いたけど、どこ？」
Runbooks: チーム全員が同じRunbookを参照

2. コンテキストの転送

リポジトリA の Runbook
  ↓
リポジトリB で再利用
  ↓
一貫した実装パターン

3. ステークホルダーの統合

Product Manager → 仕様を書く
Tech Lead → レビュー・承認
Developer → Runbookを元に実装
AI Agent → 自動実装

4. 監査証跡

「なぜこの設計にしたの？」
→ Runbookを見れば、全ての決定プロセスが分かる

実装例：Aviator Runbooks

# Aviator Runbooksのインストール（仮想例）
npm install -g @aviator/runbooks

# 新しいRunbookを作成
aviator runbook create auth-system

# Runbookを共有
aviator runbook share auth-system --team engineering

# Runbookから実装を開始
aviator runbook execute auth-system \
  --agent github-copilot \
  --reviewer @alice

RunbooksとSpec-Drivenの統合

【統合ワークフロー】

1. Specification（仕様）を書く
   ↓
2. Runbook（実行プラン）を作成
   ↓
3. チームでレビュー・承認
   ↓
4. 複数の開発者/AIが並行実装
   ↓
5. 結果をRunbookにフィードバック
   ↓
6. 次のプロジェクトで再利用

Runbooks = 個人の実験を、チーム全体のエンジニアリングプロジェクトに変える仕組み

今日から始める実践ガイド

「理論はわかった。で、実際どうやって始めるの？」

このセクションでは、あなたが明日から実践できるように、3つのレベル別の導入パスを用意しました：

初心者向け: パターンC（シンプルなMarkdown）
中級者向け: パターンA（Spec Kit）
上級者向け: パターンB（Kiro）

それぞれ、実際の画面操作、コマンド実行、期待される結果まで詳しく解説します。

🎯 まず、どのパターンを選ぶべきか？

選択フローチャート：

あなたの状況は？

├─ 「まず試してみたい」
│  └→ パターンC（Markdownのみ）
│     ツール不要、今すぐ始められる
│
├─ 「チームで本格導入したい」
│  └→ パターンA（Spec Kit）
│     GitHubが推奨、実績あり
│
└─ 「VS Codeでリアルタイム開発したい」
   └→ パターンB（Kiro）
      自動検知、リアルタイム更新

パターンC: シンプルなMarkdownから始める（初心者向け）

このパターンが最適な人：

「まず概念を理解したい」
「特別なツールをインストールしたくない」
「既存プロジェクトにすぐ適用したい」

ステップ1: プロジェクト構造を作る（5分）

まず、仕様を置くディレクトリを作ります：

# あなたのプロジェクトで実行
cd my-existing-project

# 仕様書用のディレクトリを作成
mkdir -p spec/features
mkdir -p spec/api

# 確認
tree spec
# spec/
# ├── features/
# └── api/

なぜこの構造？

spec/: すべての仕様を一箇所に集約
features/: 機能別の仕様
api/: API仕様（OpenAPIなど）

ステップ2: 最初の仕様書を書く（30分）

実際に手を動かしてみましょう。例：「ユーザー認証機能」

# エディタで新規ファイルを作成
code spec/features/auth.md

以下の内容をコピペして、あなたのプロジェクトに合わせて修正：

# ユーザー認証機能

## 1. 概要
ユーザーがメールアドレスとパスワードでログインできる機能

## 2. 目的
- セキュアなユーザー認証を提供
- 不正アクセスを防止
- ユーザーセッション管理

## 3. 入出力定義

### 入力
| パラメータ | 型 | 必須 | 説明 |
|----------|-----|------|------|
| email | string | Yes | メールアドレス（RFC 5322準拠） |
| password | string | Yes | パスワード（8文字以上、英数字） |

### 出力
| パラメータ | 型 | 説明 |
|----------|-----|------|
| token | string | JWT認証トークン（24時間有効） |
| user | object | ユーザー情報（id, name, email） |

## 4. 振る舞い

### 正常系
1. ユーザーがメールアドレスとパスワードを入力
2. サーバーがデータベースでユーザーを検索
3. パスワードをbcryptで検証
4. JWTトークンを生成（有効期限24時間）
5. トークンとユーザー情報を返す

### 異常系
| ケース | エラーコード | HTTPステータス | メッセージ |
|--------|-------------|---------------|------------|
| メールアドレスが存在しない | AUTH001 | 401 | Invalid credentials |
| パスワードが間違っている | AUTH001 | 401 | Invalid credentials |
| アカウントがロック中 | AUTH002 | 403 | Account locked |
| リクエストが多すぎる | AUTH003 | 429 | Too many attempts |

## 5. セキュリティ要件
- パスワードはbcryptでハッシュ化（cost: 12）
- JWTトークンにはuser_idとroleのみ含める
- レートリミット：5回/15分（IPアドレス単位）
- 失敗5回でアカウントを30分ロック

## 6. テスト観点
- [ ] 正しいメール・パスワードでログイン成功
- [ ] 間違ったパスワードで401エラー
- [ ] 存在しないメールで401エラー
- [ ] レートリミット超過で429エラー
- [ ] トークンの有効期限が24時間
- [ ] ロックされたアカウントで403エラー

保存したら、内容を確認：

cat spec/features/auth.md
# → 上記の内容が表示されればOK

ステップ3: AIに実装を依頼する（10分）

Claude Code、Cursor、GitHub Copilotなど、お好きなAIツールで：

あなた: @spec/features/auth.md を読んで、この認証機能のAPI実装を
       TypeScript + Express で作成してください。

制約:
- ファイル構造はクリーンアーキテクチャで
- エラーハンドリングは仕様書のエラーコード体系に従う
- テストも同時に作成（Jest + Supertest）

AIが生成するファイル構成の例：

src/
├── controllers/
│   └── authController.ts      # エンドポイント処理
├── services/
│   └── authService.ts         # ビジネスロジック
├── models/
│   └── user.ts                # データモデル
├── middlewares/
│   └── rateLimit.ts           # レート制限
├── errors/
│   └── authErrors.ts          # カスタムエラー
└── __tests__/
    └── auth.test.ts           # テスト

生成されるコードの例:
- authController.ts: POST /api/auth/login エンドポイント
- authService.ts: パスワード検証、JWT生成ロジック
- authErrors.ts: AUTH001, AUTH002, AUTH003 エラー

ステップ4: 生成されたコードをレビュー（20分）

チェックポイント：

// ✅ チェック1: エラーコードが仕様通りか？
if (!user) {
  throw new AuthError('AUTH001', 'Invalid credentials');
  // ✅ OK: 仕様書通り
}

// ✅ チェック2: セキュリティ要件を満たしているか？
const isValid = await bcrypt.compare(password, user.passwordHash);
// ✅ OK: bcryptを使用

// ✅ チェック3: レートリミットが実装されているか？
// rateLimit.ts を確認

// ✅ チェック4: テストが網羅的か？
// auth.test.ts で仕様書の「テスト観点」が全てカバーされているか確認

もし仕様と違う部分があれば：

あなた: @spec/features/auth.md を見てください。
       エラーコードは AUTH001 を使うべきですが、
       現在のコードでは "INVALID_CREDENTIALS" になっています。
       仕様書に合わせて修正してください。

AI: → コードを修正

ステップ5: 仕様書を更新（必要に応じて）

実装中に気づいた改善点を仕様書に反映：

# spec/features/auth.md に追記

## 7. 実装メモ（2024-10-15）
- bcryptのcostは12で実装（推奨値）
- JWTの署名アルゴリズムはHS256
- リフレッシュトークンの実装は次フェーズ
- 環境変数 JWT_SECRET は必須

## 8. 既知の制限
- 現在はメールアドレスのみ対応（電話番号は未対応）
- ソーシャルログインは未実装

ステップ6: チームで共有

仕様書をGitにコミット：

git add spec/features/auth.md
git commit -m "spec: Add user authentication specification"
git push

Pull Requestのテンプレートに追加：

## 関連する仕様書
- [ユーザー認証機能](../spec/features/auth.md)

## 仕様との整合性
- [ ] 仕様書の要件をすべて満たしている
- [ ] エラーコード体系が一致している
- [ ] テスト観点がすべてカバーされている

パターンA: Spec Kitで始める（中級者向け）

このパターンが最適な人：

「GitHubの公式ツールを使いたい」
「チーム全体で標準化したい」
「CLIツールに慣れている」

なぜSpec Kitなのか？

✅ GitHubが開発・推奨
✅ GitHub Copilotとシームレス連携
✅ 4フェーズワークフロー（Specify→Plan→Tasks→Implement）を強制
✅ オープンソースで無料

ステップ1: インストール（5分）

前提条件：

Python 3.8以上がインストールされていること
uvxがインストールされていること

# uvxのインストール（まだの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Spec Kitのインストール確認
uvx --from git+https://github.com/github/spec-kit.git specify --version
# → specify 0.1.0 などと表示されればOK

ステップ2: 新規プロジェクトの作成（10分）

練習用プロジェクトを作成：

# 新規プロジェクトを初期化
uvx --from git+https://github.com/github/spec-kit.git specify init todo-app

# 生成されたファイルを確認
cd todo-app
tree .

生成される構造：

todo-app/
├── SPECIFICATION.md    # まだ空
├── PLAN.md            # まだ空
├── tasks/             # タスクはこここに生成される
└── .specify/
    └── config.yaml    # Spec Kitの設定

config.yamlの中身：

# .specify/config.yaml
version: "1.0"
ai_provider: "github_copilot"  # or "openai", "anthropic"
project_name: "todo-app"

ステップ3: 仕様書を生成（15分）

AIに仕様書の初稿を作らせる：

# Specify フェーズ: 高レベル仕様の生成
specify spec --generate "タスク管理アプリ。ユーザーはタスクを作成・編集・削除でき、完了/未完了を切り替えられる"

実行すると、エディタが開いて以下のような内容が生成されます：

# SPECIFICATION.md

## Project Overview
シンプルなタスク管理（ToDo）アプリケーション

## Purpose
- ユーザーが日常のタスクを効率的に管理できる
- タスクの優先順位付けと進捗追跡

## Target Users
- 個人ユーザー
- 小規模チーム（将来的に）

## Key Features
1. タスクの作成・編集・削除
2. 完了/未完了の切り替え
3. タスク一覧表示
4. タスクの検索（タイトル・説明）

## Non-functional Requirements
- レスポンス時間: <200ms
- 同時ユーザー: 100人
- データ永続化必須

ここで人間がレビュー：

# あなたが追加・修正する内容

## Key Features（修正）
1. タスクの作成・編集・削除
2. 完了/未完了の切り替え
3. 優先度の設定（High/Medium/Low）  ← 追加
4. 期限の設定とリマインダー  ← 追加
5. タスク一覧表示（フィルタ・ソート可能）  ← 修正
6. タスクの検索（タイトル・説明）

## Business Rules（新規追加）
- 期限を過ぎたタスクは赤色で表示
- 優先度Highのタスクは常にリストの上部
- 完了タスクは7日後に自動アーカイブ

保存してコミット：

git add SPECIFICATION.md
git commit -m "spec: Initial specification for todo app"

ステップ4: 技術設計を生成（15分）

Plan フェーズ: 技術スタックと設計：

# 技術スタックを指定して設計書を生成
specify plan --generate --stack "typescript,react,postgresql,express"

生成されるPLAN.md：

# PLAN.md

## Technical Stack
- Frontend: React 18 + TypeScript 5
- Backend: Node.js 20 + Express 4
- Database: PostgreSQL 15
- State Management: Zustand
- Testing: Jest + React Testing Library

## Architecture

[フロントエンド] ←REST API→ [バックエンド] ← [PostgreSQL]


## API Design
```yaml
GET    /api/tasks          # タスク一覧取得
POST   /api/tasks          # タスク作成
PATCH  /api/tasks/:id      # タスク更新
DELETE /api/tasks/:id      # タスク削除

Data Model

interface Task {
  id: string;
  title: string;
  description?: string;
  completed: boolean;
  priority: 'high' | 'medium' | 'low';
  dueDate?: Date;
  createdAt: Date;
  updatedAt: Date;
}

Implementation Constraints

TypeScript strict mode必須
すべてのAPI応答は統一JSON形式
エラーハンドリングはミドルウェアで集約
環境変数で設定管理（dotenv）


**レビューして修正があれば編集・保存。**

#### ステップ5: タスクに分解（10分）

**Tasks フェーズ: 実装可能な小さなタスクに分割：**

```bash
# タスク分解を実行
specify tasks --generate

生成されるタスクファイル：

tasks/
├── 001-setup-project.md
├── 002-database-schema.md
├── 003-api-tasks-list.md
├── 004-api-tasks-create.md
├── 005-api-tasks-update.md
├── 006-api-tasks-delete.md
├── 007-frontend-task-list.md
├── 008-frontend-task-form.md
└── 009-frontend-filters.md

各タスクファイルの例（tasks/003-api-tasks-list.md）：

## Task: GET /api/tasks エンドポイントの実装

### Dependencies
- 002-database-schema.md

### Acceptance Criteria
- [ ] GET /api/tasks でタスク一覧が取得できる
- [ ] クエリパラメータでフィルタリング可能（completed, priority）
- [ ] ページネーション対応（limit, offset）
- [ ] エラーハンドリング実装

### Implementation Steps
1. `src/routes/tasks.ts` にルート定義
2. `src/controllers/tasksController.ts` にロジック実装
3. `src/services/tasksService.ts` でデータベースクエリ
4. テスト作成（`__tests__/tasks.test.ts`）

### Estimated Time
2時間

ステップ6: タスクを実装（継続的）

1つずつタスクを実装：

# タスク001を実装
specify implement tasks/001-setup-project.md

# AIが実装を生成
# → レビュー・調整
# → テスト実行
# → コミット

git add .
git commit -m "feat: Setup project structure (task 001)"

# 次のタスクへ
specify implement tasks/002-database-schema.md
# ... 繰り返し

パターンB: Kiroで始める（上級者向け）

このパターンが最適な人：

「VS Codeで開発している」
「仕様を書くとリアルタイムでコードが生成されるのを体験したい」
「既存プロジェクトに段階的に導入したい」

なぜKiroなのか？

✅ 仕様を保存すると自動的にコード生成
✅ VS Code統合でシームレスな開発体験
✅ 既存プロジェクトにも導入しやすい
✅ 仕様とコードの双方向同期

ステップ1: インストール（3分）

VS Code拡張機能をインストール：

# コマンドラインからインストール
code --install-extension kiro.kiro-vscode

# または、VS Code内で
# 1. 拡張機能パネルを開く（Cmd+Shift+X / Ctrl+Shift+X）
# 2. "Kiro" で検索
# 3. "Install" をクリック

インストール確認：

VS Codeの左側のアクティビティバーに
Kiroのアイコン（K）が表示されればOK

ステップ2: プロジェクトの初期設定（10分）

既存プロジェクトに追加する場合：

cd your-existing-project

# 仕様ディレクトリを作成
mkdir -p spec

# VS Codeの設定ファイルを作成
mkdir -p .vscode

.vscode/settings.jsonを作成・編集：

{
  // Kiro設定
  "kiro.enabled": true,
  "kiro.specDirectory": "spec",
  "kiro.autoGenerate": true,
  "kiro.aiProvider": "anthropic",  // "openai" or "anthropic"

  // オプション設定
  "kiro.autoSave": true,           // 仕様保存時に自動生成
  "kiro.generateTests": true,      // テストも自動生成
  "kiro.codeReviewMode": false     // レビューモード（生成前に確認）
}

API Keyの設定（初回のみ）：

# VS Codeのコマンドパレットを開く（Cmd+Shift+P / Ctrl+Shift+P）
# 「Kiro: Configure API Key」を検索
# → Anthropic Claude API Keyを入力

# または環境変数で設定
export ANTHROPIC_API_KEY="your-key-here"

ステップ3: 最初の仕様を書く（20分）

VS Codeで新規ファイルを作成：

# spec/auth.md を作成
touch spec/auth.md
code spec/auth.md

以下を入力（Kiroが自動検知します）：

# User Authentication

## Requirements
- Email + Password authentication
- JWT token generation (24 hour expiry)
- Refresh token support (7 day expiry)
- Password reset via email
- Account lockout after 5 failed attempts

## API Endpoints

### POST /api/auth/login
Input:
- email: string (required, valid email format)
- password: string (required, min 8 chars)

Output:
- accessToken: string (JWT)
- refreshToken: string
- user: object { id, name, email }

Errors:
- 401: Invalid credentials
- 403: Account locked
- 429: Too many requests

## Security
- Passwords hashed with bcrypt (cost: 12)
- JWT signed with HS256
- Rate limiting: 5 attempts per 15 minutes per IP
- Lockout duration: 30 minutes

## Implementation Notes
- Use Express.js framework
- PostgreSQL for user storage
- Redis for rate limiting and session storage
- Jest for testing

保存すると...（Ctrl+S / Cmd+S）

[Kiro通知]
"仕様を検出しました。コードを生成しますか？"

[Yes] をクリック

→ 30秒後...

Kiroが自動生成するファイル：

あなたのプロジェクト/
├── spec/
│   └── auth.md                    # あなたが書いた仕様
├── src/
│   ├── routes/
│   │   └── auth.routes.ts         # ← 自動生成
│   ├── controllers/
│   │   └── auth.controller.ts     # ← 自動生成
│   ├── services/
│   │   └── auth.service.ts        # ← 自動生成
│   ├── middlewares/
│   │   ├── authenticate.ts        # ← 自動生成
│   │   └── rateLimit.ts           # ← 自動生成
│   └── models/
│       └── user.model.ts          # ← 自動生成
└── __tests__/
    └── auth.test.ts               # ← 自動生成

ステップ4: 生成されたコードを確認（15分）

VS Codeの「Kiro」パネルを開く：

左側のアクティビティバーの "K" アイコンをクリック

→ Kiroパネルが表示

表示内容:
┌─────────────────────────────┐
│ Kiro                        │
├─────────────────────────────┤
│ ✅ Generated: auth.routes.ts │
│ ✅ Generated: auth.controller│
│ ✅ Generated: auth.service   │
│ ⚠️  Review: auth.test.ts     │
│    (テストの網羅性を確認)      │
└─────────────────────────────┘

ファイルを1つずつレビュー：

// src/controllers/auth.controller.ts（生成されたコード）
import { Request, Response } from 'express';
import { AuthService } from '../services/auth.service';

export class AuthController {
  async login(req: Request, res: Response) {
    try {
      const { email, password } = req.body;

      // ✅ 仕様書通りのバリデーション
      if (!email || !password) {
        return res.status(400).json({ error: 'Missing credentials' });
      }

      const result = await AuthService.login(email, password);

      // ✅ 仕様書通りの出力形式
      res.json({
        accessToken: result.accessToken,
        refreshToken: result.refreshToken,
        user: result.user
      });
    } catch (error) {
      // ✅ 仕様書のエラーコード体系に従っている
      if (error.code === 'INVALID_CREDENTIALS') {
        return res.status(401).json({ error: 'Invalid credentials' });
      }
      // ...
    }
  }
}

もし修正が必要なら：

方法1: コードを直接編集
→ Kiroが検知して仕様書を更新提案

方法2: 仕様書を修正
→ Kiroが自動的にコードを再生成

ステップ5: Kiroの双方向同期を体験（10分）

実験：コードを修正すると仕様が更新される

// src/controllers/auth.controller.ts を編集
export class AuthController {
  // 新しいメソッドを追加
  async logout(req: Request, res: Response) {
    const { refreshToken } = req.body;
    await AuthService.revokeToken(refreshToken);
    res.status(204).send();
  }
}

保存すると...（Ctrl+S）

[Kiro通知]
"コードに新しいエンドポイントを検出しました。
 仕様書を更新しますか？"

[Yes] をクリック

→ spec/auth.md が自動更新される

更新された仕様書：

# User Authentication

## API Endpoints

### POST /api/auth/login
...

### POST /api/auth/logout  ← 自動追加
Input:
- refreshToken: string (required)

Output:
- 204 No Content

Description:
ユーザーのリフレッシュトークンを無効化し、ログアウトします。

これがKiroの双方向同期です！

ステップ6: チーム開発での活用

Kiroの仕様をチームで共有：

# 仕様書をコミット
git add spec/auth.md
git add .vscode/settings.json
git commit -m "spec: Add authentication specification"
git push

# チームメンバーが pull すると...
git pull

# VS CodeでKiroが自動的に検知
# → 「仕様からコードを生成しますか？」
# → 全員が同じコードベースで開発開始

Kiroのコラボレーション機能：

チームメンバーA: 仕様書を更新
    ↓
Git push
    ↓
チームメンバーB: Git pull
    ↓
Kiroが変更を検知
    ↓
「コードを再生成しますか？」
    ↓
全員のコードが同期

よくある失敗と対策

失敗1: 「仕様が抽象的すぎる」

# ❌ 悪い例
## Feature: User Management
- Users can manage their accounts

# ✅ 良い例
## Feature: User Profile Management

### Functional Requirements
1. Users can view their profile (GET /api/users/:id)
2. Users can edit name, email, avatar (PATCH /api/users/:id)
3. Email changes require verification
4. Avatar upload max size: 2MB, formats: JPG, PNG

### Non-functional Requirements
- Profile load time < 200ms
- Avatar upload timeout: 30s
- Rate limit: 10 requests/minute per user

### Validation Rules
- Name: 2-50 characters, alphanumeric + spaces
- Email: RFC 5322 compliant
- Avatar: max 2MB, 1:1 aspect ratio recommended

対策： 「WHAT」だけでなく、「ACCEPTANCE CRITERIA」も明記する。

失敗2: 「仕様とコードが乖離した」

現象：

1. 仕様を書く
2. AIがコードを生成
3. バグ修正でコードを直接編集
4. 仕様を更新し忘れる
5. 乖離が発生 😱

対策：

# .github/workflows/spec-sync.yml
name: Spec-Code Sync Check

on: [pull_request]

jobs:
  check-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      # 仕様ファイルが変更されているかチェック
      - name: Check spec changes
        run: |
          if git diff --name-only origin/main | grep "^spec/"; then
            echo "✅ Spec files updated"
          else
            if git diff --name-only origin/main | grep "^src/"; then
              echo "❌ Code changed but spec not updated"
              exit 1
            fi
          fi

失敗3: 「仕様が長すぎてAIが理解できない」

# ❌ 1つのファイルに全部書く（10,000行）
spec/everything.md

# ✅ 機能・ドメインごとに分割
spec/
├── OVERVIEW.md (500行)
├── auth/
│   ├── authentication.md (200行)
│   └── authorization.md (300行)
├── api/
│   ├── users.md (400行)
│   └── posts.md (300行)
└── frontend/
    ├── components.md (500行)
    └── state-management.md (300行)

対策： 1ファイル = 500行以内を目安に分割。

失敗4: 「チームメンバーが仕様を書かない」

問題： 開発者が「仕様を書くのは面倒」と感じる

対策：

1. プロセスの義務化
   - PR作成前に仕様レビュー必須
   - 仕様なしのPRはマージ不可

2. テンプレート化
   - よくあるパターンのテンプレートを用意
   - コピペ + 編集で完成

3. AI活用
   - 初稿はAIに生成させる
   - 人間はレビューと調整だけ

4. 成功事例の共有
   - 「仕様があって助かった」事例を共有
   - 工数削減の実績を可視化

失敗5: 「過度に詳細な仕様」

# ❌ 実装レベルまで指定
## Button Component

### Implementation
```typescript
import React from 'react';
import styled from 'styled-components';

const StyledButton = styled.button`
  background-color: #007bff;
  color: white;
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;

  &:hover {
    background-color: #0056b3;
  }
`;

export const Button: React.FC<{
  label: string;
  onClick: () => void;
}> = ({ label, onClick }) => {
  return <StyledButton onClick={onClick}>{label}</StyledButton>;
};


```markdown
# ✅ 「WHAT」に集中
## Button Component

### Requirements
- Clickable button element
- Visual feedback on hover
- Disabled state support
- Size variants: small, medium, large
- Color variants: primary, secondary, danger

### Accessibility
- Keyboard accessible (Tab + Enter)
- ARIA label support
- Focus visible

### Behavior
- onClick callback required
- Disabled state prevents clicks
- Loading state shows spinner

対策： 「WHAT（何を実現するか）」を書き、「HOW（どう実装するか）」はAIに任せる。

まとめ：AI時代の開発者の役割

パラダイムシフト

【コード中心の時代（~2023）】
開発者 = コードを書く人
価値 = 実装力

【AI時代（2024~）】
開発者 = 意図を設計する人
価値 = 仕様化力

Spec-Driven Developmentの本質

観点	説明
定義	仕様を「唯一の真実の源泉」とし、そこからすべてを導き出す開発手法
目的	人間の意図を正確に表現し、AIによる実装を制御する
本質	"Code is the source of truth" → "Intent is the source of truth"
価値	仕様精度 = 出力品質
進化	プログラミングの抽象度を「HOW」から「WHAT」へ引き上げる

AI時代の開発者に求められるスキル

次のステップ

1. 今日: 小さなプロジェクトでSDD を試す
   → Spec Kitをインストール
   → ToDoアプリで練習

2. 今週: チームに提案
   → 成功事例を共有
   → 次のスプリントで試験導入

3. 今月: プロセスに組み込む
   → 仕様レビューを必須化
   → CI/CDパイプラインに統合

4. 今四半期: 組織全体に展開
   → ベストプラクティス集を作成
   → トレーニングプログラム実施

おわりに：選択ではなく、必然

Sean Groveの予言

"The person who communicates the best will be the most valuable programmer in the future."

「将来、最も価値のあるプログラマーは、最もうまくコミュニケーションできる人になるでしょう。」

— Sean Grove, OpenAI, 2024

The New Stackの結論

"Spec-driven development is not a choice but a necessity as we move from vibe coding a cool app to building real-world brownfield projects."

「仕様駆動開発は、クールなアプリのVibe Codingから、実世界のブラウンフィールドプロジェクトの構築に移行する際に、選択ではなく必然である。」

— The New Stack, 2024

あなたの選択

【Vibe Codingを続ける】
✅ 小規模プロトタイプでは速い
❌ チームではスケールしない
❌ エンタープライズでは使えない
❌ 技術的負債が蓄積する

【Spec-Drivenに移行する】
✅ チーム全体で一貫性
✅ エンタープライズでも機能
✅ 技術的負債を最小化
✅ AIの能力を最大化
❌ 初期学習コストがかかる

The future is jazz with structure

Frontend at Scaleの記事の最後の言葉：

"The future of software development might just be jazz. Everyone improvising."

「ソフトウェア開発の未来はジャズかもしれない。みんなが即興演奏する。」

しかし、ジャズにもコード進行（構造）があります。

Spec-Driven Development = 開発のコード進行

自由な即興（Vibe Coding）
構造化された設計（SDD）
両方を使いこなす

これが、AI時代の開発者に求められるスキルです。

あなたの次の一手

今日: この記事を読み終えた
明日: 小さな機能で仕様を書いてみる
来週: チームに提案する
来月: プロセスに組み込む

1年後: 「仕様駆動開発なしでは開発できない」

コードを書く前に、仕様を設計する。
それが、AI時代の新常識です。

参考資料

公式ツール・プラットフォーム

GitHub Spec Kit - GitHubの公式SDDツール（オープンソース）
Kiro - Spec-driven開発専用IDE（VS Code拡張）
Aviator - AI対応開発者生産性プラットフォーム（Runbooks機能含む）
Amazon Q Developer - AWSのAI IDE（SDD対応）

重要記事

Spec-driven development with AI (GitHub Blog, 2024) - GitHubの公式発表
Spec-Driven Development: The Key to Scalable AI Agents (The New Stack, 2024) - Sean Groveの講演内容含む
Spec Driven Development (SDD): A initial review (dev.to) - 実践レビュー
Kiro and the future of software development - Kiro創業者の哲学
Frontend at Scale #49 - Vibe CodingとSDDの比較

キーパーソン

Sean Grove - OpenAI、AI Engineer Conference登壇者
Ankit Jain - Aviator創業者、The New Stack寄稿者

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

AI時代の新常識：「Vibe Codingの限界」と「SDD - 仕様駆動開発 / スペック駆動開発」の実践

📚 この記事の位置づけ

目次

あなたは「Vibe Coding」していませんか？

OpenAIのSean Groveの警告

Vibe Codingとは？

Vibe Codingの本質的な問題

コンテキストの質が成功を決める

実際の開発者の声

Spec-Driven Developmentとは

定義

SDDが求める明確化

従来の開発 vs SDD

重要な概念：「Intent is the source of truth」

仕様書 = バージョン管理された「スーパープロンプト」

なぜ今SDDなのか：プログラミングの進化史

プログラミング言語の抽象化の歴史

Kiroの創業者の洞察

なぜ今なのか？

理由1: AIの能力が実用レベルに到達した

理由2: コードの複雑性が限界に達した

理由3: チーム開発での一貫性が必須になった

SDDの4フェーズワークフロー

フェーズ1: Specify（高レベル仕様）

フェーズ2: Plan（技術設計）

フェーズ3: Tasks（タスク分解）

フェーズ4: Implement（実装）

実践：GitHub Spec Kitを使った開発

Spec Kitとは？

インストール

基本的な使い方

1. プロジェクト初期化

2. 仕様の作成

3. 技術計画の作成

4. タスク分解

5. 実装

Spec Kitの実践例：実際の開発フロー

Spec Kitの利点

Kiroによる実践例：Towers of Hanoiゲーム

Kiroとは？

Kiroの特徴

実践例：Towers of Hanoiゲームの開発

ステップ1: 初期仕様の作成

ステップ2: 仕様の段階的拡張

ステップ3: バグ修正も仕様で

Kiroの実践的な使い方

KiroとSpec Kitの比較

適切なアプローチの選択

開発アプローチのスペクトラム

プロジェクト特性による選択

機能別の選択

実践的な判断基準

ハイブリッドアプローチ

実際の導入事例と効果

事例1: GitHubの内部プロジェクト

事例2: スタートアップのMVP開発

事例3: エンタープライズでのレガシーマイグレーション

マルチプレイヤー開発への進化：Runbooksの概念

シングルプレイヤーからマルチプレイヤーへ

Runbooksとは？

Runbooksの特徴

Runbooksの実践例

Runbooksのメリット

実装例：Aviator Runbooks

RunbooksとSpec-Drivenの統合

今日から始める実践ガイド

🎯 まず、どのパターンを選ぶべきか？

パターンC: シンプルなMarkdownから始める（初心者向け）

ステップ1: プロジェクト構造を作る（5分）

ステップ2: 最初の仕様書を書く（30分）

ステップ3: AIに実装を依頼する（10分）

ステップ4: 生成されたコードをレビュー（20分）

ステップ5: 仕様書を更新（必要に応じて）

ステップ6: チームで共有

パターンA: Spec Kitで始める（中級者向け）

なぜSpec Kitなのか？

ステップ1: インストール（5分）

ステップ2: 新規プロジェクトの作成（10分）

ステップ3: 仕様書を生成（15分）

ステップ4: 技術設計を生成（15分）