camunda-docs

Camunda ドキュメント検索

ユーティリティスキル：出典に基づいて Camunda ドキュメントを取得し、実装作業を専門スキルに引き継ぎます。

次の用途には使用しないでください：

BPMN、DMN、フォーム、コネクターの作成や、プロセスインスタンスのデプロイと運用には、このスキルを使用しないでください。バージョンによって異なる事実をここで確認した後、該当する Camunda スキルに作業を引き継いでください。

docs.camunda.io を検索する方法は2つあり、それぞれ得意分野が異なります。質問の内容に応じて使い分け、両方とも利用できない場合に限り llms.txt に切り替えてください。

方法	仕組み	適している用途	返される内容
camunda-docs MCP	ドキュメントとその他の Camunda ナレッジソースに対するセマンティック検索（ベクトル検索）	概念的な質問や曖昧な質問、正確な用語が分からない場合、すぐに読めるチャンクが必要な場合	ソース URL 付きの上位 k 件の Markdown チャンク
Algolia DocSearch	従来型の語彙検索（docs.camunda.io の検索ボックスで使われているものと同じインデックス）	用語が分かっている場合、バージョンを指定した結果（8.7、8.9、next）が必要な場合、ランキングされたページ一覧を絞り込みたい場合	タイトル、階層、スニペットを含むランキング順のページ。全文を読むにはページを取得してください
llms.txt / llms-full.txt	静的なテキストインデックス／コーパス	どちらのサービスにも接続できない場合のオフラインでの代替手段	プレーンテキスト。ローカルで grep できます

迷った場合は、両方の主要な方法を並行して使ってください。コストが低く、異なる関連ページが見つかることもよくあります。

camunda-docs MCP サーバー

camunda-docs MCP サーバー（HTTP トランスポート、https://camunda-docs.mcp.kapa.ai）に接続されている場合は、ナレッジ検索ツールを使い、自然言語で簡潔かつ適切な一文を入力してください（このツールはキーワードではなく、完結した文を必要とします）。

接続されていない場合は、今後の質問に備えてサーバーを一度設定するよう提案してください。この会話ですでに提案している場合は、再度提案する必要はありません。ハーネスに記載された MCP 設定手順に従い、https://camunda-docs.mcp.kapa.ai に HTTP サーバーを追加してください。VS Code Copilot、Cursor、その他の汎用 MCP クライアントについては、リファレンスを参照してください。初回利用時は Google でのサインインが必要です。ユーザーあたり1時間に40リクエスト、1日に200リクエストまでです。CI には使用できません。

Algolia DocSearch

公開 Algolia DocSearch エンドポイントを利用する bash ラッパーは、 $CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh にあります。実行する前に、 CAMUNDA_DOCS_SKILL_DIR をインストール済みの camunda-docs ディレクトリに設定してください。

"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "<query>" [--version stable|next|<major>.<minor>|all] [--limit N]

デフォルトの --version stable は、インデックス内の最も大きい数値のバージョンに解決されるため、9.0 のリリース後も引き続き動作します。デフォルトの --limit は 10 です。JSON が返されます。

{
  "query": "...",
  "version": "stable",
  "algolia_version": "8.9",
  "total": 5,
  "total_matching": 25,
  "hits": [
    { "url": "...", "hierarchy": "...", "title": "...", "snippet": "..." }
  ]
}

• total — このレスポンスに含まれるヒット数。
• total_matching — ページネーションや重複排除を行う前に、インデックス内でクエリに一致したページの実数です。「この用語はどの程度広く出現するか」を調べる際に役立ちます。
• algolia_version — インデックスに送信された version ファセットの値（例："8.9"、"current"）。--version all モードでは（ファセットフィルターが適用されないため）null です。

検索の流れ

1. バージョンを選択します（下の表を参照）。デフォルトは stable です。
2. スクリプトをまず --limit 5 で、1行で実行します（\ による行継続は使用しないでください。対話型シェルが停止することがあります）。各ヒットはタスクの残りの間ずっとコンテキストに保持されるため、最初のページで見つからなかった場合に限り、上限を増やしてください。
3. ヒットを確認します。それぞれに url、hierarchy、title、snippet が含まれています。
4. 最も関連性の高いページを URL から直接取得し、文脈全体を読んでください。スニペットは短いため、詳細が必要な質問では、それだけを根拠に回答しないでください。
5. 結果が不十分な場合は検索を絞り込みます。下記の絞り込み方法を参照してください。

バージョンの扱い

Camunda のドキュメントは URL パスでバージョン管理されています。Algolia の version ファセットではそれらのバージョンを指定できます。フィルタリングしない場合、同じページがバージョンごとに 3〜4 回返され、結果が煩雑になります。

フラグの値	Algolia ファセット	URL プレフィックス	使用する場面
stable（デフォルト）	最大の数値（例：8.9）	/docs/	バージョンの指定がない一般的な質問
next	current	/docs/next/	今後リリース予定の動作、アルファ機能
8.8 / 8.7 / など	一致する数値	/docs/8.8/ など	特定世代の顧客／クラスターについて
all	（なし）	任意	バージョンの比較。URL のルート部分で重複排除し、ページごとに関連性が最も高いバージョンの結果を採用

