【2026年1月】Claudeプロジェクトのファイル文字化け問題と解決法 - UTF-8 BOM付き保存の効果

はじめに

ClaudeのProプラン以上で利用できる「プロジェクト機能」で、JavaScriptファイルをアップロードすると日本語コメントが文字化けするという問題に遭遇しました。

本記事では、この問題の原因究明から解決までの実体験を詳しく解説します。結論から言うと、UTF-8 BOM（Byte Order Mark）付きで保存することで解決しましたが、さらに便利な方法も見つかりました。

🚨 発生した問題

初期症状

WordPress自動投稿システムの開発中、publish.js（35KB, 860行）をClaudeプロジェクトにアップロードしたところ：

// 正常なコード: // オプション解析
// プロジェクト表示: // オプション解æž

日本語コメントが盛大に文字化けしました。

さらなる調査

ユーザーからの詳細な報告で判明：

• 114行、3901byteまで: 正常表示 ✅
• 3902byte以降: 文字化け ❌

興味深いことに、特定のバイト数境界で問題が発生していました。

🔍 試行錯誤の過程

❌ 最初に試したこと（効果なし）

試行1: 改行コードの変更

dos2unix publish.js

# CRLF → LF に変更
unix2dos publish.js

結果： 文字化けは変わらず ❌

試行2: ファイル名の変更

# .js → .txt に変更
cp publish.js publish.txt

結果： 文字化けは変わらず ❌

試行3: VSCodeで「UTF-8」として保存

VSCodeの右下から「UTF-8」を選択して保存。

結果： 文字化けは変わらず ❌

✅ 解決策の発見

UTF-8 BOM付き保存が効果的！

VSCodeでの操作：

1. ファイルを開く
2. 右下の「UTF-8」をクリック
3. 「UTF-8 with BOM で保存」 を選択
4. 保存して、Claudeプロジェクトに再アップロード

結果：

✅ ファイルサイズ: 28.83 KB（約29KB）
✅ 行数: 864行
✅ 日本語コメント: 完全に正常表示
✅ 文字化けなし

検証結果

🤔 なぜBOMが効果的だったのか？

BOM（Byte Order Mark）とは

BOMは、ファイルの先頭3バイト（EF BB BF）に付加される特殊なマーカーです：

UTF-8 without BOM:
[ファイル内容...]

UTF-8 with BOM:
[EF BB BF][ファイル内容...]
     ↑
   BOMマーカー

Claudeプロジェクトでの効果

推測される理由：

1. エンコーディング自動判定の改善

   • BOMがあることで、Claudeが「UTF-8」であることを確実に認識
   • マルチバイト文字（日本語）の処理が正確に

2. バイト境界の処理改善

   • 3901/3902byte境界での切断問題が解消
   • BOMにより、文字単位での処理が適切に

3. ファイル全体の読み込み

   • BOMによりファイル形式が明確化
   • 切り詰めではなく全文を読み込み

🎯 推奨される保存方法

方法1: VSCodeで保存

Windows

1. ファイルを開く
2. Ctrl + Shift + P でコマンドパレット
3. 「encoding」と入力
4. 「Save with Encoding」 を選択
5. 「UTF-8 with BOM」 を選択

macOS

1. ファイルを開く
2. Cmd + Shift + P でコマンドパレット
3. 「encoding」と入力
4. 「Save with Encoding」 を選択
5. 「UTF-8 with BOM」 を選択

方法2: コマンドラインで一括変換

# Linux/macOS/Git Bash (Windows)
# UTF-8 → UTF-8 with BOM

# 単一ファイル
printf '\xEF\xBB\xBF' | cat - publish.js > publish-utf8bom.js

