windows-path-troubleshooting

🚨 重大なガイドライン

Windows のファイルパス要件

必須：Windows ではファイルパスに必ずバックスラッシュを使用してください

Windows で Edit または Write ツールを使用する場合、ファイルパスにはスラッシュ（/）ではなく、必ずバックスラッシュ（\）を使用してください。

例：

• ❌ 誤り：D:/repos/project/file.tsx
• ✅ 正しい：D:\repos\project\file.tsx

次の項目に適用されます。

• Edit ツールの file_path パラメーター
• Write ツールの file_path パラメーター
• Windows システムでのすべてのファイル操作

ドキュメント作成ガイドライン

ユーザーから明示的に依頼されない限り、新しいドキュメントファイルを作成しないでください。

• 優先事項：新しいドキュメントを作成するのではなく、既存の README.md ファイルを更新してください
• リポジトリの整理：ユーザーから別途依頼されない限り、リポジトリのルートは README.md のみとし、すっきり保ってください
• スタイル：ドキュメントは簡潔で直接的かつプロフェッショナルなものにし、AI が生成したような口調は避けてください
• ユーザーの希望：ユーザーがドキュメント作成を具体的に依頼した場合にのみ、追加の .md ファイルを作成してください

---

Claude Code での Windows パスのトラブルシューティング

🚨 重大：Windows ではファイルパスに必ずバックスラッシュを使用してください

必須：Windows で Edit、Write、または Read ツールを使用する場合、ファイルパスにはスラッシュ（/）ではなく、必ずバックスラッシュ（\）を使用してください。

ルール

Windows のファイルパス要件：

• ✅ 正しい：D:\repos\project\file.tsx
• ❌ 誤り：D:/repos/project/file.tsx

次の項目に適用されます。

• Edit ツールの file_path パラメーター
• Write ツールの file_path パラメーター
• Read ツールの file_path パラメーター
• Windows システムでのすべてのファイル操作

重要な理由

Windows でスラッシュを使用した場合によく表示されるエラーメッセージ：

Error: ENOENT: no such file or directory

根本原因：

• Windows のネイティブファイルシステムでは、パスの区切り文字としてバックスラッシュ（\）を使用します
• スラッシュ（/）は一部の Windows 環境では機能しますが、Claude Code のファイルツールでは機能しません
• Git Bash ではパスがスラッシュで表示されますが、Windows API ではバックスラッシュが必要です
• Claude Code の Read／Write／Edit ツールは、バックスラッシュを想定する Windows ネイティブ API を使用します

🔍 Claude Code でよくある Windows パスの問題

問題 1：ツール呼び出しでスラッシュを使用

症状：

Edit tool fails with "file not found" or "no such file or directory"

原因： Git Bash の出力からスラッシュを含むパスをコピーしている：

# Git Bash shows:
/s/repos/claude-plugin-marketplace/file.tsx

誤った使い方：

Edit(file_path="/s/repos/myproject/file.tsx")

正しい使い方：

Edit(file_path="S:\repos\myproject\file.tsx")

解決手順：

1. Windows のドライブ文字を確認します（例：/s/ → S:）
2. スラッシュをバックスラッシュに置き換えます
3. コロン付きのドライブ文字を追加します
4. 絶対 Windows パス形式を使用します

問題 2：Git Bash の MINGW パス形式

症状： /s/repos/ や /c/Users/ のようなパスは、Edit／Write／Read ツールでは機能しません

MINGW パス形式の説明：

• Git Bash は Windows 上で POSIX 形式のパスを使用します
• ドライブ文字は /c/、/d/、/s/ などで表されます
• これらは MINGW の仮想パスであり、Windows パスではありません
• Claude Code のツールには Windows ネイティブのパスが必要です

変換表：

Git Bash（MINGW）	Windows ネイティブ
/c/Users/name/	C:\Users\name\
/d/repos/project/	D:\repos\project\
/s/work/code/	S:\work\code\
/mnt/c/Windows/	C:\Windows\

変換アルゴリズム：

1. 最初のパス要素からドライブ文字を取り出します（例：/s/ → S）
2. ドライブ文字にコロンを追加します（例：S → S:）
3. 残りのスラッシュをバックスラッシュに置き換えます
4. 結合します：S: + \repos\project\file.tsx

問題 3：Git Bash での相対パス

症状： Git Bash の相対パスは、Claude Code のツールで正しく解決されません

原因： Git Bash の現在の作業ディレクトリは MINGW 形式ですが、Claude Code のツールは Windows 形式を使用します

シナリオの例：

# In Git Bash:
pwd
# Shows: /s/repos/my-project

# User provides relative path:
./src/components/Button.tsx

問題： Claude Code は、MINGW の /s/repos/my-project から ./src/ を解決できません

解決方法：

1. Git Bash から Windows のフルパスを取得します：

   pwd -W
   # Shows: S:/repos/my-project (Windows format with forward slashes)
   

2. 適切な Windows パスに変換します：S:\repos\my-project
3. 相対パスをバックスラッシュで追加します：S:\repos\my-project\src\components\Button.tsx

