explore

コードベースの探索

ホストに依存しないワークフローです。スキル名（explore）で呼び出します。Claude Code のスラッシュルーティング、YAML フックローダー、.claude/chain については references/claude-code.md を参照してください。

3～5 個の並列エージェントを使って、多角的にコードベースを探索します。

🎯 クイックスタート

explore authentication

Opus 5.5：探索エージェントは、ネイティブの適応的思考を使って、大規模なコードベース全体からより深いパターンを認識します。

---

STEP -0.5：作業量に応じたエージェント数の調整（CC 2.1.120+）

ほかの判断を行う前に、$CLAUDE_EFFORT を読み取り、探索の深さを調整します。

# CC 2.1.120+ env var; explicit --effort= overrides
EFFORT = os.environ.get("CLAUDE_EFFORT")
for token in "$ARGUMENTS".split():
    if token.startswith("--effort="):
        EFFORT = token.split("=", 1)[1]
EFFORT = EFFORT or "high"  # default

作業量	エージェント数	フェーズ	時間
low	1（構造のみ）	1、2、8	約1分
medium	2（構造＋データフロー）	1、2、3（一部）、8	約3分
high（デフォルト）	4（完全並列チーム）	1～8	約6分
xhigh（Opus 5）	5（ヘルススコアの不確実性チェックを追加）	1～8＋注意事項	約8分

上書き条件： $CLAUDE_EFFORT が low のときに、ユーザーが --effort=high を明示的に指定した場合は、そのフラグが優先されます。doctor が警告するのは、XHIGH_UNSUPPORTED_PREFIXES テーブルに記載されたモデルで xhigh が設定されている場合のみです。

---

STEP 0：AskUserQuestion でユーザーの意図を確認する

タスクを作成する前に、ユーザーが何を探索したいのかを確認します。

AskUserQuestion(
  questions=[{
    "question": "What aspect do you want to explore?",
    "header": "Focus",
    "options": [
      {"label": "Full exploration (Recommended)", "description": "Code structure + data flow + architecture + health assessment"},
      {"label": "Quick scan", "description": "Find relevant files + structure, skip deep analysis"},
      {"label": "Data flow", "description": "Trace how data moves through the system"},
      {"label": "Architecture patterns", "description": "Identify design patterns and integrations"}
    ],
    "multiSelect": false
  }]
)

回答に応じてワークフローを調整します：

• 全体探索：すべてのフェーズと、すべての並列エージェントを実行
• クイックスキャン：ファイルと構造のみ（フェーズ1～2）。ヘルス、依存関係、プロダクトの分析は省略し、詳細なエージェントも使用しない
• データフロー：フェーズ3のエージェントをデータの追跡に集中させる
• アーキテクチャパターン：backend-system-architect エージェントに集中させる

---

STEP 0b：オーケストレーションモードを選択する

MCP プローブ

# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")
Write(".claude/chain/capabilities.json", { memory, timestamp })

if capabilities.memory:
  mcp__memory__search_nodes({ query: "architecture decisions for {path}" })
  # Enrich exploration with past decisions

探索結果の引き継ぎ

探索の完了後、後続のスキルで使えるよう結果を書き出します。

Write(".claude/chain/exploration.json", JSON.stringify({
  "phase": "explore", "skill": "explore",
  "timestamp": now(), "status": "completed",
  "outputs": {
    "architecture_map": { ... },
    "patterns_found": ["repository", "service-layer"],
    "complexity_hotspots": ["src/auth/", "src/payments/"]
  }
}))

---

エージェントチーム（メッシュ）または Agent ツール（スター）を選択します。

1. Agent Teams モード（CC 2.1.33 以降で GA）→ 4 つ以上のエージェントに推奨
2. Agent ツールモード → クイック探索／単一の焦点を絞った探索向け
3. ORCHESTKIT_FORCE_TASK_TOOL=1 → Agent ツール（上書き）

項目	Agent ツール	Agent Teams
発見内容の共有	すべての処理完了後にリードが統合	探索エージェントが進行中に発見内容を共有
相互参照	リードが関連性を見つける	データフロー探索エージェントがアーキテクチャ探索エージェントに通知
コスト	約150Kトークン	約400Kトークン
最適な用途	クイック／焦点を絞った検索	コードベース全体の詳細な探索

フォールバック： Agent Teams で問題が発生した場合、残りの探索には Agent ツールを使用します。

モデルの固定： Agent ツールモードでは、組み込みの Explore 呼び出しに model="haiku" を設定します。このトライアルの対象はこの経路のみです。Agent Teams の呼び出しでは、既存のモデル選択を維持します。フォークでは親モデルと共有コンテキストが使われます。

---

🚨 タスク管理（必須）

ほかの作業を始める前に、進捗を示すタスクを作成します：

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Explore: {topic}", description="Deep codebase exploration for {topic}", activeForm="Exploring {topic}")

