aiskillstore/spec

/spec Skill - 仕様策定ワークフロー

仕様駆動開発（SDD）の上流工程を担当するSkill。 自然言語の要件から、構造化された仕様書（EPIC/Story/Subtask）を段階的に生成します。

発動条件

以下のキーワードで自動発動：

• 「specを作成して」「仕様を策定して」
• 「[機能名]のspecを書いて」
• 「新機能の仕様を定義して」
• 「要件を整理して」

基本原則

1. 段階的対話: Requirements → Design → Tasks の3フェーズ
2. EARS記法: 曖昧さのない受け入れ基準を生成
3. ユーザー承認: 各フェーズで「次に進んで」を確認してからファイル生成
4. 3階層出力: EPIC/Story/Subtaskファイルを適切に分割

---

ワークフロー

Phase 1: Requirements Discovery（要件発見）

┌─────────────────────────────────────────────────┐
│  1. 要件ヒアリング                              │
│     - ユーザーからの自然言語入力を受け取る      │
│     - 不明点があれば質問する                    │
│                                                 │
│  2. ユーザーストーリー生成                      │
│     - ペルソナ、目的、価値、理由を明確化        │
│     - 暗黙の要件を明示化                        │
│                                                 │
│  3. EARS記法でAC生成                            │
│     - WHEN/GIVEN/THEN形式で構造化               │
│     - エッジケースを考慮                        │
│     - セキュリティ/パフォーマンス要件を補完     │
│                                                 │
│  4. ユーザー確認                                │
│     「この要件で進めますか？」                  │
│     - 「次に進んで」→ Phase 2へ                 │
│     - 「修正して」→ 内容を調整                  │
└─────────────────────────────────────────────────┘

Phase 2: Design Exploration（設計探索）

┌─────────────────────────────────────────────────┐
│  1. 既存コードベース分析                        │
│     - 関連する既存コードを探索                  │
│     - 使用技術スタック確認                      │
│     - 既存パターンとの整合性確認                │
│                                                 │
│  2. 技術設計生成                                │
│     - データフロー図（Mermaid）                 │
│     - インターフェース定義（TypeScript）        │
│     - API設計（必要に応じて）                   │
│                                                 │
│  3. アーキテクチャ決定                          │
│     - 複数アプローチがある場合は選択肢を提示    │
│     - トレードオフを説明                        │
│                                                 │
│  4. ユーザー確認                                │
│     「この設計で進めますか？」                  │
│     - 「次に進んで」→ Phase 3へ                 │
│     - 「修正して」→ 設計を調整                  │
└─────────────────────────────────────────────────┘

Phase 3: Task Breakdown（タスク分割）

┌─────────────────────────────────────────────────┐
│  1. EPIC/Story/Subtask分割                      │
│     - 適切な粒度でSubtaskに分割                 │
│     - 1 Subtask = 1機能                         │
│     - 依存関係を整理                            │
│                                                 │
│  2. 実装順序の最適化                            │
│     - 依存関係に基づく順序付け                  │
│     - 基盤機能を先に配置                        │
│                                                 │
│  3. ファイル生成プレビュー                      │
│     - 生成するファイル一覧を表示                │
│     - 各ファイルの概要を説明                    │
│                                                 │
│  4. ユーザー確認                                │
│     「このタスク分割で進めますか？」            │
│     - 「次に進んで」→ ファイル生成              │
│     - 「修正して」→ 分割を調整                  │
└─────────────────────────────────────────────────┘

ファイル生成

┌─────────────────────────────────────────────────┐
│  生成ファイル:                                  │
│                                                 │
│  specs/{epic-id}/{epic-id}.md                   │
│  ├── ユーザーストーリー                         │
│  ├── EPICレベルAC                               │
│  └── 関連Storyへのリンク                        │
│                                                 │
│  specs/{epic-id}/{story-id}/{story-id}.md       │
│  ├── ユーザーストーリー                         │
│  ├── StoryレベルAC                              │
│  └── 関連Subtaskへのリンク                      │
│                                                 │
│  specs/{epic-id}/{story-id}/{subtask-id}.md     │
│  ├── ユーザーストーリー                         │
│  ├── EARS記法によるAC                           │
│  ├── 設計セクション（該当する場合）             │
│  └── テストケーステンプレート                   │
│                                                 │
│  一覧ファイル:                                  │
│  specs/epic-list.md                             │
│  specs/{epic-id}/story-list.md                  │
│  specs/{epic-id}/{story-id}/subtask-list.md     │
└─────────────────────────────────────────────────┘

---

EARS記法テンプレート

イベント駆動型

