這是你的 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，並且有造成附帶編輯的風險。