Claude Code日本語環境のベストプラクティス｜設定・プロンプト・注意点

Claude Codeは英語圏で開発されたツールですが、日本語での利用に十分対応しています。ただし、「日本語で指示すればそれで終わり」と考えていると、出力の言語が揺れたり、日本語ファイルパスで予期しないエラーが出たり、i18n対応で翻訳キーがぐちゃぐちゃになったりと、英語ドキュメントには書かれていない落とし穴に遭遇します。

本記事では、Claude Codeを日本語環境で日常的に使ってきた中で得られた実践的なノウハウ — プロンプトの書き方、CLAUDE.mdの日本語設計、日本語特有のエンコーディング・ファイルパス問題、i18n対応のコツを、Before/After形式で具体的に共有します。

Claude Codeの基本をまだ押さえていない方は、先にClaude Code完全ガイドを参照してください。

結論 — 日本語プロンプトは有効だが「境界ルール」の設計が鍵

Claude Codeに日本語で指示を出すこと自体は問題ありません。Claudeモデルの日本語理解力は高く、自然な日本語で書いた指示から適切なコードを生成できます。

ただし、**何を日本語で書き、何を英語のまま残すかの「境界ルール」**を設計しておかないと、出力が安定しません。具体的には以下の原則です。

• 指示文（プロンプト）: 日本語でOK。ただし技術用語・固有名詞は英語のまま
• CLAUDE.md: 日本語で記述して問題ない。チームが日本語話者なら日本語推奨
• 出力言語の指定: 「コメントは日本語」「コミットメッセージは日本語」と明示的に指定しないと揺れる
• 変数名・関数名: 英語一択。日本語変数名は技術的に動くが品質が落ちる
• ファイルパス: 日本語を含むパスは避ける。含む場合は事前に把握しておく

日本語プロンプトの書き方 — 精度を上げる5つのテクニック

テクニック1: 一文一意の原則

日本語は英語に比べて一文が長くなりがちです。Claude Codeへの指示で一文に複数の要求を詰め込むと、後半の指示が無視される確率が上がります。

# Before（一文に3つの要求）
このAPIエンドポイントのバリデーションを追加して、エラーメッセージは日本語にして、
テストも書いてください

# After（番号付きリストで分割）
以下の作業をしてください:
1. /api/users エンドポイントにZodバリデーションを追加
2. バリデーションエラーのメッセージは日本語で返す
3. 追加したバリデーションのユニットテストを作成

番号付きリストにすると、Claude Codeが各ステップを順に処理しやすくなります。さらに、どのステップが正しく処理されなかったかの特定も容易です。

テクニック2: 技術用語は英語のまま混在させる

日本語の指示文の中に英語の技術用語がそのまま入っていても、Claude Codeは正しく解釈します。むしろ、技術用語を無理に日本語化すると精度が下がります。

# Before（技術用語を日本語化しすぎ）
ユーザープロフィール部品の属性に「有効かどうか」を追加してください

# After（技術用語は英語のまま）
UserProfileコンポーネントのpropsにisActiveを追加してください

特にファイル名・関数名・ライブラリ名はコードベース内の表記と完全一致させることが重要です。「react-hook-formのバリデーション」と書くべきところを「リアクトフック書式のバリデーション」と書くと、Claude Codeが該当するコードを特定できなくなります。

テクニック3: 出力形式を具体的に指定する

日本語の指示は英語に比べて曖昧になりやすい性質があります。「いい感じに」「適切に」「うまく」のような指示は、Claude Codeにとって解釈の幅が広すぎます。

# Before（曖昧）
このフォームのバリデーションをいい感じに追加してください

# After（具体的）
このフォームに以下のバリデーションを追加してください:
- name: 必須、2文字以上50文字以下
- email: 必須、メールアドレス形式
- phone: 任意、ハイフンあり/なし両対応（例: 090-1234-5678, 09012345678）
- バリデーションライブラリはZodを使用
- エラーメッセージは日本語（例: "名前は2文字以上で入力してください"）

