codemod

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codemod Best Practices

Codemod 最佳实践

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.

这是为AI Agent和LLM设计的Codemod（JSSG、ast-grep、工作流）综合最佳实践指南。包含11个类别共48条规则，按影响优先级排序，用于指导自动重构和代码生成。

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

在以下场景中参考本指南：

使用JSSG或ast-grep编写新的codemod
设计用于迁移的工作流配置
调试模式匹配或AST遍历问题
审查codemod代码的性能与安全性
设置用于验证转换的测试夹具

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-`


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

优先级	类别	影响级别	前缀
1	AST理解	关键	`ast-`
2	模式效率	关键	`pattern-`
3	解析策略	关键	`parse-`
4	节点遍历	高	`traverse-`
5	语义分析	高	`semantic-`
6	编辑操作	中高	`edit-`
7	工作流设计	中高	`workflow-`
8	测试策略	中	`test-`
9	状态管理	中	`state-`
10	安全与权限	中低	`security-`
11	包结构	低	`pkg-`

Quick Reference

快速参考

1. AST Understanding (CRITICAL)

1. AST理解（关键）

```
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

```
ast-explore-before-writing
```
- 编写模式前先使用AST Explorer
```
ast-understand-named-vs-anonymous
```
- 理解命名节点与匿名节点的区别
```
ast-use-kind-for-precision
```
- 使用类型约束提高精度
```
ast-field-access-for-structure
```
- 使用字段访问进行结构化查询
```
ast-check-null-before-access
```
- 访问属性前先检查空值

2. Pattern Efficiency (CRITICAL)

2. 模式效率（关键）

```
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

```
pattern-use-meta-variables
```
- 使用元变量实现灵活匹配
```
pattern-avoid-overly-generic
```
- 避免过于宽泛的模式
```
pattern-combine-with-rules
```
- 将模式与规则运算符结合使用
```
pattern-use-constraints
```
- 使用约束实现可复用的匹配逻辑
```
pattern-use-relational-patterns
```
- 使用关系模式获取上下文
```
pattern-ensure-idempotency
```
- 确保模式具有幂等性

3. Parsing Strategy (CRITICAL)

3. 解析策略（关键）

```
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

```
parse-select-correct-parser
```
- 根据文件类型选择正确的解析器
```
parse-handle-embedded-languages
```
- 使用parseAsync处理嵌入式语言
```
parse-provide-pattern-context
```
- 为模糊模式提供上下文
```
parse-early-return-non-applicable
```
- 对不适用的文件提前返回

4. Node Traversal (HIGH)

4. 节点遍历（高）

```
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

```
traverse-use-find-vs-findall
```
- 单个匹配使用find()，多个匹配使用findAll()
```
traverse-single-pass-collection
```
- 在单次遍历中收集多个模式
```
traverse-use-stopby-for-depth
```
- 使用stopBy控制遍历深度
```
traverse-use-siblings-efficiently
```
- 高效使用同级节点导航
```
traverse-cache-repeated-lookups
```
- 缓存重复的节点查询

5. Semantic Analysis (HIGH)

5. 语义分析（高）

```
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

```
semantic-use-file-scope-first
```
- 优先使用文件作用域语义分析
```
semantic-check-null-results
```
- 处理语义分析的空结果
```
semantic-verify-file-ownership
```
- 跨文件编辑前验证文件归属
```
semantic-cache-cross-file-results
```
- 缓存跨文件语义分析结果

6. Edit Operations (MEDIUM-HIGH)

6. 编辑操作（中高）

```
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

```
edit-batch-before-commit
```
- 提交前批量处理编辑操作
```
edit-preserve-formatting
```
- 编辑时保留周围的格式
```
edit-handle-overlapping-ranges
```
- 处理重叠的编辑范围
```
edit-use-flatmap-for-conditional
```
- 使用flatMap处理条件式编辑
```
edit-add-imports-correctly
```
- 在正确位置添加导入语句

7. Workflow Design (MEDIUM-HIGH)

7. 工作流设计（中高）

```
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

```
workflow-order-nodes-by-dependency
```
- 按依赖关系排序节点
```
workflow-use-matrix-for-parallelism
```
- 使用矩阵策略实现并行处理
```
workflow-use-manual-gates
```
- 为关键步骤设置手动审核关卡
```
workflow-validate-before-run
```
- 运行前验证工作流
```
workflow-use-conditional-steps
```
- 使用条件步骤实现动态工作流

8. Testing Strategy (MEDIUM)

8. 测试策略（中）

```
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

```
test-use-fixture-pairs
```
- 使用输入/预期结果的夹具对
```
test-cover-edge-cases
```
- 在测试夹具中覆盖边缘情况
```
test-use-strictness-levels
```
- 选择合适的测试严格级别
```
test-update-fixtures-intentionally
```
- 有目的地更新测试夹具
```
test-run-on-subset-first
```
- 先在文件子集上测试，再全面运行

9. State Management (MEDIUM)

9. 状态管理（中）

```
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

```
state-use-for-resumability
```
- 使用状态实现可恢复的迁移
```
state-make-transforms-idempotent
```
- 使转换具有幂等性以支持安全重跑
```
state-log-progress-for-observability
```
- 记录进度以提升可观测性

10. Security and Capabilities (LOW-MEDIUM)

10. 安全与权限（中低）

```
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

```
security-minimize-capabilities
```
- 最小化请求的权限
```
security-validate-external-inputs
```
- 使用前验证外部输入

security-review-before-running-third-party

- 运行第三方codemod前先审查

11. Package Structure (LOW)

11. 包结构（低）

```
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

```
pkg-use-semantic-versioning
```
- 对包使用语义化版本控制
```
pkg-write-descriptive-metadata
```
- 编写描述性的包元数据
```
pkg-organize-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.

如需包含所有规则扩展内容的完整指南，请查看 AGENTS.md。