問題 4：環境変数の展開

症状： $HOME や %USERPROFILE% などの環境変数を含むパスで失敗する

Git Bash の環境変数：

echo $HOME
# Shows: /c/Users/username (MINGW format)

Windows の環境変数：

echo %USERPROFILE%
# Shows: C:\Users\username (Windows format)

ベストプラクティス：

• Claude Code のツールでは、ファイルパスに環境変数を使用しないでください
• 代わりに Windows の絶対パスを使用してください
• ユーザーが $HOME を指定した場合は、echo $HOME を実行して結果を変換するよう依頼してください

問題 5：ファイルパス内のスペース

症状： スペースを含むパスが機能しない、または「ファイルが見つかりません」というエラーが発生する

正しい処理方法：

✅ CORRECT: Edit(file_path="C:\Program Files\My App\config.json")
✅ CORRECT: Edit(file_path="D:\My Documents\project\file.txt")

注意事項：

• パラメーター内のパスを引用符で囲まないでください
• ツール呼び出し自体がエスケープ処理を行います
• バックスラッシュを使用する場合、Windows パス内のスペースは問題ありません

問題 6：UNC ネットワークパス

症状： \\server\share\file.txt のようなネットワークパスで失敗する

Windows の UNC 形式：

\\server\share\folder\file.txt

Git Bash での表現：

//server/share/folder/file.txt

Claude Code での正しい使用方法：

Edit(file_path="\\\\server\\share\\folder\\file.txt")

注意： エスケープ処理のため、状況によってはバックスラッシュを二重にする必要がありますが、Claude Code のツールがこれを自動的に処理します。

🔧 パス検出および変換アルゴリズム

ユーザーがファイルパスを指定した場合は、次の判断手順に従ってください。

ステップ 1：パス形式を特定する

MINGW パス（Git Bash）：

• / の後に1文字と / が続く形式で始まる（例：/c/、/s/）
• 例：/s/repos/project/file.tsx
• 対応： Windows 形式に変換する

Windows パス：

• ドライブ文字とコロンで始まる（例：C:、D:）
• バックスラッシュまたはスラッシュを使用する
• 例：S:\repos\project\file.tsx または S:/repos/project/file.tsx
• 対応： バックスラッシュが使用されていることを確認する

相対パス：

• ./、../、またはファイル名だけで始まる
• 例：./src/components/Button.tsx
• 対応： ユーザーにフルパスを尋ねるか、現在のディレクトリを特定する

UNC パス：

• \\ または // で始まる
• 例：\\server\share\file.txt
• 対応： バックスラッシュが使用されていることを確認する

ステップ 2：変換処理

MINGW パス（/x/...）の場合：

Input: /s/repos/myproject/src/components/Button.tsx

Process:
1. Extract drive letter: "s"
2. Uppercase: "S"
3. Add colon: "S:"
4. Replace remaining slashes: \repos\myproject\src\components\Button.tsx
5. Combine: S:\repos\myproject\src\components\Button.tsx

Output: S:\repos\myproject\src\components\Button.tsx

スラッシュを使用した Windows パス（X:/...）の場合：

Input: S:/repos/project/file.tsx

Process:
1. Detect drive letter already present: "S:"
2. Replace forward slashes with backslashes: \repos\project\file.tsx
3. Combine: S:\repos\project\file.tsx

Output: S:\repos\project\file.tsx

相対パスの場合：

Input: ./src/components/Button.tsx
Current directory (from user or detection): S:\repos\my-project

Process:
1. Remove ./ prefix
2. Replace forward slashes: src\components\Button.tsx
3. Combine with current directory: S:\repos\my-project\src\components\Button.tsx

Output: S:\repos\my-project\src\components\Button.tsx

🛠️ 対話形式のパス修正ワークフロー

Windows でファイルパスのエラーが発生した場合：

ステップ 1：エラーを検出する

エラーの兆候：

• 「ENOENT: no such file or directory」
• 「ファイルが見つかりません」
• Edit/Write/Read ツールの失敗
• ユーザーが「Windows」または「Git Bash」に言及している

ステップ 2：パスを分析する

自問してください：

1. ユーザーが指定したパスは MINGW 形式ですか？
2. パスにスラッシュが使われていますか？
3. 相対パスですか？
4. Git Bash のコマンド出力からパスを受け取りましたか？

ステップ 3：必要に応じて確認する

パスが曖昧な場合は、次のように尋ねてください：

I see you're working on Windows with Git Bash. To ensure I use the correct path format,
could you run this command and share the output?

pwd -W

This will give me the Windows-formatted path.

ステップ 4：変換して再試行する

変換テンプレート：

I'll convert the path from Git Bash format to Windows format:
- Git Bash: /s/repos/project/file.tsx
- Windows: S:\repos\project\file.tsx

Retrying with the correct Windows path...

ステップ 5：成功を確認する

変換後、操作が成功したことを確認し、修正した内容を説明してください：

✅ Successfully edited the file using the Windows path format (S:\repos\...).

Note: On Windows with Git Bash, always use backslashes (\) in file paths for
Claude Code's Edit/Write/Read tools, even though Git Bash displays paths with
forward slashes (/).