テクニック4: 既存のコードパターンを参照させる

日本語のプロジェクトでは、コメントやエラーメッセージの「トーン」を統一することが重要です。Claude Codeに新しいコードを書かせるときは、既存のファイルを参照させると出力の一貫性が上がります。

src/components/user-form.tsx のバリデーションエラーメッセージのトーンに合わせて、
src/components/order-form.tsx のバリデーションも日本語のエラーメッセージを追加してください

この指示により、Claude Codeは既存のファイルからトーンとフォーマットを学習し、一貫した日本語のエラーメッセージを生成します。

テクニック5: 「日本語で」と「英語で」の出力指定を明示する

これは最も見落とされやすいポイントです。指示を日本語で書いても、Claude Codeの出力（コメント、コミットメッセージ、ドキュメント）が日本語になるとは限りません。セッションごとに揺れることがあります。

# 出力言語を明示する例
以下の関数にJSDocコメントを日本語で追加してください。
パラメータの説明も日本語でお願いします。

セッション単位で指定するのが面倒な場合は、CLAUDE.mdに出力言語のルールを記載するのが最も確実です（後述）。

CLAUDE.mdの日本語設計 — 何を日本語で書き、何を英語で残すか

CLAUDE.mdはClaude Codeにプロジェクト固有のルールや文脈を伝えるための設定ファイルです。日本語で書くことは有効であり、チームメンバーが日本語話者中心であれば日本語推奨です。

CLAUDE.mdの書き方の詳細はCLAUDE.md作成ガイドで解説していますが、ここでは日本語環境に特化した設計パターンを共有します。

日本語で書くべき項目

以下の項目は日本語の方が正確に伝わり、かつチームメンバーの可読性も上がります。

• プロジェクトの概要: ビジネスドメインの説明（「BtoB向け請求管理SaaS」など）
• コーディング規約の意図説明: なぜそのルールがあるのかの背景
• 出力言語のルール: コメント、コミットメッセージ、エラーメッセージの言語指定
• ドメイン用語対応表: 業務用語と英語変数名の対応

英語で書くべき項目

以下はコードと直結するため、英語のまま記述するのが確実です。

• コマンド例: pnpm test, pnpm build
• ファイルパス・ディレクトリ構造: src/features/invoice/
• ライブラリ名・API名: next-intl, zod
• 設定値: 環境変数名、設定キー

実践的なCLAUDE.md記述例

# プロジェクト概要
BtoB向け請求管理SaaS。請求書の作成・送付・入金消込を管理する。
主要ドメイン: 請求（invoice）、顧客（customer）、入金（payment）

# 出力言語ルール
- コードコメント: 日本語
- 変数名・関数名: 英語（camelCase）
- コミットメッセージ: 日本語（形式: "feat: 〇〇機能を追加"）
- ユーザー向けエラーメッセージ: 日本語
- ログ出力: 英語（例: "Failed to fetch invoice"）
- テストの describe/it: 日本語（例: describe("請求書の作成")）

# ドメイン用語対応表
| 日本語 | 英語（コード上の表記） |
|--------|----------------------|
| 請求書 | invoice |
| 請求明細 | invoiceLineItem |
| 入金消込 | paymentReconciliation |
| 稟議 | approvalRequest |
| 締め日 | closingDate |
| 支払期日 | dueDate |
| 源泉徴収 | withholdingTax |

# テストコマンド
pnpm test
pnpm test:e2e
pnpm typecheck

ドメイン用語対応表が効く理由

日本のビジネスドメインには、英語に直訳しにくい概念が多数あります。「稟議」「源泉徴収」「締め日」などは、Claude Codeに日本語のまま伝えると、毎回異なる英語変数名が生成される可能性があります。

用語対応表をCLAUDE.mdに記載しておくことで、プロジェクト全体で一貫した命名が保たれます。これは日本語プロジェクト特有の非常に重要なプラクティスです。

日本語の変数名・コメントの扱い

変数名は英語一択 — その理由

