Claude Code で日本語ファイルが文字化けする時の対処 — Shift-JIS と UTF-8 を見分けて安全に変換する

廣川政樹です。2014年から個人開発でアプリを公開し続けて12年、累計5,000万ダウンロードを超えました。長年運営している壁紙アプリのカテゴリ管理 CSV や、古いブログから引き継いだログファイルを Claude Code に読ませようとした時、Read ツールの出力が「縺ゅ＞縺ゅ＞」のような記号の羅列になり、修正どころか内容を確認することすらできなくなる現象に何度もぶつかってきました。

原因はほぼ常にエンコーディングです。Claude Code の Read ツールは内部的に UTF-8 として解釈するため、Shift-JIS や EUC-JP で保存されたファイルはそのままだと崩れます。慌てて Edit ツールで上書きするとファイルが破壊されるので、判定 → 変換 → 確認の順番を守ることが大切です。現場でそのまま使える判定コマンドと変換手順を、自分の運用ノウハウとして残しておきます。

文字化けの典型パターンと、どのエンコーディングが疑わしいか

化けた文字列を眺めるだけで、ある程度元のエンコーディングが推測できます。よくあるパターンを覚えておくと、診断の入口がぐっと楽になります。

• 「縺ゅ＞縺ゅ＞」「繧定ｪｭ縺ｿ」のように「縺」「繧」「ｦ」が頻出する → 元は UTF-8 だが、Shift-JIS として読まれて二重に壊れている。あるいは Read 側が UTF-8 を別エンコーディングと誤判定している可能性
• 「・ｱ・ｱ・ｱ」のような半角カナ風の点列 → 元は Shift-JIS を UTF-8 として読んでしまったケース。ターミナルでよく見る
• 先頭3バイトが EF BB BF で始まる → UTF-8 BOM 付き。エディタによっては問題ないが、シェルスクリプトや CSV パーサーでは余計な不可視文字としてエラー要因になる
• ASCII 文字（半角英数）は読めるのに日本語だけ崩れる → マルチバイト境界が崩れた典型

私の場合は古いアプリのリリースノートが EUC-JP で残っていて、Claude Code に渡す前に毎回変換する必要がありました。「日本語が壊れている時はまず疑う」というチェックリストを claude.md に書いておくと、再発した時の対応が早くなります。

1分でできるエンコーディング判定

Bash ツールから以下のコマンドを叩けば、ファイルの実エンコーディングをほぼ確定できます。

# 1. file コマンドで素早く判定（macOS / Linux 標準）
file -bi notes_legacy.csv
# 出力例:
#   text/plain; charset=utf-8
#   text/plain; charset=iso-8859-1   ← 「unknown 8bit」の典型。SJIS の可能性大
#   text/plain; charset=us-ascii
 
# 2. nkf -g で日本語に強い判定（要 brew install nkf）
nkf -g notes_legacy.csv
# 出力例:
#   Shift_JIS
#   EUC-JP
#   UTF-8
 
# 3. 先頭バイトを直接見る（BOM 検出に確実）
head -c 16 notes_legacy.csv | hexdump -C
# 先頭 EF BB BF → UTF-8 BOM 付き
# 先頭 FF FE     → UTF-16 LE
# 先頭 FE FF     → UTF-16 BE

経験上、file -bi で iso-8859-1 と出たら 90% は Shift-JIS、unknown-8bit と出たら EUC-JP の可能性が残ります。決め手がほしい時は nkf -g を使ってください。Claude Code 上で nkf が入っていなければ、brew install nkf（macOS）または apt install nkf（Linux）で導入できます。

Read ツールに渡す前に UTF-8 へ変換する

判定が済んだら、元ファイルを直接書き換えるのではなく UTF-8 化したコピーを別名で作る のが安全です。元ファイルを残しておけば、変換ミスがあっても巻き戻せます。

# Shift-JIS → UTF-8（最も多いパターン）
iconv -f CP932 -t UTF-8 notes_legacy.csv > notes_legacy.utf8.csv
 
# CP932 を使う理由: Windows 由来の Shift-JIS は厳密には CP932（マイクロソフト拡張）。
# Shift_JIS 指定だと「①」「㈱」「髙」などの機種依存文字で変換に失敗する
 
# EUC-JP → UTF-8
iconv -f EUC-JP -t UTF-8 old_release_notes.txt > old_release_notes.utf8.txt
 
# UTF-8 BOM を除去（CSV パーサーが BOM で詰まる時）
sed -i.bak '1s/^\xEF\xBB\xBF//' data.csv
 
# 変換失敗時に止まらないよう // 修飾を付ける（壊れた文字を ? に置換）
iconv -f CP932 -t UTF-8//TRANSLIT//IGNORE notes_legacy.csv > notes_legacy.utf8.csv

iconv で unknown character エラーが出る場合、ほとんどは機種依存文字（丸数字・ローマ数字・旧字体）が原因です。//TRANSLIT//IGNORE を付けると、変換不能な文字を黙って削除するため、業務 CSV の取り込みには現実的な選択です。

