Claude Codeで日本語コメント・日本語変数名を書くときの注意点

Claude Codeは日本語のコメントも日本語の変数名も、書くこと自体は問題なく扱えます。ただし「読める」ことと「意図どおりに運用できる」ことは別です。つまずく場所は3つに分かれます。CLAUDE.mdの日本語指示に強制力がないこと、統合ターミナルで文字が化けること、日本語だとCLAUDE.mdやMEMORY.mdに入る量が減ることです。コマンド名では、Claude Desktopで日本語名のスラッシュコマンドが送れない不具合も報告されています。

CLAUDE.mdに日本語で指示を書いても機能するか

機能します。CLAUDE.mdはプレーンテキストのMarkdownファイルで、Claude Codeはセッション開始時にその内容をそのまま読み込みます。書く言語に制約はありません。「日本語コメントを使う」「変数名は英語のキャメルケースにする」のような命名規約も、日本語の文章でそのまま書けます。

多言語対応ページの表は、MMLUを14言語に翻訳した評価の相対値で、コーディング作業そのものの測定ではありません。英語を100%としたとき、日本語はSonnet 4.5(拡張思考あり)で96.8%、Haiku 4.5で93.5%です。同じ表にはスワヒリ語が91.1%(Sonnet 4.5)、ヨルバ語が79.7%(同)と52.7%(Haiku 4.5)という行もあり、日本語は英語との差が数ポイントに収まる位置にあります。評価の方法とスコア表の全体はClaudeの多言語性能を言語別データで見るにまとめています。

CLAUDE.mdの指示は「強制」ではなく「文脈」として扱われる

実装前に押さえたい最重要点がここです。CLAUDE.mdとauto memoryの両方について、ドキュメントは次のように書いています。

Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.

CLAUDE.mdに「日本語コメントを必ず使う」と書いても、Claudeはそれを文脈として参照するだけです。コードを書くたびに機械的に照合するわけではありません。同じページには、指示が具体的で簡潔なほど守られやすいという説明もあります。ただし強制ではないため、守られない場合があります。

プロジェクト直下のCLAUDE.mdは、/compactの後もディスクから再読み込みされて再注入されます。サブディレクトリのCLAUDE.mdやpaths:付きのルールは、該当ファイルを読んだときに再読み込みされます。

多言語対応ページは、応答の言語は会話から推定されるものの、本番のアプリケーションでは対象の言語を明示するよう勧めています。コメントの言語も同じ発想で、推定に任せず規約として書いておくと揺れにくくなります。

フックはどう書くのでしょうか。フック入門には、EditかWriteのツール呼び出しの前にスクリプトを走らせ、保護対象のファイルなら止める例があります。登録は.claude/settings.jsonに次のように書きます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

この例では、.envへの編集がClaude Codeに止められ、スクリプトのBlocked:メッセージがClaudeへのフィードバックとして返ります。命名規約の検査も、同じ登録の形に検査用スクリプトを差し替えて組めます。

この登録が対象にするのはEditとWriteだけで、Bash経由のファイル書き込みは止められません。日本語コメントや命名の検査を組むときは、止めたい経路をmatcherに入れる必要があります。

抽象的な一文より、例外まで含めた実例を添えたほうが意図が伝わります。

## コーディング規約
- コメントは日本語で書く
- 変数名・関数名は英語のcamelCaseにする(例: userId, fetchOrderList)
- 例外: ドメイン固有の日本語用語(勘定科目名など)は変数名にそのまま使ってよい

CLAUDE.mdの書き方そのものはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンで扱っています。CLAUDE.mdとauto memoryの使い分けはClaude Code memoryの三層構造にまとめています。日本語の運用規約を書く場面でも、この2記事の型がそのまま使えます。

日本語の変数名は技術的に書けるか

書けます。作業用の空ディレクトリで、Python 3とNode.js(v20.18.0)に日本語の変数名を実行させてみました。どちらもエラーなく動き、出力は同じ2000でした。

合計金額 = 1000
print(合計金額 * 2)  # 2000

const 合計金額 = 1000;
console.log(合計金額 * 2); // 2000

通るかどうかと、チームで採用するかどうかは別の話です。PEP 8(Pythonのスタイルガイド)は、標準ライブラリの識別子はASCIIのみ、できるだけ英単語を使うよう定めています。この規則が対象にするのは標準ライブラリで、利用者のコードは縛りません。ただしPEP 8は、グローバルな読者を持つオープンソースにも同じ方針を勧めています。