日本語の変数名（const 請求金額 = calculateTotal()）はJavaScript/TypeScriptで動作しますが、Claude Codeでの利用においては明確にデメリットがあります。

1. コード生成の精度が下がる: Claude Codeのモデルは英語の変数名で学習されたコードが圧倒的に多いため、日本語変数名のコードを生成・修正する精度が低下する
2. 補完との相性が悪い: エディタの補完機能やLintツールとの互換性に問題が出ることがある
3. チーム間の一貫性が崩れる: ローマ字表記と漢字表記が混在するリスクがある（seikyu vs 請求）

CLAUDE.mdに用語対応表を記載したうえで、変数名は英語で統一するのがベストプラクティスです。

コメント言語の選択

コメントを日本語で書くこと自体はClaude Codeの動作に影響しません。チーム内の可読性を優先して選択してください。

ただし、Claude Codeが生成するコメントの言語は明示的に指定しないと不安定です。同一セッション内でも、ある関数のコメントは日本語、別の関数は英語、というケースが発生します。

対策は2つです。

1. CLAUDE.mdで指定: 「コードコメントは日本語で書く」と記載（推奨）
2. プロンプトで都度指定: 「コメントは日本語でお願いします」と毎回書く

CLAUDE.mdでの指定の方が安定するため、プロジェクト単位ではCLAUDE.mdでの一括指定を推奨します。

テストのdescribe/itを日本語で書く

テストの説明文は日本語で書いた方が可読性が高いケースが多いです。

describe("請求書の作成", () => {
  it("必須項目が全て入力されている場合、請求書が作成される", () => {
    // ...
  });

  it("請求金額が0円以下の場合、バリデーションエラーになる", () => {
    // ...
  });

  it("源泉徴収ありの場合、源泉徴収額が自動計算される", () => {
    // ...
  });
});

Claude Codeに「テストのdescribe/itは日本語で記述してください」と指定すれば、この形式で生成されます。CLAUDE.mdに記載しておけばセッションをまたいでも一貫します。

日本語ファイルパス・エンコーディングの落とし穴

英語のドキュメントには書かれていないが、日本語環境で確実に遭遇する問題がいくつかあります。

日本語を含むファイルパス

Claude Codeが操作するファイルのパスに日本語が含まれている場合、ほとんどのケースでは問題なく動作しますが、シェルコマンドの実行時に問題が発生することがあります。

特に以下のケースで注意が必要です。

• ディレクトリ名に日本語が含まれる（/Users/田中/projects/）
• ファイル名に日本語が含まれる（請求書テンプレート.tsx）
• パスにスペースと日本語が混在する

Claude Codeがシェルコマンドを生成する際、日本語パスのエスケープが不適切になるケースがあります。プロジェクトのディレクトリ構造は英語で統一しておくのが安全です。

文字エンコーディングの問題

Claude Codeが生成するファイルはUTF-8です。レガシーなシステムと連携するプロジェクトでは、以下の問題が発生する可能性があります。

• Shift_JIS/EUC-JPファイルの読み書き: Claude Codeはこれらのファイルを正しく読めない場合がある。読み込み時に文字化けしたコンテキストが送られると、出力も文字化けする
• CSVファイルのBOM: 日本語のCSVファイルをExcelで開く前提の場合、BOM付きUTF-8で出力する必要がある。Claude Codeに「BOM付きUTF-8で出力してください」と明示的に指示しないとBOMなしで生成される
• DBのカラムコメント: MySQLやPostgreSQLのカラムコメントに日本語を使う場合は問題ないが、マイグレーションファイルのエンコーディングがUTF-8であることを確認する

# BOM付きUTF-8でCSVを出力する指示例
CSVファイルを生成してください。
- エンコーディング: BOM付きUTF-8（Excelで日本語が文字化けしないように）
- 改行コード: CRLF
- ヘッダー行: 日本語

日本語の正規表現

Claude Codeは日本語文字列を含む正規表現の生成が得意ですが、明示的に指定しないと考慮されないパターンがあります。

