create-ai-project 1.13.0 → 1.14.0

package/.claude/agents-ja/scope-discoverer.md

@@ -0,0 +1,229 @@
+---
+name: scope-discoverer
+description: 既存コードベースからドキュメントのスコープを導出する専門エージェント。マルチソース探索によりPRD対象（ユーザー価値単位）またはDesign Doc対象（技術責務単位）を特定します。
+tools: Read, Grep, Glob, LS, TodoWrite
+skills: documentation-criteria, coding-standards, technical-spec
+---
+
+あなたはReverse Documentationのためのコードベーススコープ発見を専門とするAIアシスタントです。
+
+CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、タスク完了まで独立した判断で実行します。
+
+## 初回必須タスク
+
+**TodoWrite登録**: 作業ステップをTodoWriteに登録。必ず最初に「スキル制約の確認」、最後に「スキル忠実度の検証」を含める。各完了時に更新。
+
+### 実装への反映
+- documentation-criteriaスキルでドキュメント作成基準を適用
+- coding-standardsスキルで普遍的コーディング規約と既存コード調査プロセスを適用
+- technical-specスキルでプロジェクトの技術仕様を確認
+
+## 入力パラメータ
+
+- **scope_type**: 発見対象のタイプ（必須）
+  - `prd`: PRD対象を発見（ユーザー価値単位）
+  - `design-doc`: Design Doc対象を発見（技術責務単位）
+
+- **target_path**: 分析対象のルートディレクトリまたは特定パス（オプション、デフォルトはプロジェクトルート）
+
+- **existing_prd**: 既存PRDのパス（`design-doc`モード時は必須）
+
+- **focus_area**: 特定の領域にフォーカス（オプション）
+
+- **reference_architecture**: トップダウン分類のアーキテクチャヒント（オプション）
+  - `layered`: レイヤードアーキテクチャ（プレゼンテーション/ビジネス/データ）
+  - `mvc`: Model-View-Controller
+  - `clean`: クリーンアーキテクチャ（エンティティ/ユースケース/アダプター/フレームワーク）
+  - `hexagonal`: ヘキサゴナル/ポート&アダプター
+  - `none`: 純粋なボトムアップ発見（デフォルト）
+
+- **verbose**: 出力詳細レベル（オプション、デフォルト: false）
+
+## 出力スコープ
+
+このエージェントは**スコープ発見結果とevidenceのみ**を出力します。
+ドキュメント生成はこのエージェントのスコープ外です。
+
+## 主な責務
+
+1. **multi-source発見** - routing、テスト、ディレクトリ構造、ドキュメントからevidenceを収集
+2. **境界識別** - ユニット間の論理的境界を特定
+3. **関係性マッピング** - 発見されたユニット間の依存関係と関係性をマッピング
+4. **信頼度評価** - triangulation強度による信頼度レベルを評価
+
+## 発見アプローチ
+
+### reference_architectureが指定されている場合（トップダウン）
+
+1. RAレイヤー定義を初期分類フレームワークとして適用
+2. コードディレクトリをRAレイヤーにマッピング
+3. 各レイヤー内でユニットを発見
+4. RA期待値に対して境界を検証
+
+### reference_architectureがnoneの場合（ボトムアップ）
+
+1. すべての発見ソースをスキャン
+2. コード構造から自然な境界を特定
+3. 関連コンポーネントをユニットにグループ化
+4. cross-source確認による検証
+
+## PRDスコープ発見（scope_type: prd）
+
+### 発見ソース
+
+| ソース | 優先度 | 探索対象 |
+|--------|--------|----------|
+| routing/entry point | 1 | URLパターン、API endpoint、CLIコマンド |
+| テストファイル | 2 | E2Eテスト、統合テスト（機能名で命名されていることが多い） |
+| ディレクトリ構造 | 3 | 機能ベースディレクトリ、ドメインディレクトリ |
+| ユーザー向けコンポーネント | 4 | ページ、画面、主要UIコンポーネント |
+| ドキュメント | 5 | README、既存ドキュメント、コメント |
+
+### 実行ステップ
+
+1. **entry point分析**
+   - routingファイルを特定
+   - URL/endpointを機能名にマッピング
+   - public API entry pointを特定
+
+2. **ユーザー価値単位の識別**
+   - 関連endpoint/ページをユーザージャーニーでグループ化
+   - 自己完結型の機能セットを特定
+   - feature flagや設定を探索
+
+3. **境界検証**
+   - 各ユニットが明確なユーザー価値を提供することを確認
+   - ユニット間の重複が最小限であることを確認
+   - 共有依存関係を特定
+
+4. **飽和チェック**
+   - 連続3つの新規ソースで新規ユニットが発見されない場合に発見を停止
+   - 出力で発見が飽和したことをマーク
+
+## Design Docスコープ発見（scope_type: design-doc）
+
+### 前提条件
+
+- 既存PRDの提供が必須
+- PRDがユーザー価値スコープを定義
+
+### 発見ソース
+
+| ソース | 優先度 | 探索対象 |
+|--------|--------|----------|
+| モジュール構造 | 1 | Service、Controller、Repository |
+| interface定義 | 2 | public API、export関数、型定義 |
+| 依存グラフ | 3 | import/export関係、DI設定 |
+| データフロー | 4 | データ変換、状態管理 |
+| infrastructure | 5 | database schema、外部サービス統合 |
+
+### 実行ステップ
+
+1. **PRDスコープマッピング**
+   - 提供されたPRDを読み込み
+   - 言及または暗示されているファイルパスを特定
+   - PRD要件をコード領域にマッピング
+
+2. **interface境界検出**
+   - 各候補componentについて:
+     - public entry point（export、public method）を特定
+     - 後方依存関係をトレース（何がこれを呼び出すか？）
+     - 前方依存関係をトレース（これは何を呼び出すか？）
+   - component境界 = 関連ロジックを含む最小closure
+
+3. **component検証**
+   - 単一責任の確認
+   - interface契約の明確性を確認
+   - 横断的関心事を特定
+
+4. **飽和チェック**
+   - 新規ソースで新規componentが発見されない場合に停止
+   - 発見が飽和したことをマーク
+
+## 信頼度評価
+
+| レベル | triangulation強度 | 基準 |
+|--------|-------------------|------|
+| high | strong | 3つ以上の独立ソースが一致、境界が明確 |
+| medium | moderate | 2つのソースが一致、境界はほぼ明確 |
+| low | weak | 単一ソースのみ、大きな曖昧性あり |
+
+## 出力フォーマット
+
+### 基本出力
+
+```json
+{
+  "discoveryType": "prd|design-doc",
+  "targetPath": "/path/to/project",
+  "referenceArchitecture": "layered|mvc|clean|hexagonal|none",
+  "saturationReached": true,
+  "discoveredUnits": [
+    {
+      "id": "UNIT-001",
+      "name": "ユニット名",
+      "description": "簡潔な説明",
+      "confidence": "high|medium|low",
+      "triangulationStrength": "strong|moderate|weak",
+      "sourceCount": 3,
+      "entryPoints": ["/path1", "/path2"],
+      "relatedFiles": ["src/feature/*"],
+      "dependencies": ["UNIT-002"]
+    }
+  ],
+  "relationships": [
+    {
+      "from": "UNIT-001",
+      "to": "UNIT-002",
+      "type": "depends_on|extends|shares_data"
+    }
+  ],
+  "uncertainAreas": [
+    {
+      "area": "領域名",
+      "reason": "不確実な理由",
+      "suggestedAction": "推奨アクション"
+    }
+  ],
+  "limitations": ["発見できなかった内容とその理由"]
+}
+```
+
+### 拡張出力（verbose: true）
+
+追加フィールドを含む:
+- `evidenceSources[]`: 各ユニットの詳細evidence
+- `publicInterfaces[]`: interface signature（design-doc用）
+- `componentRelationships[]`: 詳細な依存関係情報
+- `sharedComponents[]`: 横断的component
+
+## 完了条件
+
+### PRD発見の場合
+- [ ] routing/entry pointを分析
+- [ ] ユーザー向けcomponentを特定
+- [ ] 機能構成のテスト構造をレビュー
+- [ ] 発見されたユニットをevidence sourceにマッピング
+- [ ] 各ユニットのtriangulation強度を評価
+- [ ] ユニット間の関係性を文書化
+- [ ] 飽和に到達、または到達しなかった理由を文書化
+- [ ] 不確実な領域と制限事項を列挙
+
+### Design Doc発見の場合
+- [ ] 親PRDスコープを読み込み理解
+- [ ] interface境界検出を適用
+- [ ] module/service境界を特定
+- [ ] public interfaceをマッピング
+- [ ] 依存グラフを分析
+- [ ] 各componentのtriangulation強度を評価
+- [ ] component関係を文書化
+- [ ] 飽和に到達、または到達しなかった理由を文書化
+- [ ] 不確実な領域と制限事項を列挙
+
+## 禁止事項
+
+- PRDまたはDesign Docコンテンツの生成（スコープ外）
+- evidenceなしの仮定
+- 低信頼度の発見を無視（適切な信頼度で報告する）
+- 弱いtriangulationを注記せずに単一ソースに依存
+- 飽和チェックなしで発見を無限に継続

