この記事でわかること

  • WindowsでClaude Codeを使うときにずれやすい3つのこと
  • 表示とファイルの文字化けの見分け方
  • BOMと改行コードの確かめ方と直し方
  • Claude Codeに守らせるWindowsのルールの書き方

使い始めの手順はClaude Codeの始め方と使い方で紹介しています。ここではWindowsに特有の注意点を扱います。

WindowsでClaude Codeを使うときにずれやすい3つのこと

WindowsでもClaude Codeはそのまま使えます。PowerShellやコマンドプロンプトからインストールでき、WSLの中で使うこともできます。

Git for Windowsは必須ではありません。入れると、Claude CodeはGit Bashでコマンドを実行します。入れていない場合は、PowerShellで実行します。PowerShellは、PowerShell 7があればそちらを使い、なければWindows PowerShell 5.1を使います。そのため、次の3つがずれやすくなります。

  • シェル: Git BashとPowerShellで、同じ書き方が通らないことがある
  • 文字コード: 道具によって、UTF-8の先頭にBOMが付いたり付かなかったりする
  • 改行コード: WindowsのCRLFとLinuxのLFが混ざる

STEP 1 環境を読み取りで確かめる

直す前に、どのシェルとPowerShellの版で作業しているかと、Gitの改行の設定を確かめます。

【用途】PowerShellの版とGitの設定を確かめる ／【実行場所】PowerShell ／【状態変更】なし(読み取り)

$PSVersionTable.PSVersion
git --version
git config --show-origin --get core.autocrlf

1行目が5ならWindows PowerShell 5.1、7以上ならPowerShell 7です。3行目は改行の設定の値と、それがどの設定ファイルに書かれているかを表示します。

Claude Code自体は、claude doctor で何も変えずに診断できます。

STEP 2 文字コードとBOMを確かめて直す

表示の文字化けか、ファイルの文字化けかを分ける

画面の日本語が崩れても、ファイルの中身は正しいことがあります。逆に、読めても先頭にBOMが付いていることもあります。エディタで開いて読めるかと、先頭のバイトを確かめます。ファイルを変換するのは、ファイルの中身の問題だと分かってからです。

ファイルの先頭のバイトを見る

【用途】ファイルの先頭のバイトを確かめる ／【実行場所】PowerShell ／【状態変更】なし(読み取り)

Format-Hex -Path sample.txt | Select-Object -First 1

先頭が EF BB BF なら、BOM付きのUTF-8です。BOMのないUTF-8の日本語は、E3 などの文字のバイトから始まります。0D 0A が並んでいれば、改行はCRLFです。

PowerShellの版で書き出す文字コードが違う

Windows PowerShell 5.1では、-Encoding UTF8 を指定するとBOM付きのUTF-8になります。指定しない場合の既定は命令によって違い、Out-File と > はUTF-16LE、Set-Content は新しいファイルにシステムのANSIのコードページを使います。BOMのないファイルを読むときも、Get-Content はANSIとして読みます。

PowerShell 7は、既定でBOMなしのUTF-8です。

BOMを付けるかどうかの判断

BOMは、常に悪いものでも、常に必要なものでもありません。

  • Linuxで読む設定ファイルやシェルスクリプトは、BOMなしにする(Linuxの多くのツールはBOMを扱えない)
  • 日本語を含むPowerShellのスクリプトをWindows PowerShell 5.1で動かすなら、BOM付きで保存する

直すときは、対象のファイルだけ文字コードを指定して保存し直します。フォルダ全体を一括で変換しないでください。

STEP 3 改行コードをリポジトリ単位でそろえる

今の改行コードを確かめる

【用途】ファイルごとの改行コードを確かめる ／【実行場所】Git Bash ／【状態変更】なし(読み取り)

git ls-files --eol

i/ はGitに記録された内容、w/ は手元のファイル、attr/ は.gitattributesの指定です。i/crlf や i/mixed は記録の改行がそろっていない状態、i/lf で w/crlf は手元のファイルだけがCRLFの状態です。

設定より先に.gitattributesを考える

core.autocrlf は利用者ごとの設定で、--global で変えると、その人のすべてのリポジトリに効きます。.gitattributesはリポジトリに入るので、使う人全員に同じ指定が効きます。.gitattributesで text を指定したファイルには、core.autocrlf は使われません。

【用途】.gitattributesの例 ／【実行場所】リポジトリの直下に置くファイル ／【状態変更】あり(ファイルを追加)

* text=auto
*.sh text eol=lf

1行目はテキストをGitに判断させて記録をLFにそろえ、2行目はLinuxで動かすシェルスクリプトを手元でもLFにします。これは一例です。どのファイルをどの改行にするかは、リポジトリの今の決まりと使う環境に合わせて決めます。

記録された改行をそろえ直す

.gitattributesを足しただけでは、記録済みのファイルは変わりません。そろえ直す git add --renormalize . は多くのファイルを変えることがあるため、次の順で進めます。

  1. git status で、ほかの変更がないことを確かめる(あれば先にコミット)
  2. そろえ直す
  3. 結果を確かめてから、単独でコミットする