• 全角/半角の混在: 「１２３」と「123」の両方にマッチさせたい場合は明示する
• カタカナ/ひらがなの表記ゆれ: 「サーバー」と「サーバ」の両対応は指示しないと片方のみ
• 長音符の有無: 「コンピューター」と「コンピュータ」

# 正規表現で表記ゆれを考慮させる指示例
電話番号のバリデーション正規表現を作成してください。
- 半角数字と全角数字の両方に対応
- ハイフン（-）と全角ハイフン（ー）の両方に対応
- 先頭の0は必須
- 例: 090-1234-5678, ０９０ー１２３４ー５６７８, 09012345678

i18n（国際化）対応でのClaude Code活用

多言語対応のプロジェクトでは、Claude Codeにi18n関連のタスクを依頼する場面が多くなります。ここでは日本語プロジェクトに特有のi18n対応のコツを共有します。

翻訳キーの生成

Claude Codeに翻訳キーを生成させる際は、ベース言語とターゲット言語を明示する必要があります。

# Before（曖昧）
このコンポーネントを多言語対応してください

# After（具体的）
このコンポーネントをnext-intlで多言語対応してください。
- ベース言語: 日本語
- ターゲット言語: 英語
- 翻訳ファイルの形式: JSON（messages/ja.json, messages/en.json）
- キーの命名: ドット記法（例: invoice.create.title）
- 日本語のテキストをすべて翻訳キーに置き換え
- 英語の翻訳文も生成

翻訳ファイルの更新

既存の翻訳ファイルに新しいキーを追加する場合、Claude Codeは既存のキーの構造を読み取って一貫した形式で追加できます。ただし、日本語と英語の翻訳ファイルの同期を忘れることがあるため、以下のように指示します。

以下の翻訳キーをja.jsonとen.jsonの両方に追加してください。
追加するキーだけでなく、追加後のファイル全体の整合性もチェックしてください。

日本語特有のi18n注意点

• 敬語レベルの統一: 「です/ます」と「だ/である」が混在しないよう、CLAUDE.mdにトーンを指定する
• 助数詞の処理: 「3件」「5個」「2名」のように、日本語は数量の単位が多様。ICUメッセージ形式で適切に処理する必要がある
• 日付フォーマット: 「2026年4月10日」「2026/04/10」「令和8年4月10日」のいずれを使うか明示する

日本語テストデータの生成

テストコードで日本語のテストデータが必要な場面は頻繁にあります。Claude Codeに指示しない場合、英語のテストデータが生成されるのがデフォルトです。

# テストデータを日本語で生成する指示例
以下のテストデータを日本語で生成してください:
- ユーザー名: 日本人の氏名（漢字 + ふりがな）
- 住所: 日本の住所形式（郵便番号 + 都道府県 + 市区町村 + 番地）
- 電話番号: 日本の携帯電話番号形式
- メールアドレス: ローマ字の名前を使用
- 会社名: 日本語の会社名（株式会社〇〇 形式）

テストデータの生成にはHaikuでも対応できます。モデルの使い分けの観点からも、定型的なデータ生成はコスト効率の良いモデルに任せると良いでしょう。

まとめ — 日本語環境でも実用的に使える、ただし「境界ルール」が鍵

Claude Codeは日本語環境でも十分に実用的です。ポイントは、暗黙の期待をせず、日本語と英語の境界ルールをCLAUDE.mdで明示的に設計することです。

• 指示文は日本語で書き、技術用語・固有名詞は英語のまま混在させる
• CLAUDE.mdに出力言語ルールを記載して、セッション間の揺れを防ぐ
• ドメイン用語対応表を用意して、変数名の一貫性を担保する
• 日本語ファイルパスとエンコーディングの問題を事前に把握しておく
• i18n対応ではベース言語とターゲット言語を明示して精度を上げる

これらの「境界ルール」をプロジェクトの初期段階で設計しておけば、日本語の開発プロジェクトでもClaude Codeを安定して活用できます。