explore

探索 - 内部コードベースの探索

さまざまな深さで内部コードベースを探索するためのメタスキルです。読み取り専用のワークフローです。コードは変更しません。

使用方法

/explore <depth> [options]

質問フロー（引数なし）

ユーザーが引数なし、または一部の引数のみで /explore と入力した場合は、この質問フローを案内します。各フェーズで AskUserQuestion を使用してください。

フェーズ 0：ワークフローの選択

question: "How would you like to explore?"
header: "Explore"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask questions to pick the right exploration depth"
  - label: "Quick - fast overview"
    description: "Chain: tldr tree → tldr structure (~1 min)"
  - label: "Deep - comprehensive analysis"
    description: "Chain: onboard → tldr → research → document (~5 min)"
  - label: "Architecture - layers & dependencies"
    description: "Chain: tldr arch → call graph → layer mapping (~3 min)"

対応関係：

• 「選択を手伝って」→ フェーズ 1～4 の質問に進みます
• 「クイック」→ depth=quick に設定し、フェーズ 2（スコープ）に進みます
• 「詳細」→ depth=deep に設定し、フェーズ 2（スコープ）に進みます
• 「アーキテクチャ」→ depth=architecture に設定し、フェーズ 2（スコープ）に進みます

回答が不明確な場合（「その他」を選択）：

question: "I want to understand how deep you want to explore. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure - guide me through questions"
  - label: "Quick - fast overview"
    description: "Just want to see what's here"
  - label: "Deep - comprehensive analysis"
    description: "Need thorough understanding"
  - label: "Neither - let me explain differently"
    description: "I'll describe what I need"

フェーズ 1：探索の目的

question: "What are you trying to understand?"
header: "Goal"
options:
  - label: "Get oriented in the codebase"
    description: "Quick overview of structure"
  - label: "Understand how something works"
    description: "Deep dive into specific area"
  - label: "Map the architecture"
    description: "Layers, dependencies, patterns"
  - label: "Find where something is"
    description: "Locate specific code/functionality"

対応関係：

• 「概要を把握する」→ quick の深さ
• 「仕組みを理解する」→ deep の深さ
• 「アーキテクチャを把握する」→ architecture の深さ
• 「場所を探す」→ --focus を指定した quick

フェーズ 2：スコープ

question: "What area should I focus on?"
header: "Focus"
options:
  - label: "Entire codebase"
    description: "Explore everything"
  - label: "Specific directory or module"
    description: "I'll specify the path"
  - label: "Specific concept/feature"
    description: "e.g., 'authentication', 'API routes'"

「特定のディレクトリ」または「特定の概念」を選択した場合は、パスまたはキーワードを確認する質問を追加します。

フェーズ 3：出力形式

question: "What should I produce?"
header: "Output"
options:
  - label: "Just tell me what you find"
    description: "Interactive summary in chat"
  - label: "Create a documentation file"
    description: "Write to thoughts/shared/docs/"
  - label: "Create handoff for implementation"
    description: "Prepare context for coding agent"

対応関係：

• 「ドキュメントファイル」→ --output doc
• 「実装の引き継ぎ資料」→ --output handoff

フェーズ 4：エントリーポイント（Architecture のみ）

architecture の深さを選択した場合：

question: "Where should I start the analysis?"
header: "Entry point"
options:
  - label: "Auto-detect (main, cli, app)"
    description: "Find common entry points"
  - label: "Specific function/file"
    description: "I'll specify the entry point"

実行前の概要

Based on your answers, I'll run:

**Depth:** deep
**Focus:** "authentication"
**Output:** handoff
**Path:** src/

Proceed? [Yes / Adjust settings]

深さ

深さ	時間	内容
quick	約 1 分	tldr-explorer のみ - 高速な構造の概要
deep	約 5 分	onboard + tldr-explorer + research-codebase + ドキュメントの作成
architecture	約 3 分	tldr arch + 呼び出しグラフ + レイヤーマッピング + 循環依存の検出

