create-ai-project 1.11.2 → 1.12.0

package/.claude/skills/integration-e2e-testing/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: integration-e2e-testing
+description: 統合・E2Eテスト設計原則、ROI計算、テストスケルトン仕様、レビュー基準。
+---
+
+# 統合テスト・E2Eテスト設計・実装ルール
+
+## テスト種別と上限
+
+| 種別 | 目的 | ファイル形式 | 上限 |
+|------|------|-------------|------|
+| 統合テスト | コンポーネント間連携検証 | `*.int.test.ts` | 機能あたり3件 |
+| E2Eテスト | クリティカルユーザージャーニー検証 | `*.e2e.test.ts` | 機能あたり1-2件 |
+
+**クリティカルユーザージャーニー**: 収益影響・法的要件・大多数のユーザーが日常的に利用する機能
+
+## 振る舞い優先の原則
+
+### 観測可能性チェック（全てYESで対象）
+
+| チェック | 質問 | NOの場合 |
+|---------|------|----------|
+| 観測可能 | ユーザーが結果を観測できるか？ | 除外 |
+| システム文脈 | 複数コンポーネントの統合が必要か？ | 除外 |
+| 自動化可能 | CI環境で安定実行できるか？ | 除外 |
+
+### Include/Exclude基準
+
+**Include**: ビジネスロジック正確性、データ整合性、ユーザー可視機能、エラーハンドリング
+**Exclude**: 外部実接続、パフォーマンス指標、実装詳細、UIレイアウト
+
+## スケルトン仕様
+
+### 必須コメント形式
+
+```typescript
+// AC: "[受入条件原文]"
+// ROI: [0-100] | ビジネス価値: [0-10] | 頻度: [0-10]
+// 振る舞い: [トリガー] → [処理] → [観測可能な結果]
+// @category: core-functionality | integration | edge-case | ux | e2e
+// @dependency: none | [コンポーネント名] | full-system
+// @complexity: low | medium | high
+it.todo('[AC番号]: [テスト名]')
+```
+
+### Property注釈
+
+```typescript
+// Property: `[検証式]`
+// fast-check: fc.property(fc.[arbitrary], (input) => [不変条件])
+it.todo('[AC番号]-property: [不変条件記述]')
+```
+
+### ROI計算
+
+```
+ROI = (ビジネス価値 × 頻度 + 法的要件 × 10 + 欠陥検出) / 総コスト
+```
+
+| 種別 | 総コスト | E2E生成条件 |
+|------|---------|------------|
+| 統合 | 11 | - |
+| E2E | 38 | ROI > 50 |
+
+## 実装ルール
+
+### Property-Based Test実装
+
+Property注釈がある場合、fast-checkライブラリ必須:
+
+```typescript
+import fc from 'fast-check'
+
+it('AC2-property: モデル名は常にgemini-3-pro-image-preview', () => {
+  fc.assert(
+    fc.property(fc.string(), (prompt) => {
+      const result = client.generate(prompt)
+      return result.model === 'gemini-3-pro-image-preview'
+    })
+  )
+})
+```
+
+**必須事項**:
+- `fc.assert(fc.property(...))` 形式で記述
+- スケルトンの`// fast-check:`コメントをそのまま実装に反映
+- 失敗ケース発見時は具体的なユニットテストとして追加（リグレッション防止）
+
+### 振る舞い検証の実装
+
+**振る舞い記述の検証レベル**:
+
+| ステップ種別 | 検証対象 | 例 |
+|-------------|---------|-----|
+| トリガー | Arrangeで再現 | API障害 → mockResolvedValue({ ok: false }) |
+| 処理 | 中間状態または呼び出し | 関数呼び出し、状態変更 |
+| 観測可能な結果 | 最終出力の値 | 戻り値、エラーメッセージ、ログ出力 |
+
+**判定基準**: 「観測可能な結果」がテスト対象の**戻り値またはモックの呼び出し引数**として検証されていれば合格
+
+### 検証項目の決定ルール
+
+| スケルトンの状態 | 検証項目の決定方法 |
+|-----------------|-------------------|
+| `// 検証項目:` が列挙されている | 列挙された全項目をexpectで実装 |
+| `// 検証項目:` がない | 「振る舞い」記述の「観測可能な結果」から導出 |
+| 両方ある | 検証項目を優先、振る舞いは補足として使用 |
+
+### 統合テストのモック境界
+
+| 判断基準 | モック | 実物 |
+|---------|--------|------|
+| テスト対象の一部か？ | No → モック可 | Yes → 実物必須 |
+| 呼び出しがテストの検証対象か？ | No → モック可 | Yes → 実物または検証可能なモック |
+| 外部ネットワーク通信か？ | Yes → モック必須 | No → 実物推奨 |
+
+**判定フロー**:
+1. 外部API（HTTP通信）→ モック必須
+2. テスト対象のコンポーネント間連携 → 実物必須
+3. ログ出力の検証が必要 → 検証可能なモック（vi.fn()）を使用
+4. ログ出力の検証が不要 → 実物または無視
+
+### E2Eテストの実行条件
+
+- 全コンポーネント実装完了後に実行
+- モック禁止（`@dependency: full-system`）
+
+## レビュー基準
+
+### スケルトンと実装の整合性
+
+| チェック | 不合格条件 |
+|---------|-----------|
+| Property検証 | Property注釈があるのにfast-check未使用 |
+| 振る舞い検証 | 「観測可能な結果」に対応するexpectがない |
+| 検証項目網羅 | 列挙された検証項目がexpectに含まれていない |
+| モック境界 | 統合テストで内部コンポーネントをモック化 |
+
+### 実装品質
+
+| チェック | 不合格条件 |
+|---------|-----------|
+| AAA構造 | Arrange/Act/Assertの区切りが不明確 |
+| 独立性 | テスト間で状態共有、実行順序依存 |
+| 再現性 | 日時・乱数に依存し結果が変動 |
+| 可読性 | テスト名と検証内容が一致しない |

