investigation-workflow

調査ワークフロースキル

目的

このスキルでは、既存のシステム、コードベース、アーキテクチャを調査し、理解するための体系的な6フェーズのワークフローを提供します。実装に最適化された開発ワークフローとは異なり、このワークフローは探索、理解、知識の記録に最適化されています。

このスキルを使用する場面

調査タスク（このワークフローを使用します）：

• 「認証システムの仕組みを調査する」
• 「neo4j のメモリ統合について説明する」
• 「CI が一貫して失敗する理由を理解する」
• 「リフレクションシステムのアーキテクチャを分析する」
• 「セッション開始時にどのフックがトリガーされるか調べる」

開発タスク（代わりに DEFAULT_WORKFLOW.md を使用します）：

• 「OAuth サポートを実装する」
• 「新しい API エンドポイントを構築する」
• 「機能 X を追加する」
• 「バグ Y を修正する」

基本理念

まず探索する：コードを調べる前に、範囲と方針を定義します
並行して深く調査する：複数のエージェントを同時に稼働させ、効率的に情報を収集します
検証を必須とする：実践的な適用を通じて理解を検証します
知識を記録する：調査の繰り返しを防ぐため、調査結果を文書化します

6フェーズの調査ワークフロー

フェーズ1：範囲の定義

目的：調査を始める前に、調査範囲と成功基準を定義します。

タスク：

• 最初に：ユーザーの明示的な要件を特定します。どの具体的な質問に答える必要がありますか？
• prompt-writer エージェントを使用して、調査範囲を明確にします
• 質問が曖昧な場合は、ambiguity エージェントを使用します
• 「理解できた」とみなす条件を定義します
• 回答が必要な具体的な質問を列挙します
• 範囲を設定します：対象に含めるものと対象外のものを定めます
• 必要な調査の深さ（表面的な調査か、詳細な調査か）を見積もります

成功基準：

• 回答すべき質問の明確な一覧
• 定義された調査範囲
• 測定可能な成功基準（例：「システムの流れを説明できる」「アーキテクチャを図示できる」）

成果物：

• 以下を含む調査範囲ドキュメント：
  • 回答すべき主要な質問
  • 成功基準
  • 調査範囲（対象に含めるもの／対象外のもの）
  • 推定される調査の深さと期間

フェーズ2：探索方針の策定

目的：どのエージェントを稼働させ、何を調査するかを計画し、非効率な手当たり次第の探索を防ぎます。

タスク：

• architect エージェントを使用して、探索方針を設計します
• patterns エージェントを使用して、過去に類似の調査が行われていないか確認します
• 調査する主要な領域（コードパス、設定、ドキュメント）を特定します
• フェーズ3で並行して稼働させる専門エージェントを選定します
• 優先順位を付けた調査ロードマップを作成します
• 避けるべき行き止まりを特定します
• 検証方法（理解度をどのようにテストするか）を計画します

エージェント選定のガイドライン：

• コードの理解には：analyzer、patterns エージェント
• システムアーキテクチャには：architect、api-designer エージェント
• パフォーマンスの問題には：optimizer、analyzer エージェント
• セキュリティ上の懸念には：security、patterns エージェント
• 統合フローには：integration、database エージェント

成功基準：

• 明確な探索ロードマップ
• フェーズ3で稼働させるエージェントの一覧
• 優先順位付けされた調査領域

成果物：

• 以下を含む探索方針ドキュメント：
  • 調査ロードマップ
  • フェーズ3のエージェント稼働計画
  • 探索の優先順位
  • 各調査で期待される成果

フェーズ 3：並行して詳細調査

目的：複数の調査エージェントを同時に稼働させ、効率的に情報を収集します。

重要：このフェーズでは、デフォルトで並列実行を使用します。

タスク：

• フェーズ 2 の戦略に基づいて、選定したエージェントを並列で稼働させる
• よくある並列実行パターン：
  • [analyzer(module1), analyzer(module2), analyzer(module3)] - 複数のコード領域
  • [analyzer, patterns, security] - 同じ領域を複数の観点から調査
  • [architect, database, integration] - システムアーキテクチャの調査
• 各エージェントが割り当てられた領域を個別に調査します
• すべての並行調査から得られた知見を収集します
• 知見間のつながりと依存関係を特定します
• 予期しない発見や異常があれば記録します

並列エージェントの例：

Investigation: "How does the reflection system work?"
→ [analyzer(~/.amplihack/.claude/tools/amplihack/hooks/), patterns(reflection), integration(logging)]

Investigation: "Why is CI failing?"
→ [analyzer(ci-config), patterns(ci-failures), integration(github-actions)]

Investigation: "Understand authentication flow"
→ [analyzer(auth-module), security(auth), patterns(auth), integration(external-auth)]

成功基準：

• 計画したすべてのエージェントが稼働し、完了している
• 各調査で得られた知見が収集されている
• 知見間のつながりが特定されている

成果物：

