codealive-context-engine

CodeAlive Context Engine

コードエコシステム全体（現在のプロジェクト、組織のリポジトリ、依存関係、インデックス化された任意のコードベース）を対象とするセマンティックコードインテリジェンスです。

認証

すべてのスクリプトで CodeAlive API キーが必要です。スクリプトが「API key not configured」というエラーで失敗した場合は、ユーザーが設定できるよう案内してください。

オプション 1（推奨）： 対話型セットアップを実行し、ユーザーが完了するまで待ちます。

python setup.py

オプション 2（非推奨 — チャット履歴にキーが表示されます）： ユーザーがチャットに API キーを直接貼り付けた場合は、次のコマンドで保存します。

python setup.py --key THE_KEY

セットアップが正常に完了するまで、失敗したスクリプトを再試行しないでください。

目次

• 認証
• ツールの概要
• 使用するタイミング
• クイックスタート
• ツールリファレンス
• データソース
• 設定

ツールの概要

ツール	スクリプト	速度	コスト	最適な用途
データソース一覧	datasources.py	即時	無料	インデックス化されたリポジトリやワークスペースを確認します。--query "task" を指定すると、AI による関連性フィルターを実行し（低コストですが即時ではありません）、関連するソースのみを返します
セマンティック検索	search.py	高速	低	デフォルトの探索手段です。意味（概念、動作、アーキテクチャ）に基づいてコードを検索します
Grep 検索	grep.py	高速	低	特定の文字列または正規表現（識別子、リテラル、パターン）を含むコードを検索します
リポジトリのオントロジー	ontology.py	高速	低	1 つのリポジトリに特化した概要を把握します
ファイルツリー	tree.py	高速	無料	範囲を指定してリポジトリのツリーを調べます
ファイルを読む	read_file.py	高速	無料	リポジトリ相対のファイルパスを 1 つ読み取ります。行範囲も指定できます
アーティファクトを取得	fetch.py	高速	無料	検索結果の識別子に対応する完全な内容を取得します
アーティファクトの関係	relationships.py	高速	無料	1 つのアーティファクトについて、完全な呼び出しグラフ、継承、またはシンボル参照を取得します
ArtifactQuery スキーマ	schema.py	高速	無料	対応するメタデータクエリのエンティティ、フィールド、例を確認します
アーティファクトのメタデータクエリ	metadata.py	高速	低	インデックス化されたリポジトリ全体の、読み取り専用の集計・クエリアナリティクスを実行します
コードベースとチャット	chat.py	低速	高	ステートレスな回答の合成です。ユーザーが明示的に依頼した場合にのみ呼び出してください。
バージョンを取得	get_version.py	即時	無料	インストールされている CodeAlive スキルのバージョンを JSON 形式で返します。API キーやネットワーク呼び出しは不要です

コストに関するガイダンス： semantic_search と grep_search が、デフォルトの開始点です。高速で低コストです。完全なソースを読み込むには fetch_artifacts を、呼び出しグラフを追跡するには get_artifact_relationships を使用してください。これら 4 つのツールはいずれも低コストです。

チャットは推奨されません： chat.py はサーバー側で LLM を呼び出すため、検索より大幅に時間がかかる場合があり、1 回あたりのコストもかなり高くなります。v3 ではステートレスです。質問ごとに、これまでの調査結果、アーティファクトの識別子、前提、対象範囲、制約を含めてください。ユーザーが明示的に依頼しない限り（例：「チャットを使って」「チャットツールを呼び出して」）、呼び出さないでください。「CodeAlive に聞いて」や「CodeAlive で検索して」といった表現は該当しません。これらは検索ツールを指しています。

修復可能なツールエラー： 返された <tool_error> は、空の結果を伴う成功ではなく、呼び出しの失敗として扱ってください。その <try> の指示に従って引数を修正し、<retry> フィールドで許可されている場合にのみ再試行してください。ツール API v3 は、JSON モードの自動化において、同じエラーを常に obj.error に保持します。

