名称:代码修改 描述:Codemod (JSSG, ast-grep, workflows) 最佳实践,用于编写高效、安全且可维护的代码转换。此技能应在编写、审查或调试代码修改、AST转换或自动化重构工具时使用。在涉及代码修改、ast-grep、JSSG、代码转换或自动化迁移的任务时触发。
代码修改最佳实践
针对代码修改 (JSSG, ast-grep, workflows) 的综合最佳实践指南,专为AI代理和LLMs设计。包含11个类别的48条规则,按影响优先级排序,以指导自动化重构和代码生成。
何时应用
在以下情况下参考这些指南:
- 使用JSSG或ast-grep编写新代码修改
- 设计迁移的工作流配置
- 调试模式匹配或AST遍历问题
- 审查代码修改代码的性能和安全性
- 设置转换验证的测试夹具
按优先级排序的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | AST理解 | 关键 | ast- |
| 2 | 模式效率 | 关键 | pattern- |
| 3 | 解析策略 | 关键 | parse- |
| 4 | 节点遍历 | 高 | traverse- |
| 5 | 语义分析 | 高 | semantic- |
| 6 | 编辑操作 | 中-高 | edit- |
| 7 | 工作流设计 | 中-高 | workflow- |
| 8 | 测试策略 | 中 | test- |
| 9 | 状态管理 | 中 | state- |
| 10 | 安全与能力 | 低-中 | security- |
| 11 | 包结构 | 低 | pkg- |
快速参考
1. AST理解 (关键)
ast-探索前先编写- 在编写模式前使用AST探索器ast-理解命名与匿名节点- 理解命名与匿名节点ast-使用种类获取精确性- 使用种类约束获取精确性ast-字段访问用于结构查询- 使用字段访问进行结构查询ast-访问前检查空值- 访问属性前检查空值
2. 模式效率 (关键)
pattern-使用元变量- 使用元变量进行灵活匹配pattern-避免过度通用- 避免过度通用模式pattern-结合规则运算符- 结合模式与规则运算符pattern-使用约束- 使用约束实现可重用匹配逻辑pattern-使用关系模式- 使用关系模式处理上下文pattern-确保幂等性- 确保模式幂等
3. 解析策略 (关键)
parse-选择正确解析器- 为文件类型选择正确解析器parse-处理嵌入式语言- 使用parseAsync处理嵌入式语言parse-提供模式上下文- 为模糊模式提供上下文parse-早期返回不适用文件- 对不适用文件早期返回
4. 节点遍历 (高)
traverse-使用find与findAll- 使用find()进行单次匹配,findAll()进行多次匹配traverse-单遍遍历收集- 在单遍遍历中收集多个模式traverse-使用stopBy控制深度- 使用stopBy控制遍历深度traverse-高效使用兄弟节点导航- 高效使用兄弟节点导航traverse-缓存重复查找- 缓存重复节点查找
5. 语义分析 (高)
semantic-优先使用文件范围- 优先使用文件范围语义分析semantic-检查空结果- 处理空语义分析结果semantic-验证文件所有权- 跨文件编辑前验证文件所有权semantic-缓存跨文件结果- 缓存语义分析结果
6. 编辑操作 (中-高)
edit-提交前批处理编辑- 提交前批处理编辑edit-保留格式化- 在编辑中保留周围格式化edit-处理重叠范围- 处理重叠编辑范围edit-使用flatMap进行条件编辑- 使用flatMap进行条件编辑edit-正确添加导入- 在正确位置添加导入
7. 工作流设计 (中-高)
workflow-按依赖排序节点- 按依赖排序节点workflow-使用矩阵实现并行- 使用矩阵策略实现并行化workflow-使用手动门控- 对关键步骤使用手动门控workflow-运行前验证- 运行前验证工作流workflow-使用条件步骤- 为动态工作流使用条件步骤
8. 测试策略 (中)
test-使用夹具对- 使用输入/预期夹具对test-覆盖边缘情况- 在测试夹具中覆盖边缘情况test-使用严格度级别- 选择适当的测试严格度级别test-有意更新夹具- 有意更新测试夹具test-先在子集上测试- 在全量运行前在文件子集上测试
9. 状态管理 (中)
state-使用状态实现可恢复性- 使用状态实现可恢复迁移state-使变换幂等- 使变换幂等以确保安全重跑state-记录进度以观察- 为长运行迁移记录进度
10. 安全与能力 (低-中)
security-最小化能力- 最小化请求的能力security-验证外部输入- 使用前验证外部输入security-运行前审查第三方- 运行前审查第三方代码修改
11. 包结构 (低)
pkg-使用语义版本控制- 为包使用语义版本控制pkg-编写描述性元数据- 编写描述性包元数据pkg-按约定组织- 按约定组织包
如何使用
阅读个别参考文件以获取详细解释和代码示例:
完整编译文档
有关所有规则扩展的完整指南,请参阅 AGENTS.md。