inquisitor

概要

inquisitor は、AI エージェントにチェスエンジンのような問題解決をさせます。すべての分岐を探索できないため、まず複雑さを見積もり、情報を増やさない経路を刈り込み、問題の核心にだけ探索予算を費やします。

連携する 2 つのレイヤーで構成されています。

• MCP サーバー（inquisitor-mcp） — エンジンです。ウェブ検索、プロジェクト分析、コードの追跡、プロジェクトのひな形作成、永続的な調査ステートマシンを提供します。OpenCode、Claude Code、Claude Desktop、Cursor など、MCP 互換のあらゆるエージェントで動作します。
• エージェントスキル（skills/inquisitor/SKILL.md） — 行動レイヤーです。調査とゲートのループ、枝刈りのルール、手法全体をエージェントの推論に組み込みます。

この手法はここで発明されたものではありません。一次資料を組み合わせたものです。Newton の Analysis→Synthesis の骨格を、誤った前提に対する科学的方法独自の防御策（反証、強い推論、競合仮説分析、固着を避けるための視点の切り替え、プレモーテム）で強化し、工学的な規律（NASA/JPL の Power of Ten、外科的変更のガイドライン、最小化の段階）で制約しています。出典はすべて基礎に記載されています。

ウェブ検索、コードベースのスキャン、コードの追跡は、ローカルの証拠が不十分な場合に使うツールであり、必須の儀式ではありません。

---

判断の仕組み

深さはラベルではなく、出力です。LLM による事前の難易度予測は、最も信頼性の低いシグナルです。適切に調整されておらず、重要な難問ほど簡単だと見積もる傾向があります。そのため inquisitor は、問題を理解する前に分類することはありません。まず低コストの調査を行います（現在最有力の仮説を確認または否定できる、最も低コストな単一のアクションです）。深さを決めるのは、予測ではなく、調査の結果です。

flowchart TD
    P([Problem]) --> F["FRAME<br/>done = ? · must not break = ?"]
    F --> D{"delegate?<br/>a specialist skill<br/>owns this"}
    D -->|yes| SK["hand off — /tdd,<br/>/code-review, ..."]
    D -->|no| PR["PROBE<br/>cheapest action that could confirm<br/>or kill the best hypothesis"]
    PR -->|"obvious, local"| SH["<b>Shallow</b><br/>fix → verify<br/><i>no ceremony</i>"]
    PR -->|"clear single-<br/>component cause"| ST["<b>Standard</b><br/>frame → minimal evidence<br/>→ fix → verify"]
    PR -->|"root cause unknown,<br/>multi-component"| DE["<b>Deep</b> — Newton 7-phase:<br/>DEFINE → AXIOMS → ANALYSIS →<br/>EXPERIMENT → SYNTHESIS →<br/>VALIDATE → QUERY<br/><i>+ session tracking as memory</i>"]

    SH -.->|"gate trigger /<br/>failed fix / low confidence"| ST
    ST -.->|"gate only raises depth —<br/>never lowers"| DE

エスカレーションは許可されるだけでなく、必ず実施されます。 調査は出発点にすぎません。インフラ／デプロイ／ルーティング／設定、認証／セキュリティ、データ移行、複数ファイルにまたがる修正、本番環境でのみ発生する症状などの客観的なゲート条件に該当すると、問題がどれほど「明白」に感じられても、深さの最低基準が強制されます。また、3 つの質問による確信度チェック（実行時の経路を読みましたか？ 実行時のシグナルを特定できますか？ プラットフォームに関する前提を検証しましたか？）により、答えられない質問ごとに深さが引き上げられます。深さを下げるには、感覚ではなく、根拠を示す必要があります。過剰な儀式も認められません。誤字に対する 7 段階の調査は、競合状態に対する当てずっぽうと同じく誤りです。

闇雲な再試行は決して行いません。 「成功するまでループ」するエージェント（Ralph-loop パターン）は粘り強さはあっても記憶がありません。失敗すると、元に戻して状態を消去し、再び試します。つまり、同じ誤った考えを、新たな確信を持って再試行します。inquisitor は代わりに失敗台帳を維持します。否定された仮説はすべて、それを否定した証拠とともに記録されます。再試行する際は、何が異なり、それによってなぜ結果が変わるのかを必ず明示します。同じ系統の仮説が 2 つ否定された場合は、必ず視点を切り替えます。前提を再監査する、問いを逆転させる、システムの境界を広げるなど、同じ考えを 3 回目に試すことはありません。記憶を伴う粘り強さ、証拠に基づく創造性です。

---

基礎

この手法の各ルールは、一次資料に基づいています。左列は出典、右列は inquisitor がそこから採用した具体的な仕組みです。