# 2. Create subtasks for each phase
TaskCreate(subject="Initial file search", activeForm="Searching files")                # id=2
TaskCreate(subject="Check knowledge graph", activeForm="Checking memory")              # id=3
TaskCreate(subject="Launch exploration agents", activeForm="Dispatching explorers")     # id=4
TaskCreate(subject="Assess code health (0-10)", activeForm="Assessing code health")    # id=5
TaskCreate(subject="Map dependency hotspots", activeForm="Mapping dependencies")       # id=6
TaskCreate(subject="Add product perspective", activeForm="Adding product context")     # id=7
TaskCreate(subject="Generate exploration report", activeForm="Generating report")      # id=8

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Memory check needs file search first
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Agents need memory context
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Health needs exploration done
TaskUpdate(taskId="6", addBlockedBy=["4"])  # Hotspots need exploration done
TaskUpdate(taskId="7", addBlockedBy=["4"])  # Product needs exploration done
TaskUpdate(taskId="8", addBlockedBy=["5", "6", "7"])  # Report needs all analysis done

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

---

🔄 ワークフローの概要

フェーズ	アクティビティ	出力
1. 初期検索	Grep、Glob で一致箇所を検索	ファイルの場所
2. メモリの確認	ナレッジグラフを検索	既存のコンテキスト
3. 詳細な探索	4 つの並列探索エージェント	多角的な分析
4. AI システム（該当する場合）	LangGraph、プロンプト、RAG	AI 固有の調査結果
5. コードの健全性	コードを 0～10 で評価	品質スコア
6. 依存関係のホットスポット	密結合箇所を特定	ホットスポットの可視化
7. プロダクトの視点	ビジネス上の背景	見つけやすさに関する提案
8. レポートの生成	調査結果をまとめる	実行可能なレポート

段階的な出力（CC 2.1.76）

各フェーズが完了するたびに、調査結果を段階的に出力します。レポートが完成するまでまとめて出力しないでください。

フェーズ完了後	ユーザーに表示する内容
1. 初期検索	ファイルの一致結果、grep の検索結果
2. メモリの確認	過去の決定事項と関連するコンテキスト
3. 詳細調査	各調査エージェントの結果が返り次第、その内容
5. コードの健全性	健全性スコアと各評価軸の内訳

フェーズ 3 の並列エージェントでは、4 つすべての調査エージェントを待たず、各エージェントの結果が返り次第、すぐに出力します。あるエージェントからの初期調査結果でユーザーの質問に答えられる場合、残りのエージェントの処理が完了する前に終了できます。

---

フェーズ 1：初期検索

最初にリポジトリマップを読み込みます。 フォークしたスキルでは frontmatter のフックが実行されないため（#4683）、ローダーを手動で実行し、その additionalContext を念頭に置いてください。

echo '{"tool_name":"Bash","tool_input":{}}' | node "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs" skill/repo-structure-indexer

# PARALLEL - Quick searches
Grep(pattern="$ARGUMENTS[0]", output_mode="files_with_matches")
Glob(pattern="**/*$ARGUMENTS[0]*")

フェーズ 2：メモリの確認

mcp__memory__search_nodes(query="$ARGUMENTS[0]")
mcp__memory__search_nodes(query="architecture")

フェーズ 3：並列での詳細調査（4 エージェント）

Agent ツールモードのプロンプトについては、Read("rules/exploration-agents.md") を読み込みます。

Agent Teams の代替手段については、Read("rules/agent-teams-mode.md") を読み込みます。

フェーズ 4：AI システムの調査（該当する場合）

AI／ML に関するトピックでは、以下についても調査します。LangGraph のワークフロー、プロンプトテンプレート、RAG パイプライン、キャッシュ戦略。

フェーズ 5：コードの健全性の評価

エージェントのプロンプトについては、Read("rules/code-health-assessment.md") を読み込みます。スコアリング基準については、Read("references/code-health-rubric.md") を読み込みます。

フェーズ 6：依存関係のホットスポットマップ

エージェントのプロンプトについては、Read("rules/dependency-hotspot-analysis.md") を読み込みます。指標については、Read("references/dependency-analysis.md") を読み込みます。

フェーズ 7：プロダクトの視点

エージェントのプロンプトについては、Read("rules/product-perspective.md") を読み込みます。ベストプラクティスについては、Read("references/findability-patterns.md") を読み込みます。

フェーズ 8：レポートの生成

Read("references/exploration-report-template.md") を読み込みます。

フェーズ 8b：ダッシュボード仕様の出力（json-render）

$ARGUMENTS から --render= を解析します。デフォルトは both です。

モード	動作
markdown	現在の動作。Markdown レポートのみを出力し、仕様は出力しません。
json-render	.claude/chain/explore-dashboard.json のみを出力します。Markdown レポートは省略します。
both	仕様と Markdown の両方を出力します。デフォルトでは、ユーザー向けのレポートと、後続スキル向けの構造化された引き継ぎ情報を提供します。

仕様を出力する場合：

1. フォーマットとカタログを読み込みます。Read("references/dashboard-spec.md")。参照例：references/dashboard-example.json。
2. カタログにあるコンポーネントタイプのみを使用して仕様オブジェクトを作成します。Card、StatGrid、DataTable、StatusBadge、BarMeter、Heatmap、Markdown。
3. .claude/chain/explore-dashboard.json に、インデントなしのコンパクトな JSON として書き込みます。後続のコンシューマーのトークンコストを抑えられます。
4. 成功を宣言する前に検証します。

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/explore-dashboard.json --check