📋 トラブルシューティングチェックリスト

Windows でファイル操作が失敗した場合：

• パス区切り文字を確認：スラッシュ（/）ではなく、バックスラッシュ（\）を使用していますか？
• ドライブ文字の形式を確認：/c/ ではなく C: になっていますか？
• MINGW 変換を確認：/x/path を X:\path に変換しましたか？
• 相対パスか絶対パスかを確認：ドライブ文字で始まる絶対パスですか？
• 環境変数を確認：$HOME または %USERPROFILE% を展開しましたか？
• スペースを確認：パス内のスペースは正しく処理されていますか？
• UNC パスを確認：ネットワークパスは \\server\share 形式になっていますか？
• ファイルの存在を確認：そのパスにファイルは実際に存在しますか？

🎯 クイックリファレンス：パス変換の例

コンテキスト	パス形式	Claude Code ツール形式
Git Bash pwd	/s/repos/project	S:\repos\project
Git Bash の相対パス	./src/file.tsx	S:\repos\project\src\file.tsx
Windows Explorer	S:\repos\project\file.tsx	S:\repos\project\file.tsx ✅
/ を使った Windows のパス	S:/repos/project/file.tsx	S:\repos\project\file.tsx
MINGW の絶対パス	/c/Users/name/file.txt	C:\Users\name\file.txt
ネットワーク共有（Git Bash）	//server/share/file.txt	\\server\share\file.txt
WSL のパス	/mnt/c/repos/project	C:\repos\project

🚀 Windows でのファイル操作のベストプラクティス

1. パスは必ず事前に変換する

エラーを待たないでください — MINGW 形式のように見えるパスがあれば、すぐに変換します。

User provides: /s/repos/project/file.tsx
You think: "This is MINGW format, I need to convert it to S:\repos\project\file.tsx"
You do: Convert before calling Edit/Write/Read tool

2. Git Bash では pwd -W を使う

Windows で現在のディレクトリが必要な場合：

# Instead of:
pwd                    # Shows: /s/repos/project (MINGW format)

# Use:
pwd -W                 # Shows: S:/repos/project (Windows format with /)

次に、スラッシュをバックスラッシュに変換します。

3. パス形式を変更したことを伝える

パスを変換した場合は、必ず説明してください：

I'll convert the Git Bash path to Windows format for the Edit tool:
- From: /s/repos/project/file.tsx
- To: S:\repos\project\file.tsx

これにより、ユーザーは変換が必要な理由を理解し、今後のやり取りに活用できます。

4. ツールを使う前に検証する

Windows で Edit／Write／Read ツールを呼び出す前に：

Pre-flight checklist:
✅ Path starts with drive letter and colon (e.g., C:, S:)
✅ Path uses backslashes (\) not forward slashes (/)
✅ Path is absolute, not relative
✅ No MINGW format (no /c/, /s/, etc.)

5. ユーザーが指定したパスは慎重に扱う

ユーザーがさまざまな形式でパスを指定する場合があります：

• Git Bash からコピーしたパス（MINGW 形式）
• Windows Explorer からコピーしたパス（Windows 形式）
• 手入力したパス（どちらの形式の場合もあります）
• コマンド出力から取得したパス（ツールによって異なります）

必要に応じて、必ず形式を判別して変換してください。

エラーの検索、プラットフォームに関する注意点、ユーザーへの説明、応用シナリオ

Claude Code でよく発生する Windows のパスエラーに関する詳細な検索表、プラットフォームごとの動作（PowerShell、CMD、Git Bash、WSL、Node／Python）、ユーザーへの説明用スクリプト、および応用的なパスのシナリオ（UNC パス、長いパス、空白、特殊文字）については、references/error-platform-advanced.md を参照してください。クイック変換ワークフローでパスの問題を解決できない場合は、このリファレンスを読み込んでください。

✅ 成功基準

次の条件を満たせば、Windows のパスを正しく扱えています。

1. ✅ Windows では、すべての Edit／Write／Read ツール呼び出しでバックスラッシュを使用している
2. ✅ MINGW のパスをツールの使用前に変換している
3. ✅ 相対パスを絶対 Windows パスに解決している
4. ✅ 変換が必要だった理由をユーザーが理解している
5. ✅ パス関連のエラーなくファイル操作が成功している
6. ✅ セッション全体でパス形式が一貫している

🆘 このスキルを使う場面

次の場合は、この知識を積極的に活用してください：

1. ユーザーが Windows を使っていると言った場合
2. ユーザーが Git Bash または MINGW に言及した場合
3. /c/、/s/ などで始まるパスを見かけた場合
4. Edit／Write／Read ツールで「ファイルが見つかりません」というエラーが発生した場合
5. ユーザーが Windows 上でスラッシュを使ったパスを指定した場合
6. Windows システム上のファイルを読み取り、編集、または書き込む必要がある場合

このスキルは Windows ユーザーにとって非常に重要です — Git Bash を使う Windows では、パス形式のエラーがファイル操作に失敗する最大の原因です。