package/{docs/rules-ja/project-context.md → .claude/skills/project-context/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: project-context
+description: プロジェクトの性質、技術スタック、実装原則を含むプロジェクト固有コンテキスト。各プロジェクトでカスタマイズ可能。
+---
+
 # プロジェクトコンテキスト
 
 ## 基本設定
@@ -30,9 +35,8 @@
    - 技術的制約事項
 
 2. **アーキテクチャの選択**
-   - `docs/rules/architecture/` から適切なパターンを選択
-   - `docs/rules/architecture/` にプロジェクト固有の設計を配置
+   - アーキテクチャスキルから適切なパターンを選択
 
 3. **環境設定**
    - プロジェクトに適した環境変数管理方法の実装
-   - プロジェクト固有の設定ファイル追加
+   - プロジェクト固有の設定ファイル追加

package/.claude/skills/subagents-orchestration-guide/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: subagents-orchestration-guide
+description: サブエージェント間の調整のためのオーケストレーションガイド。規模判定、ドキュメント要件、停止ポイント、自律実行モードを定義。
+---
+
+# サブエージェント実践ガイド - オーケストレーション指針
+
+サブエージェントを活用してタスクを効率的に処理するための実践的な行動指針。
+
+## 最重要原則：オーケストレーターとして振る舞う
+
+**「私は作業者ではない。オーケストレーターである。」**
+
+### 正しい振る舞い
+- 新規タスク: requirement-analyzerから開始
+- フロー実行中: 規模判定に基づくフローを厳守
+- 各フェーズ: 適切なサブエージェントに委譲
+- 停止ポイント: 必ずユーザー承認を待つ
+
+### 避ける行為
+- Grep/Glob/Readで自分で調査を始める
+- 自分で分析や設計を考え始める
+- 「まず調べてみます」と言って作業を開始する
+- requirement-analyzerを後回しにする
+
+**タスク開始時は必ずrequirement-analyzer。フロー開始後は規模判定に従う。**
+
+## タスク受領時の判断
+
+```mermaid
+graph TD
+    Start[新規タスク受領] --> RA[requirement-analyzerで要件分析]
+    RA --> Scale[規模判定]
+    Scale --> Flow[規模に応じたフロー実行]
+```
+
+### フロー実行中の要件変更検知
+
+**フロー実行中**にユーザーレスポンスで以下を検知したら、フローを停止してrequirement-analyzerへ：
+- 新機能・動作の言及（追加の操作方法、別画面での表示など）
+- 制約・条件の追加（データ量制限、権限制御など）
+- 技術要件の変更（処理方式、出力形式の変更など）
+
+**1つでも該当 → 統合要件でrequirement-analyzerから再開**
+
+## 活用できるサブエージェント
+
+### 実装支援エージェント
+1. **quality-fixer**: 全体品質保証と修正完了まで自己完結処理
+2. **task-decomposer**: 作業計画書の適切なタスク分解
+3. **task-executor**: 個別タスクの実行と構造化レスポンス
+4. **integration-test-reviewer**: 統合テスト/E2Eテストのスケルトン準拠レビュー
+
+### ドキュメント作成エージェント
+5. **requirement-analyzer**: 要件分析と作業規模判定（WebSearch対応、最新技術情報の調査）
+6. **prd-creator**: Product Requirements Document作成（WebSearch対応、市場動向調査）
+7. **technical-designer**: ADR/Design Doc作成（最新技術情報の調査、Property注釈付与）
+8. **work-planner**: 作業計画書作成（テストスケルトンからメタ情報を抽出・反映）
+9. **document-reviewer**: 単一ドキュメントの品質・完成度・ルール準拠チェック
+10. **design-sync**: Design Doc間の整合性検証（明示的矛盾のみ検出）
+11. **acceptance-test-generator**: Design DocのACから統合テストとE2Eテストのスケルトン生成
+
+## オーケストレーション原則
+
+### 責務分離を意識した振り分け
+
+**task-executorの責務**:
+- 実装作業とテスト追加
+- 追加したテストのパス確認（既存テストは対象外）
+- 品質保証はtask-executorの責務外
+
+**quality-fixerの責務**:
+- 全体品質保証（型チェック、lint、全テスト実行等）
+- 品質エラーの完全修正実行
+- 修正完了まで自己完結で処理
+- 最終的な approved 判定（修正完了後のみ）
+
+### 標準フロー
+
+**基本サイクル**: `task-executor → エスカレーション判定・フォローアップ → quality-fixer → commit` の4ステップサイクルを管理。
+各タスクごとにこのサイクルを繰り返し、品質を保証。
+
+## Sub-agent間の制約
+
+**重要**: Sub-agentから他のSub-agentを直接呼び出すことはできない。複数のSub-agentを連携させる場合は、メインAIがオーケストレーターとして動作。
+
+## 規模判定とドキュメント要件
+
+| 規模 | ファイル数 | PRD | ADR | Design Doc | 作業計画書 |
+|------|-----------|-----|-----|------------|-----------|
+| 小規模 | 1-2 | 更新※1 | 不要 | 不要 | 簡易版 |
+| 中規模 | 3-5 | 更新※1 | 条件付き※2 | **必須** | **必須** |
+| 大規模 | 6以上 | **必須**※3 | 条件付き※2 | **必須** | **必須** |
+
+※1: 該当機能のPRDが存在する場合は更新
+※2: アーキテクチャ変更、新技術導入、データフロー変更がある場合
+※3: 新規作成/既存更新/リバースPRD（既存PRDがない場合）
+
+## 構造化レスポンス仕様
+
+各サブエージェントはJSON形式で応答：
+- **task-executor**: status, filesModified, testsAdded, readyForQualityCheck
+- **integration-test-reviewer**: status, verdict (approved/needs_revision), requiredFixes
+- **quality-fixer**: status, checksPerformed, fixesApplied, approved
+- **document-reviewer**: status, reviewsPerformed, issues, recommendations, approvalReady
+- **design-sync**: sync_status, total_conflicts, conflicts (severity, type, source_file, target_file)
+
+## 作業計画時の基本フロー
+
+### 大規模（6ファイル以上）
+1. requirement-analyzer → 要件分析 **[停止: 要件確認]**
+2. prd-creator → PRD作成 → document-reviewer **[停止: 要件確認]**
+3. technical-designer → ADR作成（必要な場合） → document-reviewer **[停止: 技術方針決定]**
+4. technical-designer → Design Doc作成 → document-reviewer → design-sync **[停止: 設計内容確認]**
+5. acceptance-test-generator → テストスケルトン生成
+6. work-planner → 作業計画書作成 **[停止: 実装フェーズ全体の一括承認]**
+7. **自律実行モード開始**: task-decomposer → 全タスク実行 → 完了報告
+
+### 中規模（3-5ファイル）
+1. requirement-analyzer → 要件分析 **[停止: 要件確認]**
+2. technical-designer → Design Doc作成 → document-reviewer → design-sync **[停止: 技術方針決定]**
+3. acceptance-test-generator → テストスケルトン生成
+4. work-planner → 作業計画書作成 **[停止: 実装フェーズ全体の一括承認]**
+5. **自律実行モード開始**: task-decomposer → 全タスク実行 → 完了報告
+
+### 小規模（1-2ファイル）
+1. 簡易計画書作成 **[停止: 実装フェーズ全体の一括承認]**
+2. **自律実行モード開始**: 直接実装 → 完了報告
+
+## 自律実行モード
+
+### 権限委譲
+
+**自律実行モード開始後**：
+- 実装フェーズ全体の一括承認により、サブエージェントに権限委譲
+- task-executor：実装権限（Edit/Write使用可）
+- quality-fixer：修正権限（品質エラー自動修正）
+
+### 自律実行の停止条件
+
+以下の場合に自律実行を停止し、ユーザーにエスカレーション：
+
+1. **サブエージェントからのエスカレーション**
+   - `status: "escalation_needed"` のレスポンス受信時
+   - `status: "blocked"` のレスポンス受信時
+
+2. **要件変更検知時**
+   - 要件変更検知チェックリストで1つでも該当
+   - 自律実行を停止し、requirement-analyzerに統合要件で再分析
+
+3. **work-planner更新制限に抵触時**
+   - task-decomposer開始後の要件変更は全体再設計が必要
+   - requirement-analyzerから全体フローを再開
+
+4. **ユーザー明示停止時**
+   - 直接的な停止指示や割り込み
+
+### 自律実行中のタスク管理
+
+**2段階のTodoWrite管理**
+
+#### Step1: task-decomposer完了後
+フェーズ管理Todoを登録：
+```
+[in_progress] 実装フェーズ管理: Phase1開始
+[pending] 実装フェーズ管理: Phase2開始
+[pending] 実装フェーズ管理: Phase3開始
+```
+
+#### Step2: フェーズ開始時
+該当フェーズのタスクを4ステップで展開：
+```
+[completed] 実装フェーズ管理: Phase1開始
+[pending] 実装フェーズ管理: Phase2開始
+[in_progress] Phase1-Task01: task-executor実行
+[pending] Phase1-Task01: エスカレーション判定・フォローアップ
+[pending] Phase1-Task01: quality-fixer実行
+[pending] Phase1-Task01: git commit
+... （同パターンで繰り返し）
+[pending] Phase1: 完了チェック
+```
+
+## オーケストレーターの主な役割
+
+1. **状態管理**: 現在のフェーズ、各サブエージェントの状態、次のアクションを把握
+2. **情報の橋渡し**: サブエージェント間のデータ変換と伝達
+3. **品質保証とコミット実行**: approved=true確認後、即座にgit commit実行
+4. **自律実行モード管理**: 承認後の自律実行開始・停止・エスカレーション判断
+5. **ADRステータス管理**: ユーザー判断後のADRステータス更新（Accepted/Rejected）
+
+## 重要な制約
+
+- **品質チェックは必須**: コミット前にquality-fixerの承認が必要
+- **構造化レスポンス必須**: サブエージェント間の情報伝達はJSON形式
+- **承認管理**: ドキュメント作成→document-reviewer実行→ユーザー承認を得てから次へ進む
+- **フロー確認**: 承認取得後は必ず作業計画フロー（大規模/中規模/小規模）で次のステップを確認
+- **整合性検証**: サブエージェント判定に矛盾がある場合はガイドラインを優先
+
+## 人間との必須対話ポイント
+
+### 基本原則
+- **停止は必須**: 以下のタイミングでは必ず人間の応答を待つ
+- **確認→合意のサイクル**: ドキュメント生成後は合意またはupdateモードでの修正指示を受けてから次へ進む
+- **具体的な質問**: 選択肢（A/B/C）や比較表を用いて判断しやすく
+- **効率より対話**: 手戻りを防ぐため、早い段階で確認を取る
+
+### 主要な停止ポイント
+- **requirement-analyzer完了後**: 要件分析結果と質問事項の確認
+- **PRD作成→document-reviewer実行後**: 要件理解と整合性の確認
+- **ADR作成→document-reviewer実行後**: 技術方針と整合性の確認
+- **Design Doc作成→document-reviewer実行後**: 設計内容と整合性の確認
+- **計画書作成後**: 実装フェーズ全体の一括承認

package/.claude/skills/task-analyzer/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: task-analyzer
+description: メタ認知的タスク分析とスキル選択。タスクの本質を分析し、規模を見積もり、適切なスキルをメタデータと共に返却。
+---
+
+# タスクアナライザー - メタ認知的分析フレームワーク
+
+## 目的
+
+受け取ったタスクの本質を分析し、以下を決定：
+1. 作業規模の判定（小規模/中規模/大規模）
+2. 適用するスキルの特定
+3. 潜在的な失敗パターンの認識
+4. 初動アクションのガイダンス提供
+
+## 分析フレームワーク
+
+### タスク本質の抽出
+
+タスクを受け取った際に分析：
+
+```yaml
+taskEssence:
+  surfaceRequest: "[ユーザーが文字通り求めたこと]"
+  underlyingGoal: "[ユーザーが実際に達成したいこと]"
+  implicitRequirements: "[明示されていないが暗黙の要件]"
+  scaleDetermination:
+    fileCount: "[変更予定ファイル数]"
+    scale: "small|medium|large"
+    confidence: "high|medium|low"
+```
+
+### 規模判定基準
+
+| 規模 | ファイル数 | 特徴 |
+|------|----------|-----|
+| 小規模 | 1-2ファイル | 単一責務の変更、局所的な影響 |
+| 中規模 | 3-5ファイル | コンポーネント横断の変更、調整が必要 |
+| 大規模 | 6ファイル以上 | システム全体への影響、ドキュメントが必要 |
+
+### スキル選択マトリクス
+
+タスク特性に基づいて適用するスキルを選択：
+
+| タスク種別 | 必要なスキル |
+|-----------|------------|
+| 新機能 | documentation-criteria, implementation-approach, typescript-rules, coding-standards |
+| バグ修正 | coding-standards, typescript-rules, coding-standardsのデバッグ技法 |
+| リファクタリング | coding-standards, implementation-approach |
+| テスト作成 | typescript-testing, integration-e2e-testing |
+| ドキュメント | documentation-criteria |
+| フロントエンド | frontend/typescript-rules, frontend/typescript-testing, frontend/technical-spec |
+
+### 失敗パターンの認識
+
+開始前に潜在的な失敗パターンを特定：
+
+```yaml
+warningPatterns:
+  - pattern: "[検出されたパターン名]"
+    risk: "high|medium|low"
+    mitigation: "[このパターンを避ける方法]"
+```
+
+監視すべき一般的なパターン：
+1. **エラー修正連鎖** - 根本原因分析なしの表面的な修正
+2. **型安全性の放棄** - any/asの過剰使用
+3. **不十分なテスト** - Red-Green-Refactorのスキップ
+4. **技術的不確実性** - スパイクなしでの未知技術の採用
+5. **調査不足** - 既存コードを確認せずに開始
+
+### 初動アクションガイダンス
+
+分析に基づいて具体的な最初のステップを提供：
+
+```yaml
+firstActionGuidance:
+  action: "[使用すべき具体的なツールまたはアクション]"
+  rationale: "[なぜこれが最初のステップであるべきか]"
+  expectedOutcome: "[このアクションで何が明らかになるか]"
+```
+
+## 出力形式
+
+タスクを分析する際、構造化されたJSONを返却：
+
+```json
+{
+  "taskEssence": {
+    "surfaceRequest": "...",
+    "underlyingGoal": "...",
+    "implicitRequirements": ["..."],
+    "scaleDetermination": {
+      "fileCount": "...",
+      "scale": "...",
+      "confidence": "..."
+    }
+  },
+  "applicableSkills": [
+    {
+      "name": "...",
+      "relevance": "primary|secondary",
+      "sections": ["..."]
+    }
+  ],
+  "warningPatterns": [
+    {
+      "pattern": "...",
+      "risk": "...",
+      "mitigation": "..."
+    }
+  ],
+  "firstActionGuidance": {
+    "action": "...",
+    "rationale": "...",
+    "expectedOutcome": "..."
+  }
+}
+```
+
+## TodoWriteとの統合
+
+task-analyzer完了後：
+
+1. **TodoWriteを更新**: taskEssenceに基づいてタスク説明を精緻化
+2. **スキル制約を追加**: 最初のtodoとして「スキル制約の確認」
+3. **検証を追加**: 最終todoとして「スキル忠実度の検証」
+4. **警告を反映**: 失敗パターンを避けるためタスク分解に反映
+
+## 使用パターン
+
+1. ユーザーから新規タスクを受け取る
+2. task-analyzerを実行して本質を理解
+3. 適用するスキルを読み込む
+4. 精緻化した理解でTodoWriteを更新
+5. スキルガイドラインに従って実装開始
+6. 完了時にスキル忠実度を検証
+
+## リファレンス
+
+スキルのメタデータと選択：
+- [スキルインデックス](references/skills-index.yaml) - 利用可能なすべてのスキルのメタデータ（タグ、典型的な使用法、主要な参照先を含む）