ast-grep Community Best Practices

Comprehensive best practices guide for ast-grep rule writing and usage, maintained by the ast-grep community. Contains 42 rules across 8 categories, prioritized by impact to guide automated rule generation and code transformation.

When to Apply

Reference these guidelines when:

• Writing new ast-grep rules for linting or search
• Debugging patterns that don't match expected code
• Optimizing rule performance for large codebases
• Setting up ast-grep projects with proper organization
• Reviewing ast-grep rules for correctness and maintainability

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Pattern Correctness	CRITICAL	pattern-
2	Meta Variable Usage	CRITICAL	meta-
3	Rule Composition	HIGH	compose-
4	Constraint Design	HIGH	const-
5	Rewrite Correctness	MEDIUM-HIGH	rewrite-
6	Project Organization	MEDIUM	org-
7	Performance Optimization	MEDIUM	perf-
8	Testing & Debugging	LOW-MEDIUM	test-

Quick Reference

1. Pattern Correctness (CRITICAL)

• pattern-valid-syntax - Use valid parseable code as patterns
• pattern-language-aware - Account for language-specific syntax differences
• pattern-context-selector - Use context and selector for code fragments
• pattern-avoid-comments-strings - Avoid matching inside comments and strings
• pattern-strictness-levels - Configure pattern strictness appropriately
• pattern-kind-vs-pattern - Choose kind or pattern based on specificity needs
• pattern-debug-ast - Use debug query to inspect AST structure

2. Meta Variable Usage (CRITICAL)

• meta-naming-convention - Follow meta variable naming conventions
• meta-single-node - Match single AST nodes with meta variables
• meta-reuse-binding - Reuse meta variables to enforce equality
• meta-underscore-noncapture - Use underscore prefix for non-capturing matches
• meta-named-vs-unnamed - Use double dollar for unnamed node matching
• meta-multi-match-lazy - Understand multi-match variables are lazy

3. Rule Composition (HIGH)

• compose-all-for-and-logic - Use all for AND logic between rules
• compose-any-for-or-logic - Use any for OR logic between rules
• compose-not-for-exclusion - Use not for exclusion patterns
• compose-inside-for-context - Use inside for contextual matching
• compose-has-for-children - Use has for child node requirements
• compose-matches-for-reuse - Use matches for rule reusability

4. Constraint Design (HIGH)

• const-kind-filter - Use kind constraints to filter meta variables
• const-regex-filter - Use regex constraints for text patterns
• const-not-inside-not - Avoid constraints inside not rules
• const-pattern-constraint - Use pattern constraints for structural filtering
• const-post-match-timing - Understand constraints apply after matching

5. Rewrite Correctness (MEDIUM-HIGH)

• rewrite-preserve-semantics - Preserve program semantics in rewrites
• rewrite-meta-variable-reference - Reference all necessary meta variables in fix
• rewrite-transform-operations - Use transform for complex rewrites
• rewrite-test-before-deploy - Test rewrites on representative code
• rewrite-syntax-validity - Ensure fix templates produce valid syntax

6. Project Organization (MEDIUM)

• org-project-structure - Use standard project directory structure
• org-unique-rule-ids - Use unique descriptive rule IDs
• org-severity-levels - Assign appropriate severity levels
• org-file-filtering - Use file filtering for targeted rules
• org-message-clarity - Write clear actionable messages

7. Performance Optimization (MEDIUM)

• perf-specific-patterns - Use specific patterns over generic ones
• perf-stopby-boundaries - Use stopBy to limit search depth
• perf-thread-parallelism - Leverage parallel scanning with threads
• perf-avoid-regex-heavy - Avoid heavy regex in hot paths

8. Testing & Debugging (LOW-MEDIUM)

• test-valid-invalid-cases - Write both valid and invalid test cases
• test-snapshot-updates - Use snapshot testing for fix verification
• test-playground-first - Test patterns in playground first
• test-edge-cases - Test edge cases and boundary conditions

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Full Compiled Document

• AGENTS.md - Complete compiled guide with all rules

Reference Files

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information