ast-grep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> This skill turns natural-language structure queries into tested ast-grep searches.

Non-negotiable rules:

Verify
```
ast-grep
```
is installed before relying on it.
Create a minimal example of the desired pattern before searching the repository.
Inspect the AST with
```
--debug-query
```
when node kinds or match shape are uncertain.
Add
```
stopBy: end
```
to relational rules unless there is a specific reason not to.
Test the rule on the example before running it across the codebase.

</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> 本技能可将自然语言描述的结构查询转换为经过测试的ast-grep搜索。

不可违背的规则：

在依赖ast-grep之前，先确认它已安装。
在搜索代码库前，创建一个符合目标模式的最小示例。
当不确定节点类型或匹配结构时，使用
```
--debug-query
```
检查AST。
除非有特殊原因，否则在关系规则中添加
```
stopBy: end
```
。
在全代码库运行规则之前，先在示例上测试。

</EXTREMELY-IMPORTANT>

ast-grep Code Search

ast-grep代码搜索

Inputs

输入

```
$request
```
: The structural pattern to find, plus any known language, exclusions, or edge cases

```
$request
```
：要查找的结构模式，以及任何已知的语言、排除项或边缘情况

Goal

目标

Produce a reliable structural search by:

confirming ast-grep is available
clarifying the intended pattern and language
building the smallest rule that can work
testing it on example code first
validating repository results before reporting them

通过以下步骤生成可靠的结构化搜索：

确认ast-grep可用
明确目标模式和编程语言
构建最简可行规则
先在示例代码上测试规则
在报告结果前验证代码库的搜索结果

Step 0: Verify availability and resolve the query

步骤0：验证可用性并明确查询

First verify

ast-grep

is installed with

ast-grep --version

If it is not installed:

stop
tell the user
```
ast-grep
```
is required for this workflow
provide installation guidance instead of pretending the search can proceed

Then resolve:

the programming language
what should match
what should not match
any edge cases the user cares about

Use

AskUserQuestion

only if those details are ambiguous enough to risk a bad rule.

Success criteria:

ast-grep

availability, language, and pattern intent are explicit.

首先使用

ast-grep --version

确认ast-grep已安装。

如果未安装：

停止操作
告知用户此工作流需要ast-grep
提供安装指南，而非继续执行搜索

随后明确：

编程语言
需要匹配的内容
需要排除的内容
用户关心的任何边缘情况

只有当这些细节模糊到可能导致规则失效时，才使用

AskUserQuestion

询问用户。

成功标准：ast-grep可用性、编程语言和模式意图均已明确。

Step 1: Create a minimal example and inspect the AST

步骤1：创建最小示例并检查AST

Write a tiny example snippet that should match.

Use

--debug-query=cst

--debug-query=pattern

when needed to understand:

the real node kinds
how metavariables are parsed
where the target structure sits in the tree

Rules:

keep the example as small as possible
debug the AST when kind names or nesting are uncertain
do not skip this step just because the pattern "looks obvious"

Load

references/rule_reference.md

for syntax details and

references/search-recipes.md

for common command shapes.

Success criteria: The target shape is represented by a tested example and the AST structure is understood well enough to write the rule.

编写一个符合匹配要求的极小代码片段。

必要时使用

--debug-query=cst

或

--debug-query=pattern

来了解：

实际节点类型
元变量的解析方式
目标结构在语法树中的位置

规则：

示例尽可能精简
当不确定节点类型或嵌套结构时，调试AST
不要因为模式“看起来很明显”就跳过此步骤

查阅

references/rule_reference.md

获取语法细节，查阅

references/search-recipes.md

获取常见命令格式。

成功标准：目标结构已有经过测试的示例，且AST结构已清晰到足以编写规则。

Step 2: Write the smallest rule that can work

步骤2：编写最简可行规则

Start from the simplest viable rule:

```
pattern
```
first for direct structural matches
```
kind
```
plus relational rules for more complex structures
```
all
```
,
```
any
```
, or
```
not
```
only when needed

Rules:

add
```
stopBy: end
```
to
```
inside
```
and
```
has
```
unless a tighter stop condition is intentional
keep the rule minimal until it proves insufficient
escape metavariables correctly when using inline shell commands

Load

references/rule_reference.md

for rule semantics.

Success criteria: The rule is syntactically valid and appropriately simple for the problem.

从最简可行规则开始：

优先使用
```
pattern
```
进行直接结构匹配
对于更复杂的结构，使用
```
kind
```
加关系规则
仅在必要时使用
```
all
```
、
```
any
```
或
```
not
```

规则：

