Claude Codeで作った setup.bat / start.bat が動かない原因は文字コードだった
Claude Code で Windows 向けのセットアップ用スクリプトや起動用バッチを作らせたとき、 setup.bat や start.bat がうまく動かないことがあります。 一見するとコマンドの書き方やパスの問題に見えますが、実際には .bat ファイルの文字コードが原因になっているケースがあります。
原因は .bat の文字コードだった
今回の原因は、setup.bat と start.bat が 日本語を含んだ UTF-8 のまま保存されていたことでした。
Windows の cmd.exe は、バッチファイルの文字コードや含まれている文字に敏感です。 とくに、日本語を含む UTF-8 の .bat は環境によって正しく解釈されず、 本来は説明文やコメントであるはずの本文が壊れたコマンドとして扱われることがあります。
その結果、バッチファイルの見た目は問題なさそうでも、実行時には行の解釈が崩れ、 起動失敗や意味不明なエラーにつながります。
つまり今回の問題は、処理ロジックそのものではなく、 cmd.exe がファイルを正しく読めていなかったことにありました。
実際に行った修正
今回は、setup.bat と start.bat を ASCII のみで安全に書き直す対応を行いました。
これにより、少なくともバッチファイルそのものが文字コード起因で壊れる状態は解消できました。
修正のポイント
setup.batを ASCII のみで書き直したstart.batを ASCII のみで書き直した- 文字コード起因で
cmd.exeの解釈が壊れる状態を解消した
setup.bat 側であわせて調整したこと
あわせて setup.bat では、フロントエンドの本番ビルド失敗を 致命エラーにしないよう変更しました。
現在の環境では npm run build が、 Vite / Tailwind のネイティブ依存まわりの問題で失敗します。 ただし、これは start.bat による開発起動そのものには必須ではないため、 セットアップ全体がそこで止まらないようにしています。
確認できた範囲
setup.bat は実行確認済みです。
一方で start.bat は、別コンソール起動やブラウザ起動を含むため、 sandbox 環境では最後までの実地確認はしていません。 ただし、少なくとも 文字コードが原因でバッチファイルそのものが壊れる状態は解消済みです。
残っている問題は別件
現時点で残っているのは 1 点で、フロントエンド側の npm run build が Vite / Tailwind のネイティブ依存まわりの別問題で失敗していることです。
これは .bat の文字コード問題とは別件です。 つまり今回の修正で「バッチが壊れている問題」は直ったものの、 ビルドが落ちる原因は別に存在している、という整理になります。
Claude Code に .bat を作らせるときの対策
今回の件で重要なのは、 Windows 用の .bat は最初から ASCII 限定で作らせるべき ということです。
Claude Code は自然言語でファイルを生成できる反面、 説明コメントやメッセージ文に日本語を混ぜたバッチをそのまま出力しがちです。 しかし Windows の cmd.exe では、それが不安定要因になります。
Windows の
.batファイルは ASCII のみで作成すること。
日本語コメント、日本語メッセージ、UTF-8 依存の文字列は入れないこと。
この指示を最初から与えておくだけで、 文字コード由来の起動不能をかなり避けやすくなります。
まとめ
Claude Code で作った Windows バッチが動かないとき、 原因は必ずしもロジックミスとは限りません。 .bat の文字コード、特に日本語入り UTF-8 が原因で cmd.exe の解釈が壊れていることがあります。
今回も setup.bat と start.bat を ASCII のみで書き直すことで、 少なくともバッチファイル自体が壊れて実行不能になる問題は解消できました。
Claude Code で Windows 向けスクリプトを作るなら、対策はシンプルです。
.bat は最初から ASCII 限定で生成させる。
これだけでも、ハマりどころを 1 つ大きく減らせます。
コメント