# Codemod

> Codemod Best Practices

- Skill: `comeonoliver/codemod` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/codemod`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/codemod/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/codemod

---

# 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

| 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`](references/ast-explore-before-writing.md) - Use AST Explorer before writing patterns
- [`ast-understand-named-vs-anonymous`](references/ast-understand-named-vs-anonymous.md) - Understand named vs anonymous nodes
- [`ast-use-kind-for-precision`](references/ast-use-kind-for-precision.md) - Use kind constraint for precision
- [`ast-field-access-for-structure`](references/ast-field-access-for-structure.md) - Use field access for structural queries
- [`ast-check-null-before-access`](references/ast-check-null-before-access.md) - Check null before property access

### 2. Pattern Efficiency (CRITICAL)

- [`pattern-use-meta-variables`](references/pattern-use-meta-variables.md) - Use meta variables for flexible matching
- [`pattern-avoid-overly-generic`](references/pattern-avoid-overly-generic.md) - Avoid overly generic patterns
- [`pattern-combine-with-rules`](references/pattern-combine-with-rules.md) - Combine patterns with rule operators
- [`pattern-use-constraints`](references/pattern-use-constraints.md) - Use constraints for reusable matching logic
- [`pattern-use-relational-patterns`](references/pattern-use-relational-patterns.md) - Use relational patterns for context
- [`pattern-ensure-idempotency`](references/pattern-ensure-idempotency.md) - Ensure patterns are idempotent

### 3. Parsing Strategy (CRITICAL)

- [`parse-select-correct-parser`](references/parse-select-correct-parser.md) - Select the correct parser for file type
- [`parse-handle-embedded-languages`](references/parse-handle-embedded-languages.md) - Handle embedded languages with parseAsync
- [`parse-provide-pattern-context`](references/parse-provide-pattern-context.md) - Provide context for ambiguous patterns
- [`parse-early-return-non-applicable`](references/parse-early-return-non-applicable.md) - Early return for non-applicable files

### 4. Node Traversal (HIGH)

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

### 5. Semantic Analysis (HIGH)

- [`semantic-use-file-scope-first`](references/semantic-use-file-scope-first.md) - Use file scope semantic analysis first
- [`semantic-check-null-results`](references/semantic-check-null-results.md) - Handle null semantic analysis results
- [`semantic-verify-file-ownership`](references/semantic-verify-file-ownership.md) - Verify file ownership before cross-file edits
- [`semantic-cache-cross-file-results`](references/semantic-cache-cross-file-results.md) - Cache semantic analysis results

### 6. Edit Operations (MEDIUM-HIGH)

- [`edit-batch-before-commit`](references/edit-batch-before-commit.md) - Batch edits before committing
- [`edit-preserve-formatting`](references/edit-preserve-formatting.md) - Preserve surrounding formatting in edits
- [`edit-handle-overlapping-ranges`](references/edit-handle-overlapping-ranges.md) - Handle overlapping edit ranges
- [`edit-use-flatmap-for-conditional`](references/edit-use-flatmap-for-conditional.md) - Use flatMap for conditional edits
- [`edit-add-imports-correctly`](references/edit-add-imports-correctly.md) - Add imports at correct position

### 7. Workflow Design (MEDIUM-HIGH)

- [`workflow-order-nodes-by-dependency`](references/workflow-order-nodes-by-dependency.md) - Order nodes by dependency
- [`workflow-use-matrix-for-parallelism`](references/workflow-use-matrix-for-parallelism.md) - Use matrix strategy for parallelism
- [`workflow-use-manual-gates`](references/workflow-use-manual-gates.md) - Use manual gates for critical steps
- [`workflow-validate-before-run`](references/workflow-validate-before-run.md) - Validate workflows before running
- [`workflow-use-conditional-steps`](references/workflow-use-conditional-steps.md) - Use conditional steps for dynamic workflows

### 8. Testing Strategy (MEDIUM)

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

### 9. State Management (MEDIUM)

- [`state-use-for-resumability`](references/state-use-for-resumability.md) - Use state for resumable migrations
- [`state-make-transforms-idempotent`](references/state-make-transforms-idempotent.md) - Make transforms idempotent for safe reruns
- [`state-log-progress-for-observability`](references/state-log-progress-for-observability.md) - Log progress for long-running migrations

### 10. Security and Capabilities (LOW-MEDIUM)

- [`security-minimize-capabilities`](references/security-minimize-capabilities.md) - Minimize requested capabilities
- [`security-validate-external-inputs`](references/security-validate-external-inputs.md) - Validate external inputs before use
- [`security-review-before-running-third-party`](references/security-review-before-running-third-party.md) - Review third-party codemods before running

### 11. Package Structure (LOW)

- [`pkg-use-semantic-versioning`](references/pkg-use-semantic-versioning.md) - Use semantic versioning for packages
- [`pkg-write-descriptive-metadata`](references/pkg-write-descriptive-metadata.md) - Write descriptive package metadata
- [`pkg-organize-by-convention`](references/pkg-organize-by-convention.md) - Organize package by convention

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Full Compiled Document

For a complete guide with all rules expanded, see [AGENTS.md](AGENTS.md).