Back to Details

analyzing-code-structure

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ast-grep: Structural Code Search and Editing

ast-grep：结构化代码搜索与编辑

Always invoke the ast-grep skill for structural code search and refactoring - do not execute bash commands directly.
请始终调用analyzing-code-structure技能进行结构化代码搜索与重构——不要直接执行bash命令。

Default Strategy

默认策略

Invoke analyzing-code-structure skill for structural code search and refactoring. Use when:
  • Text-based Edit tool fails with "old_string not unique"
  • Need formatting-independent pattern matching
  • Performing structural changes across code
Common workflow: Invoke extracting-code-structure skill first, then analyzing-code-structure skill for structural modifications.
Use ast-grep to solve the "old_string not unique" problem by matching code structure instead of exact text. This enables refactoring across formatting variations and structural patterns.
调用analyzing-code-structure技能进行结构化代码搜索与重构。适用于以下场景：
  • 基于文本的编辑工具因“old_string不唯一”而执行失败
  • 需要与格式无关的模式匹配
  • 对代码进行跨范围的结构性修改
常见工作流：先调用extracting-code-structure技能，再调用analyzing-code-structure技能进行结构化修改。
使用ast-grep通过匹配代码结构而非精确文本来解决“old_string不唯一”问题，这支持跨不同格式变体和结构模式的重构操作。

When to Use analyzing-code-structure vs Text Tools

何时使用analyzing-code-structure vs 文本工具

Use analyzing-code-structure when:

选择analyzing-code-structure的场景：

  • Structural code changes - Refactoring function signatures, method calls, class structures
  • Formatting-independent matching - Need to find code regardless of whitespace/line breaks
  • Pattern variations - Matching similar structures with different variable names/arguments
  • "old_string not unique" problem - Edit tool fails because text appears in multiple contexts
  • Complex queries - Finding nested structures, specific AST patterns
  • 结构性代码变更——重构函数签名、方法调用、类结构
  • 与格式无关的匹配——需要忽略空格/换行来查找代码
  • 模式变体匹配——匹配具有不同变量名/参数的相似结构
  • “old_string不唯一”问题——编辑工具因文本出现在多个上下文而执行失败
  • 复杂查询——查找嵌套结构、特定AST模式

Use text tools (Edit/Grep) when:

选择文本工具（Edit/Grep）的场景：

  • Simple, unique string replacement - The exact text appears once or in consistent format
  • Non-code files - Markdown, configs, data files
  • Comment/documentation edits - Content that isn't code structure
  • Very small changes - Single line, obvious context, no ambiguity
  • 简单、唯一字符串替换——精确文本仅出现一次或格式一致
  • 非代码文件——Markdown、配置文件、数据文件
  • 注释/文档编辑——不属于代码结构的内容
  • 极小变更——单行、上下文明确、无歧义

Key Decision Rule

核心决策规则

If editing code structure and there's any ambiguity in text matching → use analyzing-code-structure.
ast-grep's primary value: Solves the "old_string not unique" problem by matching structure instead of exact text.
如果要编辑代码结构且文本匹配存在任何歧义→使用analyzing-code-structure。
ast-grep的核心价值：通过匹配结构而非精确文本来解决“old_string不唯一”问题。

Detailed Reference

详细参考

For comprehensive patterns, syntax, metavariables, common use cases, language-specific tips, and best practices, load analyzing-code-structure guide when needing:
  • Complex pattern matching with metavariables
  • Language-specific syntax variations
  • Advanced refactoring workflows
  • Integration with other tools
  • Common pitfalls and solutions
The reference includes:
  • Pattern syntax and metavariables (
    $VAR
    , 
    $$$ARGS
    , 
    $$STMT
    )
  • Recommended workflow (search, verify, apply, validate)
  • Common use cases with examples (function calls, imports, method renames)
  • Language-specific tips (JavaScript/TypeScript, Python, Go, Rust)
  • Best practices and pitfalls to avoid
  • Integration strategies with Edit tool
如需了解全面的模式、语法、元变量、常见用例、语言特定技巧和最佳实践，请在需要以下内容时加载analyzing-code-structure指南：
  • 使用元变量进行复杂模式匹配
  • 特定语言的语法变体
  • 高级重构工作流
  • 与其他工具的集成
  • 常见陷阱与解决方案
该参考文档包含：
  • 模式语法与元变量（
    $VAR
    、
    $$$ARGS
    、
    $$STMT
    ）
  • 推荐工作流（搜索、验证、应用、确认）
  • 带示例的常见用例（函数调用、导入、方法重命名）
  • 特定语言技巧（JavaScript/TypeScript、Python、Go、Rust）
  • 最佳实践与需避免的陷阱
  • 与Edit工具的集成策略

Skill Combinations

技能组合

For Discovery Phase

发现阶段

  • extracting-code-structure → analyzing-code-structure: Get code outline first, then perform structural refactoring
  • searching-text → analyzing-code-structure: Search text patterns to locate areas needing structural changes
  • finding-files → analyzing-code-structure: Find files of specific type, then apply structural modifications
  • extracting-code-structure → analyzing-code-structure：先获取代码大纲，再执行结构化重构
  • searching-text → analyzing-code-structure：搜索文本模式以定位需要结构性变更的区域
  • finding-files → analyzing-code-structure：找到特定类型的文件，再应用结构性修改

For Analysis Phase

分析阶段

  • analyzing-code-structure → viewing-files: Preview changes with syntax highlighting before committing
  • analyzing-code-structure → searching-text: Verify no unintended occurrences remain
  • analyzing-code-structure → extracting-code-structure: Validate structural changes against code outline
  • analyzing-code-structure → viewing-files：在提交变更前，通过语法高亮预览修改内容
  • analyzing-code-structure → searching-text：验证是否存在未预期的残留内容
  • analyzing-code-structure → extracting-code-structure：对照代码大纲验证结构性变更

For Refactoring Phase

重构阶段

  • analyzing-code-structure → analyzing-code: Measure changes impact on code statistics
  • analyzing-code-structure → replacing-text: Follow structural changes with text-based replacements if needed
  • analyzing-code-structure → querying-json/querying-yaml: Update configuration files related to code changes
  • analyzing-code-structure → analyzing-code：评估变更对代码统计数据的影响
  • analyzing-code-structure → replacing-text：如果需要，在结构性变更后执行基于文本的替换
  • analyzing-code-structure → querying-json/querying-yaml：更新与代码变更相关的配置文件