• 以下を含む調査結果レポート：
  • 各並行調査の概要
  • コードパスとフロー図
  • アーキテクチャに関する知見
  • 予期しない発見
  • 検証が必要な未解決の質問

フェーズ 4：検証とテスト

目的：実践的な適用を通じて、理解をテストし検証します。

タスク：

• フェーズ 3 の調査結果に基づいて仮説を立てます
• 理解を検証するための実践的なテストを設計します：
  • 特定のコードパスを手作業で追跡する
  • ログと出力を調べる
  • エッジケースと前提をテストする
  • 設定による影響を検証する
• 検証テストを実行します
• テスト内容と結果を記録します
• 理解が不十分な部分を特定します
• テスト結果に基づいて仮説を修正します
• 不明確な領域があれば、検証を繰り返します

検証の例：

Understanding: "Authentication uses JWT tokens"
Verification: Trace actual token creation and validation in code

Understanding: "CI fails because of dependency conflict"
Verification: Check CI logs, reproduce locally, verify fix works

Understanding: "Reflection analyzes all user messages"
Verification: Examine reflection logs, trace message processing

成功基準：

• すべての仮説がテストされている
• 実践的なテストを通じて理解が検証されている
• 理解が不十分な部分が特定され、解消されている

成果物：

• 以下を含む検証レポート：
  • 実施したテスト
  • 結果と観察事項
  • 確認された理解
  • 残っている不足点や不確実性

フェーズ 5：統合

目的：調査結果をまとめ、当初の質問に答える一貫した説明を作成します。

タスク：

• reviewer エージェントを使用して、調査結果の網羅性を確認します
• patterns エージェントを使用して、発見された再利用可能なパターンを特定します
• フェーズ 3～4 の調査結果を一貫した説明にまとめます
• 役立つ場合は、視覚資料（図、フローチャートなど）を作成します
• フェーズ 1 のスコープ定義にある各質問に回答します
• うまくいった点と予想外だった点を特定します
• 残っている前提や不確実性があれば記録します
• ユーザーに適した明確な説明を用意します

統合結果：

1. エグゼクティブサマリー：主な質問への回答を 2～3 文でまとめます
2. 詳細な説明：裏付けとなる根拠を含む完全な説明
3. 視覚資料：システムフロー、アーキテクチャなどを示す図
4. 重要な知見：一見して明らかではない発見やパターン
5. 未解明の点：依然として不明、または不確かな点

成功基準：

• フェーズ 1 のすべての質問に回答している
• 説明が明確かつ完全である
• 検証で得られた根拠が調査結果を裏付けている
• 視覚資料が複雑な領域の理解を助けている

成果物：

• 5 つすべての統合結果を含む調査レポート
• フェーズ 6 でナレッジとして記録する準備が整っている

フェーズ 6：知識の記録

目的：今回の調査を二度と繰り返さなくて済むよう、長期的に活用できるドキュメントを作成します。

タスク：

• amplihack.memory.discoveries の store_discovery() を使用して、発見事項をメモリに保存します
• 再利用可能なパターンが見つかった場合は、.claude/context/PATTERNS.md を更新します
• 関連するドキュメントファイルを作成または更新します
• 重要な理解事項について、コードにインラインコメントを追加します
• 任意：今後の改善に向けて GitHub issue を作成します
• 任意：必要に応じてアーキテクチャ図を更新します
• 将来の調査担当者がこの知識を簡単に見つけられるようにします

ドキュメント作成のガイドライン：

## Discovery: [Brief Title]

**Context**: What was investigated and why
**Key Findings**:

- Main insight 1
- Main insight 2
  - **Supporting Evidence**: Links to code, logs, or verification tests
  - **Implications**: How this affects the project
  - **Related Patterns**: Links to similar patterns in PATTERNS.md

成功基準：

• 将来参照できるよう、発見事項がメモリに保存されている
• 関連するドキュメントファイルが更新されている
• 将来の調査担当者が知識を見つけられる
• 情報が失われていない

成果物：

• メモリに保存された発見事項
• 更新された PATTERNS.md（該当する場合）
• 更新されたプロジェクトドキュメント
• 任意：改善に向けた GitHub issue
• ~/.amplihack/.claude/runtime/logs/ に保存された調査セッションログ

開発ワークフローへの移行

調査完了後、タスクに実装が必要な場合（理解だけでなく）、DEFAULT_WORKFLOW.md に移行します。

1. 調査で得た知識をもとに、ステップ 4（調査と設計）から再開します
2. 調査ですでに明確な設計指針が得られている場合は、ステップ 5（ソリューションの実装）から再開します
3. 設計の判断には、メモリ（get_recent_discoveries() 経由）とセッションログから調査結果を活用します

ハイブリッドワークフローの例：

User: "/ultrathink investigate how authentication works, then add OAuth support"

Phase 1: Investigation
→ Run INVESTIGATION_WORKFLOW.md (6 phases)
→ Complete understanding of existing auth system
→ Store findings in memory via discoveries adapter

