codegraph-ast-grep

CodeGraph + ast-grep

目的

リポジトリのコーディングエージェントが、意味的なスコープの把握には CodeGraph を、構造的な根拠の確認には ast-grep CLI をすぐに使えるようにします。この機能を管理するのは公開ワークフローです。セットアップ後のリポジトリの調査やリファクタリングは、通常の内部的なコーディング作業です。

使用する場合

• CodeGraph、ast-grep CLI、MCP の公開、インデックス作成、エージェント向けガイダンスをインストールまたは調整する場合。
• インストール済みの分析スタックを更新し、必要な設定、インデックス、スキーマの移行を実行する場合。
• セットアップを修復せずに、見つからない、古い、接続されていない、または壊れているように見える状態を診断する場合。

使用しない場合

すでに準備が整った分析スタックをコーディング作業に活用できるというだけの理由で、このスキルを有効にしないでください。保存済みのリポジトリガイダンスに従ってください。一般的な依存関係の監査、コンパイラ／ランタイムによる検証、またはレビューされていない広範な書き換えには使用しないでください。

ワークフローの選択

ワークフローの完全な一覧は、メリットを先に示した平易な説明で、次のとおりです。

• setup：Semantic Code Intelligence と構造的なコード検索によってリポジトリを強化し、コーディングエージェントがより少ないツール呼び出しで、より速く回答できるようにします。不足している要素をインストールし、コーディングクライアントを接続して、コードインデックスを作成し、リポジトリ向けガイダンスを追加します。既存のセットアップがあれば、安全に再利用または修復します。
• update：インストール方法を変更せずに、既存のセットアップを最新の安定版に更新します。必要に応じて設定やインデックスデータを移行し、コーディングクライアントを再接続して、引き続きすべてが動作することを確認します。
• doctor：セットアップの状態を診断し、修復は行わずに分析結果を報告します。

簡単な呼び出し、実質的に曖昧な呼び出し、または選択肢を明示的に求められた場合は、文書に記載された順序でワークフローの完全な一覧を提示してください。選択肢を求められただけでは、実行やリポジトリ／ツールの調査は許可されません。文書に記載された一覧に基づいて回答してください。意図が明確で実行が許可されている場合は、選択したワークフローとその理由、重要なスコープと証拠の項目だけを伝えてから、実行に進んでください。

auto ワークフローはありません。意図に基づいて選択してください。

• セットアップまたはインストールの明示的な依頼には、setup を選択します。
• 安定版ツールの明示的な更新、移行、またはリフレッシュの依頼には、update を選択します。
• 「何かが壊れている」、ヘルスチェック、またはセットアップの分析結果を求める依頼には、doctor を選択します。
• 簡単な呼び出しや曖昧な意図の場合は、3 つすべてのワークフローを提示し、ユーザーに選択を求めます。

意図が明確な直接の依頼では、選択したワークフロー、理由、ルート、想定される書き込み／生成物、保護対象の状態だけを伝えてから、実行に進んでください。エージェントが開始する場合に選択して通知できるのは doctor のみです。セットアップまたは更新の許可を推測してはなりません。setup または update を選択できるのは、指定されたルートに対してユーザーがすでにその結果を依頼している場合に限られます。特権を伴う／グローバルなインストール、有料サービスまたは外部サービス、公開／デプロイ、破壊的な置換、テレメトリーの変更、スコープの拡大には、それぞれ別途承認が必要です。

調査する入力

• 正確なリポジトリルート、ネストされたリポジトリまたはモノレポのパッケージ、パッケージ／宣言型ポリシー、保護対象の Git 状態。
• 有効な CODEGRAPH_DIR（デフォルト .codegraph/）、サポートされている場合はルートの codegraph.json、sgconfig.yml／sgconfig.yaml、リポジトリの指示ファイル。
• 実行ファイルのパス、インストーラーのチャネルとスコープ、バージョンの固定情報、インストール済みのヘルプ、設定済みのクライアント、公開されている MCP ツール。
• パッケージ／設定／インデックスへの書き込みについて承認されたスコープ、および生成メタデータが移行される可能性のある、正確なルートを指定したプロジェクトのオープン。

ワークフロー

setup