科学的方法

出典	採用した仕組み
Isaac Newton、Opticks、Query 31（1704）	調査の骨格：Analysis を Synthesis より先に行います。定義し、分解し、実験し、その後で初めて再構築します。締めくくりには、誤った確信ではなく、未解決の Query を提示します。Hypotheses non fingo.
T.C. Chamberlin、The Method of Multiple Working Hypotheses、Science（1890）	常に少なくとも二つの競合する説明を保ちます。単一の仮説では、その後の観察がすべて裏付けになってしまいます。
Abraham Luchins、Mechanization in Problem Solving（1942）—Einstellung 効果	失敗記録の発動条件です。慣れた方法が効かなくなった後も繰り返すのは、測定可能な固執です。その解決策は、もう一度試すことではなく、強制的に捉え直すことです。
Karl Popper、The Logic of Scientific Discovery（1959）	まず反証します。最有力の仮説について、それを否定する観察結果を挙げ、何よりも先にその結果を探します。
John Platt、Strong Inference、Science（1964）	お気に入りの仮説を裏付ける実験ではなく、仮説を排除する実験を設計します。確認テストよりも、仮説を識別するテストを優先します。
Richards J. Heuer、Psychology of Intelligence Analysis、CIA（1999）	競合仮説分析：それぞれの仮説について、証拠と矛盾する度合いで順位を付けます。裏付ける証拠を見つけるのは簡単で、通常は複数の仮説に当てはまります。
Gary Klein、Performing a Project Premortem、Harvard Business Review（2007）	リリース前に、修正を適用しても問題が起き続けると仮定します。最もありそうな理由を挙げ、今すぐ検証します。

エンジニアリングの規律

出典	採用した仕組み
Gerard J. Holzmann（NASA/JPL）、The Power of Ten: Rules for Developing Safety-Critical Code（2006）	P10 テンプレート：覚えられるほど小さく、機械的に検証できるほど厳格なルールセットです。
Andrej Karpathy の LLM コーディングガイドライン（2025）	コーディングの前に考える · シンプルさを優先する · 変更は必要な箇所に限定する · 目標に沿って実行する。
Ponytail の意思決定ラダー	YAGNI → 再利用 → 標準ライブラリ → ネイティブプラットフォーム → インストール済みの依存関係 → 1 行 → 動作する最小限のコード。

---

インストール

uv と Python 3.12 以降が必要です。

Claude Code — プラグインのインストール（推奨）

inquisitor は、スキルと MCP サーバーの両方をインストールする Claude Code プラグインとして提供されています。クローン、絶対パスの編集、手動でのシンボリックリンク作成は不要です。

Claude Code 内で、まずマーケットプレイスを追加します。

/plugin marketplace add iamalisson/inquisitor

次に、プラグインをインストールします。

/plugin install inquisitor@inquisitor

これで完了です。プラグインには inquisitor-mcp サーバー（${CLAUDE_PLUGIN_ROOT} 経由で自動登録）と inquisitor スキルが含まれています。初回起動時に uv がサーバーの依存関係を同期します。後で /plugin marketplace update inquisitor を実行して更新できます。

GitHub ではなくローカルのチェックアウトを指定しますか？/plugin marketplace add /path/to/inquisitor も使えます。

OpenCode や Claude Desktop（Claude Code のプラグインを使用しない場合）、または Claude Code を手動で設定する場合は、以下の手順を使用してください。

ステップ 1 — サーバーを取得する

オプション A — クローン不要（推奨）。 PyPI に公開されると、uvx が必要に応じて取得して実行するため、クローンも絶対パスも不要です。

uvx inquisitor-mcp   # prints a ready message and waits for a client — Ctrl+C to exit

以下の設定では、uvx inquisitor-mcp を直接指定します。

オプション B — チェックアウトから（ローカル開発の場合、または PyPI でのリリース前の場合）：

git clone https://github.com/iamalisson/inquisitor.git ~/tools/inquisitor
cd ~/tools/inquisitor
uv sync

クローン先は任意です。以下の設定では、同じ絶対パスを使用してください。JSON 設定ファイル内では ~ は展開されないため、完全なパスを記述してください（例：/home/you/tools/inquisitor）。

サーバーを手動で実行する必要はありません。これは stdio MCP サーバーです。エージェントが自動的に起動して管理します。（手動で実行すると、stderr に準備完了メッセージを出力した後、何も表示せずに待機します。これは正常です。）

ステップ 2 — MCP サーバーをエージェントに登録する