Phase 2: Development
→ Transition to DEFAULT_WORKFLOW.md
→ Resume at Step 4 (Research and Design)
→ Use investigation insights to design OAuth integration
→ Continue through Step 15 (implementation → testing → PR)

移行するタイミング：

• 調査の結果、実装が必要だと判明した場合
• ユーザーが調査と開発の両方を明示的に依頼した場合
• 知識の記録中に後続作業が特定された場合

効率性の目標

目標効率：このワークフローでは、場当たり的な調査と比べてメッセージ数を 30～40％削減することを目指します。

場当たり的なアプローチ	調査ワークフロー
70～90 メッセージ	40～60 メッセージ
頻繁な後戻り	計画的な探索
重複する調査	並行した詳細調査
不明確な範囲	明確な範囲の定義
失われる知識	記録された知見

効率性が向上する理由：

1. 範囲の定義により、スコープの拡大や目的のない調査を防ぎます
2. 探索戦略により、無作為で成果につながらない探索を防ぎます
3. 並行した詳細調査により、情報収集の速度を最大化します
4. 検証フェーズにより、誤解を早期に発見します
5. 統合により、すべての質問に回答できていることを確認します
6. 知識の記録により、同じ調査の繰り返しを防ぎます

DEFAULT_WORKFLOW.md との比較

共通点（構造の一貫性）

両方のワークフローには、次の基本原則があります。

• 明確な成果物を伴う、明示的なフェーズ
• 各フェーズでのエージェント主導の実行
• 早すぎる進行を防ぐ品質ゲート
• 知識の記録とドキュメント化
• 進捗管理のための TodoWrite による追跡

相違点（調査と開発）

項目	調査ワークフロー	DEFAULT_WORKFLOW.md
目標	理解	実装
フェーズ	6 フェーズ	複数ステップのワークフロー
実行	探索を優先	実装を優先
並行作業	フェーズ 3（詳細調査）	複数のステップ
テスト	理解の検証	コードの検証
成果物	ドキュメント	動作するコード
Git の使用	任意	必須（ブランチ、PR）

フェーズマッピング（ユーザーにとって分かりやすい対応関係）

調査フェーズ	DEFAULT_WORKFLOW における対応項目	目的
フェーズ 1：範囲の定義	ステップ 1：要件の明確化	成功の基準を定義します
フェーズ 2：探索戦略	ステップ 4：調査と設計	アプローチを計画します
フェーズ 3：並行した詳細調査	ステップ 5：実装	計画を実行します（調査または構築）
フェーズ 4：検証	ステップ 7～8：テスト	結果を検証します
フェーズ 5：統合	ステップ 11：レビュー	品質と完全性を確保します
フェーズ 6：知識の記録	ステップ 15：クリーンアップ	結果を永続化します

UltraThink との統合

UltraThink ワークフローの検出：/ultrathink が呼び出されると、キーワードを使って調査タスクを自動的に検出し、このワークフローを提案します。

ワークフローの自動提案：

User: "/ultrathink investigate how authentication works"

UltraThink: Detected investigation task. Using INVESTIGATION_WORKFLOW.md
→ Reading workflow from .claude/workflow/INVESTIGATION_WORKFLOW.md
→ Following 6-phase investigation workflow
→ Starting Phase 1: Scope Definition

カスタマイズ

このワークフローをカスタマイズするには：

1. ~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md を編集して、フェーズを変更、追加、削除します
2. ニーズに合わせてエージェントの配置戦略を調整します
3. プロジェクト固有の調査パターンを追加します
4. 指標に基づいて効率目標を更新します

変更は、以降の調査にすぐに反映されます。

成功指標

ワークフローの有効性を検証するには、次の指標を追跡します：

• メッセージ数：アドホックな方法と比べて 30～40％削減を目標とします（要検証）
• 調査時間：完了までの時間を追跡します
• 知識の再利用：メモリの検索によって作業の繰り返しを防げた頻度
• 完全性：完全なドキュメントを伴う調査の割合
• ユーザー満足度：明確な理解が得られたか

主要な原則

• まず範囲を定め、次に探索する - 調査に着手する前に境界を定義します
• 並行探索が重要 - フェーズ 3 では複数のエージェントを同時に配置します
• 理解を検証する - フェーズ 4 で仮説をテストします
• 知識を記録する - フェーズ 6 では、発見事項を必ずメモリに保存します
• このワークフローは実装ではなく、理解の最適化を目的とします

調査か開発か判断に迷った場合：

• 調査：「X を理解する必要があります」
• 開発：「X を構築／修正／実装する必要があります」

関連リソース

• ワークフローのソース：~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md（全 436 行の仕様）
• 知識の抽出：調査後に knowledge-extractor スキルを使って学びを記録します
• エージェントカタログ：利用可能なすべてのエージェントについては ~/.amplihack/.claude/agents/CATALOG.md を参照してください
• パターンライブラリ：再利用可能な調査パターンについては ~/.amplihack/.claude/context/PATTERNS.md を参照してください