明示的に選択する場面：

• 既知の世代を使用する特定の顧客／クラスターについての質問 → そのバージョンを使用します。
• 今後追加される機能、アルファ機能、または「これは 8.10 で変更されますか？」についての質問 → stable と next を並行して実行し、比較します。
• バージョンに依存しない質問（概念、BPMN のセマンティクス、一般的な API の形状） → stable で問題ありません。

--version all モードでは、スクリプトは多めに取得します（--limit の 4 倍、最大 100 件）。これにより、URL のルート部分で重複排除した後も、--limit に近い数の一意なページが応答に含まれます。重複排除では Algolia の関連性順を維持します。一意な URL のルート部分ごとに最初の結果を採用し、その後 --limit 件に絞り込みます。

例

シェルはインストールされたスキルのディレクトリではなく、ユーザーのプロジェクトディレクトリから開始します。ラッパーを実行する前に CAMUNDA_DOCS_SKILL_DIR をインストール済みの camunda-docs ディレクトリ（この SKILL.md があるディレクトリ）に設定するか、 ホストアダプターでその値を指定してください。

# Default — latest stable
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "zeebe gateway long polling timeout"

# Specific version (customer on 8.7)
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "task assignment" --version 8.7

# Upcoming behavior
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "agentic connectors" --version next

# Compare across versions (deduped by URL stem)
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "decision evaluation API" --version all --limit 15

検索の絞り込み方

最初のクエリで役立つ結果が得られない場合：

• 広すぎる → 関係のない結果が多すぎる：コンポーネント、エラーコード、設定キーなどの詳細を追加します。
• 狭すぎる → 結果がない：形容詞を削除し、正式な製品用語を試します（例："task UI" ではなく "Tasklist"、"workflow engine" ではなく "Zeebe"）。
• バージョンが違う：--version all を試してその用語が別のバージョンに存在するか確認し、適切なリリースに絞り込みます。
• 同義語：別の名称を試します。例："Operate" ↔ "process monitoring"、"Optimize" ↔ "analytics"。

絞り込みは 2〜3 回までにしてください。それでも見つからない場合は MCP の方法に切り替えるか、情報が見つからなかったことをユーザーに伝えてください。

認証情報は不要です

Algolia の検索専用 API キーは公開されています。Algolia は docs.camunda.io のブラウザー JS バンドルにこのキーを含めているため、すべての訪問者がすでに利用できます。安全にコミットできる理由を説明するコメントとともに、"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" の先頭にハードコードされています。認証情報や API 環境変数は不要で、ラッパーは CI でも安全に使用できます。

ラッパースクリプトを使わない場合

"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" を実行できない、または実行したくない場合（例：jq がない、サンドボックスの制限がある、生の API が必要なだけの場合）は、Algolia エンドポイントを直接呼び出してください。

curl -sS -f -X POST \
  "https://6KYF3VMCXZ-dsn.algolia.net/1/indexes/camunda-v2/query" \
  -H "X-Algolia-API-Key: 68db7725a8410eace68419c29385ad1e" \
  -H "X-Algolia-Application-Id: 6KYF3VMCXZ" \
  -H "Content-Type: application/json" \
  -d '{"query":"YOUR QUERY","hitsPerPage":10,"facetFilters":[["version:8.9"]]}'

必要なバージョンに合わせて version: ファセットを指定してください（next の場合は current を指定し、all の場合は facetFilters を完全に省略します）。応答は Algolia の生のヒットデータです。各ヒットで役立つフィールドは url、hierarchy.lvl0..lvl5、content です。curl も利用できない場合は、JSON を POST できる任意の HTTP クライアント（Python の urllib、Node の fetch、PowerShell の Invoke-RestMethod）を使用してください。エンドポイント、ヘッダー、本文は同じです。スニペットに含まれる認証情報は意図的に公開されています（上記「認証情報は不要」を参照）。

フォールバック：llms.txt（ドキュメントのインデックス）

MCP も Algolia も使えない場合は、https://docs.camunda.io/llms.txt（約 540 KB）を取得してください。これは、Camunda 8 のすべてのドキュメントページについて - [Title](url): description. 形式の行を含むインデックスです。ファイル全体をコンテキストに読み込まないでください。 ローカルにキャッシュし、検索語で該当する URL を見つけてから、そのページを直接取得してください。

最終手段：llms-full.txt（ドキュメント全体）

llms.txt で必要な情報が見つからない場合に限り、https://docs.camunda.io/llms-full.txt（約 11 MB）にフォールバックします。すべてのドキュメントページが連結されています。**さらに大きいため、全文をコンテキストに読み込まないでください。**ローカルにキャッシュし、用語の前後のコンテキストも含めて検索してください。インデックスから適切なページ名が分からない場合に使用します。

トラブルシューティング

• MCP が利用できない場合は、curl と jq がインストールされていれば "$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" を使用してください。
• Algolia 検索に失敗した場合は、llms.txt インデックスでページを特定してから、そのページを直接取得してください。
• 参照できるソースがない場合は、記憶している動作を現行のものとして示すのではなく、確認できていないことを明記してください。