オプション

オプション	説明	例
--focus "area"	特定の領域に焦点を当てます	--focus "auth"、--focus "api"
--output handoff	次のエージェント用の引き継ぎ資料を作成します	--output handoff
--output doc	ドキュメントファイルを作成します	--output doc
--entry "func"	特定のエントリーポイントから開始します	--entry "main"、--entry "process_request"

例

# Quick structure overview
/explore quick

# Deep exploration focused on auth
/explore deep --focus "auth" --output doc

# Architecture analysis from specific entry
/explore architecture --entry "cli" --output handoff

# Quick focused exploration
/explore quick --focus "hooks"

ワークフローの詳細

Quick の深さ

tldr-explorer を使用して高速に構造の概要を把握します。次の場合に最適です：

• 最初に概要を把握するとき
• 構造について手早く質問するとき
• 項目の場所を探すとき

手順：

1. tldr tree を実行してファイル構造を確認します
2. tldr structure を実行してコードマップを確認します
3. --focus が指定されている場合は、tldr search を実行して対象を絞った結果を取得します
4. 概要を返します

コマンド：

# 1. File tree
tldr tree ${PATH:-src/} --ext .py

# 2. Code structure
tldr structure ${PATH:-src/} --lang python

# 3. Focused search (if --focus provided)
tldr search "${FOCUS}" ${PATH:-src/}

Deep の深さ

ドキュメント出力を伴う包括的な探索です。次の場合に最適です：

• コードベースを初めて扱うとき
• 大規模な作業の準備をするとき
• 参考ドキュメントを作成するとき

手順：

1. オンボーディング済みか確認します（.claude/cache/tldr/ を探します）。未実施の場合は onboard を実行します
2. tldr-explorer を実行して構造を確認します
3. research-codebase エージェントを起動してパターンを調査します
4. 調査結果をドキュメントまたは引き継ぎ資料に記録します

サブプロセス：

# 1. Onboard check
if [ ! -f .claude/cache/tldr/arch.json ]; then
    # Spawn onboard agent
fi

# 2. Structure analysis
tldr structure src/ --lang python
tldr calls src/

# 3. Research patterns (via scout agent)
Task: research-codebase → "Document existing patterns in ${FOCUS:-codebase}"

# 4. Write output
→ thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md
→ OR thoughts/shared/handoffs/{session}/explore-{focus}.yaml

Architecture の深さ

レイヤー検出を行う、アーキテクチャに焦点を当てた分析です。次の場合に最適です：

• システムの境界を理解するとき
• リファクタリングの準備をするとき
• 結合の問題を特定するとき

手順：

1. tldr arch を実行してレイヤーを検出します
2. tldr calls を実行してファイル間の呼び出しグラフを確認します
3. エントリー、ミドル、リーフの各レイヤーを分析します
4. 循環依存を検出します
5. アーキテクチャ上の境界をマッピングします

コマンド：

# 1. Architecture detection
tldr arch ${PATH:-src/}
# Returns: entry_layer, middle_layer, leaf_layer, circular_deps

# 2. Call graph
tldr calls ${PATH:-src/}
# Returns: edges, nodes

# 3. Impact analysis from entry point (if --entry provided)
tldr impact ${ENTRY} ${PATH:-src/} --depth 3

出力構成：

layers:
  entry: [routes.py, cli.py, main.py]  # Controllers/handlers
  middle: [services.py, auth.py]        # Business logic
  leaf: [utils.py, helpers.py]          # Utilities

call_graph:
  total_edges: 142
  hot_paths: [process_request → validate → authorize]

circular_deps:
  - [module_a, module_b]  # A imports B, B imports A