1. 正確なルート、保護対象の状態、実行時クライアント、パッケージ／宣言型ポリシー、既存インストーラーの導入元、オフライン／テレメトリーの制約を記録します。
2. 変更を加える前に、既存のバイナリ、設定、MCP への公開状況、状態のパス、リポジトリのガイダンスを確認します。インストール済みのヘルプと公開されているツールを正とします。
3. リポジトリで承認されたインストールチャネルとスコープを通じて、安定版 CodeGraph リリースと安定版 ast-grep CLI を整合させます。通常のセットアップでは、実験的な ast-grep MCP サーバーをインストールしないでください。
4. 選択した実行時クライアントと CodeGraph のプロジェクトルートを設定し、ヘルプで確認できる初期化、および承認済みルート内で必要な設定／インデックス／スキーマの移行を実行します。
5. コーディングエージェント向けに、簡潔でリポジトリに適したガイダンスを永続化します。そこには、同等の表現で次の内容を明記する必要があります。意味的なシンボル、呼び出し元、呼び出し経路、影響範囲には CodeGraph を使用し、構文の構造的な根拠には ast-grep CLI を使用し、広範な編集の前に両方の結果を照合してください。
6. 必要に応じてクライアントを再接続または再起動し、意味的クエリを1つ、範囲を限定した構造的クエリを1つ実行して、状態の鮮度とガイダンスの検出を検証します。
7. インストール済みバージョンと導入元、書き込み内容、移行／再接続の根拠、準備状況、残る制限事項を報告します。

セットアップは冪等で、エージェントだけで完結します。再実行時は、設定、手順、インデックス、依存関係を重複させずにドリフトを整合させます。

update

1. セットアップと同じルート、ポリシー、保護対象の状態、テレメトリー、導入元の根拠を記録します。
2. インストール済みのコアツールを、それぞれの正規の安定版チャネルと一度だけ比較します。オフラインの意図、DO_NOT_TRACK、CODEGRAPH_NO_UPDATE_CHECK、レジストリの制限、リポジトリのピン留めを尊重します。
3. 既存のインストーラーチャネルとグローバル／プロジェクト／宣言型のスコープを維持します。リポジトリのポリシーで選択された安定版 CodeGraph と ast-grep CLI のコンポーネントのみを更新し、更新対象をすべて一括更新する操作は実行しません。
4. バージョンに応じて必要となる設定、インデックス、スキーマの移行をすべて、承認済みルート内で実行します。バイナリの置き換え、実行時設定の変更、プロンプトフック、テレメトリー、グラフ操作を実行記録に明示します。
5. クライアントを再接続／再起動し、必要な場合に限りグラフを更新して、バージョン／PATH、MCP への公開、グラフの準備状況、意味的クエリ、構造的クエリ、永続化されたガイダンスを検証します。
6. 更新に失敗した場合は、それ以上の変更を停止し、設定／インデックスの状態を保護して、引き続き機能するものを報告し、事前に開示された安全なロールバックのみを使用します。

ユーザーの明示的な更新依頼は、通常のルート内更新と必要な移行を承認するものです。権限の昇格、インストールチャネルまたはスコープの変更、無関係な依存関係の変更、破壊的な再構築、外部サービスに対する操作については、別途確認してください。

doctor

1. 実行ファイル／導入元、バージョン／ヘルプ、設定の有無、MCP 登録、状態のパス、無視ポリシー、リポジトリのガイダンス、接続を開かずに得られる根拠を確認します。
2. インストール、更新、設定への書き込みを伴う再接続、初期化／再構築／同期、修復、ソースの書き換えは行いません。
3. プロジェクトを開いて生成メタデータを移行する可能性のある codegraph status、MCP グラフクエリ、その他の診断を実行する前に、正確なルートを明示して明確な承認を得るか、承認済みの使い捨てコピーを使用します。承認が得られない場合は、詳細チェックを省略したことを報告します。
4. 承認を得た場合は、範囲を限定したグラフの健全性と、鮮度、インデックス化された言語、シンボル／ファイルの網羅率、クエリの準備状況など、有用な分析情報を収集します。メタデータが移行された可能性がある場合、完全な読み取り専用であったとは説明しません。
5. 診断結果、根拠、確信度、推奨する setup または update の次の手順、未検証の範囲を返します。doctor の一環として修復は行いません。

内部コーディング動作

セットアップが完了した後、コーディングエージェントはこれらの動作を公開されているスキルモードとして扱わずに使用します。

通常のセマンティック探索、構造検索、影響分析、ルール作成、レビュー済みの書き換えは、内部コーディング動作です。

• セマンティック探索： 公開されている codegraph_explore を優先し、次にインストール済みヘルプで確認した codegraph explore を使用し、その後、より範囲を絞った検証済みの CodeGraph 機能を使用します。
• 構造検索： 構文の形が判明した後に ast-grep CLI を使用します。曖昧な場合は言語を指定し、パスと出力の範囲を制限します。
• 影響分析： セマンティックな所有関係と呼び出し経路を、構造マッチの一覧および対象を絞ったソースの読み取りと照合します。
• ルール作成： 再利用可能なパターンや関係性を持つパターンには、肯定・否定のフィクスチャを含む、テスト済みの YAML ルールを使用します。
• レビュー済みの書き換え： 対象を一覧化してテストし、プレビューしたうえで、正確かつ限定された範囲の承認を得て適用し、差分を確認して、リポジトリ標準の検証を実行します。

