clj-replace

clj-replace：Clojure コードの構造的置換

Clojure を認識するコード置換ツールです。リテラルテキストではなく、コード構造（S 式）を比較することで、Claude Code に組み込まれている str_replace を改良しています。

使用する場面

次のような場合に /clj-replace を使用してください。

• 書式（空白、インデント、改行）が old_string と対象コードで異なるため、Claude Code の str_replace が失敗する場合
• コードを置換したいものの、空白や書式がソースと完全には一致しない場合
• 元のファイルの書式やスタイルを保ったまま置換したい場合

例： コード構造が同じに見えるのに str_replace が「old_string not found」で失敗する場合は、clj-replace に切り替えてください。

仕組み

clj-replace は文字単位でテキストを比較する代わりに、構造的な比較を行います。

1. old-string とファイルの内容を S 式ツリー（ジッパー）にパースします
2. ファイル内をたどり、各ノードの構造（S 式に対する =）を対象と比較します
3. 比較時には書式の違い（空白、インデント、改行）を無視します
4. 一致が見つかると、元のファイルの書式を保ったままノードを置換します

つまり、以下はすべて同等として扱われます。

(foo bar)          ≡ (foo  bar)        ≡ (foo
                                           bar)

パラメーター

位置引数：

1. filename — 変更する Clojure ソースファイルのパス
2. old-string — 検索するコードスニペット（文字列）
3. new-string — 置換後のコードスニペット（文字列）

使い方

/clj-replace path/to/file.clj "old code here" "new code here"

例

例 1：空白の違い

ファイルの内容：

(defn update-user
  [db id attrs]
  (merge-user db id attrs))

コマンド：

/clj-replace src/app.clj "(merge-user db id attrs)" "(update-user-in-db db id attrs)"

ファイルのインデントが異なっていても動作します。ファイルのスタイルを保ちながら、該当するフォームを正確に置換します。

例 2：複数行のフォーム

ファイルの内容：

(some-function
  arg1
  arg2
  arg3)

コマンド：

/clj-replace src/app.clj "(some-function arg1 arg2 arg3)" "(other-function arg1 arg2 arg3)"

元のコードの複数行にわたる書式にかかわらず一致します。

終了コード

• 0 — 成功：1 つ以上のノードを置換しました
• 1 — エラー：ファイルが存在しないか、old-string または new-string が有効な Clojure ではありません
• 2 — エラー：ファイル内に一致する S 式が見つかりません
• 3 — エラー：一致する S 式が複数見つかりました（曖昧です）。ユーザーはより具体的な old-string を指定する必要があります

出力

成功時：

✓ Replaced 1 node(s) in path/to/file.clj
  Location: line 42, column 5
  Old: (merge-user db id attrs)
  New: (update-user-in-db db id attrs)

一致する箇所が複数ある場合：

✗ Found 3 matching S-expressions in path/to/file.clj (ambiguous)
  1. line 42, column 5: (foo bar)
  2. line 85, column 10: (foo bar)
  3. line 120, column 1: (foo bar)
Please provide a more specific old-string (e.g., include surrounding context)

実装の詳細

rewrite-clj ライブラリを使用して、以下を行います。

• 書式を保ったパースと変更
• S 式の構造的比較
• 空白やスタイルを維持する安全なノード置換

このツールは Clojure のセマンティクスに従います。表面的な書式にかかわらず、同じ構造にパースされる 2 つの式は同等です。