ast-grep

このスキルは、自然言語による構造クエリを、テスト済みの ast-grep 検索に変換します。

譲れないルール：

1. ast-grep を利用する前に、インストールされていることを確認してください。
2. リポジトリを検索する前に、目的のパターンを示す最小限の例を作成してください。
3. ノードの種類や一致する構造が不明確な場合は、--debug-query で AST を調べてください。
4. 特別な理由がない限り、リレーショナルルールに stopBy: end を追加してください。
5. コードベース全体で実行する前に、例に対してルールをテストしてください。

ast-grep コード検索

入力

• $request：検索する構造パターンと、既知の言語、除外条件、エッジケース

目標

次の手順で、信頼性の高い構造検索を実行します。

• ast-grep が利用可能であることを確認する
• 検索対象のパターンと言語を明確にする
• 機能する最小限のルールを作成する
• まず例に対してテストする
• 報告する前に、リポジトリの検索結果を検証する

ステップ 0：利用可能か確認し、クエリを明確にする

最初に、ast-grep --version を実行して ast-grep がインストールされていることを確認します。

インストールされていない場合：

• 作業を中止します
• このワークフローには ast-grep が必要であることをユーザーに伝えます
• 検索を続行できるかのように振る舞わず、インストール方法を案内します

次に、以下を明確にします。

• プログラミング言語
• 一致させる対象
• 一致させない対象
• ユーザーが重視するエッジケース

詳細が曖昧で、質の低いルールにつながるおそれがある場合に限り、AskUserQuestion を使用します。

成功基準：ast-grep が利用可能であること、言語、パターンの意図が明確になっていること。

ステップ 1：最小限の例を作成し、AST を調べる

一致するはずの小さなコードスニペットを作成します。

必要に応じて --debug-query=cst または --debug-query=pattern を使い、以下を確認します。

• 実際のノードの種類
• メタ変数の解析方法
• 対象の構造がツリー内のどこにあるか

ルール：

• 例はできる限り小さくします
• ノードの種類やネストが不明確な場合は AST をデバッグします
• パターンが「明らか」に見えるからといって、このステップを省略しないでください

構文の詳細については references/rule_reference.md を、一般的なコマンドの形式については references/search-recipes.md を読み込みます。

成功基準：対象の構造がテスト済みの例で表現され、ルールを記述できるだけの AST 構造を把握していること。

ステップ 2：機能する最小限のルールを作成する

最もシンプルな実行可能な方法から始めます。

• 直接的な構造一致には、まず pattern を使います
• より複雑な構造には、kind とリレーショナルルールを使います
• 必要な場合に限り、all、any、または not を使います

ルール：

• より限定的な停止条件を意図していない限り、inside と has に stopBy: end を追加します
• ルールが不十分だと分かるまでは、最小限のままにします
• インラインのシェルコマンドを使う場合は、メタ変数を正しくエスケープします

ルールの意味については references/rule_reference.md を読み込みます。

成功基準：ルールの構文が有効で、問題に対して適切にシンプルであること。

ステップ 3：例に対してルールをテストする

--stdin または一時ファイルを使い、例のコードスニペットに対してルールをテストします。

以下を確認します。

• 意図した例に一致する
• 明らかな過剰一致がない
• リレーショナルルールが意図した範囲を走査する

ルールが機能しない場合：

• 簡素化します
• AST を再確認します
• ノードの種類やルールの構造を調整します
• リポジトリを検索する前に再テストします

成功基準：既知の例に対して、ルールが正しく一致すること。

ステップ 4：コードベースを検索し、結果を検証する

例でルールが機能したら、リポジトリに対して実行します。

続いて、以下を検証します。

• 一致件数
• 代表的なファイルパスと行番号
• 意図どおりかを確認するためのスポットチェック（3～5 件）
• ユーザーが明示したエッジケース

ルール：

• 結局 Grep で十分だった場合はその旨を伝えます。ただし、ast-grep 検索をすでに開始している場合は、現在の検索を完了します
• ルールが複雑すぎる、または不安定になる場合は、未検証のノイズを返すのではなく、クエリの範囲を狭めます

一般的な検索とデバッグの手順については references/search-recipes.md を読み込みます。

成功基準：リポジトリの検索結果が信頼でき、再現可能で、明らかにノイズが多くないこと。

Step 5: 結果と再利用可能なルールを報告する

次の内容を報告します。

• パターンの説明
• 言語
• 使用したルールの種類
• 一致件数
• 代表的なファイル名と行番号の一致箇所
• 最終的な再利用可能なルールまたはコマンドの形式

一致が見つからなかった場合は、その旨を明示し、次のどれに該当する可能性が高いかを説明します。

• パターンが存在しない
• ルールの範囲が意図的に狭かった
• 追加の確認が必要

成功条件：出力を使って、ユーザーが検索を再実行したり、条件を絞り込んだりできます。

ガードレール

• 非破壊的な検索スキルであるため、disable-model-invocation を追加しないでください。
• ユーザーは通常、現在のフローでの結果を求めているため、context: fork を追加しないでください。
• 汎用的な検索ワークフローであるため、paths: を追加しないでください。
• クエリが複雑な場合は、未テストのルールでリポジトリを検索しないでください。
• 巨大な CLI マニュアル、レシピ集、失敗事例集を SKILL.md にそのまま記載しないでください。
• 通常の Grep で明らかに十分な場合は、ast-grep を使わないでください。

参照資料を読み込むタイミング

• references/rule_reference.md ast-grep のルール構文、関係ルール、複合ルール、メタ変数の意味を確認する場合に使用します。

• references/search-recipes.md インストール方法、コマンドのパターン、一般的なユースケース、デバッグの流れを確認する場合に使用します。

出力要件

次の内容を報告します。

1. 検索した構造パターン
2. 言語と使用したルールの種類
3. 一致件数と代表的なファイル名・行番号の結果
4. 最終的なルールまたは再利用可能なコマンドの形式
5. 重要な注意点や、さらに条件を絞り込む方法