codemod

Original：🇺🇸 English

Translated

Codemod (JSSG, ast-grep, workflows) best practices for writing efficient, safe, and maintainable code transformations. This skill should be used when writing, reviewing, or debugging codemods, AST transformations, or automated refactoring tools. Triggers on tasks involving codemod, ast-grep, JSSG, code transformation, or automated migration.

2installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-skills codemod

SKILL.md Content

View Translation Comparison →

Codemod Best Practices

Comprehensive best practices guide for Codemod (JSSG, ast-grep, workflows), designed for AI agents and LLMs. Contains 48 rules across 11 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

Writing new codemods with JSSG or ast-grep
Designing workflow configurations for migrations
Debugging pattern matching or AST traversal issues
Reviewing codemod code for performance and safety
Setting up test fixtures for transform validation

Rule Categories by Priority


ast-
pattern-
parse-
traverse-
semantic-
edit-
workflow-
test-
state-
security-
pkg-

Priority	Category	Impact	Prefix
1	AST Understanding	CRITICAL	`ast-`
2	Pattern Efficiency	CRITICAL	`pattern-`
3	Parsing Strategy	CRITICAL	`parse-`
4	Node Traversal	HIGH	`traverse-`
5	Semantic Analysis	HIGH	`semantic-`
6	Edit Operations	MEDIUM-HIGH	`edit-`
7	Workflow Design	MEDIUM-HIGH	`workflow-`
8	Testing Strategy	MEDIUM	`test-`
9	State Management	MEDIUM	`state-`
10	Security and Capabilities	LOW-MEDIUM	`security-`
11	Package Structure	LOW	`pkg-`

Quick Reference

1. AST Understanding (CRITICAL)

```
ast-explore-before-writing
```
- Use AST Explorer before writing patterns
```
ast-understand-named-vs-anonymous
```
- Understand named vs anonymous nodes
```
ast-use-kind-for-precision
```
- Use kind constraint for precision
```
ast-field-access-for-structure
```
- Use field access for structural queries
```
ast-check-null-before-access
```
- Check null before property access

2. Pattern Efficiency (CRITICAL)

```
pattern-use-meta-variables
```
- Use meta variables for flexible matching
```
pattern-avoid-overly-generic
```
- Avoid overly generic patterns
```
pattern-combine-with-rules
```
- Combine patterns with rule operators
```
pattern-use-constraints
```
- Use constraints for reusable matching logic
```
pattern-use-relational-patterns
```
- Use relational patterns for context
```
pattern-ensure-idempotency
```
- Ensure patterns are idempotent

3. Parsing Strategy (CRITICAL)

```
parse-select-correct-parser
```
- Select the correct parser for file type
```
parse-handle-embedded-languages
```
- Handle embedded languages with parseAsync
```
parse-provide-pattern-context
```
- Provide context for ambiguous patterns
```
parse-early-return-non-applicable
```
- Early return for non-applicable files

4. Node Traversal (HIGH)

```
traverse-use-find-vs-findall
```
- Use find() for single match, findAll() for multiple
```
traverse-single-pass-collection
```
- Collect multiple patterns in single traversal
```
traverse-use-stopby-for-depth
```
- Use stopBy to control traversal depth
```
traverse-use-siblings-efficiently
```
- Use sibling navigation efficiently
```
traverse-cache-repeated-lookups
```
- Cache repeated node lookups

5. Semantic Analysis (HIGH)

```
semantic-use-file-scope-first
```
- Use file scope semantic analysis first
```
semantic-check-null-results
```
- Handle null semantic analysis results
```
semantic-verify-file-ownership
```
- Verify file ownership before cross-file edits
```
semantic-cache-cross-file-results
```
- Cache semantic analysis results

6. Edit Operations (MEDIUM-HIGH)

```
edit-batch-before-commit
```
- Batch edits before committing
```
edit-preserve-formatting
```
- Preserve surrounding formatting in edits
```
edit-handle-overlapping-ranges
```
- Handle overlapping edit ranges
```
edit-use-flatmap-for-conditional
```
- Use flatMap for conditional edits
```
edit-add-imports-correctly
```
- Add imports at correct position

7. Workflow Design (MEDIUM-HIGH)

```
workflow-order-nodes-by-dependency
```
- Order nodes by dependency
```
workflow-use-matrix-for-parallelism
```
- Use matrix strategy for parallelism
```
workflow-use-manual-gates
```
- Use manual gates for critical steps
```
workflow-validate-before-run
```
- Validate workflows before running
```
workflow-use-conditional-steps
```
- Use conditional steps for dynamic workflows

8. Testing Strategy (MEDIUM)

```
test-use-fixture-pairs
```
- Use input/expected fixture pairs
```
test-cover-edge-cases
```
- Cover edge cases in test fixtures
```
test-use-strictness-levels
```
- Choose appropriate test strictness level
```
test-update-fixtures-intentionally
```
- Update test fixtures intentionally
```
test-run-on-subset-first
```
- Test on file subset before full run

9. State Management (MEDIUM)

```
state-use-for-resumability
```
- Use state for resumable migrations
```
state-make-transforms-idempotent
```
- Make transforms idempotent for safe reruns
```
state-log-progress-for-observability
```
- Log progress for long-running migrations

10. Security and Capabilities (LOW-MEDIUM)

```
security-minimize-capabilities
```
- Minimize requested capabilities
```
security-validate-external-inputs
```
- Validate external inputs before use
```
security-review-before-running-third-party
```
- Review third-party codemods before running

11. Package Structure (LOW)

```
pkg-use-semantic-versioning
```
- Use semantic versioning for packages
```
pkg-write-descriptive-metadata
```
- Write descriptive package metadata
```
pkg-organize-by-convention
```
- Organize package by convention

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

For a complete guide with all rules expanded, see AGENTS.md.