deadends.dev

deadends.dev

AI エージェントが、コードでも現実世界でも、既知の失敗を繰り返さないようにします。

AI アシスタントは、既知の失敗に終わったコード修正と、トレーニングで一度も触れたことのない、国ごとの現実世界のルールという、2 種類の問題で確実につまずきます。deadends.dev は、その両方に対応するようになりました。

• コードエラー（51 ドメインに 2,089 件）：エージェントが ModuleNotFoundError、CUDA OOM、CrashLoopBackOff などに遭遇したとき、試してはいけないこと。
• 国別の行き止まり情報（52 か国に 250 件以上）：ビザのルール（ETA/eVisitor、NZeTA、電子ビザ、到着カード）、銀行の要件、法的な一線（不敬罪、§86a、第 301 条）、文化的タブー（ご飯に箸を立てる、中国で時計を贈る、韓国で名前を赤字で書く）、食品の安全性（国別の水道水の安全性）、緊急電話番号、運転の習慣（左側通行）、住宅契約など、もっともらしい世界共通の回答が、現地では誤りとなるあらゆる摩擦に対応します。

なぜ対象を拡大したのですか？ コーディングに関する行き止まりの多くは、優れた LLM で解決できます。 日本の印鑑要件、シェンゲン協定の 90/180 日計算、ラマダン中の営業時間、サウジアラビアの禁酒、インドの牛肉に関するタブーなど、国ごとの摩擦こそ、一般的な AI のアドバイスがもっとも大きく破綻する領域です。コードベースとスキーマは同一で、env セグメントに国コードが入るだけです。

Precision@1 90% · MRR 0.935 · データ品質ダッシュボード

ウェブサイト： deadends.dev · MCP サーバー： Smithery · PyPI： deadends-dev · API： /api/v1/index.json リポジトリ： https://github.com/dbwls99706/deadends.dev

これを使う理由

deadends.dev を使わない場合	deadends.dev を使う場合
エージェントが sudo pip install を試す → システムの Python を壊す → 3 回の再試行を無駄にする	エージェントは「行き止まり：sudo pip - 70% の確率で失敗」と認識 → すぐに回避する
エージェントが東京のレストランで 15% のチップを払うようユーザーに伝える	エージェントは日本ではチップが断られると認識する（culture/tipping-refused/jp）
エージェントがタイの SNS 投稿にラーマ 10 世国王に言及する文面を作成する	エージェントが停止する：不敬罪の第 112 条に抵触するリスク（legal/lese-majeste-article-112/th）
エージェントがエラー A を修正し、エラー B で混乱する	エージェントは「78% の確率で A が B につながる」と認識 → 両方に対処する
エージェントが未婚のカップルに、ドバイで人前でキスするよう勧める	エージェントが UAE の公序良俗法に関する警告を表示する（legal/unmarried-public-affection/ae）

LLM に尋ねるのとは何が違うのでしょうか？

• 決定論的：同じクエリには毎回同じ回答が返ります。ハルシネーションはありません。
• 国別対応：ID 形式は {domain}/{slug}/{env} です。env には国コード（kr、jp、us、de...）が入り、同じタブーでも法域に応じて異なる回答を返せます。
• 一次情報源に基づく：国別の各情報には、政府のウェブサイト、大使館、または検証可能な報道への引用があります。「一般知識に基づく」回答はありません。
• コミュニティによる検証：実際の結果報告に基づいて、修正の成功率が更新されます。
• 1 ミリ秒未満：ローカルでの正規表現マッチングを行うため、API への往復はありません。

現実的な限界（運用の観点）

• すべてのエラーを網羅しているわけではありません。未対応のケースは、イシュー／PR／report_outcome で速やかに補完します。
• 説明の詳しさよりも、実践的な解決を優先（行き止まり／回避策を中心）する設計です。
• 信頼性はドメインやケースによって異なるため、リスクの高い変更は公式ドキュメントやベンダーガイドとの照合を推奨します。

クイックスタート（30秒）

pip install deadends-dev
deadends "CUDA error: out of memory"

MCP サーバー（Claude Desktop / Cursor）

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

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

または、Smithery からインストールできます（ローカルでの設定は不要です）：

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

MCP Unauthorized のクイック解決ガイド（ユーザー向け）

deadend: calling "initialize": sending "initialize": Unauthorized エラーが表示された場合は、以下を順番どおりに実行／確認してください。

1. ローカルサーバーモードかリモート（Smithery）モードのどちらか一方だけを使用します