最も信頼性の高いガイダンス： エージェントがサブエージェントに対応しており、タスクで最大限の信頼性や深さが必要な場合は、ontology.py、search.py、grep.py、fetch.py、tree.py／read_file.py、relationships.py、metadata.py、およびローカルファイルの読み取りを組み合わせた、サブエージェント主導のワークフローを優先してください。 3 ステップのワークフロー（検索 → 選別 → 実際のコンテンツを読み込む）：

1. 検索 — 説明と識別子を使って、関連するコードの場所を見つけます
2. 選別 — 結果をさらに詳しく調べる価値があるかどうかは、description だけを使って判断してください。これは手がかりであり、信頼できる情報源ではありません。ここから結論を導き出さないでください。
3. 実際のコンテンツを取得 — 関連性があると判断したすべてのアーティファクトについて、次のようにします。
   • 外部リポジトリ（ローカルアクセス不可）：python fetch.py <identifier>
   • 現在の作業リポジトリ：エディターのファイル読み取りツールで、表示されたパスにあるファイルを読み込みます 信頼できる情報として扱うのは、実際のcontentだけです。

取得プレビューでは不十分な場合に、relationships.pyを詳しく調べます。 fetch.pyの応答では、関数のようなアーティファクトについて、呼び出し元と呼び出し先の情報が最大3件ずつプレビューされます。そのため、小さなアーティファクトをすべて取得した後で、呼び出しグラフだけを理由にrelationships.pyを実行する必要はほとんどありません。次の場合に使用してください。

• すべての呼び出し元が必要な場合 — 取得プレビューは最大3件です。 完全な呼び出し元リストには、テストファイルからの呼び出しも表示され、テストカバレッジを確認できます。
• 継承ツリーが必要な場合 — --profile inheritanceOnlyは祖先と子孫（インターフェースの実装、サブクラス、基底クラスの階層）を返します。プレビューには継承情報が含まれません。
• シンボル参照が必要な場合 — 型または識別子を参照している場所を調べるには、--profile referencesOnlyを使います。
• アーティファクトが大きすぎてコンテキストに取得できない場合 — 呼び出しグラフを使えば、ソース全体を取り込むより低コストで概要を把握できます。

アナライザーのノイズ： foreach／LINQを使用するメソッドでは、呼び出し先にコンパイラーが生成したヘルパー（MoveNext、GetEnumerator、クロージャーの呼び出し）が含まれることがあります。アーティファクトの実際のロジックと一致しない呼び出し先は無視してください。

使用する場面

セマンティック検索（デフォルト）— 動作や概念を説明する場合：

• 「認証はどのように実装されていますか？」
• 「サービス全体にわたるエラー処理のパターンを見せてください」
• 「このライブラリの内部の仕組みを教えてください」
• 「実装の参考になる類似機能を見つけてください」

grep検索 — 正確なテキストがわかっている場合：

• 「RepositoryDeletedのすべての使用箇所を見つけてください」
• 「ConnectionStringはどこで設定されていますか？」
• 「コードベース全体からTODO: fixを検索してください」
• エラーメッセージ、URL、設定キー、インポートパス、正規表現パターン

次の場合は、代わりにローカルのファイルツールを使います。

• 名前またはパターンを指定して特定のファイルを探す
• 現在のディレクトリ内で完全一致するキーワードを検索する
• パスがわかっているファイルを読み込む
• 未コミットの変更を検索する

クイックスタート

1. インデックス済みの項目を確認する

python scripts/datasources.py --query "the user's task in natural language"

推奨：ユーザーのタスクを--queryとして渡すと、バックエンドは関連するデータソースだけを、それぞれrelevanceReasonとともに返します。すべてを一覧表示するには--queryを省略します（即時に返され、AIによるフィルタリングは行われません）。

2. コードを検索する（高速、低コスト）

python scripts/search.py "JWT token validation" my-backend
python scripts/search.py "authentication flow" my-repo --path src/auth --ext .py
python scripts/grep.py "AuthService" my-repo
python scripts/grep.py "auth\\(" my-repo --regex

3. コンテンツ全体を取得する（外部リポジトリの場合）

python scripts/fetch.py "my-org/backend::src/auth.py::AuthService.login()"

4. アーティファクトの関連情報を詳しく調べる（任意）

# Full call graph (default)
python scripts/relationships.py "my-org/backend::src/auth.py::AuthService.login()"