コメントについても、PEP 8は英語圏以外のPython開発者に向けて、読み手が自分と同じ言語の話者だけだと確信できる場合を除き、英語で書くよう求めています。英語で書くかどうかの目安は、コードを誰が読むかです。読み手が日本語話者だけに限られるなら、日本語コメントを選ぶ理由は十分にあります。

どの言語で名前を付けるかは、CLAUDE.mdの規約や既存コードの命名が判断材料になります。「変数名は英語にする」という指示も、前節のとおり強制ではなく文脈です。この点は変数名でもコメントでも変わりません。

統合ターミナルで日本語が文字化けするとき

VS Code・Cursor・Devin Desktopの統合ターミナルでClaude Codeを動かすと、文字が四角や別のグリフで表示されることがあります。トラブルシューティングのページは、原因はターミナルのGPUレンダリングである可能性が高いとしています。対処は/terminal-setupの実行です。

手動で直す場合は、エディタの設定に同じキーを書いて再読み込みしても構いません。Shift+Enterが効かない別の症状との関係はterminal-setupコマンドでShift+Enterが効かないときの対処にまとめてあります。

CLAUDE.mdとMEMORY.mdは日本語だと入る量が減る

見落とされがちなのが、文字コードによる実質的な容量の目減りです。UTF-8では英数字が1文字1バイトですが、ひらがな・カタカナ・漢字は1文字3バイトで、全角記号や半角カナも同じ3バイトです。手元でwc -cを使って測ると、コメント行// 合計金額を計算するは改行込みで31バイト、英語の// calc totalは14バイトでした。内容は同じでも、日本語は2倍以上のバイトを使います。

この差が効くのは、ドキュメントが定める2つの読み込み上限です。

効いてくるのはMEMORY.mdのほうです。auto memoryはセッションをまたいで学んだ内容をMEMORY.mdに1行ずつ書き足し、この索引ファイルは毎セッションの冒頭で読み込まれます。上限を超えた分はセッション開始時に読み込まれず、冒頭には載りません。

ここで行数の上限とバイトの上限の関係が変わります。KBを1,000バイトと数え、行が日本語だけの場合で考えます。25KBを200行で割ると、1行あたり約125バイトです。英語なら約125字までの行は、200行の上限が先に効きます。日本語は1文字3バイトなので、日本語だけの行なら約42字を超える行が増えるとバイトの上限が先に効きます。説明文が長くなりがちな日本語の運用では、200行に届く前に25KBへ着きやすい計算です。KBを1,024バイトと数えても、1行あたり約128バイト、日本語で約42.7字となり、結論は変わりません。

CLAUDE.md側にも、バイト上限とは別の目安があります。1ファイル200行以内が推奨で、長いほど文脈を消費して遵守率が下がるためです。一部のディレクトリにしか関係ない規約は、pathsを指定したルールに移せば、該当するファイルを触るときだけ読み込まれます。@pathで日本語の規約を分割しても、インポートされたファイルも起動時に読み込まれるため、読み込まれる量は変わりません。減らしたいときは、paths指定のルールへ移します。

上限に近づくと、Claude Codeは「1行1エントリーに保つ」「詳細はトピックファイルへ移す」という圧縮をClaudeに促します。上限を超えても書き込みは成功し、書き換えを促すエラーが返ります。日本語で運用するなら、この圧縮が英語運用より早く起きると見込んでおくと、古いメモが読み込み対象から外れる場面に慌てずに済みます。

日本語コメントはトークン消費を増やすのか

日本語コメントでトークンがどれだけ増えるかに、言語ごとの決まった係数はありません。モデル側の変化としては、Claude Opus 4.7以降のモデルとMythos Previewが新しいトークナイザーを使い、同じ入力テキストでも旧モデルより約30%多くのトークンを消費します。正確な増加幅は内容や使い方によって変わります。Claude Fable 5.1とMythos 5.1、Fable 5、Mythos 5も、Opus 4.7と同じトークナイザーです。

日本語コメントの実際のコストは、トークンカウントAPI(Messages APIのcount_tokensエンドポイント)で測れます。トークンカウントのページには、移行先のモデルIDを指定して数えるよう書かれています。日本語コメントを大量に含むファイルを扱うなら、代表的なファイルを現行のモデルIDで一度測っておくと、コンテキストウィンドウの余裕を見積もれます。

まとめ

日本語のコメントと変数名そのものに障害はなく、日本語で困るのは容量の計算です。英語運用の目安である200行をそのまま持ち込むと、日本語では先に25KBへ当たります。