research-external

外部リサーチワークフロー

ライブラリ、ベストプラクティス、一般的なトピックについて、外部ソース（ドキュメント、Web、API）を調査します。

注： 現在の年は2025年です。ベストプラクティスを調査する際は、2024～2025年を参考期間としてください。

呼び出し

/research-external <focus> [options]

質問フロー（引数なし）

ユーザーが引数なし、または不完全な引数で /research-external と入力した場合は、この質問フローに沿って案内します。各フェーズで AskUserQuestion を使用します。

フェーズ 1：調査の種類

question: "What kind of information do you need?"
header: "Type"
options:
  - label: "How to use a library/package"
    description: "API docs, examples, patterns"
  - label: "Best practices for a task"
    description: "Recommended approaches, comparisons"
  - label: "General topic research"
    description: "Comprehensive multi-source search"
  - label: "Compare options/alternatives"
    description: "Which tool/library/approach is best"

対応関係：

• 「ライブラリの使い方」→ ライブラリに重点
• 「ベストプラクティス」→ ベストプラクティスに重点
• 「一般的なトピック」→ 一般に重点
• 「選択肢を比較」→ 比較の観点を含め、ベストプラクティスに重点

フェーズ 2：具体的なトピック

question: "What specifically do you want to research?"
header: "Topic"
options: []  # Free text input

回答例：

• 「TypeScript で Prisma ORM を使う方法」
• 「Python でのエラー処理のベストプラクティス」
• 「ダッシュボード向けの React、Vue、Svelte の比較」

フェーズ 3：ライブラリの詳細（ライブラリに重点を置く場合）

ユーザーがライブラリに重点を置くことを選択した場合：

question: "Which package registry?"
header: "Registry"
options:
  - label: "npm (JavaScript/TypeScript)"
    description: "Node.js packages"
  - label: "PyPI (Python)"
    description: "Python packages"
  - label: "crates.io (Rust)"
    description: "Rust crates"
  - label: "Go modules"
    description: "Go packages"

次に、すでに指定されていない場合は、具体的なライブラリ名を尋ねます。

フェーズ 4：調査の深さ

question: "How thorough should the research be?"
header: "Depth"
options:
  - label: "Quick answer"
    description: "Just the essentials"
  - label: "Thorough research"
    description: "Multiple sources, examples, edge cases"

対応関係：

• 「簡潔な回答」→ --depth shallow
• 「詳細」→ --depth thorough

フェーズ 5：出力

question: "What should I produce?"
header: "Output"
options:
  - label: "Summary in chat"
    description: "Tell me what you found"
  - label: "Research document"
    description: "Write to thoughts/shared/research/"
  - label: "Handoff for implementation"
    description: "Prepare context for coding"

対応関係：

• 「調査ドキュメント」→ --output doc
• 「引き継ぎ」→ --output handoff

実行前の概要

Based on your answers, I'll research:

**Focus:** library
**Topic:** "Prisma ORM connection pooling"
**Library:** prisma (npm)
**Depth:** thorough
**Output:** doc

Proceed? [Yes / Adjust settings]

フォーカスモード（第 1 引数）

フォーカス	主なツール	目的
library	nia-docs	API ドキュメント、使用パターン、コード例
best-practices	perplexity-search	推奨される方法、パターン、比較
general	すべての MCP ツール	複数のソースを網羅した包括的な調査

オプション

オプション	値	説明
--topic	"string"	必須。 調査するトピック／ライブラリ／概念
--depth	shallow、thorough	検索の深さ（デフォルト：shallow）
--output	handoff、doc	出力形式（デフォルト：doc）
--library	"name"	library フォーカスの場合：特定のパッケージ名
--registry	npm、py_pi、crates、go_modules	library フォーカスの場合：パッケージレジストリ

ワークフロー

ステップ 1：引数を解析する

ユーザー入力から以下を抽出します：

FOCUS=$1           # library | best-practices | general
TOPIC="..."        # from --topic
DEPTH="shallow"    # from --depth (default: shallow)
OUTPUT="doc"       # from --output (default: doc)
LIBRARY="..."      # from --library (optional)
REGISTRY="npm"     # from --registry (default: npm)

ステップ 2：フォーカスに応じて調査を実行する

フォーカス：library

主なツール：nia-docs — API ドキュメント、使用パターン、コード例を見つけます。

# Semantic search in package
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --registry "$REGISTRY" \
  --query "$TOPIC" \
  --limit 10)

# If thorough depth, also grep for specific patterns
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --grep "$TOPIC")

# Supplement with official docs if URL known
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py \
  --url "https://docs.example.com/api/$TOPIC" \
  --format markdown)

詳細な調査で追加する内容：

• バリエーションを含む複数のセマンティック検索クエリ
• 特定の関数名／クラス名を Grep で検索
• 公式ドキュメントのページをスクレイピング

フォーカス：best-practices

主なツール：perplexity-search — 推奨される方法、パターン、アンチパターンを見つけます。

# AI-synthesized research (sonar-pro)
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --research "$TOPIC best practices 2024 2025")

# If comparing alternatives
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC vs alternatives - which to choose?")

詳細な調査で追加する内容：

# Chain-of-thought for complex decisions
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC tradeoffs and considerations 2025")

# Deep comprehensive research
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --deep "$TOPIC comprehensive guide 2025")