# Inheritance hierarchy for a class
python scripts/relationships.py "my-org/backend::src/models.py::User" --profile inheritanceOnly

# Calls + inheritance, raise the per-type cap
python scripts/relationships.py "my-org/backend::src/svc.py::Service" --profile allRelevant --max-count 200

5. コードベースとチャットする（非推奨 — ユーザーから明示的に求められた場合のみ）

python scripts/chat.py "Explain the authentication flow. Prior context: none." my-backend
python scripts/chat.py "Given these prior findings and identifiers: ..., what about security considerations?" my-backend

ユーザーから明示的に求められない限り、チャットを呼び出さないでください。 v3のチャットはステートレスで、conversation_idを持ちません。質問ごとに必要なコンテキストをすべて含めてください。それ以外のタスクには、オントロジー、検索、grep、取得／読み込み、関連情報、メタデータクエリを使用してください。

ツールリファレンス

get_version.py — インストール済みバージョンを取得

インストール済みのCodeAlive Context EngineスキルのバージョンをJSONで返します。認証は不要で、ネットワークリクエストも行いません。

python scripts/get_version.py
# {"name": "codealive-context-engine", "version": "3.0.0"}

datasources.py — データソースの一覧表示

python scripts/datasources.py --query "add OAuth to checkout"  # Only sources relevant to a task (recommended)
python scripts/datasources.py              # Ready-to-use sources (full list)
python scripts/datasources.py --all        # All (including processing)
python scripts/datasources.py --json       # JSON output

オプション	説明
--query "TASK"	自然言語で記述したユーザーのタスク／意図です。バックエンドが AI 関連性フィルターを実行し、関連性の理由を示す relevanceReason とともに、関連するソースのみを返します。ユーザーが何を達成しようとしているかがわかっている場合に推奨されます
--all	処理中のソースも含めます
--json	JSON の生出力（--query を指定した場合：{"dataSources": [...], "message": "..."}）

フェイルオープン： 関連性フィルタリングを利用できない場合は、全件が返され、 その旨が出力されます。結果を関連性のある候補リストとして扱う前に、 メッセージを確認してください。

search.py — セマンティックコード検索（既定の探索ツール）

既定の開始地点です。コードを正確なテキストではなく、機能、動作、 アーキテクチャなどの概念から検索します。探しているものを説明できても、 コードベース内での正確な名前がわからない場合に使用します。

python scripts/search.py <query> <data_sources...> [options]

オプション	説明
--max-results N	返されるアーティファクト数の上限を任意で指定します
--path PATH	リポジトリからの相対パス、またはディレクトリの範囲を指定します（繰り返し指定可能）
--ext EXT	.py や .ts などのファイル拡張子の範囲を指定します（繰り返し指定可能）

description はトリアージの手がかりにすぎません。 詳しく調べる価値のある アーティファクトを示すものです。信頼できる情報源ではなく、これをもとに 結論を導いてはいけません。関連性があると判断した結果については、必ず 実際のソースを読み込んでください。外部リポジトリの場合は fetch.py <identifier> を、 現在の作業ディレクトリにあるリポジトリの場合はエディターの ファイル読み込みツールを使用してください。実際の content のみを 信頼できる情報として扱ってください。

grep.py — 完全一致テキスト／正規表現検索

特定の文字列または正規表現パターンを含むコードを検索します。 識別子、エラーメッセージ、設定キー、URL、ドメインイベント、 インポートパス、TODO コメントなど、検索するテキストが正確にわかっている 場合に使用します。

python scripts/grep.py <query> <data_sources...> [--regex] [--max-results N] [--path PATH] [--ext EXT]

オプション	説明
--regex	クエリを正規表現パターンとして解釈します
--max-results N	返されるアーティファクト数の上限を任意で指定します
--path PATH	リポジトリからの相対パス、またはディレクトリの範囲を指定します（繰り返し指定可能）
--ext EXT	.py や .ts などのファイル拡張子の範囲を指定します（繰り返し指定可能）

行プレビューはあくまで検索の証拠であり、信頼できる情報源ではありません。 動作について結論を導く前に、fetch.py またはローカルのファイル読み込みツールを 使用してください。