# 複数ファイルを一括変換
for file in scripts/*.js; do
  printf '\xEF\xBB\xBF' | cat - "$file" > "${file%.js}-utf8bom.js"
done

方法3: Windows PowerShell

# UTF-8 BOM付きで保存
$content = Get-Content -Path "publish.js" -Encoding UTF8
$content | Out-File -FilePath "publish-utf8bom.js" -Encoding UTF8

📊 さらなる解決策：GitHub MCP

UTF-8 BOM付き保存で問題は解決しましたが、もっと便利な方法があります。

Claude Desktop + GitHub MCP

Claude Desktopアプリ に GitHub MCPサーバー を接続すると：

✅ エンコーディング問題を完全回避
✅ ファイルサイズ制限なし
✅ リポジトリ全体にリアルタイムアクセス
✅ ファイル読み書き
✅ BOM付き保存の手間不要
✅ 常に最新版を参照

具体的な利点

実際の使い方

あなた: 「caytech-blog-repoのscripts/publish.jsを確認して」

Claude Desktop (GitHub MCP):
[リポジトリから最新版を取得]
[35KB全文を確認]
[エンコーディング問題なし]
「複数スラッグ対応が正しく実装されています...」

詳しいセットアップ方法：

【2026年版】Claude Desktop + GitHub MCP 完全セットアップガイド - 初心者でも30分で完了

はじめにClaude Desktop + GitHub MCP（Model Context Protocol） を使えば、あなたのGitHubリポジトリ全体をClaudeから直接操作できます。この記事では、完全初心者でも30分でセットアップ...

caymezon.com

2026.01.24

🔬 技術的な詳細

マルチバイト文字の切断問題

UTF-8では、日本語は1文字=3バイト：

// オプション解析
   ↓
[E3 82 AA][E3 83 97][E3 82 B7][E3 83 A7][E3 83 B3]...
   オ      プ      シ      ョ      ン

切断が発生する場合：

3901byte: [E3 82 AA] ← 完全
3902byte: [E3]      ← 不完全（2バイト欠損）
         ↓
      文字化け発生

BOM付きの場合：

[EF BB BF] + ファイル内容
    ↓
エンコーディングが明確
    ↓
文字単位で正しく処理
    ↓
切断されない

📝 プロジェクトファイルの正しい運用

プロジェクトファイルが向いているもの

• ✅ 小〜中規模のコードファイル（UTF-8 BOM付き）
• ✅ ドキュメント（README.md、USAGE.mdなど）
• ✅ 設定ファイル（.env.example、.gitignoreなど）
• ✅ 簡潔な指示（プロジェクトの「手順」セクション）

より便利な選択肢

実用的なプロジェクト構成例

Claudeプロジェクト: ブログ管理

├── 手順（Instructions）
│   ├── 基本情報
│   ├── 重要なファイル位置
│   └── 作業フロー
│
├── ファイル
│   ├── README.md（システム概要） ✅
│   ├── USAGE.md（使い方） ✅
│   └── publish-utf8bom.js（必要に応じて）
│
└── GitHub MCP接続 ⭐
    └── リポジトリ全体にアクセス（推奨）

💡 トークン消費への影響

重要な事実

claude.ai (Web) + Claude Desktop
        ↓
   同じアカウント
        ↓
  同じusage limit（5時間ごとに約44,000トークン）

プロジェクトファイルとGitHub MCP、どちらを使っても基本的なトークン消費は同じです。

それぞれのトークン消費

プロジェクトファイル

publish.js (BOM付き、30KB):
- プロジェクト読み込み: 常時コンテキストに配置
- トークン: 約8,000トークン（常時消費）

GitHub MCP

publish.js (GitHub経由):
- 必要な時だけ取得: 必要時のみコンテキストに配置
- トークン: 約8,000トークン（使用時のみ）
- MCP定義: 約5,000トークン（常時）

GitHub MCPの方が効率的：必要な時だけファイルを取得するため。

🎯 ベストプラクティス

シナリオ別の推奨方法

シナリオ1: 単発の確認作業

✅ 推奨: UTF-8 BOM付きでプロジェクトファイル
理由: 手軽、セットアップ不要

シナリオ2: 継続的な開発作業

✅ 推奨: Claude Desktop + GitHub MCP
理由: 常に最新版、複数ファイル、エンコーディング不要

シナリオ3: チーム開発

✅ 推奨: Claude Desktop + GitHub MCP
理由: 全員が同じリポジトリにアクセス、履歴管理

トークン節約テクニック

1. こまめに新規会話を開始

   • タスクごとに分ける
   • 会話履歴の累積を防ぐ

2. 質問をまとめる

   • 1回で完結させる
   • 往復を減らす

3. 必要なファイルのみ参照

   • 全ファイルを一度に読まない
   • GitHub MCPで必要な部分だけ取得

詳しくは次の記事で：

【2026年版】Claude Desktop + GitHub MCP 完全セットアップガイド - 初心者でも30分で完了

はじめにClaude Desktop + GitHub MCP（Model Context Protocol） を使えば、あなたのGitHubリポジトリ全体をClaudeから直接操作できます。この記事では、完全初心者でも30分でセットアップ...

caymezon.com

2026.01.24

📊 解決方法の比較

完全比較表

推奨度

🥇 1位: Claude Desktop + GitHub MCP
└─ 長期的な開発・チーム作業に最適

🥈 2位: UTF-8 BOM付きプロジェクトファイル
└─ 単発確認・個人作業に便利

🥉 3位: チャット内アップロード
└─ 一時的な確認に使用

🔧 トラブルシューティング

Q1: BOM付きで保存したのに文字化けする

確認ポイント：

1. 本当にBOMが付いているか確認

   # Linux/macOS/Git Bash
   xxd -l 3 publish.js
   # 出力: 0000000: efbb bf
   # ↑ これがあればBOM付き

2. ファイルサイズを確認

   • 極端に大きいファイル（100MB以上）は制限がある可能性

3. 再アップロード

   • Claudeプロジェクトから一度削除
   • 再度アップロード

Q2: BOMを付けるとエラーが出る

JavaScriptでBOMが原因でエラーが出る場合：

// ❌ Node.jsで実行するとエラー
// SyntaxError: Invalid or unexpected token

// ✅ 解決策
// Claudeプロジェクト用: UTF-8 BOM
// 実行用: UTF-8 without BOM

// 2つのファイルを用意：
publish.js         // 実行用（BOMなし）
publish-bom.js     // Claude用（BOM付き）

または： GitHub MCPを使えばこの問題は発生しません。

Q3: 複数のファイルを一度にBOM付きにしたい

# Linux/macOS/Git Bash
# scriptsフォルダ内の全.jsファイルをBOM付きに

for file in scripts/*.js; do
  # BOMが既にあるかチェック
  if ! head -c 3 "$file" | xxd -p | grep -q "efbbbf"; then
    # BOMを追加
    printf '\xEF\xBB\xBF' | cat - "$file" > "${file}.tmp"
    mv "${file}.tmp" "$file"
    echo "BOM added: $file"
  else
    echo "Already has BOM: $file"
  fi
done

📝 まとめ

問題と解決

重要なポイント

1. UTF-8 BOM付き保存で文字化けは解決 ✅
2. 3901/3902byte境界問題も解消 ✅
3. VSCodeで簡単に変換可能 ✅
4. さらに便利なのはGitHub MCP ⭐

推奨される運用

【パターンA: 単発確認】
UTF-8 BOM付きでプロジェクトファイル
↓
手軽に確認

【パターンB: 継続開発】
Claude Desktop + GitHub MCP
↓
効率的な開発環境

次のステップ

より快適な開発環境を構築しましょう：

【2026年版】Claude Desktop + GitHub MCP 完全セットアップガイド - 初心者でも30分で完了

はじめにClaude Desktop + GitHub MCP（Model Context Protocol） を使えば、あなたのGitHubリポジトリ全体をClaudeから直接操作できます。この記事では、完全初心者でも30分でセットアップ...

caymezon.com

2026.01.24

【2026年版】Claude Desktop 効果的な活用ガイド - メリット・デメリット・ベストプラクティス完全版

はじめにClaude Desktopは、Claudeをネイティブアプリとして利用できる強力なツールです。本記事では、Web版との違い、効果的な使い方、トークン消費を最小化するテクニック、そして今後の展望まで、実践的な知見を完全網羅します。(...

caymezon.com

2026.01.24

参考情報

• Unicode BOM (Byte Order Mark) 仕様
• VSCode Encoding Documentation
• Claude公式ドキュメント
• Model Context Protocol

更新履歴

• 2026-01-24: 初版公開（UTF-8 BOM解決策を確認）