【用途】記録された改行をそろえ直して確かめる ／【実行場所】Git Bash(リポジトリの直下) ／【状態変更】あり(2行目がGitの記録を変える。ほかは読み取り)

git status
git add --renormalize .
git diff --cached --stat
git diff --cached --check
git ls-files --eol

変わったファイルが想定より多い・改行以外の変更が混ざるときは、コミットせずに git restore --staged . で取り消します。コミットの後なら git revert で戻せます。テストがあれば、コミットの前に実行します。--renormalize が変えるのはGitの記録で、手元のファイルの改行は取り出し直すまで変わらないことがあります。

Linuxへ送るファイルは送る前と後で確かめる

Windowsで正しく表示できても、Linuxでそのまま使えるとは限りません。送る前に、BOMの有無と改行コードを確かめます。Gitに記録した内容を送ると、手元の改行の設定に左右されません。送った後はハッシュ(SHA-256)を比べます。サーバー側の状態の確かめ方はサーバーの状態確認をClaude Codeに読み取り専用で任せる方法で紹介しています。

STEP 4 WindowsのルールをCLAUDE.mdに書く

Windowsの事情は、毎回の依頼で説明するより、CLAUDE.mdに書いておくほうが確実です。書き方そのものはCLAUDE.mdの書き方で紹介しています。

【用途】CLAUDE.mdに書くWindowsのルールの例 ／【実行場所】CLAUDE.md ／【状態変更】あり(ファイルを編集)

## Windowsでの作業
- コマンドはGit Bashで実行する(PowerShellを使うときは先に書く)
- 日本語を含むファイルは、ファイルの編集機能で書く。PowerShellの文字列の置換で書き換えない
- 新しいテキストファイルはUTF-8(BOMなし)・改行LFで作る
- Linuxへ送るファイルは、送る前に文字コードと改行コードを確かめる
- 設定やファイルを変える前に、git status と git ls-files --eol で状態を確かめる
- パスワードや鍵などの値を出力に出さない

日本語のファイルをWindows PowerShell 5.1の読み書きで置き換えると、BOMのないUTF-8をANSIとして読んでしまい、文字化けの原因になります。変更の前の調査は、次のように頼みます。

【用途】文字コードと改行の調査を頼む ／【実行場所】Claude Code ／【状態変更】なし(調べるだけ)

このリポジトリの文字コードと改行コードを、何も変更せずに調べてください。
ファイル・Gitの設定・Windowsの設定は変更しないでください。
1. 使っているシェルとPowerShellの版、.gitattributes の内容、core.autocrlf の値と設定ファイルを書いてください。
2. git ls-files --eol で、記録がCRLF・LF・混在のファイルを種類ごとに数えてください。
3. 先頭にBOMがあるテキストファイルを一覧にしてください。
4. そろえたほうがよい点と、変更の案を分けて書いてください。
表にまとめて報告したら、変更はせずに私の確認を待ってください。

つまずきやすい点: 表示とファイルの文字化けを混同する

  • 表示だけが崩れているのに、ファイルを変換して正しい中身を壊す
  • Bashの書き方をPowerShellで実行して失敗する。&& で命令をつなぐ書き方は、PowerShell 7からの機能で、Windows PowerShell 5.1では使えない
  • グローバルの core.autocrlf を変えて、ほかのリポジトリの改行まで変わる

このサイトで実際に起きたこと

このサイトは、Windowsの作業PCで作ったファイルをLinuxのサーバーへ送って運用しています。

  • PowerShellで書き出した.envの先頭にBOMが入り、最初の設定を読めずにデータベースの準備が失敗した。サーバーでBOMを取り除いて解決した
  • サーバーのファイルを照合したところ、17件が改行コードだけ違っていた。以後は、Gitに記録した内容をLFのまま書き出して送り、送った後に1件ずつハッシュで照合している
  • CRLFのファイルを書き換える処理が、行末の文字を消してしまう不具合を、テストで見つけて直した
  • Git Bashのヒアドキュメントの中のバックスラッシュが、別の文字に変わっていた
  • クリップボードへHTMLを入れる処理をWindows PowerShell 5.1で行ったところ、日本語が化けた。UTF-8で入れ直した

作業PCのこのリポジトリでも core.autocrlf が有効で、記録はLFのまま手元のファイルだけがCRLFのものが50件以上ありました。

ファイルを送る方法の違いで起きた文字化けは、Claude CodeでAlmaLinuxサーバーを構築・運用する方法で紹介しています。

まとめ

  • 最初に、表示の文字化けかファイルの文字化けかを分ける
  • PowerShellは版で書き出す文字コードが違い、BOMは読み手に合わせて決める
  • 改行は.gitattributesでそろえ、正規化はコミットしてから差分で確かめる
  • WindowsのルールはCLAUDE.mdに書いておく