# 로컬 서버 확인 (정상 시 툴 목록이 출력됨)
python -m mcp.server --help

2. Claude Desktop の設定ファイルを確認します（cwd は実際のパスである必要があります）

cat ~/.claude/claude_desktop_config.json

3. ローカルサーバーを直接実行してテストします

cd /path/to/deadends.dev
python -m mcp.server

4. Smithery モードの場合は再インストールします（トークンや設定の不整合を解消します）

npx -y @smithery/cli@latest uninstall deadend/deadends-dev --client claude
npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

5. 最後に Claude Desktop を完全に再起動します

# macOS 예시
osascript -e 'quit app "Claude"'
open -a Claude

ヒント：Unauthorized は通常、誤った cwd、サーバー設定の重複（ローカルとリモートの同時設定）、または認証状態の期限切れが原因で発生します。

Antigravity（Google AI IDE）

認証は不要です。リモート MCP サーバーとして追加します：

{
  "mcpServers": {
    "deadend": {
      "serverUrl": "https://deadends.dev/mcp",
      "type": "http"
    }
  }
}

注： Antigravity では url ではなく serverUrl を使用します。Unauthorized が発生する場合は、MCP Store にある既存の deadend エントリを削除し、上記の設定を使って手動で再追加してください。一般的なトラブルシューティングについては、Antigravity MCP 認証ガイドを参照してください。

Python SDK

from generator.lookup import lookup, batch_lookup, search

# Single error lookup
result = lookup("ModuleNotFoundError: No module named 'torch'")

# What NOT to try (saves tokens and time)
for d in result["dead_ends"]:
    print(f"AVOID: {d['action']} - fails {int(d['fail_rate']*100)}%")

# What actually works
for w in result["workarounds"]:
    print(f"TRY: {w['action']} - works {int(w['success_rate']*100)}%")

# Batch lookup (multiple errors at once)
results = batch_lookup(["error1", "error2", "error3"])

応答例

## 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%)

MCP ツール（11）

ツール	説明
lookup_error	エラーメッセージを既知の 2000 件以上のパターンと照合します
get_error_detail	ID を指定して完全な canon を取得します
list_error_domains	件数付きで 54 の全ドメインを表示します
search_errors	全ドメインを対象に TF-IDF キーワード検索を行います
list_errors_by_domain	指定したドメインのすべてのエラーを表示します
list_errors_by_country	ISO alpha-2 コードに対応する、国別のすべての行き止まりを表示します
get_country_summary	国単位の概要（エントリ数、修正率、ドメイン構成）を取得します
batch_lookup	複数のエラーを一度に検索します（最大 10 件）
get_domain_stats	ドメインの品質指標と信頼度を取得します
get_error_chain	エラー遷移グラフをたどります
report_outcome	回避策が機能したかどうかを報告します（成功率に反映されます）

API エンドポイント

エンドポイント	説明
/api/v1/match.json	軽量な正規表現マッチング（コンテキストウィンドウに収まります）
/api/v1/index.json	メタデータ付きのエラーインデックス全体（エントリには国別 canon を示す country フィールドが含まれます）
/api/v1/{id}.json	個別の ErrorCanon
/api/v1/countries.json	件数と更新日を含む国別インデックス
/api/v1/country/{cc}.json	国別集約データ（1 回の呼び出しですべてのエントリを取得します）
/api/v1/openapi.json	OpenAPI 3.1 仕様
/api/v1/stats.json	ドメイン別のデータセット品質指標
/api/v1/errors.ndjson	NDJSON ストリーミング
/llms.txt	LLM 向けに最適化された一覧（llmstxt.org）
/dashboard/	データ品質ダッシュボード

対応ドメイン（54）

コードエラーの分野（51）

分野	エラー数	例
Python	88	ModuleNotFoundError、TypeError、KeyError、MemoryError、RecursionError
Node	70	ERR_MODULE_NOT_FOUND、EACCES、EADDRINUSE、ヒープ OOM、ERR_REQUIRE_ESM
Docker	65	空き容量不足、実行形式エラー、バインド先アドレスが使用中、ヘルスチェック
Kubernetes	61	CrashLoopBackOff、ImagePullBackOff、OOMKilled、RBAC による拒否、HPA
Git	60	プッシュ失敗、マージ競合、detached HEAD、stash apply、タグ
CUDA	57	OOM、デバイス側アサート、NCCL、cuDNN、テンソルのデバイス不一致
Go	54	nil ポインター、未使用のインポート、インターフェース変換、スライスの範囲外アクセス
Java	54	NullPointerException、ClassNotFound、OutOfMemoryError、コネクションプール
Database	52	デッドロック、コネクションプール、遅いクエリ、レプリケーションの遅延
AWS	51	AccessDenied、S3 NoSuchBucket、Lambda のタイムアウト、CloudFormation のロールバック
.NET	50	NullReferenceException、LINQ の変換、DI の循環参照、EF の同時実行性
ROS 2	50	ノードのスピン、起動エラー、QoS の不一致、tf2 の変換
TypeScript	49	TS2307、TS2322、TS2345、TS2532、TS7053
Rust	48	E0382 の借用、E0308 の不一致、E0277 のトレイト、E0106 のライフタイム
その他 37 分野	各 40 以上	CI/CD、PHP、Terraform、Networking、Next.js、React、pip、Android、...