変換後は必ず head で目視確認してから Claude Code の Read ツールに渡してください。

head -3 notes_legacy.utf8.csv
file -bi notes_legacy.utf8.csv  # charset=utf-8 を確認

Claude Code 経由でまとめて変換するワークフロー

複数ファイルを一括で変換する時は、Bash ツールで for ループを回します。Claude Code 側からの呼び出しを想定して、出力の冗長性を抑える書き方にしておくと結果を確認しやすくなります。

# .legacy/ 配下の Shift-JIS ファイルをまとめて .utf8/ に変換
mkdir -p .utf8
for f in .legacy/*.csv; do
  out=".utf8/$(basename "$f")"
  enc=$(nkf -g "$f")
  case "$enc" in
    "Shift_JIS")
      iconv -f CP932 -t UTF-8//TRANSLIT "$f" > "$out" && echo "OK   sjis  $f"
      ;;
    "EUC-JP")
      iconv -f EUC-JP -t UTF-8//TRANSLIT "$f" > "$out" && echo "OK   eucjp $f"
      ;;
    "UTF-8"|"BINARY")
      cp "$f" "$out" && echo "SKIP utf8  $f"
      ;;
    *)
      echo "WARN $enc $f"
      ;;
  esac
done

実際にこのスクリプトを壁紙アプリのカテゴリ管理 CSV（約120ファイル）に流して、Shift-JIS と UTF-8 が混在していた状態を一晩で整理しました。Claude Code に「.utf8/ 配下を読んでカテゴリの重複をチェックして」と頼めば、もう文字化けに悩まされません。

それでも化ける時に確認したい4つの落とし穴

1. Git の core.autocrlf が悪さをしている: Windows 側で true、macOS / Linux で false のように混在すると、改行とエンコーディングがずれることがあります。プロジェクト直下に .gitattributes を置き *.csv text working-tree-encoding=CP932 eol=crlf のように指定すると、Git レベルで自動変換できます
2. CSV の区切り文字が TAB や ; になっている: 日本語自体は読めているのに崩れて見える場合は、エンコーディングではなくデリミタの問題かもしれません。head -1 で1行目を確認してください
3. Claude Code の Bash 出力が UTF-8 を期待している: LANG=ja_JP.UTF-8 が設定されていない環境では echo の結果すら化けます。locale コマンドで確認し、必要なら export LANG=ja_JP.UTF-8 LC_ALL=ja_JP.UTF-8 を実行してください
4. エディタが BOM を勝手に付ける: VSCode のエンコーディング設定で「Save with BOM」を切ってあるか、.editorconfig で charset = utf-8 を明示しているかを確認します

私自身、App Store Connect から落としてきた古い売上 CSV が CP932 のまま渡ってきて、pandas.read_csv が ParserError を吐き続けて1時間溶かしたことがあります。最初に file -bi を打つ習慣をつけておけば、こうした遠回りは防げるはずです。

エンコーディングを「触らずに済む」ように予防する

文字化け対応のうちもっとも時間がかかるのは、判定や変換そのものではなく、後から発覚してやり直すことです。新規にファイルを生成する段階で UTF-8 を強制してしまえば、Claude Code を含むモダンなツールチェーンとは原則ぶつかりません。

私が運営している複数のアプリプロジェクトでは、最低限次の3つを守るようにしています。

• 新規ファイルはエディタ側で「UTF-8（BOM なし）」を既定にしておく
• CSV のダウンロード元（管理画面・スプレッドシートのエクスポート）で UTF-8 を選べるなら必ず選ぶ
• 受け取った時点で file -bi をかけて、Shift-JIS 混入を即時に検知する

特に3つ目は、レガシーファイルを Claude Code に投げる前のチェックポイントとして強力です。Pre-commit フックや、リポジトリ直下の Makefile に check-encoding ターゲットを置いておけば、チームメンバーや将来の自分にも同じ規約を引き継げます。

# Makefile に置いておくと便利な検査ターゲット
check-encoding:
	@for f in $$(git ls-files '*.csv' '*.txt' '*.md'); do \
		enc=$$(file -bi "$$f" | sed 's/.*charset=//'); \
		if [ "$$enc" != "utf-8" ] && [ "$$enc" != "us-ascii" ] && [ "$$enc" != "binary" ]; then \
			echo "NG  $$enc  $$f"; \
		fi; \
	done

このようなガードを敷いておくと、Claude Code 側で「読めない」「壊した」というトラブルが手前で止まり、結果として作業時間も短くなります。

次に試すこと

文字化けに遭遇したら、ぜひ次の流れを試してみてください。

1. file -bi <ファイル名> で素性を判定する
2. 怪しい場合は nkf -g でセカンドオピニオンを取る
3. iconv -f CP932 -t UTF-8//TRANSLIT//IGNORE で UTF-8 化コピーを別名作成
4. head と file -bi で目視確認してから Claude Code の Read ツールに渡す

レガシーファイルを安全に扱えるようになると、過去資産を Claude Code に読み込ませて分析・リファクタする幅が一気に広がります。同じ課題に取り組んでいる方の参考になれば幸いです。