fetch.py — アーティファクトの内容を取得

検索で見つかったアーティファクトのソースコード全体を取得します。ローカルからアクセスできない外部リポジトリに使用してください。

python scripts/fetch.py <identifier1> [identifier2...] [--data-source NAME_OR_ID]

制約	値
リクエストあたりの識別子の最大数	50
識別子の取得元	検索結果の identifier フィールド
識別子の形式	{owner/repo}::{path}::{symbol}（シンボル）、{owner/repo}::{path}（ファイル）
--data-source NAME_OR_ID	任意。複数のデータソースにインデックスされている識別子を区別するためのデータソース名または ID（検索結果の Source: 行に記載）

関数のようなアーティファクトの場合、レスポンスには簡易的な関係性のプレビュー（呼び出し元と呼び出し先を各方向につき最大 3 件）が含まれます。呼び出しグラフ、継承関係、参照の全体を確認するには、アーティファクトの識別子を指定して relationships.py を実行してください。

見つからない識別子。 識別子を解決できない場合（またはアクセス範囲外の場合）、fetch.py はその識別子を黙って除外しません。各識別子を列挙した「not found」セクションを出力し、該当する ID を再確認して問題のあるものを再試行するよう促します。取得できなかったアーティファクトは省略せず、ユーザーに伝えてください。

複数のデータソースに存在する識別子の区別。 アーティファクトの識別子はデータソースごとにのみ一意であるため、同じ識別子が複数のデータソースに属することがあります。このような識別子を --data-source を指定せずに取得すると、バックエンドはデータソースを選択せず、候補となるデータソースを列挙した 409 を返します。列挙された候補はすべて解決可能です。したがって、手順は次のとおりです。--data-source を指定せずに呼び出す → 409 の候補を確認する → 1 つ試す → 目的のデータソースでなければ次を試す。解決するには、目的の検索結果の横に表示された Source: の名前または ID を取得し、それを指定して再実行します — python scripts/fetch.py <identifier> --data-source "backend"（または ID）。 同じ --data-source フラグは relationships.py でも使用できます。--data-source を指定した呼び出しで何も見つからない場合（スクリプトが「nothing was found in data source …」というヒントを出力する場合）、その識別子は別のデータソースに属しているか、指定値が誤っています。別の Source: の値を指定して再試行するか、--data-source を省略して 409 の候補リストを取得してください。

relationships.py — アーティファクトの関連グラフを詳しく調べる

単一のアーティファクトについて、完全な呼び出しグラフ（呼び出し元／呼び出し先）、継承階層（祖先／子孫）、またはシンボル参照を返します。これは詳細調査用のツールです。識別子を取得し、そのアーティファクトがコードベース内の他の部分とどのように関連しているかを把握したい場合は、search.py または fetch.py を使った後に使用してください。

python scripts/relationships.py <identifier> [--profile PROFILE] [--max-count N] [--data-source NAME_OR_ID]

オプション	説明
--profile callsOnly	デフォルト。呼び出し先＋呼び出し元
--profile inheritanceOnly	祖先＋子孫
--profile allRelevant	呼び出し＋継承（4 グループ）
--profile referencesOnly	シンボル参照
--max-count N	関係タイプごとの関連アーティファクトの最大数（1～1000、デフォルト 50）
--data-source NAME_OR_ID	省略可能。複数のデータソースでインデックス化された識別子を区別するための、データソースの Name または Id（fetch.py と同じ 409 の契約）
--json	フォーマット済みの表示ではなく、未加工の JSON レスポンスを出力します

fetch のプレビューより有用な場合：

• すべての呼び出し元（テストを含む）が必要な場合 — fetch のプレビューでは各方向につき最大 3 件に制限されます
• 継承ツリー（--profile inheritanceOnly）が必要な場合 — プレビューには祖先／子孫が含まれません
• シンボル参照（--profile referencesOnly）が必要な場合 — プレビューには参照が含まれません
• アーティファクトが大きすぎてコンテキストに読み込めない場合

通常は不要な場合： コンテキストに収まる小さなアーティファクトに対して、すでに fetch.py を実行している場合です。必要な呼び出し先は、読み取ったソースか、プレビューの最大 3 件に含まれています。relationships.py は、呼び出し元、継承、参照が特に必要な場合にのみ使用してください。

