@sk8metal/michi-cli 0.10.1 → 0.12.0

package/docs/user-guide/hands-on/workflow-walkthrough.md

@@ -1,1078 +0,0 @@
-# Michiワークフロー体験ガイド
-
-このガイドでは、サンプル機能（`health-check-endpoint`）を使って、Michiの全ワークフローを実際に体験します。
-
-## 🎯 このガイドの目的
-
-- spec-init → requirements → design → tasks → 実装の流れを体験
-- Confluence/JIRA自動連携の動作を確認
-- phase:runコマンドの使い方を習得
-- 実際のプロジェクトで使えるスキルを身につける
-
-## 📋 前提条件
-
-このガイドを開始する前に、環境別セットアップを完了してください：
-
-- [Cursor IDEセットアップ](./cursor-setup.md)
-- [Claude Codeセットアップ](./claude-setup.md)
-- [Claude Subagentsセットアップ](./claude-agent-setup.md)
-
-## 🚀 サンプル機能: health-check-endpoint
-
-### 機能概要
-
-アプリケーションの稼働状況を確認するHTTPエンドポイント
-
-**エンドポイント**: `GET /health`
-
-**レスポンス例**:
-
-```json
-{
-  "status": "ok",
-  "timestamp": "2025-01-15T10:30:00Z",
-  "version": "1.0.0"
-}
-```
-
-### なぜこの機能を選んだか
-
-- シンプルで理解しやすい
-- 実装が少ない（検証が容易）
-- 実際のプロジェクトでもよく使われる
-- すべての開発フェーズを体験できる
-
-## 📖 ワークフロー全体像
-
-```
-Phase 0.0: 初期化 (spec-init)
-  ↓
-Phase 0.1: 要件定義 (spec-requirements + phase:run)
-  ↓ Confluence自動作成
-  ↓
-Phase 0.2: 設計 (spec-design + phase:run)
-  ↓ Confluence自動作成
-  ↓
-Phase 0.3-0.4: テスト計画（テストタイプ選択 + テスト仕様書作成）
-  ↓
-Phase 0.5: タスク分割 (spec-tasks)
-  ↓
-Phase 0.6: タスクのJIRA同期 (phase:run tasks)
-  ↓ JIRA Epic/Story自動作成
-  ↓
-Phase 1: 環境構築・基盤整備
-  ↓ テスト環境セットアップ
-  ↓
-Phase 2: TDD実装 → Phase A (PR前テスト) → Phase 3 (追加QA) → Phase B (リリース前テスト) → Phase 4-5 (リリース準備・実行)
-```
-
-**注意**: このワークフローガイドでは、体験の便宜上、Phase 0.3-0.4（テスト計画）とPhase 1（環境構築）はスキップします。
-詳細なテスト計画については [テスト計画フロー](../testing/test-planning-flow.md) を参照してください。
-
-## ステップバイステップガイド
-
-### Step 0: 環境セットアップの確認
-
-このワークフローを開始する前に、Michiの環境セットアップが完了している必要があります。
-
-#### 0-1: セットアップ状態の確認
-
-```bash
-# プロジェクトディレクトリに移動
-cd /path/to/your-project
-
-# .kiro/ディレクトリが存在するか確認
-ls -la .kiro/
-```
-
-**✅ セットアップ完了済みの場合**:
-
-以下のディレクトリ/ファイルが存在するはずです：
-
-```
-drwxr-xr-x  4 user  staff  128 Jan 15 10:00 .
-drwxr-xr-x  10 user  staff  320 Jan 15 10:00 ..
--rw-r--r--  1 user  staff  512 Jan 15 10:00 project.json
-drwxr-xr-x  3 user  staff   96 Jan 15 10:00 settings
-drwxr-xr-x  2 user  staff   64 Jan 15 10:00 specs
-```
-
-確認項目：
-
-- ✅ `.kiro/project.json` が存在
-- ✅ `.kiro/settings/templates/` が存在
-- ✅ `.kiro/specs/` が存在（空でもOK）
-
-**注意**: `.kiro/steering/` は `/kiro:steering` コマンドで必要に応じて作成します（セットアップ直後には存在しません）。
-
-→ **すべて存在する場合、Step 1に進んでください**
-
-**❌ セットアップ未完了の場合**:
-
-以下のエラーが表示されます：
-
-```
-ls: .kiro/: No such file or directory
-```
-
-または、一部のディレクトリ/ファイルが不足しています。
-
-→ **以下の「0-2: セットアップ実行」を完了してください**
-
-#### 0-2: セットアップ実行（未完了の場合のみ）
-
-**重要**: セットアップを実行する前に、プロジェクトの基本構成を確認してください。
-
-##### Git リポジトリの確認（推奨）
-
-Michiは Git リポジトリでの使用を推奨していますが、必須ではありません。
-
-```bash
-# プロジェクトディレクトリに移動
-cd /path/to/your-project
-
-# Git リポジトリかどうか確認
-ls -la .git
-
-# .git ディレクトリがない場合は初期化（推奨）
-git init
-```
-
-**注意**: Git リポジトリでない場合でも `setup-existing` は実行できますが、警告が表示されます。
-
-##### セットアップの実行
-
-環境別セットアップガイドに従ってセットアップを完了してください：
-
-> **📦 パッケージ公開状況について**:
->
-> - **パッケージ公開後**: `npx @sk8metal/michi-cli` を使用
-> - **パッケージ公開前（ローカルテスト）**: 以下の方法を使用
->   - 方法1（推奨）: `npm link` でグローバルリンクを作成後、`michi` コマンドを使用
->   - 方法2: `npx tsx /path/to/michi/src/cli.ts` で直接実行
-
-**Cursor IDEの場合**:
-
-```bash
-# Step 1: cc-sdd導入
-npx cc-sdd@latest --cursor --lang ja
-
-# Step 2: Michi固有ファイル追加
-
-# パッケージ公開後:
-npx @sk8metal/michi-cli setup-existing --cursor --lang ja
-
-# パッケージ公開前（ローカルテスト）- 方法1（推奨）:
-# 事前準備（一度だけ実行）:
-#   cd /Users/arigatatsuya/Work/git/michi
-#   npm link
-# その後:
-michi setup-existing --cursor --lang ja
-
-# パッケージ公開前（ローカルテスト）- 方法2:
-npx tsx /Users/arigatatsuya/Work/git/michi/src/cli.ts setup-existing --cursor --lang ja
-
-# 対話的プロンプトで入力:
-# - 環境: 1 (Cursor IDE)
-# - プロジェクト名: サンプルプロジェクト（または任意の名前）
-# - JIRAプロジェクトキー: DEMO（または任意のキー）
-
-# Step 3: 環境変数設定
-vim .env
-# 最低限、以下を設定:
-# GITHUB_TOKEN=your-token
-# GITHUB_ORG=your-org
-```
-
-> **Note (v0.5.0以降)**: `GITHUB_REPO` 環境変数は廃止されました。リポジトリ情報は `.kiro/project.json` の `repository` フィールドから自動的に取得されます。
-
-```
-
-詳細: [Cursor IDEセットアップガイド](./cursor-setup.md)
-
-**Claude Codeの場合**:
-
-```bash
-# Step 1: cc-sdd導入
-npx cc-sdd@latest --claude --lang ja
-
-# Step 2: Michi固有ファイル追加
-
-# パッケージ公開後:
-npx @sk8metal/michi-cli setup-existing --claude --lang ja
-
-# パッケージ公開前（ローカルテスト）:
-npx tsx /Users/arigatatsuya/Work/git/michi/src/cli.ts setup-existing --claude --lang ja
-
-# または npm link 使用時:
-michi setup-existing --claude --lang ja
-
-# Step 3: 環境変数設定
-vim .env
-```
-
-詳細: [Claude Codeセットアップガイド](./claude-setup.md)
-
-**Claude Subagentsの場合**:
-
-詳細: [Claude Subagentsセットアップガイド](./claude-agent-setup.md)
-
-#### 0-3: セットアップ完了の確認
-
-セットアップが完了したら、再度確認してください：
-
-```bash
-# .kiro/ディレクトリの確認
-ls -la .kiro/
-
-# 必要なファイルが存在することを確認
-ls -la .kiro/project.json
-ls -la .kiro/settings/templates/
-ls -la .kiro/steering/
-```
-
-すべて存在することを確認したら、**Step 1**に進んでください。
-
-### Step 1: 機能の初期化 (spec-init)
-
-#### Cursor IDE / VS Codeの場合
-
-Cursor/VS Codeで以下のコマンドを実行：
-
-```
-/kiro:spec-init ヘルスチェックエンドポイント。GET /health で稼働状況を返すAPI。
-```
-
-#### Claude Codeの場合
-
-Claude Codeで以下のスラッシュコマンドを実行：
-
-```
-/kiro:spec-init ヘルスチェックエンドポイント。GET /health で稼働状況を返すAPI。
-```
-
-#### 実行結果の確認
-
-```bash
-# 生成されたディレクトリを確認
-ls -la .kiro/specs/health-check-endpoint/
-
-# 期待される結果:
-# drwxr-xr-x  2 user  staff   64 Jan 15 10:00 .
-# drwxr-xr-x  3 user  staff   96 Jan 15 10:00 ..
-# -rw-r--r--  1 user  staff  512 Jan 15 10:00 spec.json
-```
-
-**spec.jsonの内容を確認**:
-
-```bash
-cat .kiro/specs/health-check-endpoint/spec.json
-```
-
-```json
-{
-  "feature": "health-check-endpoint",
-  "status": "draft",
-  "createdAt": "2025-01-15T10:00:00Z",
-  "phases": {
-    "requirements": "pending",
-    "design": "pending",
-    "tasks": "pending",
-    "implementation": "pending"
-  }
-}
-```
-
-### Step 2: 要件定義の作成 (spec-requirements)
-
-#### AIで requirements.md を生成
-
-**Cursor IDE / VS Codeの場合**:
-
-```
-/kiro:spec-requirements health-check-endpoint
-```
-
-**Claude Codeの場合**:
-
-```
-/kiro:spec-requirements health-check-endpoint
-```
-
-#### 生成されたファイルの確認
-
-```bash
-# requirements.mdが生成されたか確認
-ls -la .kiro/specs/health-check-endpoint/
-
-cat .kiro/specs/health-check-endpoint/requirements.md
-```
-
-**期待される内容（例）**:
-
-```markdown
-# health-check-endpoint 要件定義
-
-## ビジネス要件
-
-- アプリケーションの稼働状況を監視する
-- ヘルスチェックツールから定期的に呼び出される
-- 障害発生時の早期検知に使用
-
-## 機能要件
-
-### FR-1: ヘルスチェックエンドポイント
-
-- エンドポイント: GET /health
-- レスポンス形式: JSON
-- ステータスコード: 200 (正常), 503 (異常)
-
-...
-```
-
-#### Confluenceに同期（phase:run）
-
-**重要**: AIでファイルを生成しただけでは、Confluenceには同期されません。`phase:run`コマンドを実行する必要があります。
-
-```bash
-# requirements フェーズを実行（Confluence作成 + バリデーション）
-
-# パッケージ公開後:
-npx @sk8metal/michi-cli phase:run health-check-endpoint requirements
-
-# パッケージ公開前（ローカルテスト）:
-npx tsx /Users/arigatatsuya/Work/git/michi/src/cli.ts phase:run health-check-endpoint requirements
-
-# または npm link 使用時:
-michi phase:run health-check-endpoint requirements
-```
-
-**実行結果**:
-
-```
-🚀 Phase Runner: requirements
-📁 Feature: health-check-endpoint
-
-Step 1: Validating requirements.md exists...
-   ✅ requirements.md found
-
-Step 2: Creating Confluence page...
-   ✅ Confluence page created
-   📄 Page ID: 123456789
-   🔗 URL: https://your-domain.atlassian.net/wiki/spaces/PRD/pages/123456789
-
-Step 3: Updating spec.json...
-   ✅ spec.json updated
-   ✅ confluence.requirementsPageId: 123456789
-
-Step 4: Validation complete
-   ✅ All checks passed
-```
-
-#### 確認: Confluenceページを開く
-
-ブラウザでConfluenceページを開いて確認：
-
-```bash
-# Confluenceページを開く
-open "https://your-domain.atlassian.net/wiki/spaces/PRD/pages/123456789"
-```
-
-**期待される内容**:
-
-- タイトル: `[DEMO] health-check-endpoint - 要件定義`
-- ラベル: `project:xxx`, `feature:health-check-endpoint`, `phase:requirements`
-- 本文: requirements.mdの内容がConfluence形式で表示される
-
-### Step 3: 設計書の作成 (spec-design)
-
-#### AIで design.md を生成
-
-**Cursor IDE / VS Codeの場合**:
-
-```
-/kiro:spec-design health-check-endpoint
-```
-
-**Claude Codeの場合**:
-
-```
-/kiro:spec-design health-check-endpoint
-```
-
-#### 生成されたファイルの確認
-
-```bash
-cat .kiro/specs/health-check-endpoint/design.md
-```
-
-**期待される内容（例）**:
-
-```markdown
-# health-check-endpoint 設計書
-
-## アーキテクチャ
-
-### コンポーネント構成
-```
-
-Client → API Gateway → Health Controller → Health Service
-
-````
-
-## API設計
-
-### GET /health
-
-**リクエスト**: なし
-
-**レスポンス**:
-```json
-{
-  "status": "ok",
-  "timestamp": "2025-01-15T10:30:00Z",
-  "version": "1.0.0"
-}
-````
-
-...
-
-````
-
-#### Confluenceに同期（phase:run）
-
-```bash
-# design フェーズを実行（Confluence作成 + バリデーション）
-
-# パッケージ公開後:
-npx @sk8metal/michi-cli phase:run health-check-endpoint design
-
-# パッケージ公開前（ローカルテスト）:
-npx tsx /Users/arigatatsuya/Work/git/michi/src/cli.ts phase:run health-check-endpoint design
-
-# または npm link 使用時:
-michi phase:run health-check-endpoint design
-````
-
-**実行結果**:
-
-```
-🚀 Phase Runner: design
-📁 Feature: health-check-endpoint
-
-Step 1: Validating design.md exists...
-   ✅ design.md found
-
-Step 2: Creating Confluence page...
-   ✅ Confluence page created
-   📄 Page ID: 123456790
-   🔗 URL: https://your-domain.atlassian.net/wiki/spaces/PRD/pages/123456790
-
-Step 3: Updating spec.json...
-   ✅ spec.json updated
-   ✅ confluence.designPageId: 123456790
-
-Step 4: Validation complete
-   ✅ All checks passed
-```
-
-### Step 4: タスク分割 (spec-tasks)
-
-#### AIで tasks.md を生成（全6フェーズ）
-
-**重要**: tasks.mdは、要件定義からリリースまでの**全6フェーズ**を含む必要があります。
-
-**Cursor IDE / VS Codeの場合**:
-
-```
-/kiro:spec-tasks health-check-endpoint
-```
-
-**Claude Codeの場合**:
-
-```
-/kiro:spec-tasks health-check-endpoint
-```
-
-**重要**: 全6フェーズを含めるよう指示してください。
-
-#### 生成されたファイルの確認
-
-```bash
-cat .kiro/specs/health-check-endpoint/tasks.md
-```
-
-**期待される構造**:
-
-```markdown
-# health-check-endpoint タスク分割
-
-## Phase 0: 要件定義（Requirements）
-
-### Story 0.1: 要件定義書作成
-
-- タスク: requirements.mdを作成
-- 見積もり: 2時間
-- 担当: PL
-
-## Phase 1: 設計（Design）
-
-### Story 1.1: 基本設計
-
-- タスク: design.mdを作成
-- 見積もり: 4時間
-- 担当: アーキテクト
-
-## Phase 2: 実装（Implementation）
-
-### Story 2.1: Health Controller実装
-
-- タスク: HealthController.javaを実装
-- 見積もり: 3時間
-- 担当: 開発者
-
-### Story 2.2: Health Service実装
-
-- タスク: HealthService.javaを実装
-- 見積もり: 2時間
-- 担当: 開発者
-
-## Phase 3: 試験（Testing）
-
-### Story 3.1: 単体テスト
-
-- タスク: HealthControllerTest.javaを実装
-- 見積もり: 2時間
-- 担当: テスター
-
-### Story 3.2: 結合テスト
-
-- タスク: Health APIの結合テスト
-- 見積もり: 3時間
-- 担当: テスター
-
-## Phase 4: リリース準備（Release Preparation）
-
-### Story 4.1: ドキュメント作成
-
-- タスク: API仕様書を作成
-- 見積もり: 1時間
-- 担当: 開発者
-
-## Phase 5: リリース（Release）
-
-### Story 5.1: ステージングデプロイ
-
-- タスク: ステージング環境にデプロイ
-- 見積もり: 1時間
-- 担当: SM
-
-### Story 5.2: 本番リリース
-
-- タスク: 本番環境にリリース
-- 見積もり: 1時間
-- 担当: SM
-```
-
-#### JIRAに同期（phase:run）
-
-**重要**: これが最も重要なステップです。全6フェーズのJIRA Epic/Storyが自動作成されます。
-
-```bash
-# tasks フェーズを実行（JIRA Epic/Story作成 + バリデーション）
-
-# パッケージ公開後:
-npx @sk8metal/michi-cli phase:run health-check-endpoint tasks
-
-# パッケージ公開前（ローカルテスト）:
-npx tsx /Users/arigatatsuya/Work/git/michi/src/cli.ts phase:run health-check-endpoint tasks
-
-# または npm link 使用時:
-michi phase:run health-check-endpoint tasks
-```
-
-**実行結果**:
-
-```
-🚀 Phase Runner: tasks
-📁 Feature: health-check-endpoint
-
-Step 1: Validating tasks.md exists...
-   ✅ tasks.md found
-
-Step 2: Validating tasks.md structure...
-   ✅ All 6 phases detected:
-      - Phase 0: 要件定義（Requirements）
-      - Phase 1: 設計（Design）
-      - Phase 2: 実装（Implementation）
-      - Phase 3: 試験（Testing）
-      - Phase 4: リリース準備（Release Preparation）
-      - Phase 5: リリース（Release）
-
-Step 3: Creating JIRA Epic...
-   ✅ Epic created: DEMO-100
-   📋 Epic: [サンプルプロジェクト] health-check-endpoint
-
-Step 4: Creating JIRA Stories...
-   ✅ Story created: DEMO-101 (Phase 0: Story 0.1)
-   ✅ Story created: DEMO-102 (Phase 1: Story 1.1)
-   ✅ Story created: DEMO-103 (Phase 2: Story 2.1)
-   ✅ Story created: DEMO-104 (Phase 2: Story 2.2)
-   ✅ Story created: DEMO-105 (Phase 3: Story 3.1)
-   ✅ Story created: DEMO-106 (Phase 3: Story 3.2)
-   ✅ Story created: DEMO-107 (Phase 4: Story 4.1)
-   ✅ Story created: DEMO-108 (Phase 5: Story 5.1)
-   ✅ Story created: DEMO-109 (Phase 5: Story 5.2)
-
-Step 5: Updating spec.json...
-   ✅ spec.json updated
-   ✅ jira.epicKey: DEMO-100
-   ✅ jira.stories: [DEMO-101, ..., DEMO-109]
-
-Step 6: Validation complete
-   ✅ All checks passed
-```
-
-#### 確認: JIRAを開く
-
-ブラウザでJIRAを開いて確認：
-
-```bash
-# JIRAのEpicを開く
-open "https://your-domain.atlassian.net/browse/DEMO-100"
-```
-
-**期待される内容**:
-
-- Epic: `[サンプルプロジェクト] health-check-endpoint`
-- リンクされたStory: 9件（DEMO-101〜DEMO-109）
-- 各Storyにラベル自動付与：
-  - `Requirements`
-  - `Design`
-  - `Implementation`
-  - `Testing`
-  - `Release-Preparation`
-  - `Release`
-
-### Step 5: 生成物の確認
-
-すべてのフェーズが完了したら、生成物を確認します。
-
-#### ローカルファイルの確認
-
-```bash
-# 生成されたファイルを確認
-ls -la .kiro/specs/health-check-endpoint/
-
-# 期待される結果:
-# -rw-r--r--  1 user  staff  2048 Jan 15 10:00 spec.json
-# -rw-r--r--  1 user  staff  4096 Jan 15 10:10 requirements.md
-# -rw-r--r--  1 user  staff  6144 Jan 15 10:20 design.md
-# -rw-r--r--  1 user  staff  8192 Jan 15 10:30 tasks.md
-```
-
-#### spec.jsonの確認
-
-```bash
-cat .kiro/specs/health-check-endpoint/spec.json
-```
-
-**期待される内容**:
-
-```json
-{
-  "feature": "health-check-endpoint",
-  "status": "in_progress",
-  "createdAt": "2025-01-15T10:00:00Z",
-  "updatedAt": "2025-01-15T10:30:00Z",
-  "phases": {
-    "requirements": "completed",
-    "design": "completed",
-    "tasks": "completed",
-    "implementation": "pending"
-  },
-  "confluence": {
-    "requirementsPageId": "123456789",
-    "designPageId": "123456790"
-  },
-  "jira": {
-    "epicKey": "DEMO-100",
-    "stories": [
-      "DEMO-101",
-      "DEMO-102",
-      "DEMO-103",
-      "DEMO-104",
-      "DEMO-105",
-      "DEMO-106",
-      "DEMO-107",
-      "DEMO-108",
-      "DEMO-109"
-    ]
-  }
-}
-```
-
-#### Confluenceページの確認
-
-```bash
-# 要件定義ページを開く
-open "https://your-domain.atlassian.net/wiki/spaces/PRD/pages/123456789"
-
-# 設計書ページを開く
-open "https://your-domain.atlassian.net/wiki/spaces/PRD/pages/123456790"
-```
-
-#### JIRAの確認
-
-```bash
-# Epicを開く
-open "https://your-domain.atlassian.net/browse/DEMO-100"
-
-# 特定のStoryを開く
-open "https://your-domain.atlassian.net/browse/DEMO-103"
-```
-
-### Step 6: 実装（JIRA連携は自動）
-
-実装フェーズを開始します。JIRA連携はAIコマンドが自動で行います。
-
-#### 実装タスクの確認
-
-```bash
-# tasks.mdの実装フェーズを確認
-grep -A 10 "Phase 2: 実装" .kiro/specs/health-check-endpoint/tasks.md
-```
-
-**期待される内容**:
-
-```
-## Phase 2: 実装（Implementation）
-
-### Story 2.1: Health Controller実装
-- タスク: HealthController.javaを実装
-- 見積もり: 3時間
-- 担当: 開発者
-- JIRA: DEMO-103
-```
-
-#### TDDで実装（JIRA連携付き）
-
-Michiは**TDD（テスト駆動開発）**を推奨しています：
-
-```
-# Cursor/VS Code/Claude Code:
-/kiro:spec-impl health-check-endpoint
-```
-
-**自動実行される処理**:
-
-- ✅ spec.json から JIRA 情報を自動取得
-- ✅ Epic + 最初の Story を「進行中」に移動
-- ✅ TDD で実装（テスト → コード → リファクタリング）
-- ✅ PR 作成
-- ✅ Epic + 最初の Story を「レビュー待ち」に移動
-- ✅ JIRA に PR リンクをコメント
-
-**注意**: JIRA キーの手動指定は不要です。`jira:sync` 実行時に spec.json に保存された情報が自動で使用されます。
-
-#### GitHubブランチの作成（手動の場合）
-
-```bash
-# 新しい作業を開始
-jj new main
-
-# コミット
-jj commit -m "feat: health-check-endpoint の実装開始 [DEMO-103]"
-jj bookmark create michi/feature/health-check-endpoint -r '@-'
-```
-
-#### 個別のJIRA操作（必要な場合のみ）
-
-```bash
-# ステータス変更のみ
-michi jira:transition DEMO-103 "Ready for Review"
-
-# コメント追加のみ
-michi jira:comment DEMO-103 "PRを作成しました: https://github.com/..."
-```
-
-## ✅ 完了チェックリスト
-
-すべてのステップが正常に完了したか確認してください：
-
-### Phase 0.0: 初期化
-
-- [ ] `.kiro/specs/health-check-endpoint/` ディレクトリが作成された
-- [ ] `spec.json` が生成された
-
-### Phase 0.1: 要件定義
-
-- [ ] `requirements.md` が生成された
-- [ ] Confluenceページが作成された（要件定義）
-- [ ] `spec.json` に `confluence.requirementsPageId` が記録された
-
-### Phase 0.2: 設計
-
-- [ ] `design.md` が生成された
-- [ ] Confluenceページが作成された（設計書）
-- [ ] `spec.json` に `confluence.designPageId` が記録された
-
-### Phase 0.3-0.4: テスト計画
-
-#### Phase 0.3: テストタイプの選択
-
-health-check-endpointの場合、以下のテストタイプを選択します：
-
-**判断基準**:
-
-| テストタイプ | 必要性 | 判断理由 |
-|-------------|--------|----------|
-| **単体テスト** | ✅ 必須 | HealthControllerとHealthServiceのロジックを検証 |
-| **統合テスト** | ✅ 推奨 | API全体の動作とレスポンス形式を検証 |
-| E2Eテスト | ❌ 不要 | 単一エンドポイントのみで複雑なフローなし |
-| パフォーマンステスト | ⚠️ 任意 | ヘルスチェックは高頻度で呼ばれるため検討可能 |
-| セキュリティテスト | ❌ 不要 | 認証不要の公開エンドポイント |
-
-**結論**: health-check-endpointでは**単体テスト**と**統合テスト**を実施します。
-
-#### Phase 0.4: テスト仕様書の作成
-
-テストタイプごとに仕様書を作成します。
-
-##### 単体テスト仕様書
-
-**作成場所**: `tests/specs/unit-test-spec.md`
-
-**期待される内容（例）**:
-
-```markdown
-# health-check-endpoint 単体テスト仕様
-
-## テスト対象
-
-- HealthController
-- HealthService
-
-## HealthControllerTest
-
-### TC-U-001: 正常系 - ステータス取得
-
-**目的**: HealthControllerが正常にヘルスチェック情報を返す
-
-**前提条件**:
-- HealthServiceがモック化されている
-- HealthService.getStatus()が`{status: "ok", timestamp: "2025-01-15T10:00:00Z"}`を返す
-
-**実行手順**:
-1. GET /health エンドポイントを呼び出す
-
-**期待結果**:
-- HTTPステータス: 200
-- レスポンスボディ: `{"status": "ok", "timestamp": "2025-01-15T10:00:00Z"}`
-
-### TC-U-002: 異常系 - サービスエラー
-
-**目的**: サービス層でエラーが発生した場合の処理
-
-**前提条件**:
-- HealthService.getStatus()が例外をスローする
-
-**実行手順**:
-1. GET /health エンドポイントを呼び出す
-
-**期待結果**:
-- HTTPステータス: 503
-- レスポンスボディ: `{"status": "error", "message": "..."}`
-
-## HealthServiceTest
-
-### TC-U-101: システムステータス正常
-
-**目的**: HealthServiceがシステムの正常状態を正しく判定
-
-**前提条件**:
-- すべての依存サービスが正常
-
-**実行手順**:
-1. HealthService.getStatus()を呼び出す
-
-**期待結果**:
-- status: "ok"
-- timestamp: 現在時刻のISO 8601形式
-```
-
-##### 統合テスト仕様書
-
-**作成場所**: `tests/specs/integration-test-spec.md`
-
-**期待される内容（例）**:
-
-```markdown
-# health-check-endpoint 統合テスト仕様
-
-## テスト対象
-
-- Health API全体（Controller → Service → Repository）
-
-## TC-I-001: 正常系 - エンドツーエンド
-
-**目的**: Health APIが期待通りに動作する
-
-**前提条件**:
-- テストサーバーが起動している
-- データベース接続が有効
-
-**実行手順**:
-1. GET http://localhost:8080/health をHTTPクライアントで呼び出す
-
-**期待結果**:
-- HTTPステータス: 200
-- Content-Type: application/json
-- レスポンスボディ:
-  ```json
-  {
-    "status": "ok",
-    "timestamp": "<ISO 8601形式>",
-    "version": "1.0.0"
-  }
-  ```
-
-## TC-I-002: 異常系 - データベース切断
-
-**目的**: DB接続エラー時の503レスポンス
-
-**前提条件**:
-- テストサーバーが起動している
-- データベースが停止している
-
-**実行手順**:
-1. GET http://localhost:8080/health を呼び出す
-
-**期待結果**:
-- HTTPステータス: 503
-- Content-Type: application/json
-- レスポンスボディ:
-  ```json
-  {
-    "status": "error",
-    "message": "Database connection failed"
-  }
-  ```
-```
-
-#### ディレクトリ構造の準備
-
-テスト仕様書を配置するディレクトリを作成します：
-
-```bash
-mkdir -p tests/specs
-```
-
-**確認**:
-
-```bash
-ls -la tests/specs/
-```
-
-**期待されるファイル**:
-
-```
-tests/specs/
-├── unit-test-spec.md
-└── integration-test-spec.md
-```
-
-#### 検証チェックリスト
-
-テスト計画が完了したら、以下を確認してください：
-
-- [ ] Phase 0.3: 必要なテストタイプを選択した（単体テスト + 統合テスト）
-- [ ] Phase 0.4: 単体テスト仕様書を作成した（`tests/specs/unit-test-spec.md`）
-- [ ] Phase 0.4: 統合テスト仕様書を作成した（`tests/specs/integration-test-spec.md`）
-- [ ] テストケースにID（TC-U-XXX、TC-I-XXX）を付与した
-- [ ] 各テストケースに目的・前提条件・実行手順・期待結果を記載した
-
-### Phase 0.5-0.6: タスク分割とJIRA同期
-
-- [ ] `tasks.md` が生成された
-- [ ] JIRA Epicが作成された
-- [ ] JIRA Storyが作成された
-- [ ] `spec.json` に `jira.epicKey` と `jira.stories` が記録された
-
-### Phase 1: 環境構築（このガイドではスキップ）
-
-- このハンズオンでは省略していますが、実際のプロジェクトでは：
-- [ ] テスト環境をセットアップ
-- [ ] テストデータを準備
-
-### Phase 2: 実装準備
-
-- [ ] GitHubブランチが作成された
-- [ ] 実装タスクが明確になった
-
-## 🎯 次のステップ
-
-ハンズオン体験が完了したら、以下を試してください：
-
-### 1. 実際のプロジェクトで適用
-
-学んだワークフローを実際のプロジェクトで適用してください：
-
-```bash
-# 実際の機能で試す
-/kiro:spec-init あなたの機能の説明
-```
-
-### 2. 検証チェックリスト
-
-各ステップが正しく動作しているか確認：
-
-- [検証チェックリスト](./verification-checklist.md)
-
-### 3. トラブルシューティング
-
-問題が発生した場合：
-
-- [トラブルシューティングガイド](./troubleshooting.md)
-
-### 4. 詳細なワークフローガイド
-
-さらに詳しく学びたい場合：
-
-- [ワークフローガイド](../guides/workflow.md)
-- [フェーズ自動化ガイド](../guides/phase-automation.md)
-
-## 🆘 よくある質問
-
-### Q: phase:runはいつ実行すべきですか？
-
-A: AIでMarkdownファイル（requirements.md、design.md、tasks.md）を生成した**直後**に実行してください。phase:runを実行しないと、Confluence/JIRAに同期されません。
-
-### Q: Confluence/JIRAがない環境でも体験できますか？
-
-A: はい。GitHubのみでもMichiの基本的なワークフローは体験できます。ただし、phase:runコマンドは実行できません。
-
-### Q: tasks.mdに6フェーズすべて含める必要がありますか？
-
-A: はい。phase:run tasksコマンドは、全6フェーズ（要件定義〜リリース）を期待しています。フェーズが不足している場合、バリデーションエラーになります。
-
-### Q: JIRAのStoryが作成されません
-
-A: 以下を確認してください：
-
-- `.env`ファイルのJIRA認証情報
-- `JIRA_ISSUE_TYPE_STORY` と `JIRA_ISSUE_TYPE_SUBTASK` の設定
-- tasks.mdのフォーマット（Phase X: フェーズ名（ラベル）形式）
-
-### Q: 間違えてphase:runを実行してしまいました
-
-A: Confluence/JIRAページは更新されますが、削除はされません。手動で修正するか、再度phase:runを実行して上書きしてください。
-
-## 📚 関連ドキュメント
-
-- [検証チェックリスト](./verification-checklist.md)
-- [トラブルシューティング](./troubleshooting.md)
-- [ワークフローガイド](../guides/workflow.md)
-- [クイックリファレンス](../reference/quick-reference.md)
-
-おつかれさまでした！ Michiの全ワークフローを体験していただきました。🎉