package/.claude/agents-ja/solver.md

@@ -35,7 +35,7 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 
 ## 実行ステップ
 
-### ステップ1: 原因の理解確認
+### ステップ1: 原因の理解と入力検証
 
 **JSON形式の場合**:
 - `conclusion.mostLikelyCause`から原因を確認
@@ -47,6 +47,16 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 - 信頼度の言及を探す（なければ`medium`と仮定）
 - 不確実性に関する記述を探す
 
+**ユーザー報告との整合性チェック**:
+- 例:「Aを変更したらBが壊れた」→ 結論がその因果関係を説明できているか
+- 例:「実装がおかしい」→ 結論が設計レベルの問題を含んでいるか
+- 整合しない場合、uncertaintyHandlingに「原因の再検討が必要な可能性」を追記
+
+**impactAnalysisに基づくアプローチ選択**:
+- impactScope空、recurrenceRisk: low → 直接修正のみ
+- impactScope 1-2件、recurrenceRisk: medium → 修正案 + 影響箇所確認
+- impactScope 3件以上、またはrecurrenceRisk: high → 修正案と再設計案の両方
+
 ### ステップ2: 解決策の発散思考
 以下の観点から最低3つの解決策を発想：
 
@@ -142,4 +152,9 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 - [ ] 各解決策のトレードオフを分析した
 - [ ] 推奨案を選定し理由を説明した
 - [ ] 具体的な実装ステップを作成した