OpenCode — ~/.config/opencode/opencode.json（グローバル）または ./opencode.json（プロジェクトごと）に追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inquisitor": {
      "type": "local",
      "command": ["uvx", "inquisitor-mcp"],
      "enabled": true
    }
  }
}

Claude Code — プロジェクト内の .mcp.json、またはすべてのプロジェクトに適用する場合は ~/.claude.json に追加します。

{
  "mcpServers": {
    "inquisitor": {
      "command": "uvx",
      "args": ["inquisitor-mcp"]
    }
  }
}

Claude Desktop — claude_desktop_config.json の同じ mcpServers ブロックを使用します（Settings → Developer → Edit Config）。

uvx の代わりにチェックアウトを使用する場合は、コマンドを uv に変更し、引数に ["run", "--directory", "/home/you/tools/inquisitor", "inquisitor-mcp"] を指定します。

ステップ 3 — スキルをインストールする（動作レイヤー）

リポジトリの更新を反映できるよう、シンボリックリンクを作成します。

# OpenCode
mkdir -p ~/.config/opencode/skills
ln -s /home/you/tools/inquisitor/skills/inquisitor ~/.config/opencode/skills/inquisitor

# Claude Code
mkdir -p ~/.claude/skills
ln -s /home/you/tools/inquisitor/skills/inquisitor ~/.claude/skills/inquisitor

（フォルダーをコピーしてもかまいません。その場合は、更新後に再度コピーする必要があります。）

または、クローン不要 — skills CLI を使って、エージェント全体にスキルのみをインストールします。

npx skills add iamalisson/inquisitor

（これはスキルのみをインストールします。inquisitor_* ツールを使うには、ステップ 1〜2 の MCP サーバーも必要です。または、両方が含まれる上記の Claude Code プラグインを使用してください。）

ステップ 4 — エージェントを再起動する

設定は起動時に読み込まれます。OpenCode / Claude Code を終了して再度開き、次の点を確認してください。 ツール一覧に inquisitor_* ツールが表示され、inquisitor スキルが利用可能になっていることを確認します。

---

ツール

ツール	目的	使用する場面
inquisitor_search	コンテンツ抽出（HTML + PDF）に対応したマルチバックエンドのウェブ検索（DuckDuckGo の無料・キー不要の検索、Brave、SearXNG）	手元のエビデンスだけでは不十分な場合：未知のエラー、なじみのないライブラリ、最新のベストプラクティス
inquisitor_analyze	プロジェクトの概要：言語、フレームワーク、テスト、依存関係、Git 履歴	なじみのないコードベースに取り組むとき
inquisitor_trace	シンボルの追跡：定義、呼び出し元、呼び出し先を file:line 形式の参照とともに表示	バグが複数の関数／ファイルにまたがるとき
inquisitor_phase_get / _set	Newton の 7 フェーズ状態マシン。プロジェクトごとに SQLite で管理。前進時は一度に 1 フェーズ進み、後戻りのループは常に可能です	詳細な調査 — ターンをまたいで永続するメモリ
inquisitor_verify	完全性チェック：すべてのフェーズが記録されているか、エビデンスが引用されているか（矛盾や DEFINE の充足に関する意味的な検証は行わず、エージェントに委ねます）	詳細な調査を完了と宣言する前
inquisitor_scaffold	調査済みのベストプラクティスに基づく最小限のプロジェクト足場	新しいプロジェクトのセットアップ、要件を明確にした後

例：inquisitor_search

inquisitor_search(
    query="httpx ConnectTimeout retry pattern",
    max_results=8,
    time_range="year",              # day | week | month | year
    include_domains=["github.com"], # optional site: filter
    fetch_content=True,             # full page text, not just snippets
)

例：フェーズ追跡（詳細な調査）

inquisitor_phase_set(
    target_phase="experiment",
    findings="500 only occurs when session token > 4KB",
    evidence="repro script output; nginx.conf:34 large_client_header_buffers",
    open_questions="why did token size grow after v2.3 deploy?",
)

---

プロジェクト構成

inquisitor/
├── src/inquisitor/
│   ├── server.py                # MCP entry point (FastMCP, 6 tools)
│   ├── config.py                # env configuration
│   ├── tools/                   # thin MCP adapters
│   │   └── search / analyze / trace / scaffold / phase / verify
│   └── backend/                 # pure Python, zero MCP dependency
│       ├── search.py            # DDG / Brave / SearXNG + re-ranking
│       ├── extract.py           # trafilatura → readability fallback, SSRF guard
│       ├── analyzer.py          # project structure scan
│       ├── tracer.py            # callers / callees mapping
│       └── phase_tracker.py     # Newton state machine (SQLite)
├── skills/inquisitor/SKILL.md   # behavioral layer for the agent
├── .claude-plugin/
│   ├── plugin.json              # Claude Code plugin manifest
│   └── marketplace.json         # self-hosted marketplace (source ".")
├── .mcp.json                    # bundled MCP server (${CLAUDE_PLUGIN_ROOT})
└── tests/                       # 36 tests