- [ ] WHEN [トリガー・状況]
      GIVEN [前提条件]
      THEN [期待動作]
      AND [追加動作]

状態依存型

- [ ] WHILE [状態・プロセス]
      THE SYSTEM SHALL [必須動作]
      AND [関連動作]

条件付き型

- [ ] WHERE [機能・コンポーネント]
      IF [条件・状態]
      THE SYSTEM SHALL [対応動作]

---

対話制御コマンド

| コマンド | 動作 | |----------|------| | 「次に進んで」 | 現フェーズを完了し、次フェーズへ進む | | 「修正して」 | 現フェーズ内で内容を調整 | | 「やり直して」 | 現フェーズを最初からやり直し | | 「詳しく説明して」 | より詳細な説明や選択肢を提示 | | 「スキップして」 | 現フェーズをスキップ（非推奨） |

---

出力例

入力

「ユーザー認証機能のspecを作成して。OAuth対応、多要素認証を含めて」

Phase 1 出力（Requirements）

## ユーザーストーリー

**ペルソナ**: エンドユーザー / 管理者
**目的**: セキュアにシステムにアクセスする
**価値**: 個人情報を保護しながら利便性を確保
**理由**: 不正アクセスを防ぎつつ、ログイン体験を向上させたい

## Acceptance Criteria（EARS記法）

### 基本認証

- [ ] WHEN ユーザーがログインを試行する際
      GIVEN 有効なメールアドレスとパスワードを入力した場合
      THEN システムはセッションを作成する
      AND ダッシュボードにリダイレクトする

- [ ] WHEN ユーザーがログインを試行する際
      GIVEN 無効な認証情報を入力した場合
      THEN システムはエラーメッセージを表示する
      AND 試行回数をカウントする

### OAuth認証

- [ ] WHEN ユーザーがOAuthプロバイダーでログインを選択した際
      GIVEN Google/GitHubアカウントで認証した場合
      THEN システムはアカウントを連携する
      AND 初回の場合はユーザープロファイルを作成する

### 多要素認証

- [ ] WHEN MFA有効ユーザーがパスワード認証を完了した際
      GIVEN 正しいパスワードを入力した場合
      THEN システムはMFAコード入力画面を表示する
      AND 認証アプリまたはSMSでコードを送信する

この要件で進めますか？

---

禁止事項

• ユーザー確認なしでのフェーズ進行
• EARS記法を使わない曖昧なAC生成
• 依存関係を考慮しないタスク分割
• 既存コードベースを無視した設計

---

ブランチ・PR連携

本Skillは /branch と /pr を自動的に呼び出します。

連携フロー

/spec 開始
    │
    ├─ Phase 1: Requirements Discovery
    │
    ├─ Phase 2: Design Exploration
    │
    ├─ Phase 3: Task Breakdown
    │       │
    │       └─ ユーザー確認後 → /branch 発火
    │          ブランチ: spec/{subtask-id}-{description}
    │
    ├─ ファイル生成
    │   - specs/{epic-id}/{epic-id}.md
    │   - specs/{epic-id}/{story-id}/{story-id}.md
    │   - specs/{epic-id}/{story-id}/{subtask-id}.md
    │   - 各 *-list.md ファイル
    │
    └─ 完了時 → /pr 発火
        PR: 仕様レビュー用

/branch 呼び出し

ファイル生成前に自動発火：

Claude: 仕様ファイルを生成する前に、ブランチを作成します。

        ブランチ名: spec/001-01-01-user-auth
        ベース: main

        作成してよいですか？

/pr 呼び出し

ファイル生成完了後に自動発火：

Claude: 仕様ファイルの生成が完了しました。

        PRを作成しますか？
        タイトル: spec: ユーザー認証機能の仕様策定

        ## Summary
        - 001-01-01 の仕様を策定
        - specs/001-environment-setup/001-01-common-config/001-01-01-*.md を作成

        ## レビュー観点
        - [ ] ユーザーストーリーが明確か
        - [ ] ACがEARS記法で記述されているか

---

関連Skill

• /branch: ブランチ作成（本Skillから自動呼び出し）
• /pr: PR作成（本Skillから自動呼び出し）
• spec-workflow: 本Skillで生成した仕様書に基づいて実装を行う

全体連携フロー

/spec（仕様策定）
    ├─ /branch 発火（spec/*）
    ├─ ファイル生成
    └─ /pr 発火（仕様レビュー）
        ↓ マージ後
spec-workflow（実装）
    ├─ /branch 発火（impl/*）
    ├─ TDD実装
    └─ /pr 発火（実装レビュー）