# Recent developments
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --search "$TOPIC latest developments" \
  --recency month --max-results 5)

フォーカス：general

利用可能なすべての MCP ツールを使用して、複数のソースを網羅的に調査します。

ステップ 2a：ライブラリのドキュメント（nia-docs）

(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --search "$TOPIC")

ステップ 2b：Web 調査（perplexity）

(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --research "$TOPIC")

ステップ 2c：特定のドキュメント（firecrawl）

# Scrape relevant documentation pages found in perplexity results
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py \
  --url "$FOUND_DOC_URL" \
  --format markdown)

詳細な調査で追加する内容：

• 3 つのツールすべてで、クエリを拡張して実行する
• ソース間で調査結果を相互参照する
• 初期結果に含まれるリンクをたどり、背景情報をさらに調べる

ステップ 3：調査結果を統合する

すべてのソースからの結果をまとめます。

1. 主要な概念 — 中核となる考え方と用語
2. コード例 — ドキュメントにある動作する例
3. ベストプラクティス — 推奨される方法
4. 注意点 — 避けるべきよくある間違い
5. 代替案 — 検討したその他の選択肢
6. ソース — すべての引用元の URL

ステップ 4：出力を書き込む

出力：doc（デフォルト）

出力先：thoughts/shared/research/YYYY-MM-DD-{topic-slug}.md

---
date: {ISO timestamp}
type: external-research
topic: "{topic}"
focus: {focus}
sources: [nia, perplexity, firecrawl]
status: complete
---

# Research: {Topic}

## Summary
{2-3 sentence summary of findings}

## Key Findings

### Library Documentation
{From nia-docs - API references, usage patterns}

### Best Practices (2024-2025)
{From perplexity - recommended approaches}

### Code Examples
```{language}
// Working examples found

推奨事項

• {Recommendation 1}
• {Recommendation 2}

避けるべき注意点

• {Pitfall 1}
• {Pitfall 2}

検討した代替案

選択肢	メリット	デメリット
{Option 1}	...	...

ソース

• {Source 1}
• {Source 2}

#### Output: `handoff`

Write to: `thoughts/shared/handoffs/{session}/research-{topic-slug}.yaml`

```yaml
---
type: research-handoff
ts: {ISO timestamp}
topic: "{topic}"
focus: {focus}
status: complete
---

goal: Research {topic} for implementation planning
sources_used: [nia, perplexity, firecrawl]

findings:
  key_concepts:
    - {concept1}
    - {concept2}

  code_examples:
    - pattern: "{pattern name}"
      code: |
        // example code

  best_practices:
    - {practice1}
    - {practice2}

  pitfalls:
    - {pitfall1}

recommendations:
  - {rec1}
  - {rec2}

sources:
  - title: "{Source 1}"
    url: "{url1}"
    type: {documentation|article|reference}

for_plan_agent: |
  Based on research, the recommended approach is:
  1. {Step 1}
  2. {Step 2}
  Key libraries: {lib1}, {lib2}
  Avoid: {pitfall1}

ステップ 5：概要を返す

Research Complete

Topic: {topic}
Focus: {focus}
Output: {path to file}

Key findings:
- {Finding 1}
- {Finding 2}
- {Finding 3}

Sources: {N} sources cited

{If handoff output:}
Ready for plan-agent to continue.

エラー処理

MCP ツールが失敗した場合（API キーがない、レート制限に達したなど）：

1. 出力に失敗を記録します：

   tool_status:
     nia: success
     perplexity: failed (rate limited)
     firecrawl: skipped
   

2. ほかのソースを使って続行します — 部分的な結果にも価値があります

3. ステータスを適切に設定します：

   • complete — リクエストされたすべてのツールが成功
   • partial — 一部のツールは失敗したが、調査結果は引き続き有用
   • failed — 有用な結果が得られなかった

4. 調査結果に不足点を記載します：

   ## Gaps
   - Perplexity unavailable - best practices section limited to nia results
   

例

ライブラリ調査（簡易）

/research-external library --topic "dependency injection" --library fastapi --registry py_pi

ベストプラクティス（詳細）

/research-external best-practices --topic "error handling in Python async" --depth thorough

引き継ぎ用の一般的な調査

/research-external general --topic "OAuth2 PKCE flow implementation" --depth thorough --output handoff

ライブラリの簡易検索

/research-external library --topic "useEffect cleanup" --library react

ほかのスキルとの連携

調査後	使用するスキル	用途
--output handoff	plan-agent	実装計画の作成
コード例が見つかった場合	implement_task	直接実装
アーキテクチャに関する判断	create_plan	詳細な計画
ライブラリの比較	ユーザーに提示	意思決定

必要な環境

• NIA_API_KEY または mcp_config.json 内の nia サーバー
• 環境変数または ~/.claude/.env 内の PERPLEXITY_API_KEY
• FIRECRAWL_API_KEY および mcp_config.json 内の firecrawl サーバー

注意事項

• コードベースの調査には使用しないでください — その場合は research-codebase または scout を使用します
• 必ずソースを引用してください — すべての調査結果に URL を含めます
• 2024～2025 年を対象にします — 最新のベストプラクティスに焦点を当てます
• 適切に縮退します — 結果がないより、部分的な結果のほうが有用です