这是对你的 AGENTS.md 或 CLAUDE.md 文件的一个实用补充。如果你还没有安装 ast-grep，请先联系 codex 或 claude code 让他们帮你安装。 它非常方便，可以系统地查找代码中的一般模式，而使用不具备语法感知能力的常规字符串匹配可能很难做到这一点。
以下是明文： ### ast-grep 与 ripgrep 对比（快速指南） **当结构很重要时，请使用 `ast-grep`。** 它可以解析代码并匹配 AST 节点，因此结果会忽略注释/字符串，理解语法，并且可以**安全地重写**代码。 * 重构/代码修改：重命名 API、更改导入形式、重写调用点或变量类型。 * 策略检查：在整个存储库中强制执行模式（使用规则的 `scan` + `test`）。 * 编辑器/自动化：LSP 模式；`--json` 输出供工具使用。 **如果文本量足够，请使用 `ripgrep`。** 这是在文件中查找字面值/正则表达式的最快方法。 * 侦察：查找字符串、待办事项、日志行、配置值或非代码资产。 * 预筛选：在进行精确筛选之前缩小候选文件范围。 **经验法则** * 需要的是正确性而不是速度，否则你将**应用更改** → 从 `ast-grep` 开始。 * 需要极致速度或者你只是**搜索文本** → 从`rg`开始。 * 通常结合使用：`rg` 筛选文件，然后使用 `ast-grep` 精确匹配/修改。 **片段** 查找结构化代码（忽略注释/字符串）： ```bash ast-grep run -l TypeScript -p 'import $X from "$P"' ``` Codemod（只有真正的 `var` 声明会变成 `let`）： ```bash ast-grep run -l JavaScript -p 'var $A = $B' -r 'let $A = $B' -U ``` 快速文本搜索： ```bash rg -n 'console\.log\(' -t js ``` 速度与精准度兼备： ```bash rg -l -t ts 'useQuery\(' | xargs ast-grep run -l TypeScript -p 'useQuery($A)' -r 'useSuspenseQuery($A)' -U ``` 心智模型 * 匹配单位：`ast-grep` = 节点；`rg` = 行。 * 误报率：`ast-grep` 低；`rg` 取决于你的正则表达式。 * 重写：`ast-grep` 是一流的；`rg` 需要临时的 sed/awk，并且有造成附带编辑的风险。