Deadends.dev

🚀 deadends.dev

AIコーディングエージェント向けの構造化された失敗知識です。

51のドメインにまたがる2000以上のエラーエントリがあります。AIコーディングエージェントがエラーに遭遇すると、既知の失敗アプローチにトークンを浪費します。deadends.devはエージェントに試すべきではないこと、実際に機能すること、次に発生するエラーを教えます。

ウェブサイト: deadends.dev · MCPサーバー: Smithery · PyPI: deadends-dev · API: /api/v1/index.json

🚀 クイックスタート

このセクションでは、deadends.devの基本的な使い方を紹介します。

✨ 主な機能

• 51のドメインにまたがる2000以上のエラーエントリを提供します。
• AIコーディングエージェントに試すべきではないこと、実際に機能すること、次に発生するエラーを教えます。
• MCPサーバーを通じて8つのツールを提供します。

📦 インストール

pip install deadends-dev

必要条件: Python 3.10+

💻 使用例

基本的な使用法

from generator.lookup import lookup, batch_lookup, search

# 単一のエラー検索
result = lookup("ModuleNotFoundError: No module named 'torch'")

# 試すべきではないこと (トークンと時間を節約)
for d in result["dead_ends"]:
    print(f"AVOID: {d['action']} — fails {int(d['fail_rate']*100)}%")

# 実際に機能すること
for w in result["workarounds"]:
    print(f"TRY: {w['action']} — works {int(w['success_rate']*100)}%")

# result["url"] は正規の要約ページのURLです (例: /python/modulenotfounderror/)
print(result["url"])

# バッチ検索 (複数のエラーを一度に)
results = batch_lookup([
    "ModuleNotFoundError: No module named 'torch'",
    "CUDA error: out of memory",
    "CrashLoopBackOff",
])

# キーワード検索
hits = search("memory limit", domain="docker", limit=5)

高度な使用法

pip install deadends-dev
deadends "CUDA error: out of memory"
deadends --list  # すべての既知のエラーを表示

📚 ドキュメント

MCPサーバー

MCPサーバーは、AIコーディングエージェント向けに8つのツールを公開しています。

ローカル (Claude Desktop / Cursor)

~/.claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "deadend": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/deadends.dev"
    }
  }
}

ホスト型 (Smithery — ローカル設定不要)

Smithery を通じてインストールします。

# Claude Code
npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

# Cursor
npx -y @smithery/cli@latest install deadend/deadends-dev --client cursor

または直接接続します: https://server.smithery.ai/deadend/deadends-dev

応答例

エージェントが ModuleNotFoundError: No module named 'torch' に遭遇した場合、lookup_error ツールは次のような応答を返します。

## ModuleNotFoundError: No module named 'X' (Python 3.11+)
Resolvable: true | Fix rate: 0.88

### Dead Ends (DO NOT TRY):
- pip install X with system Python (fails 70%): venv not activated

### Workarounds (TRY THESE):
- Create venv, activate, then pip install (works 95%)
- Use python -m pip install instead of bare pip (works 90%)

APIエンドポイント

対象ドメイン (51)

ErrorCanonデータ形式

各エラーは次のようなJSONファイルです。

{
  "error": { "signature": "...", "regex": "...", "domain": "..." },
  "verdict": { "resolvable": "true|partial|false", "fix_success_rate": 0.88 },
  "dead_ends": [{ "action": "...", "why_fails": "...", "fail_rate": 0.75 }],
  "workarounds": [{ "action": "...", "success_rate": 0.92, "how": "..." }],
  "transition_graph": { "leads_to": [...], "preceded_by": [...] }
}

AIコーディングエージェントの統合 — 18の検出形式

deadends.devのすべてのページには、18の形式で機械可読データが含まれています。

🔧 技術詳細

開発

pip install -e ".[dev]"

# 全パイプライン (検証 → 生成 → ビルド → テスト)
python -m generator.pipeline

# 個別のステップ
python -m generator.bulk_generate     # シードからキャノンを生成
python -m generator.build_site        # 静的サイトをビルド
python -m generator.validate          # データ + サイトを検証
python -m pytest tests/ -v            # テストを実行

コントリビュート

エラー定義を generator/bulk_generate.py に追加するか、data/canons/ 内に直接JSONファイルを作成します。

python -m generator.validate --data-only  # 提出前に検証

変更履歴

v0.7.0

• 51のドメインにまたがる2089のエラーエントリに拡張されました (以前は1028/20)。
• 23の新しいドメインが追加されました: Android, API, Cloud, CMake, Communication, Data, Elasticsearch, Embedded, Flutter, gRPC, Hugging Face, Kafka, LLM, MongoDB, Nginx, OpenCV, Policy, PyTorch, Redis, ROS 2, Security, TensorFlow, Unity。
• すべてのドメインに40以上のエラーエントリが含まれるようになりました。
• 73の正規表現パターンが修正され、自らのシグネチャと一致するようになりました。

v0.5.0

• index.json、errors.ndjson、およびすべてのSDK/MCP応答に page_url フィールド が追加されました — 常に正規の要約ページ (/domain/slug/) を指し、環境固有の url フィールドとは異なります。
• Lookup SDK の url 戻り値が、環境固有のページではなく正規の要約ページを指すようになりました。
• MCPツール (match_error、get_error_detail) が正規の要約URLを返すようになりました。
• SEO修正: Atomフィード、IndexNow送信、JSON-LD TechArticle、およびOpen Graphタグがすべて正規の要約URLを使用するように修正されました。
• HTMLテンプレート内の エラーチェーンリンク が、noindex環境ページではなく要約ページを指すように修正されました。

v0.4.0

• 20のドメインにまたがる1028のエラーエントリを含む初期公開版。

📄 ライセンス

MIT (コード) · CC BY 4.0 (データ)