国ごとの実世界の分野（新規、拡大中）

分野	対象範囲	典型的な行き詰まり例
visa	渡航前の認可、オーバーステイ、再入国禁止	ESTA の 90 日ルール（US）、K-ETA（KR）、ETIAS/EES（シェンゲン）、シェンゲンの 90/180 日ルール（DE）
banking	口座開設、KYC、外国人向けルール	ARC が必要（KR）、在留カードの 6 か月要件（JP）、SSN/ITIN（US）
emergency	正しい緊急電話番号、交通機関	112 は 911 ではない（DE）、999/101/111（UK）
medical	保険、処方薬の持ち込み、補償範囲	社保／国保（JP）、NHIS の 6 か月要件（KR）、EHIC の対象外（DE）、Adderall の持ち込み禁止（JP）
legal	刑事責任、契約慣行	ナチスのシンボルに関する §86a（DE）、第 112 条（TH）、第 301 条（TR）、飲酒禁止（SA）、権利金（JP）
culture	エチケット、タブー、社会規範	ご飯に箸を立てる（JP）、時計を贈る（CN）、天安門について触れないこと、赤インクで名前を書くこと（KR）、bonjour（FR）
food-safety	水、病原体、宗教上のタブー	水道水（MX）、フグの免許（JP）、インドの牛肉、インドネシアの豚肉
communication	言葉遣い、用語	敬語（KR）、American War の捉え方（VN）、'gringo'（MX）、広東語と標準中国語の違い（HK）
safety	運転、公共の安全に関する規範	左側通行（JP）、アウトバーンの規則（DE）、クラクションの使い方（IN）

データ品質

すべての指標は、データ品質ダッシュボードで公開されています。

• 2,204 件のカノン項目を 54 分野、39+ か国にわたって収録
• ベンチマーク：Precision@1 90%、Precision@3 95%、MRR 0.935（コードのシナリオが対象）
• エラー遷移グラフ：関連エラーをつなぐエッジが 4,330 件以上
• コミュニティフィードバックループ：report_outcome により、実際の利用状況に基づいて修正成功率を更新
• 各国のカノン：各項目には政府／大使館／規制当局の一次情報源を明記し、人間がレビュー済み（review_status: human_reviewed）。LLM による一括生成はありません

国別の対応状況（v0.10 時点で 52 か国）

kr · jp · us · de · uk · fr · it · es · nl · ch · pt · ie · at · be · se · no · dk · fi · pl · gr · cn · hk · tw · th · in · vn · id · sg · ph · my · pk · bd · sa · ae · tr · il · ru · br · mx · ar · cl · co · pe · au · nz · eg · ma · et · ng · ke · za · ca

件数を含む正式な一覧は、/country/ ハブまたは /api/v1/countries.jsonを参照してください。

執筆ワークフロー、情報源の要件、信頼度の調整については、 docs/country-canon-guide.mdを参照してください。

貢献

詳細については、CONTRIBUTING.md をご覧ください。

• GitHub 自動収集の運用方針：docs/GITHUB_DATA_COLLECTION_STRATEGY.md

• 自動収集の頻度：6時間ごと（1日4回）、基本品質フィルター：min_score=2

• 収集データは候補であり、最終的な反映はメンテナーによる確認後に行います

• 新しいエラーを送信する

• 回避策の結果を報告する

• 回避策を試した後、MCP 経由で report_outcome を使用してください

開発

pip install -e ".[dev]"

python -m generator.pipeline          # Full pipeline
python -m generator.build_site        # Build static site
python -m generator.validate          # Validate data + site
python -m pytest tests/ -v            # Run tests
ruff check generator/ tests/          # Lint
python benchmarks/run_benchmark.py    # Run benchmarks

SEO チェックガイド（すべてのページ共通）