ノイズに関する注意： foreach／LINQ を使うメソッドでは、呼び出し先にコンパイラーが生成したヘルパー（MoveNext、GetEnumerator、クロージャー呼び出し）が含まれることがあります。これらはアナライザーの生成物です。アーティファクトの実際のロジックに一致しない呼び出し先の結果は無視してください。

chat.py — コードベースとチャット（非推奨）

ユーザーから明示的に依頼された場合（例：「チャットを使って」「チャットツールを呼び出して」）を除き、呼び出さないでください。「CodeAlive に聞いて」や「CodeAlive を検索して」といった表現は、チャットではなく検索ツールを指します。

選択したインデックス済みコードベースの全コンテキストを持つ AI コンサルタントに、自己完結した質問を送信します。統合された、そのまま使える回答が返されます。

処理が遅く、コストも高くなります。サーバー側で LLM を実行するため、検索より大幅に時間がかかる場合があります。v3 ではステートレスなので、各質問に過去の調査結果、識別子、前提、対象範囲、制約を含めてください。標準的なタスク（コードの検索、アーキテクチャの理解、デバッグ）には、代わりにオントロジー、検索、grep、fetch／read、relationships、メタデータクエリーを使用してください。

python scripts/chat.py <question> <data_sources...> [options]

v3 には公開された conversation_id はありません。追加の質問をする場合は、関連するコンテキストを次の question で改めて説明してください。

データソース

リポジトリ — 対象を絞った検索に使う単一のコードベース：

python scripts/search.py "query" my-backend-api

ワークスペース — プロジェクト横断のパターン検索に使う複数のリポジトリ：

python scripts/search.py "query" workspace:backend-team

複数のリポジトリ：

python scripts/search.py "query" repo-a repo-b repo-c

設定

前提条件

• Python 3.8 以降（サードパーティーパッケージは不要 — 標準ライブラリのみを使用）

API キーの設定

このスキルには CodeAlive API キーが必要です。解決順序は次のとおりです。

1. CODEALIVE_API_KEY 環境変数
2. OS の資格情報ストア（macOS Keychain／Linux secret-tool／Windows Credential Manager）

環境変数（すべてのプラットフォーム）：

export CODEALIVE_API_KEY="your_key_here"

macOS Keychain：

security add-generic-password -a "$USER" -s "codealive-api-key" -w "YOUR_API_KEY"

Linux（freedesktop secret-tool）：

secret-tool store --label="CodeAlive API Key" service codealive-api-key

Windows Credential Manager：

cmdkey /generic:codealive-api-key /user:codealive /pass:"YOUR_API_KEY"

ベース URL（省略可能。デフォルトは https://app.codealive.ai）：

export CODEALIVE_BASE_URL="https://your-instance.example.com"

セルフホスト可能な CodeAlive では、デプロイ先のオリジンを使用してください。https://your-instance.example.com が推奨されますが、https://your-instance.example.com/api も受け付けられ、自動的に正規化されます。

API キーはこちらから取得できます：https://app.codealive.ai/settings/api-keys

CodeAlive MCP サーバーと併用する

このスキルは単独でも動作しますが、CodeAlive MCP サーバーと組み合わせることで、最適な体験が得られます。MCP サーバーは Model Context Protocol を介してツールに直接アクセスできるようにし、このスキルはツールを効果的に使用するためのワークフローの知識とクエリパターンを提供します。

コンポーネント	提供内容
このスキル	クエリパターン、ワークフローのガイダンス、コストを考慮したツール選択
MCP サーバー	MCP プロトコルを介した semantic_search、grep_search、fetch_artifacts、get_artifact_relationships、get_data_sources ツールへの直接アクセス

両方をインストールしている場合は、直接操作には MCP サーバーのツールを優先し、ガイド付きワークフローにはこのスキルのスクリプトを使用してください。

詳細ガイド

高度な使用方法については、リファレンスファイルを参照してください。

• クエリパターン — 効果的なクエリの作成、アンチパターン、言語別の例
• ワークフロー — オンボーディング、デバッグ、機能計画などの段階的なワークフロー