backend/ パッケージは単独でインポートできます。MCP は不要です。

from inquisitor.backend.search import search
results = search("python asyncio best practices", max_results=5)

---

環境変数

変数	必須	デフォルト	説明
INQUISITOR_SESSION_DIR	いいえ	~/.inquisitor/sessions/	調査状態の保存先
BRAVE_API_KEY	いいえ	—	Brave Search バックエンド（月あたり 2,000 回まで無料）
SEARXNG_URL	いいえ	—	セルフホストの SearXNG インスタンス
INQUISITOR_DEFAULT_ENGINE	いいえ	ddg	ddg | brave | searxng
INQUISITOR_SEARCH_TIMEOUT	いいえ	15	HTTP タイムアウト（秒）
INQUISITOR_MAX_CONTENT_LENGTH	いいえ	40000	取得するページごとの最大文字数
INQUISITOR_PREFERRED_DOMAINS	いいえ	—	ランキングで優先するドメイン（カンマ区切り）
INQUISITOR_PDF_BACKEND	いいえ	auto	PDF 抽出：auto | docling | pypdf

API キーは不要です。DuckDuckGo はすぐに使用できます。

PDF の抽出

検索結果や取得した URL が PDF（RFC、仕様書、論文、データシート）の場合、スキップせずに内容を抽出します。デフォルトのポリシーは auto です。docling がインストールされていて GPU が利用可能な場合を除き、pypdf（純粋な Python 製で高速、モデル不要、テキスト PDF に対応）を使用します。 複雑な表や、スキャン／OCR された PDF を扱う場合は、オプションの docling バックエンドをインストールしてください。

uv pip install "inquisitor-mcp[docling]"   # or: pip install "inquisitor-mcp[docling]"

docling はサイズが大きく（torch と ML モデルをインストールします）、CPU では処理も遅いため、auto は docling がインストールされ、かつ GPU が利用可能な場合にのみ使用します。それ以外の場合は pypdf にフォールバックします。INQUISITOR_PDF_BACKEND=docling を指定すると強制的に使用できます（CPU でも動作しますが、速度は遅くなります）。または INQUISITOR_PDF_BACKEND=pypdf を指定して pypdf に固定できます。docling でエラーが発生した場合は pypdf にフォールバックするため、PDF の読み取りで処理が完全に失敗することはありません。

---

セキュリティ

• SSRF ガード：コンテンツ取得では、http(s) 以外のスキームや、ループバック／プライベート／リンクローカル／メタデータの宛先（localhost、127.0.0.1、10.x、192.168.x、169.254.169.254、…）を拒否します。
• パストラバーサルガード：ファイルシステムにアクセスする前に、セッション名をサニタイズします。
• シェル実行なし：サブプロセスの呼び出しでは引数リストを使用し、shell=True は使用しません。
• セッションストア全体で、パラメーター化 SQL を使用しています。
• サーバーはユーザーの権限で stdio を介してローカル実行され、ネットワーク上では待ち受けません。

---

関連スキル

inquisitor は調査ツールであると同時にルーターでもあります。適した専用スキル（/tdd、/code-review、…）があれば処理を委任しますが、スキルをインストールすることはありません。inquisitor と一緒にインストールする価値のある厳選スキル（mattpocock/skills、spec-kit、last30days、ponytail、gstack）と設計資料については、docs/companion-skills.md をご覧ください。

---

開発

uv sync                  # install deps
uv run pytest tests/ -v  # run tests
uv run ruff check .      # lint

技術

• uv — パッケージマネージャー
• FastMCP — MCP サーバーのフレームワーク
• ddgs / httpx — 検索 + HTTP
• trafilatura + readability-lxml — コンテンツ抽出（2 段階のフォールバック）
• SQLite — 調査状態
• pytest / ruff — テストとリンティング

---

謝辞

調査資料は Foundations に記載しています。実装では、さらに次のプロジェクトを活用しています。

• andrej-karpathy-skills (forrestchang) — LLM によるコーディングの落とし穴に関する Andrej Karpathy の考察 に基づく行動ガイドラインです。
• ponytail (Dietrich Gebert) — 意思決定の段階的手順と、経験豊富な開発者としての規律です。
• last30days-skill (mvanhorn) — 複数の情報源を用いた調査設計と、SKILL.md を契約として扱うパターンの着想元です。

MIT ライセンスの下で公開されています。