除非有意使用更严格的终止条件，否则在
```
inside
```
和
```
has
```
中添加
```
stopBy: end
```
保持规则最简，直到证明其不足以满足需求
在使用内联shell命令时，正确转义元变量

查阅

references/rule_reference.md

获取规则语义。

成功标准：规则语法有效，且针对问题复杂度保持了恰当的简洁性。

Step 3: Test the rule on the example

步骤3：在示例上测试规则

Test the rule against the example snippet using

--stdin

or a temporary file.

Check:

it matches the intended example
it does not obviously overmatch
relational rules traverse the intended scope

If the rule fails:

simplify it
re-check the AST
adjust kind names or rule shape
retest before touching the repository

Success criteria: The rule matches the known example correctly.

使用

--stdin

或临时文件，在示例代码片段上测试规则。

检查：

规则匹配了预期示例
未出现明显的过度匹配
关系规则遍历了预期范围

如果规则失败：

简化规则
重新检查AST
调整节点类型或规则结构
在处理代码库前重新测试

成功标准：规则正确匹配了已知示例。

Step 4: Search the codebase and validate results

步骤4：搜索代码库并验证结果

Once the rule works on the example, run it against the repository.

Then validate:

total match count
representative file paths and lines
3 to 5 spot-checks to confirm the intent
edge cases the user explicitly mentioned

Rules:

if Grep would have been enough after all, say so, but complete the current ast-grep search if already in motion
if the rule becomes too complex or brittle, narrow the query rather than returning unverified noise

Load

references/search-recipes.md

for common search and debug flows.

Success criteria: The repository results are credible, reproducible, and not obviously noisy.

规则在示例上运行成功后，在代码库中执行搜索。

随后验证：

总匹配次数
代表性文件路径和行号
3到5个抽查样本以确认符合意图
用户明确提到的边缘情况

规则：

如果最终发现普通Grep就足够，需告知用户，但如果已启动ast-grep搜索则完成当前操作
如果规则变得过于复杂或脆弱，应缩小查询范围，而非返回未经验证的无效结果

查阅

references/search-recipes.md

获取常见搜索和调试流程。

成功标准：代码库的搜索结果可信、可复现，且无明显无效内容。

Step 5: Report the results and reusable rule

步骤5：报告结果和可复用规则

Report:

pattern description
language
rule type used
match count
representative file:line matches
the final reusable rule or command shape

If no matches were found, say so explicitly and explain whether that likely means:

the pattern does not exist
the rule was intentionally narrow
more clarification is needed

Success criteria: The user can rerun the search or refine it from your output.

报告内容包括：

模式描述
编程语言
使用的规则类型
匹配次数
代表性的文件:行号匹配结果
最终可复用的规则或命令格式

如果未找到匹配项，需明确说明，并解释可能的原因：

模式不存在
规则设置得过于严格
需要进一步明确查询

成功标准：用户可根据你的输出重新运行搜索或优化查询。

Guardrails

约束规则

Do not add
```
disable-model-invocation
```
; this is a non-destructive search skill.
Do not add
```
context: fork
```
; the user usually wants the result in the current flow.
Do not add
```
paths:
```
; this is a generic search workflow.
Do not search the repository with an untested rule when the query is non-trivial.
Do not keep giant CLI manuals, recipe catalogs, or failure encyclopedias inline in
```
SKILL.md
```
.
Do not use ast-grep when plain Grep is clearly sufficient.

不要添加
```
disable-model-invocation
```
；这是一个非破坏性的搜索技能。
不要添加
```
context: fork
```
；用户通常希望在当前流程中获取结果。
不要添加
```
paths:
```
；这是通用搜索工作流。
当查询非 trivial 时，不要使用未测试的规则搜索代码库。
不要在
```
SKILL.md
```
中嵌入庞大的CLI手册、配方目录或故障百科。
当普通Grep显然足够时，不要使用ast-grep。

When To Load References

何时查阅参考文档

```
references/rule_reference.md
```
Use for ast-grep rule syntax, relational rules, composite rules, and metavariable semantics.
```
references/search-recipes.md
```
Use for installation guidance, command patterns, common use cases, and debugging flows.

```
references/rule_reference.md
```
用于ast-grep规则语法、关系规则、复合规则和元变量语义。
```
references/search-recipes.md
```
用于安装指南、命令模式、常见用例和调试流程。

Output Contract

输出约定

Report:

the structural pattern searched for
the language and rule type used
the match count and representative file:line results
the final rule or reusable command shape
any important caveats or follow-up refinements

报告需包含：

搜索的结构模式
使用的编程语言和规则类型
匹配次数和代表性文件:行号结果
最终规则或可复用命令格式
任何重要的注意事项或后续优化建议