ast-grep 是一套结构化代码工具，核心能力是让搜索按代码的抽象语法树（AST）结构进行，而不是仅按文本匹配。当某个搜索需求无法用普通 grep 表达时，可以使用它。
主要能力一：按 AST 模式搜索。基本用法为 ast-grep run --pattern 'console.log($ARG)' --lang javascript .，即以简单模式匹配代码。
主要能力二：规则扫描。可以内联规则执行：ast-grep scan --inline-rules "<yaml>" <path>，用于关系型或组合型规则、无需临时文件；也可以从文件加载复杂规则：ast-grep scan --rule /path/rule.yml <path>；还能先对代码片段测试规则：echo '<code>' | ast-grep scan --inline-rules "<yaml>" --stdin。
主要能力三：调试模式解析。ast-grep run --pattern '<code>' --lang <lang> --debug-query=<style> 中，cst 表示目标的完整语法树（用于找到正确的 kind），ast 表示仅命名节点，pattern 表示 ast-grep 如何解析你的模式。
注意事项：关系型规则（inside、has）在遇到第一个不匹配节点时会停止，除非加上 stopBy: end；需要深度遍历时应始终添加。例如：has: pattern: await $EXPR，stopBy: end。在 shell 中需转义元变量：双引号内使用 $VAR，或对模式使用单引号。建议先用普通模式，仅当模式单独使用出现过度匹配或匹配不足时，再加入 kind 和关系型规则，并用 all/any/not 组合。完整 YAML 规则语法见 references/rule-reference.md。
结构概览（Outline，ast-grep ≥ 0.44，alpha 阶段）：在阅读完整文件前先映射结构，展示顶层条目（函数、类、导入、导出）及其成员；仅做语法分析，不建立索引。
用法示例：ast-grep outline <file> 查看本地条目与成员摘要；ast-grep outline <dir> --items exports 查看目录的公开接口；ast-grep outline <file> --match Parser --type class --view expanded 放大查看单个符号并带行号；ast-grep outline <dir> --items imports --view signatures 生成依赖图。
参数说明：--items 可选 structure|exports|imports|all；--view 可选 names|signatures|digest|expanded，细节依次增加。默认值：文件 → structure/digest，目录 → exports/names。--match <regex> 与 --type class,enum,... 仅过滤顶层条目，不过滤成员；--pub-members 将成员视图限制为公开成员。--json[=stream] 用于结构化输出，stream 模式每个文件输出一个对象，可管道传给 jq。
适用场景：需要按代码结构而非纯文本进行搜索、在阅读完整文件前快速了解文件或模块结构、查看目录公开接口或依赖关系、以及对代码片段先行测试规则等。限制方面：outline 功能要求 ast-grep ≥ 0.44 且处于 alpha 阶段；其他平台、收费、价格等细节暂未提供。