boundaries:
  - name: API layer
    files: [src/api/*]
    calls_to: [src/services/*]

出力形式

--output doc

作成先：thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md

---
date: {ISO timestamp}
type: exploration
depth: {quick|deep|architecture}
focus: {focus area or "full"}
commit: {git hash}
---

# Codebase Exploration: {focus}

## Summary
{High-level findings}

## Structure
{File tree / codemaps}

## Architecture
{Layer analysis - for architecture depth}

## Key Components
{Important files and their roles}

## Patterns Found
{Existing patterns - for deep depth}

## References
- `path/to/file.py:line` - Description

--output handoff

作成先：thoughts/shared/handoffs/{session}/explore-{focus}.yaml

---
type: exploration
ts: {ISO timestamp}
depth: {quick|deep|architecture}
focus: {focus area}
commit: {git hash}
---

summary: {One-line summary of findings}

structure:
  entry_points: [{main.py}, {cli.py}]
  key_modules: [{auth.py}, {routes.py}]
  test_coverage: [{tests/}]

architecture:
  layers:
    entry: [{files}]
    middle: [{files}]
    leaf: [{files}]
  circular_deps: [{pairs}]

findings:
  - {key finding with file:line}

next_steps:
  - {Recommended action based on exploration}

refs:
  - path: {file.py}
    role: {what it does}

/build との連携

explore スキルは /build brownfield への情報提供を目的に設計されています：

# Step 1: Explore to understand
/explore architecture --output handoff

# Step 2: Build with context from exploration
/build brownfield --from-handoff thoughts/shared/handoffs/session/explore-full.yaml

実装

ユーザーが /explore <depth> [options] を実行した場合：

引数の解析

depth = args[0]  # quick | deep | architecture
focus = extract_option(args, "--focus")
output = extract_option(args, "--output")  # handoff | doc
entry = extract_option(args, "--entry")

深さに応じた実行

Quick：

# Just tldr commands, no agents
tldr tree ${src_dir} --ext .py
tldr structure ${src_dir} --lang python
if [ -n "$focus" ]; then
    tldr search "$focus" ${src_dir}
fi

Deep：

# 1. Check/run onboard
if [ ! -f .claude/cache/tldr/meta.json ]; then
    # Spawn onboard agent via Task tool
fi

# 2. Structure
tldr structure src/ --lang python

# 3. Research (spawn scout agent)
# Task tool with subagent_type: "scout"
# Prompt: "Research patterns in ${focus:-codebase}"

# 4. Write output
# → doc or handoff based on --output

Architecture：

# 1. Arch detection
arch_output=$(tldr arch ${src_dir})

# 2. Call graph
calls_output=$(tldr calls ${src_dir})

# 3. Impact from entry (if provided)
if [ -n "$entry" ]; then
    impact_output=$(tldr impact $entry ${src_dir} --depth 3)
fi

# 4. Synthesize and write output

主な原則

1. 読み取り専用 - このスキルはコードを変更しません
2. Explore ではなく scout を使用 - プロジェクトのルールに従い、Explore（Haiku）ではなく scout（Sonnet）を使用します
3. トークン効率に優れる - tldr コマンドを使用します（生データの読み取りと比べて 95% 削減）
4. 共有場所に出力 - thoughts/shared/research/ または引き継ぎ用ディレクトリに出力します
5. /build へのエントリーポイント - 探索の引き継ぎは、既存コードベースのビルドに活用されます

関連スキル

スキル	使用するタイミング
tldr-explorer	tldr コマンドを直接実行するとき（explore 内部で使用）
tldr-code	特定の分析コマンドを実行するとき（cfg、dfg、slice）
onboard	初回のプロジェクト設定時（deep の深さで使用）
research-codebase	パターンを文書化するとき（deep の深さで使用）
create_handoff	引き継ぎ形式を使用するとき（--output handoff で使用）

トラブルシューティング

tldr が見つからない場合：

# Check if installed
which tldr
# Install if missing
uv tool install llm-tldr
# or: pip install llm-tldr

Python ファイルが見つからない場合：

# Check language, adjust --lang
tldr structure src/ --lang typescript  # or go, rust

アーキテクチャの出力が空の場合：

# May need to specify src directory
tldr arch ./  # Current directory
tldr arch src/  # Explicit src