検証に失敗した場合（終了コード ≠ 0）、出力しないでください。Markdown のみの出力に切り替え、エラーをユーザーに提示します。部分的または無効な仕様は絶対に書き込まないでください。

5. --render=both の場合、一貫性を保つため、仕様から Markdown ビューをレンダリングします。

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/explore-dashboard.json

出力をユーザー向けの Markdown レポートに渡すか、そのまま使用します。これにより、JSON 仕様と Markdown レポートの同期が保証され、単一の信頼できる情報源となります。

これが重要な理由： 後続スキル（fix-issue、implement、create-pr）は、3000 トークンの Markdown を再読み込みする代わりに、.claude/chain/explore-dashboard.json を直接解析します。測定値：同じ内容でも仕様は約 580 トークンです。後方互換性もあります。Markdown を読み込む従来の連携ワークフローは、both モードでも引き続き動作します。

フェーズ 6.5 — ノートブックの要約（シグナル発火時、任意）

セッションの統合が完了した後、必要に応じて scripts/post_explore_summary.py <session-dir> を実行し、ノートブックに基づく探索の要約を自動生成します。正常に完了しない場合はすべて自動的にスキップするため、実行が中断されることはありません。

python3 ${CLAUDE_SKILL_DIR}/scripts/post_explore_summary.py "$CLAUDE_JOB_DIR"

自動スキップ条件（すべて終了コード 0、すべて WARN ログに記録）：

スキップ理由	発生条件
signal absent	len(dirs_scanned) < 3（または explore-output.json にフィールドがない）
yg-mcp-core not importable	yg-mcp-core>=0.3.0 がインストールされていない（orchestkit は公開されています。yg-mcp-core はプライベートな pypi.yonyon.ai にあり、HQ 専用です）
hq-content MCP unreachable	MCP サーバーが停止している、または .mcp.json に hq-content が定義されていない

セッションディレクトリには explore-output.json（dirs_scanned: list[str]、任意の synthesis: str、必須の notebook_id: str を含む）が必要です。<session-dir>/explore-summary.json に出力される引き継ぎ用 JSON には、status（fired / skipped）と、成功時の summary_path が記録されます。

PR #1889 の brainstorm における統合後のポッドキャスト生成パターンを踏襲しています。orchestkit#1893 を完了させます。

長時間の探索に関する注意

読み込みサイズが大きい場合（CC 2.1.144+）： ファイル全体の読み込みがトークン上限を超えると、Read はエラーではなく、先頭ページを切り詰めた [PARTIAL view] を返します。大きなファイルを調べる際は、この通知を検出し、明示的に offset / limit を指定して再読み込みし、残りのページを確認してください。部分的な内容をファイル全体として扱わないでください。

コンテキストがいっぱいになった場合（CC 2.1.141+）： 再起動する代わりに、巻き戻しメニューの「ここまでを要約」を使って、最近のコンテキストを維持しながら以前のターンを圧縮してください。リアクティブ圧縮（CC 2.1.142+）では、最初の要約のサイズが実際のオーバーフロー量に合わせて調整されるため、ターンの途中で再度要約が必要になることはまれです。

よくある探索クエリ

• 「認証の仕組みはどうなっていますか？」
• 「API エンドポイントはどこで定義されていますか？」
• 「EventBroadcaster の使用箇所をすべて見つけてください」
• 「コンテンツ分析のワークフローは何ですか？」

/goal で無人実行する

/goal（CC 2.1.139+）で完了条件を設定すると、このスキルは条件が満たされるまでターンをまたいで作業を続けます。インタラクティブモード、-p、Remote Control で利用できます。オーバーレイパネルには、経過時間、ターン数、トークン数がリアルタイムで表示されます。

このスキルの完了条件の例：

/goal until report.has_architecture_diagram AND patterns.detected_count >= 5, or stop after 10 turns

次の条件が満たされると停止します：コードベースのアーキテクチャ図が生成され、少なくとも 5 つのデザインパターンが分類されていること。claude.ai の Remote Control 実行に対応しています。

品質基準

以下のすべてを満たしたら完了です。

• アーキテクチャまたはデータフローに関する主張には、文章による説明だけでなく、具体的な根拠（ファイルと行番号、またはファイルパス）が示されている
• コードの健全性が、単一の数値だけでなく、次元ごとの内訳を含む 0〜10 のスコアで報告されている
• 依存関係のホットスポットや結合度が、それらの原因となっているファイルとともに示されている
• レポートに、探索対象範囲のアーキテクチャまたは構造の可視化が含まれている
• json-render 仕様を出力する場合は、render-spec.mjs --check に合格すること。不合格の場合は Markdown のみの出力に切り替え、不完全な仕様を書き込まないこと

📜 関連スキル

• ork:implement：探索後の実装

---

バージョン： 2.6.0（2026 年 4 月）— $CLAUDE_EFFORT 環境変数でエージェント数を調整します（CC 2.1.120、#1540）