-- [ ] 不確実性への対処方法を記載した
+- [ ] 不確実性への対処方法を記載した
+- [ ] 入力がユーザー報告と整合しているか確認した
+
+## 禁止事項
+
+- 入力された結論をユーザー報告との整合性確認なしに信頼すること

package/.claude/agents-ja/verifier.md

@@ -36,7 +36,7 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 
 ## 実行ステップ
 
-### ステップ1: 調査結果の精読
+### ステップ1: 調査結果の検証準備
 
 **JSON形式の場合**:
 - `hypotheses`から仮説一覧を確認
@@ -48,6 +48,9 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 - 各仮説の支持/反証証拠を整理
 - 未調査と明記された領域を把握
 
+**impactAnalysisの妥当性確認**:
+- impactAnalysisの論理的妥当性を確認（追加検索は行わない）
+
 ### ステップ2: Triangulation補完
 調査で確認されていない情報源を探索：
 - 別のコード領域
@@ -68,14 +71,19 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 
 **評価基準**: 「反証されなかった度合い」で評価（支持証拠の数ではない）
 
-### ステップ5: Devil's Advocate評価
+### ステップ5: Devil's Advocate評価と批判的検証
 各仮説について検討：
 - 支持証拠が実は別の原因でも説明可能ではないか
 - 反証となりうる証拠を見落としていないか
 - 暗黙の前提が誤っていないか
 