以下のコマンドを使うと、テンプレートに主要な SEO シグナルが含まれているかをすばやく確認できます。

python - <<'PY'
from pathlib import Path
files=[
  'generator/templates/index.html',
  'generator/templates/domain.html',
  'generator/templates/error_summary.html',
  'generator/templates/page.html',
  'generator/templates/search.html',
  'generator/templates/dashboard.html',
]
required=[
  '<title',
  'meta name="description"',
  'meta name="robots"',
  'link rel="canonical"',
  'meta property="og:title"',
  'meta name="twitter:card"',
]
for f in files:
    txt=Path(f).read_text()
    missing=[r for r in required if r not in txt]
    print(f'✅ {f}' if not missing else f'❌ {f} missing: {", ".join(missing)}')
PY

実際のビルド成果物まで確認するには：

python -m generator.build_site
python -m http.server -d public 8080

その後、ブラウザーで以下を確認します：

• view-source:http://localhost:8080/search/
• view-source:http://localhost:8080/dashboard/
• canonical / og / twitter / JSON-LD の有効性

変更履歴

v0.10.0 - 国別の対応範囲を拡大

• 52か国にわたる250件以上の国別カノン（20か国の56件から増加）：ほぼすべての対応国の緊急連絡先、最新のビザ申請窓口（ETA/eVisitor、NZeTA、電子ビザ、デジタル入国カード）、医薬品の持ち込み規則、水道水の安全性、左側通行の安全性、銀行の利用に関する情報を収録。すべて一次資料に基づき、人手でレビュー済みです
• 目的地別の相互リンク：国別概要ページから、同じ国に関する他のドメインの行き詰まりページへリンクするようになりました（「{country} のその他の行き詰まり」セクション）。これにより、トピックに関連する内部リンクが強化されます
• SEO：サイトマップの <priority> はページの強さに応じて重み付けされます（国別ページや根拠の充実したページを上位に設定）。JSON-LD では空の日付を省略します
• スタイル：サイト全体で em ダッシュをハイフンに置き換えました

v0.9.0 - 国別情報への展開

• 新しい軸：コードエラーに加え、国別の現実世界の行き詰まりを追加
• 20か国以上にわたる56件以上の国別カノン：ビザ、銀行、法律上の禁止事項、文化的タブー、食品の安全性、緊急連絡先、運転習慣
• 新しいドメインを3つ追加：visa、banking、emergency（既存の legal、culture、medical、communication、food-safety、safety ドメインも国別の env セグメントで拡張）
• 国別ランディングページを /country/{cc}/ に追加（例： /country/jp/）
• 新しい国別カノンを作成するための generator.country_canon_template ヘルパーを追加。env セグメント、audience、jurisdiction のメタデータを検証します
• docs/country-canon-guide.md：情報源の基準（一次資料 > 大使館 > 信頼できるメディア）、確信度の調整、slug/regex の規則を記載
• スキーマは変更なし（後方互換性のある enum 拡張）。既存の2,089件のコードカノンは維持

v0.8.0

• ベンチマークスイート：20のエラーシナリオ、Precision@1=90%、MRR=0.935
• データ品質ダッシュボードを /dashboard/ に追加 - 指標を透明化
• 結果のフィードバックループ：report_outcome → 統計の集計 → fix_success_rate の更新
• 利用状況の分析：匿名のツール使用状況を追跡（ドメイン／マッチのみ、PII なし）
• コミュニティからの貢献：新しいエラーや回避策の報告用 GitHub Issue テンプレート
• TF-IDF 検索：IDF スコアリングの平滑化により関連性を改善
• エラー遷移グラフ：4,330件以上のエッジを含むマテリアライズドグラフとハブノード分析
• MCP ツールを9つ追加（report_outcome を追加）

v0.7.0

• 51ドメインにわたる2,089件のエラー項目に拡大（1,028件／20ドメインから増加）
• 新しいドメインを23個追加
• 独自のシグネチャに一致しなかった正規表現パターンを73件修正

v0.5.0

• page_url フィールドを index.json、errors.ndjson、およびすべての SDK/MCP レスポンスに追加
• canonical 概要 URL の SEO を修正

v0.4.0

• 20ドメインにわたる1,028件のエラー項目を含む初回公開リリース

ライセンス

MIT（コード） · CC BY 4.0（データ）

運用ドキュメント

• SEO 運用ガイド：docs/SEO_OPERATIONS_GUIDE.md
• PyPI リリースマニュアル：docs/PYPI_RELEASE_MANUAL.md