セマンティックな証拠と構造的な証拠が一致しない場合、網羅性を主張する前に、グラフの鮮度とルート、パーサーと言語、生成コードまたは動的コード、無視ルール、対象を絞ったソースを確認します。ランタイム標準の LSP と範囲を限定したテキスト／ファイルの調査はフォールバックです。どちらのコアツールも、コンパイラー、型、汚染、またはランタイムの証明にはなりません。

安全ルール

• ast-grep CLI をサポート対象のデフォルトとして使用します。実験的な ast-grep MCP サーバーは通常のセットアップから除外されています。
• ユーザーが別途テレメトリに同意していない限り、スキル主導のチェックと承認済みのセットアップ／更新コマンドでは、CODEGRAPH_TELEMETRY=0 を指定して CodeGraph のテレメトリを無効にします。デフォルトで有効になっているテレメトリは同意を意味しません。
• 正確なパッケージまたはチェックサム付きのリリースアセットを優先します。パイプでシェルや PowerShell に渡すインストールをデフォルトにしないでください。
• インストーラーのチャネルとスコープを維持し、パッケージマネージャーの鮮度、信頼性、ライフサイクルスクリプト、チェックサム、宣言的ポリシーの各チェックを回避しないでください。
• .codegraph/config.json を作成しないでください。有効な CODEGRAPH_DIR は生成された状態として扱い、ルートの codegraph.json はバージョンや機能に依存するものとして扱います。
• アクティブなサポート対象ウォッチャーがないのに自動同期を想定したり、ステータスで鮮度が確認できるのに手動同期を必須にしたりしないでください。
• テストされていない ast-grep の書き換えを適用したり、スナップショットや update-all の動作を無差別に受け入れたりしないでください。
• シークレット、静的ヘッダー、顧客データ、非公開のサービス名、内部ホスト名を、保存される成果物や公開される成果物から削除してください。

参考資料

選択したワークフローまたは後続のコーディングタスクに必要なものだけを読みます。

• references/setup-and-mcp-config.md：インストールのスコープ、ランタイム設定、状態のパス、初期化について。
• references/update-and-provenance.md：安定チャネル、出所を保持した更新、移行、検証、ロールバックについて。
• references/troubleshooting.md：読み取り専用の診断手順と、フォローアップ先について。
• references/codegraph-capability-guide.md：現在／レガシー機能の確認、グラフの鮮度、正確なルートでのプロジェクトのオープンについて。
• references/usage-playbook.md：保存されるエージェント向けガイダンスと、内部のセマンティック／構造／影響分析の動作について。
• references/ast-grep-rule-recipes.md：範囲を限定した CLI のパターン、ルール／テスト、レビュー済みの書き換えについて。
• references/extensions-and-escalation.md：コアスタックではタスクを安全に表現できない場合に限り参照します。

スクリプト

ランタイムスクリプトはありません。インストール済みのツールとリポジトリ標準の検証コマンドを使用します。カタログの決定的なコントラクトバリデーターはメンテナー専用であり、このスキルにはインストールされません。

出力形式

選択したワークフローとその理由、正確なルート、保護された状態、インストーラーの出所、バージョン／機能、書き込みまたは書き込みのスキップ、移行／再接続の状態、検証の証拠、残る制限を報告します。doctor では、ルートを開かずに得られた証拠と、正確なルートでの詳細な分析を分け、修復は行わずに診断と推奨されるフォローアップを提示します。

完了基準

• 選択した setup、update、または doctor ワークフローと、意図の根拠が明示されています。
• セットアップ／更新では来歴と保護対象の状態が維持され、必要な移行／再接続が検証されています。
• 対象リポジトリ向けのガイダンスでは、幅広いコーディング作業において、意味的証拠と構造的証拠を標準としています。
• doctor は修復を行わず、正確なルートでのグラフを開く承認と、メタデータが変更される可能性を正確に示しています。
• 検証済みの機能と、代表的な意味的／構造的チェックによって準備状況が証明されているか、制限事項が明示されています。

失敗モード

• 意図またはルートが曖昧な場合は、3 つすべてのワークフローを示し、調査または変更を行う前に確認を求めます。
• 安定したメタデータを確認できない場合は not checked と報告し、オフライン、オプトアウト、レジストリ、またはピン留めのポリシーを回避しないでください。
• セットアップ／更新に、許可されていない権限、チャネル、スコープ、破壊的な再構築、または外部操作が必要な場合は、現在の状態を維持し、その具体的な権限を求めます。
• ツールまたはクライアントを引き続き利用できない場合は、検証済みの中間成果物／設定を保持し、準備が未完了であると報告して、必要最小限の次のアクションを示します。
• 証拠が食い違う場合は、意味的または構造的な網羅性が完全であると主張せず、不一致と信頼度を報告します。