name: ast-grep description: ast-grep 规则编写和使用的最佳实践。该技能应用于编写、审查或调试 ast-grep 规则，用于代码搜索、linting 和转换。触发涉及 YAML 规则、模式语法、元变量、约束或代码重写的任务。
ast-grep 社区最佳实践
全面的 ast-grep 规则编写和使用最佳实践指南，由 ast-grep 社区维护。包含 8 个类别中的 46 条规则，按影响优先级排序，以指导自动化规则生成和代码转换。
何时应用
在以下情况下参考这些指南：
- 编写新的 ast-grep 规则用于 linting 或搜索
- 调试不匹配预期代码的模式
- 为大型代码库优化规则性能
- 设置具有适当组织的 ast-grep 项目
- 审查 ast-grep 规则的正确性和可维护性
通用工作流
在创建 ast-grep 规则进行代码搜索时，遵循此工作流：
步骤 1: 理解查询
澄清你想要找到的内容：
- 目标编程语言
- 需要处理的边缘情况
- 包括与排除的内容
步骤 2: 创建示例代码
编写代表所需匹配模式的示例代码片段。
步骤 3: 编写 ast-grep 规则
选择正确的方法：
- 使用
pattern用于简单结构 - 使用
kind配合has/inside用于复杂结构 - 结合
all、any或not用于复合查询 - 始终对关系规则（
inside、has）使用stopBy: end，以确保完整搜索
步骤 4: 测试规则
# 检查 AST 结构
ast-grep run --pattern '[code]' --lang [language] --debug-query=ast
# 测试内联规则
echo "[code]" | ast-grep scan --inline-rules "[rule]" --stdin
# 从文件测试
ast-grep scan --rule [file.yml] [path]
步骤 5: 搜索代码库
部署已验证的规则：
# 使用模式搜索（简单匹配）
ast-grep run --pattern '[pattern]' --lang [language] [path]
# 使用规则文件搜索（复杂查询）
ast-grep scan --rule [file.yml] [path]
# 交互式应用修复
ast-grep scan --rule [file.yml] --interactive [path]
快速提示
- 始终使用
stopBy: end- 确保关系规则的完整子树遍历 - 从简单开始，增加复杂性 - 从模式开始，逐步到种类，再到关系规则
- 使用 AST 检查调试 - 使用
--debug-query=ast验证结构匹配 - 在内联规则中转义 - 使用
\$VAR或单引号用于 shell 命令 - 首先在游乐场测试 - 使用 https://ast-grep.github.io/playground.html 进行快速迭代
按优先级排序的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 模式正确性 | 关键 | pattern- |
| 2 | 元变量使用 | 关键 | meta- |
| 3 | 规则组合 | 高 | compose- |
| 4 | 约束设计 | 高 | const- |
| 5 | 重写正确性 | 中高 | rewrite- |
| 6 | 项目组织 | 中 | org- |
| 7 | 性能优化 | 中 | perf- |
| 8 | 测试与调试 | 低中 | test- |
快速参考
1. 模式正确性（关键）
pattern-valid-syntax- 使用可解析的有效代码作为模式pattern-language-aware- 考虑语言特定的语法差异pattern-context-selector- 使用上下文和选择器用于代码片段pattern-avoid-comments-strings- 避免匹配注释和字符串内部pattern-strictness-levels- 适当配置模式严格度pattern-kind-vs-pattern- 基于特异性需求选择种类或模式pattern-debug-ast- 使用调试查询检查 AST 结构pattern-nthchild-matching- 使用 nthChild 进行基于索引的位置匹配pattern-range-matching- 使用 range 进行字符位置匹配
2. 元变量使用（关键）
meta-naming-convention- 遵循元变量命名约定meta-single-node- 使用元变量匹配单个 AST 节点meta-reuse-binding- 重用元变量以强制执行相等性meta-underscore-noncapture- 使用下划线前缀用于非捕获匹配meta-named-vs-unnamed- 使用双美元符号用于未命名节点匹配meta-multi-match-lazy- 理解多匹配变量是惰性的
3. 规则组合（高）
compose-all-for-and-logic- 使用 all 用于规则间的 AND 逻辑compose-any-for-or-logic- 使用 any 用于规则间的 OR 逻辑compose-not-for-exclusion- 使用 not 用于排除模式compose-inside-for-context- 使用 inside 用于上下文匹配compose-has-for-children- 使用 has 用于子节点要求compose-matches-for-reuse- 使用 matches 用于规则可重用性compose-precedes-follows- 使用 precedes 和 follows 用于顺序定位compose-field-targeting- 使用 field 用于定位特定子节点
4. 约束设计（高）
const-kind-filter- 使用种类约束过滤元变量const-regex-filter- 使用正则表达式约束用于文本模式const-not-inside-not- 避免在 not 规则内部使用约束const-pattern-constraint- 使用模式约束用于结构过滤const-post-match-timing- 理解约束在匹配后应用
5. 重写正确性（中高）
rewrite-preserve-semantics- 在重写中保留程序语义rewrite-meta-variable-reference- 在修复中引用所有必要的元变量rewrite-transform-operations- 使用 transform 用于复杂重写rewrite-test-before-deploy- 在代表性代码上测试重写rewrite-syntax-validity- 确保修复模板产生有效语法
6. 项目组织（中）
org-project-structure- 使用标准项目目录结构org-unique-rule-ids- 使用唯一描述性规则 IDorg-severity-levels- 分配适当的严重级别org-file-filtering- 使用文件过滤用于目标规则org-message-clarity- 编写清晰可操作的消息
7. 性能优化（中）
perf-specific-patterns- 使用特定模式而非通用模式perf-stopby-boundaries- 使用 stopBy 限制搜索深度perf-thread-parallelism- 利用线程并行扫描perf-avoid-regex-heavy- 避免在热路径中使用重型正则表达式
8. 测试与调试（低中）
test-valid-invalid-cases- 编写有效和无效测试案例test-snapshot-updates- 使用快照测试验证修复test-playground-first- 首先在游乐场测试模式test-edge-cases- 测试边缘情况和边界条件
如何使用
阅读单独的参考文件以获取详细解释和代码示例：
- Section definitions - 类别结构和影响级别
- Rule template - 添加新规则的模板
完整编译文档
- AGENTS.md - 包含所有规则的完整编译指南
参考文件
| 文件 | 描述 |
|---|---|
| AGENTS.md | 包含所有规则的完整编译指南 |
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则的模板 |
| metadata.json | 版本和参考信息 |