Initial commit

2025-11-30 09:05:37 +08:00
commit f7e0d862fb
51 changed files with 11850 additions and 0 deletions
--- a/commands/spec.md
+++ b/commands/spec.md
@@ -0,0 +1,549 @@
+## Spec
+
+**「コードを書く前に構造を与える」** - Kiro の spec-driven development に完全準拠
+
+従来のコード生成ツールとは異なり、開発の混沌に構造を与えることに重点を置いた Kiro の仕様駆動開発を実現。わずかな要件入力から、プロダクトマネージャーレベルの詳細な仕様と実装可能な設計まで段階的に展開し、**プロトタイプから本番環境**まで一貫した品質を保証します。
+
+### 使い方
+
+```bash
+# Claude に Spec Mode を依頼 (最小限の要件入力)
+「[機能説明] の spec を作成して」
+
+# Kiro 式段階的展開:
+# 1. 簡単な要件 → 詳細なユーザーストーリー自動生成
+# 2. EARS 記法による構造化された要件記述
+# 3. 段階的対話を通じた仕様の精緻化
+# 4. 3 つの独立したファイルを生成:
+#    - requirements.md: EARS 記法による要件定義
+#    - design.md: Mermaid 図・TypeScript インターフェース含む設計
+#    - tasks.md: ベストプラクティス自動適用の実装計画
+```
+
+### 実証された効果 (Kiro 実績)
+
+**2 日間でセキュアファイル共有アプリ**
+
+```bash
+「ファイル共有システム (暗号化対応) の spec を作成して」
+→ 2 日間で本番レベルの暗号化ファイル共有アプリケーション完成
+→ セキュリティベストプラクティス自動適用
+→ 追加プロンプト不要
+```
+
+**1 晩でゲーム開発 (未経験者)**
+
+```bash
+「2D パズルゲームの spec を作成して」
+→ ゲーム開発未経験のオープンソース開発者
+→ 1 晩でゲーム作成完了
+→ 実装ロジックは Kiro が処理、開発者は創造性に集中
+```
+
+**週末でプロトタイプ→本番**
+
+```bash
+「EC サイトの商品管理システムの spec を作成して」
+→ 1 週末でコンセプトから動作するプロトタイプまで
+→ プロトタイプから本番環境への一貫した品質
+→ spec-driven development による構造化アプローチ
+```
+
+### 基本例
+
+```bash
+# 新機能の spec 作成 (最小限入力)
+「商品レビューシステム
+- 星評価機能
+- コメント投稿
+- 画像アップロード」
+
+# システム機能の spec 作成
+「ユーザー認証
+- OAuth 対応
+- 多要素認証」
+
+# API 機能の spec 作成
+「決済システム API
+- Stripe 連携
+- セキュリティ重視」
+```
+
+### Claude との連携
+
+```bash
+# 複雑な機能 spec
+「チャット機能の spec を作成して。WebSocket、リアルタイム通知、履歴管理を含めて」
+
+# データベース連携機能 spec
+「EC サイトの在庫管理機能の spec を作成して。商品追加、在庫更新、アラート機能を含めて」
+
+# フロントエンド機能 spec
+「React ダッシュボードの spec を作成して。グラフ表示、フィルター、エクスポート機能を含めて」
+
+# バックエンド機能 spec
+「RESTful API の spec を作成して。認証、バリデーション、ログ記録を含めて」
+```
+
+### Spec Mode の特徴
+
+**段階的対話ワークフロー**
+
+- Kiro の本来の価値である段階的議論を完全再現
+- 各フェーズでユーザーと協力的に仕様を洗練
+- 疑問点の解消、選択肢の議論、承認プロセスを経てファイル生成
+
+**3 段階の対話的展開**
+
+- **Phase 1**: Requirements Discovery → 議論 → 承認 → `requirements.md` 生成
+- **Phase 2**: Design Exploration → 議論 → 承認 → `design.md` 生成
+- **Phase 3**: Implementation Planning → 議論 → 承認 → `tasks.md` 生成
+
+**動的な仕様策定**
+
+- 要件の曖昧さを対話で解消
+- 技術選択肢の提示と議論
+- トレードオフの説明と判断確認
+
+### 詳細例
+
+```bash
+# 複雑なシステム機能
+「オンライン決済システムの spec を作成して。Stripe 連携、セキュリティ、エラーハンドリングを含めて」
+
+# フロントエンド機能
+「React コンポーネントの spec を作成して。状態管理、プロパティ設計、テストを含めて」
+
+# バックエンド機能
+「GraphQL API の spec を作成して。スキーマ設計、リゾルバー、認証を含めて」
+
+# DevOps 機能
+「CI/CD パイプラインの spec を作成して。テスト自動化、デプロイメント、監視を含めて」
+```
+
+### 段階的対話ワークフロー (Phase by Phase)
+
+#### Phase 1: Requirements Discovery & Discussion
+
+**1. 最小限入力からの自動拡張 (Kiro 式)**
+
+```text
+ユーザー: 「ユーザー管理システム
+- ログイン機能
+- プロフィール編集
+- 管理者権限」
+
+Claude: 「要件から詳細なユーザーストーリーを生成します。
+この理解で正しいですか？
+
+自動生成されたユーザーストーリー:
+- ユーザー登録・認証機能 (OAuth 対応)
+- プロフィール管理機能 (アバター、設定)
+- 権限管理機能 (RBAC)
+- パスワードリセット機能
+- セキュリティ監査ログ
+
+明示されていない詳細を補完しました。他に必要な機能はありますか？」
+```
+
+**2. EARS 記法による構造化要件記述**
+
+```text
+Claude: 「Kiro の EARS 記法で要件を構造化します：
+
+EARS 記法による要件定義:
+
+WHEN ユーザーがログインを試行する際
+GIVEN 正しいメールアドレスとパスワードを入力した場合
+THEN システムは認証を確認する
+AND 成功時はダッシュボードにリダイレクトする
+
+WHILE ユーザーがプロフィール編集画面にいる間
+THE SYSTEM SHALL リアルタイムでバリデーションを実行する
+AND 変更内容をプレビュー表示する
+
+WHERE 管理者権限が必要な機能に
+IS アクセスが試行された場合
+THE SYSTEM SHALL 権限レベルを確認する
+AND 不十分な場合はアクセス拒否する」
+```
+
+**3. エッジケース・セキュリティ要件の自動補完**
+
+```text
+Claude: 「Kiro のベストプラクティスに基づき、以下のケースも考慮しました：
+
+セキュリティ要件 (自動補完):
+- ブルートフォース攻撃対策
+- セッション管理とタイムアウト
+- CSRF 保護と XSS 対策
+- パスワード強度要件
+
+エッジケース (自動検出):
+- 同時ログイン制限
+- アカウントロック機能
+- データ移行時の整合性確保
+- 大量リクエスト時の負荷分散
+
+これらの要件は適切ですか？」
+```
+
+**5. Phase 1 完了と承認**
+
+```text
+Claude: 「Requirements Phase が完了しました。
+requirements.md を生成してよろしいですか？」
+→ 「次に進んで」→ requirements.md 生成
+```
+
+#### Phase 2: Design Exploration & Discussion
+
+**1. コードベース分析 + 自動設計提案 (Kiro 式)**
+
+```text
+Claude: 「既存コードベースを分析し、最適なアーキテクチャを提案します：
+
+コードベース分析結果:
+- 認証: JWT + Express.js(v4.18.x)
+- データベース: PostgreSQL(v14+)
+- フロントエンド: React + TypeScript(v18+)
+- 既存パターン: Repository パターン、Service 層分離
+
+Kiro 推奨アーキテクチャ:
+- Clean Architecture 準拠
+- Domain-Driven Design 要素
+- CQRS パターンの部分的適用
+- 自動化されたセキュリティベストプラクティス
+
+この設計で進めますか？」
+```
+
+**2. Mermaid 図による視覚的設計**
+
+```text
+Claude: 「システム設計を Mermaid 図で自動生成しました：
+
+自動生成されたアーキテクチャ図:
+
+graph TB
+    Client[React Client] --> API[Express API Gateway]
+    API --> Auth[Auth Service]
+    API --> User[User Service]
+    API --> Profile[Profile Service]
+
+    Auth --> AuthDB[(Auth Database)]
+    User --> UserDB[(User Database)]
+    Profile --> ProfileDB[(Profile Database)]
+
+    Auth --> JWT[JWT Service]
+    Auth --> OAuth[OAuth Provider]
+
+データフロー図も生成しますか？」
+```
+
+**3. TypeScript インターフェース自動生成**
+
+```text
+Claude: 「設計に基づいて TypeScript インターフェースを自動生成します：
+
+自動生成 TypeScript インターフェース:
+
+// Domain entities
+interface User {
+  readonly id: UserId;
+  readonly email: Email;
+  readonly profile: UserProfile;
+  readonly auth: AuthSettings;
+  readonly permissions: Permission[];
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+interface UserProfile {
+  readonly displayName: string;
+  readonly avatar: AvatarUrl;
+  readonly preferences: UserPreferences;
+}
+
+interface AuthSettings {
+  readonly passwordHash: PasswordHash;
+  readonly mfaEnabled: boolean;
+  readonly lastLoginAt: Date;
+  readonly failedAttempts: number;
+}
+
+// Use cases
+interface UserRepository {
+  findById(id: UserId): Promise<User | null>;
+  findByEmail(email: Email): Promise<User | null>;
+  save(user: User): Promise<void>;
+}
+
+interface AuthenticationService {
+  authenticate(credentials: LoginCredentials): Promise<AuthResult>;
+  refreshToken(token: RefreshToken): Promise<AccessToken>;
+}
+
+このインターフェース設計で進めますか？」
+```
+
+**4. Phase 2 完了と承認**
+
+```text
+Claude: 「Design Phase が完了しました。
+design.md を生成してよろしいですか？」
+→ 「次に進んで」→ design.md 生成
+```
+
+#### Phase 3: Implementation Planning & Discussion
+
+**1. ベストプラクティス自動適用 (Kiro 式)**
+
+```text
+Claude: 「Kiro のベストプラクティスを自動適用した実装計画を生成しました：
+
+自動生成された実装戦略:
+
+1. セキュリティファースト開発
+   - OWASP Top 10 対策の自動組み込み
+   - 暗号化・ハッシュ化の自動実装
+   - セキュリティテストの自動生成
+
+2. クリーンアーキテクチャの強制
+   - レイヤー分離の自動実装
+   - 依存性逆転の自動適用
+   - テスタブルな設計の強制
+
+3. パフォーマンス最適化
+   - キャッシュ戦略の自動実装
+   - データベース最適化
+   - 非同期処理の活用
+
+このアプローチで進めますか？」
+```
+
+**2. 品質チェックポイント自動設定**
+
+```text
+Claude: 「各実装段階での品質チェックポイントを自動設定しました：
+
+自動品質保証プロセス:
+
+Phase 3a: バックエンド実装
+
+- [ ] セキュリティスキャン (SAST/DAST)
+- [ ] API 仕様テスト (OpenAPI 準拠)
+- [ ] パフォーマンステスト (負荷・レスポンス)
+- [ ] 脆弱性スキャン (依存関係・CVE)
+
+Phase 3b: フロントエンド実装
+
+- [ ] アクセシビリティテスト (WCAG 2.1 AA)
+- [ ] ブラウザ互換性テスト
+- [ ] レスポンシブデザイン検証
+- [ ] セキュリティヘッダー確認
+
+Phase 3c: 統合・デプロイ
+
+- [ ] E2E テストスイート
+- [ ] CI/CD パイプライン設定
+- [ ] モニタリング・ログ設定
+- [ ] 本番環境セキュリティ監査
+
+すべて自動実行されます。追加の品質基準はありますか？」
+```
+
+**3. 依存関係とリスク軽減の自動分析**
+
+```text
+Claude: 「実装順序とリスク軽減策を自動分析しました：
+
+最適化された実装順序:
+
+Week 1: インフラ・セキュリティ基盤
+
+- データベース設計・スキーマ作成
+- 認証基盤 (JWT + セッション管理)
+- セキュリティミドルウェア実装
+- 基本的な API エンドポイント
+
+Week 2: コア機能実装
+
+- ユーザー管理機能
+- プロフィール管理機能
+- 権限管理システム
+- バリデーション・エラーハンドリング
+
+Week 3: 高度な機能・最適化
+
+- 多要素認証実装
+- 監査ログ機能
+- パフォーマンス最適化
+- フロントエンド統合
+
+自動検出されたリスク軽減策:
+
+- 多要素認証: 段階的導入 (SMS→アプリ認証)
+- セッション管理: Redis クラスター構成
+- 大量アクセス: レート制限 + CDN 活用
+- データ整合性: トランザクション管理強化
+
+この計画で問題ありませんか？」
+```
+
+**4. Phase 3 完了と承認**
+
+```text
+Claude: 「Implementation Planning Phase が完了しました。
+tasks.md を生成してよろしいですか？」
+→ 「次に進んで」→ tasks.md 生成
+```
+
+### Kiro 特有の機能
+
+**EARS 記法 (Easy Approach to Requirements Syntax)**
+
+```markdown
+# Kiro 標準の EARS 記法パターン
+
+WHEN [状況・トリガー]
+GIVEN [前提条件]
+THEN [システムの動作]
+AND [追加の動作]
+
+WHILE [状態・プロセス]
+THE SYSTEM SHALL [必須動作]
+AND [関連動作]
+
+WHERE [機能・コンポーネント]
+IS [条件・状態]
+THE SYSTEM SHALL [対応動作]
+```
+
+**自動生成機能**
+
+- **Mermaid 図**: アーキテクチャ・データフロー図の自動生成
+- **TypeScript インターフェース**: 設計に基づく型定義自動作成
+- **ベストプラクティス**: セキュリティ・パフォーマンス対策の自動組み込み
+- **品質チェックポイント**: 段階別品質基準の自動設定
+
+**hooks 連携**
+
+- ファイル保存時の自動品質チェック
+- コード標準の自動適用
+- セキュリティスキャンの自動実行
+- OWASP Top 10 対策の自動検証
+
+**プロトタイプ→本番品質保証**
+
+- 構造化アプローチによる一貫した設計
+- セキュリティファースト開発の強制
+- スケーラブルアーキテクチャの自動適用
+- 継続的品質管理の組み込み
+
+### 注意事項
+
+**適用範囲**
+
+- Spec Mode は機能実装に最適化
+- 単純な修正や小規模な変更の場合は通常の実装形式を使用
+- 新規機能開発や複雑な機能改修に推奨
+
+**品質保証**
+
+- 各段階での完了基準を明確化
+- 実装前の設計レビュー
+- テストとアクセシビリティを含む包括的な品質基準
+
+**実行上の注意**
+
+- 要件の曖昧さを解消してから設計段階へ
+- 設計完了後に実装タスクを生成
+- 各段階での承認プロセスを重視
+
+### トリガーフレーズとコントロール
+
+#### 段階的ワークフロー制御
+
+**開始トリガー**
+
+- 「[機能名] の spec を作成して」
+- 「spec 駆動で [機能名] を開発したい」
+- 「仕様書から [機能名] を設計して」
+
+**フェーズ進行制御**
+
+- **「次に進んで」**: 現在のフェーズを完了してファイル生成、次フェーズへ
+- **「修正して」**: 現在のフェーズ内で内容を調整・改善
+- **「やり直して」**: 現在のフェーズを最初からやり直し
+- **「詳しく説明して」**: より詳細な説明や選択肢を提示
+- **「スキップして」**: 現フェーズをスキップして次へ (非推奨)
+
+**ファイル生成タイミング**
+
+```text
+Phase 1 完了 → 「次に進んで」 → requirements.md 生成
+Phase 2 完了 → 「次に進んで」 → design.md 生成
+Phase 3 完了 → 「次に進んで」 → tasks.md 生成
+```
+
+### 実行例 (段階的フロー)
+
+```bash
+# 使用例
+ユーザー: 「ユーザー管理システムの spec を作成して」
+
+# Phase 1: Requirements Discovery
+Claude: [要件の確認と議論開始]
+ユーザー: [応答・議論・修正]
+Claude: 「Requirements Phase が完了しました。次に進んでよろしいですか？」
+ユーザー: 「次に進んで」
+→ requirements.md 生成
+
+# Phase 2: Design Exploration
+Claude: [設計の提案と議論開始]
+ユーザー: [技術選択・アーキテクチャ議論]
+Claude: 「Design Phase が完了しました。次に進んでよろしいですか？」
+ユーザー: 「次に進んで」
+→ design.md 生成
+
+# Phase 3: Implementation Planning
+Claude: [実装計画の議論開始]
+ユーザー: [優先度・リスク・工数の議論]
+Claude: 「Implementation Phase が完了しました。次に進んでよろしいですか？」
+ユーザー: 「次に進んで」
+→ tasks.md 生成
+
+# 完了
+Claude: 「spec 駆動開発の準備が完了しました。実装を開始できます。」
+```
+
+### /plan との違い
+
+| 特徴     | /plan                  | /spec                                                         |
+| -------- | ---------------------- | ------------------------------------------------------------- |
+| 対象     | 一般的な実装計画       | 機能仕様駆動開発                                              |
+| 出力形式 | 単一の計画ドキュメント | 3 つの独立したファイル (requirements.md、design.md、tasks.md) |
+| 要件定義 | 基本的な要件整理       | EARS 記法による詳細な受け入れ基準                             |
+| 設計     | 技術選定中心           | コードベース分析ベース                                        |
+| 実装     | 一般的なタスク分解     | 依存関係を考慮したシーケンス                                  |
+| 品質保証 | 基本的なテスト戦略     | 包括的な品質要件 (テスト、アクセシビリティ、パフォーマンス)   |
+| 同期     | 静的な計画             | 動的な spec 更新                                              |
+
+### 推奨ユースケース
+
+**spec 使用推奨**
+
+- 新機能開発
+- 複雑な機能改修
+- API 設計
+- データベース設計
+- UI/UX 実装
+
+**plan 使用推奨**
+
+- システム全体の設計
+- インフラ構築
+- リファクタリング
+- 技術選定
+- アーキテクチャ変更