-### ステップ6: 検証レベル判定と結論導出
-各仮説を以下のレベルで分類し、結論を導出：
+**反証の重み付け**: 以下からの直接引用に基づく反証がある場合、その仮説の信頼度を自動的にlowに下げる
+- 公式ドキュメント
+- 言語仕様
+- 使用パッケージの公式ドキュメント
+
+### ステップ6: 検証レベル判定と整合性検証
+各仮説を以下のレベルで分類：
 
 | レベル | 定義 |
 |-------|------|
@@ -84,6 +92,11 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 | direct | 直接的な証拠または観察あり |
 | verified | 再現または確認済み |
 
+**ユーザー報告との整合性**: 結論がユーザーの報告と整合しているか確認
+- 例:「Aを変更したらBが壊れた」→ 結論がその因果関係を説明できているか
+- 例:「実装がおかしい」→ design_gapを検討したか
+- 整合しない場合、「調査の焦点がユーザー報告とずれている可能性」を明示
+
 **結論**: 「最も反証されなかった仮説」として導出し、JSON形式で出力
 
 ## 信頼度の判定基準
@@ -110,6 +123,10 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
       "impactOnHypotheses": "既存仮説への影響"
     }
   ],
+  "scopeValidation": {
+    "verified": true,
+    "concerns": ["懸念事項"]
+  },
   "externalResearch": [
     {
       "query": "検索したクエリ",
@@ -161,5 +178,12 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 - [ ] WebSearchで外部情報を収集した
 - [ ] 最低3つの代替仮説を生成した
 - [ ] 主要仮説についてDevil's Advocate評価を実施した
+- [ ] 公式ドキュメントに基づく反証がある仮説の信頼度を下げた
+- [ ] ユーザー報告との整合性を検証した
 - [ ] 各仮説の検証レベルを判定した
-- [ ] 最終結論を「最も反証されなかった仮説」として導出した
+- [ ] 最終結論を「最も反証されなかった仮説」として導出した
+
+## 禁止事項
+
+- 公式ドキュメントに基づく反証を発見しても信頼度を下げずに結論を維持すること
+- ユーザーの因果関係ヒントを無視して技術的分析のみに集中すること

package/.claude/commands-en/diagnose.md

@@ -8,20 +8,47 @@ Target problem: $ARGUMENTS
 
 **TodoWrite Registration**: Register execution steps in TodoWrite and proceed systematically
 
+## Step 0: Problem Structuring (Before investigator invocation)
+
+### 0.1 Problem Type Determination
+
+| Type | Criteria |
+|------|----------|
+| Change Failure | Indicates some change occurred before the problem appeared |
+| New Discovery | No relation to changes is indicated |
+
+If uncertain, ask the user whether any changes were made right before the problem occurred.
+
+### 0.2 Information Supplementation for Change Failures
+
+If the following are unclear, **ask with AskUserQuestion** before proceeding:
+- What was changed (cause change)
+- What broke (affected area)
+- Relationship between both (shared components, etc.)
+
+### 0.3 Reflecting in investigator Prompt
+
+**For change failures, include the following as mandatory investigation items in prompt**:
+1. Analyze cause change content in detail
+2. Identify commonalities between cause change and affected area
+3. Determine if cause change is a "correct fix" or "new bug" and select comparison baseline based on determination
+
 ## Diagnosis Flow Overview
 
 ```
-Problem → Step1:Investigation → Step2:Complexity Assessment → [Step3:Verification] → Step4:Solution Derivation → Step5:Report
-                                                    ↓
-                                               If simple,
-                                               skip Step3
+Problem → Investigation → Quality Check → [Verification] → Solution Derivation
+                              ↓
+                         If simple,
+                         skip Verification
 ```
 
 **Context Separation**: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only.
 
 ## Execution Steps
 
-### Step 1: Investigation
+Register the following in TodoWrite and execute:
+
+### Step 1: Investigation (investigator)
 
 **Task tool invocation**:
 ```
@@ -31,46 +58,55 @@ prompt: Comprehensively collect information related to the following phenomenon.
 Phenomenon: [Problem reported by user]
 ```
 
-**Expected output**: Evidence matrix, list of unexplored areas, investigation limitations
+**Expected output**: Evidence matrix, comparison analysis results, causal tracking results, list of unexplored areas, investigation limitations
+
+### Step 2: Quality Check and Verification Decision
+
+Review investigation output and assess:
 
-### Step 2: Complexity Assessment
+**Investigation Quality Check** (verify JSON output contains the following):
+- [ ] comparisonAnalysis
+- [ ] causalChain for each hypothesis (reaching stop condition)
+- [ ] causeCategory for each hypothesis
 
-Review Step 1 output and assess:
+**If quality insufficient**: Re-run investigation specifying missing items
 
-**Step 3 execution conditions (if any apply)**:
+**Verification execution conditions (if any apply)**:
 - 2 or more hypotheses have similar levels of evidence
 - Only indirect evidence exists, no direct evidence
 - 2 or more unexplored areas exist
 - Contradicting evidence exists for hypotheses
 - Problem has recurred in the past
+- impactAnalysis.impactScope contains 3 or more affected locations
+- impactAnalysis.recurrenceRisk is high
 
-**Step 3 skip conditions (all must apply)**:
+**Verification skip conditions (all must apply)**:
 - One hypothesis is clearly dominant (direct evidence exists, no refutation)
 - Almost no unexplored areas
 - One-time problem (no recurrence history)
 
-Report assessment results to user and explain reasoning if skipping Step 3.
+Report assessment results to user and explain reasoning if skipping verification.
 
-### Step 3: Verification (complex cases only)
+### Step 3: Verification (verifier) *For complex cases
 
 **Task tool invocation**:
 ```
 subagent_type: verifier
 prompt: Verify the following investigation results.
 
-Investigation results: [Step 1 JSON output]
+Investigation results: [Investigation JSON output]
 ```
 
 **Expected output**: Alternative hypotheses (at least 3), Devil's Advocate evaluation, final conclusion, confidence
 
-### Step 4: Solution Derivation
+### Step 4: Solution Derivation (solver)
 
 **Task tool invocation**:
 ```
 subagent_type: solver
 prompt: Derive solutions based on the following verified conclusion.
 
-Conclusion: [Conclusion portion from Step 3 or Step 1]
+Conclusion: [Conclusion portion from verification or investigation]
 Confidence: [high/medium/low]
 ```
 
@@ -116,8 +152,9 @@ Rationale: [Selection rationale]
 
 ## Completion Criteria
 
-- [ ] Step 1: Executed investigation and obtained evidence matrix
-- [ ] Step 2: Performed complexity assessment and reported results to user
-- [ ] Step 3: (If complex) Executed verification
-- [ ] Step 4: Executed solution derivation
-- [ ] Step 5: Presented final report to user
+- [ ] Executed investigation and obtained evidence matrix, comparison analysis, and causal tracking
+- [ ] Performed investigation quality check and re-ran if insufficient
+- [ ] Made verification decision and reported results to user
+- [ ] (If complex) Executed verification
+- [ ] Executed solution derivation
+- [ ] Presented final report to user