SECTION 01
結論：CLAUDE.mdは日本語で書いて問題なく効く
Claude CodeのCLAUDE.mdは、日本語で書いても精度が落ちる実感がありません。以前ChatGPT APIを使っていた頃は「system promptは英語で書く」「日本語はトークンが多いから節約のために英語にする」という工夫をしていました。GPT-3.5 Turboで日本語質問し、それで足りなければGPT-4で英語質問、という段階的な切り替えも試していた時期があります。
しかしClaude Codeになってから、そのトークンコスト管理や言語の切り替えをほぼしなくなりました。複雑な機能の要件も日本語で説明していますし、並行して複数ターミナルを走らせていても、それぞれ日本語指示で問題なく動いています。
英語で書くべきケースがあるとすれば、技術用語・コマンド名・ファイルパスなど固有名詞の部分だけです。「TypeScriptで書く」「pnpmを使う」といった技術スタック名はそのまま英語で書き、説明文は日本語で十分に通ります。
実際の開発フローは、メモ帳で日本語の要件を下書きしてClaude Codeにコピペするというシンプルなものです。「指示の言語をどうするか」を考える時間そのものがもったいないですし、今のモデルではその工夫が不要になったと感じています。
SECTION 02
CLAUDE.mdとは何か？配置場所と読み込みの仕組み
CLAUDE.mdは、Claude Codeがセッション開始時にコンテキストとして自動で読み込むプロジェクト固有の指示書です。毎回プロンプトに手動で貼り付けなくても、プロジェクトのルールやコンテキストが自動的にAIに伝わります。設定なしの状態だと、Claude Codeはコードベースから推測して動くため、意図と異なる出力が出やすくなります。
配置場所は主に3つあり、それぞれスコープが異なります。どこに何を書くかで、AIの挙動が大きく変わるポイントです。
配置場所の使い分けは以下のとおりです。
- プロジェクトルートの
CLAUDE.md（または.claude/CLAUDE.md） — そのリポジトリ固有のルール（技術スタック、コーディング規約、ディレクトリ構成など）を書く場所。チームで共有するルールはここに置きます ~/.claude/CLAUDE.md— すべてのプロジェクトに共通で適用したいルール（文体の好み、レビュー手順など）を書く場所- プロジェクトルートの
CLAUDE.local.md— 特定プロジェクトに対するユーザー個人の指示（チーム共有しない個人設定）を書く場所。.gitignoreに入れて使います
これらのファイルは単純な上書きではなく、見つかったファイルが連結されてコンテキストに入る仕組みです。同一階層ではCLAUDE.local.mdが後ろに追加されるため、より具体的な場所や後段の指示が強く働きやすくなります。会話中に「この規約は無視して」と伝えれば、CLAUDE.mdの記載より会話内の指示が優先されます。この仕組みを理解しておくと、ルールが効かないときの原因切り分けがしやすくなります。
設定ありと設定なしの差は、繰り返しの指示が不要になる点に最も現れます。たとえばCLAUDE.mdに「テスト追加時はVitestを使う」と一度書けば、毎回「テストフレームワークはVitestで」と言わなくて済みます。
SECTION 03
日本語で効くCLAUDE.mdの書き方テンプレート
CLAUDE.mdの基本構造は、Markdownの見出し＋箇条書き＋具体例のセットで組み立てます。長い説明文を書くのではなく、ルールを一行ずつ箇条書きにするのがポイントです。AIは構造化された指示のほうが正確に拾います。
以下はコピペで使えるテンプレートの骨格です。
## 技術スタック— 使用言語、フレームワーク、パッケージマネージャを列挙する## コーディング規約— 命名規則、import順、エラーハンドリング方針を箇条書きで書く## ディレクトリ構成— 主要ディレクトリの役割を一行ずつ説明する## ビルド・テスト— ビルドコマンド、テストの実行方法、使うフレームワーク名を書く
効く書き方のコツは、命令形で短く、1ルール1行にすることです。「TypeScriptのstrictモードを使う」「コンポーネントはdefault exportしない」のように、判断に迷わない粒度で書きます。曖昧な表現は避けてください。
たとえば「きれいなコードを書いてください」はAIにとって解釈の余地が広すぎて効きません。代わりに「関数は単一責任にする」「変数名は省略せず意味が伝わる英語にする」のように、具体的な行動に落とし込みます。
自分のCLAUDE.mdには、レビュー・テスト・スクリーンショット撮影といった動作確認のルールも日本語で記述しています。仕様書レベルの指示を書いたこともあり、「rawよりdistilledを優先する」「不明点は埋めすぎず保守的に書く」といった判断基準も全部日本語で記載して、問題なく効いています。
SECTION 04
避けるべき書き方：指示が無視されるアンチパターン
CLAUDE.mdに書いたルールが無視されるとき、日本語が原因だと思いがちですが、実際は指示の構造のほうが影響が大きいです。これは試行錯誤の中で何度も経験して確信したことです。言語を英語に変えるより、書き方の構造を直すほうがはるかに効果があります。
最も多いアンチパターンは、長文の説明調で書くことです。「このプロジェクトでは○○という背景があり、そのため△△を考慮して、××のように実装してください」という文章は、ルールの核心が埋もれます。AIは箇条書きの先頭にある指示を拾いやすいので、背景説明は最小限にしてください。
以下のパターンも指示が効きにくくなります。
- 「〜ですよね？」等のクローズド表現 — AIが忖度して「はい」と答えるだけになりやすい
- ルールが多すぎて優先順位が不明 — 重要なルールにIMPORTANTを付けるか、セクションの上部に配置する
- 「〜してください」の丁寧語の羅列 — 命令形のほうがルールとして認識されやすい
代わりに有効なのは、オープンクエスチョン型の構造に変えることです。「この要件を満たすために効率的な処理フローの選択肢を提案してください」のように、AIに考える余地を渡します。また複雑な実装を丸投げするのではなく、先に「実装計画書」を作らせてから進む、という手順を挟むだけでも精度が大きく変わります。
Markdownの見出しレベルや箇条書きの階層構造も、指示精度に直接影響します。##見出しでセクションを区切り、その下に箇条書きでルールを並べる形式が最も安定します。見出しなしでフラットに書くと、AIがどこからどこまでが一つのルールなのか判断しづらくなります。
SECTION 05
Cursorの.cursorrulesからCLAUDE.mdへの移行ガイド
.cursorrulesとCLAUDE.mdは似ているようで、概念が異なります。.cursorrulesはエディタの振る舞いを含む設定ファイルですが、CLAUDE.mdはAIへの直接指示に特化しています。この違いを理解しないまま移行すると、効かないルールが増えます。
移行時に意識すべき変換ポイントは以下です。
- エディタ固有の設定は除外する — タブ幅やフォーマッタの設定はCLAUDE.mdに書いても意味がない
- 粒度を細かくする — .cursorrulesは大まかな方針で済むことが多いが、CLAUDE.mdは具体的な行動レベルで書くほうが効く
- 配置場所を正しく選ぶ — プロジェクト固有のルールはリポジトリルートのCLAUDE.mdに置く
そのままコピペで動く部分もあります。技術スタックの列挙、命名規則、ディレクトリ構成の説明などは、.cursorrulesからそのまま持ってきて問題ありません。Markdown形式で書かれていればなおさらです。
一方で書き換えが必要な部分は、自然言語での方針記述です。「読みやすいコードを心がける」のような抽象的なルールは、Claude Code向けに「関数は単一責任にする」「ネストは3階層まで」のように具体化する必要があります。
移行作業は一度にやる必要はなく、使いながら足りないルールを追加していくのが現実的です。最初にスタック情報とビルドコマンドだけ移行し、AIの出力を見ながら規約を追加するサイクルが効率的です。
SECTION 06
CLAUDE.mdを育てるタイミングと分割の判断基準
CLAUDE.mdは最初から完璧に書く必要はなく、プロジェクトの成長に合わせて育てるものです。新規開発中はルール設定を後回しにしても問題ないと感じています。開発初期はルール自体がどんどん変わるので、固めても意味がないからです。
ただし後回しにしすぎると、設定していれば防げた手戻りが発生する場面も出てきます。プロダクトが一定の形になってきたタイミングで書き直す、というサイクルが現実的です。目安としては、同じ指示を会話のたびに繰り返し打ち込んでいることに気づいたら、それをCLAUDE.mdに書くタイミングです。
ファイル分割の判断基準は以下のとおりです。
- 1ファイルのCLAUDE.mdが長くなりすぎたら分割を検討する — 目安としてスクロールが必要な量になったとき
- 共通ルールとプロジェクト固有ルールは配置場所で分ける —
~/.claude/CLAUDE.mdとプロジェクトルートのCLAUDE.mdで棲み分ける - チーム共有しない個人設定は
CLAUDE.local.mdに置く — レビュー手順や個人的な好みはここに入れる
育て方のコツは、AIの出力に違和感を覚えたらすぐにルールを足すことです。「なんで毎回default exportにするんだろう」と思ったら、その場で「default exportは使わない」と追記します。この積み重ねが、CLAUDE.mdの精度を上げていきます。
SECTION 07
Markdownの構造が指示精度を左右する
CLAUDE.mdの中身だけでなく、Markdownの書式そのものがAIの理解度に影響します。見出し・箇条書き・改行の使い方一つで、同じ内容でも効き方が変わります。
最も安定するのは、##レベルの見出しでカテゴリを分け、その下に箇条書きでルールを並べる形式です。#（h1）は使わず、##と###で階層を作ります。これはClaude Codeがセッション開始時にコンテキストとして読み込む際に、セクション単位で構造を認識しやすいためです。
書式で意識すべきポイントをまとめます。
- 箇条書きの各項目は1ルール1行にする — 複数のルールを1行にまとめない
- 重要なルールには
IMPORTANTや太字を使う — Claude Codeは強調されたテキストを優先的に認識する傾向がある - コード例は必要最小限にする — CLAUDE.md内のコードブロックが長すぎると、ルール部分の認識が薄まる
改行の使い方にも注意が必要です。箇条書きの間に空行を入れすぎると、リストが途切れて別のセクションとして認識される場合があります。逆に詰めすぎると可読性が下がるので、Markdownのプレビューで確認しながら調整するのがおすすめです。
SECTION 08
ルールが効かないときのチェックリスト
CLAUDE.mdを書いたのにルールが無視されると感じたとき、まず配置場所が正しいかを確認してください。ファイル名の大文字小文字（CLAUDE.md）や、配置ディレクトリの階層を間違えているケースが意外と多いです。
確認の手順は以下が効率的です。
/memoryコマンドで読み込み状況を確認する — Claude Codeが認識しているCLAUDE.md・CLAUDE.local.md・rulesの一覧が表示されます。公式推奨の確認方法です- ファイル名が
CLAUDE.mdになっているか確認する —claude.mdやClaude.mdでは読み込まれない場合があります - プロジェクトルートにあるか確認する — サブディレクトリ内の
CLAUDE.mdは起動時には読み込まれません。ただし、そのディレクトリ配下のファイルをClaude Codeが読んだタイミングでオンデマンドで読み込まれる仕組みになっています
配置が正しいのに効かない場合は、ルールの衝突を疑います。会話中にCLAUDE.mdと矛盾する指示を出していると、会話内の指示が優先されます。また、CLAUDE.mdの中でルール同士が矛盾していると、AIがどちらを採用するか不安定になります。
Claude Codeのアップデート後に効き方が変わることも稀にあります。この場合、まずバージョンを確認し、同じCLAUDE.mdで以前と挙動が違うのかを切り分けます。アップデートでコンテキストの処理が変わることがあるため、効かなくなったルールは表現を変えて試すのが有効です。
最終手段として、ルールの表現をより強い形に書き換える方法があります。「〜する」を「〜すること。例外なし」に変える、セクション冒頭に「IMPORTANT:」を付ける、といった強調が効く場合があります。ただし全部のルールを強調すると逆効果なので、本当に守ってほしいルールだけに限定してください。
SECTION 09
実務で使っているCLAUDE.mdの実例と工夫
ここでは実際に使っているCLAUDE.mdの工夫を紹介します。ワークフロー全体をCLAUDE.mdに記述することで、毎回の指示量を大幅に減らせます。セルフレビューの手順、テストの実行方法、コミット前のチェック項目などを書いておくと、AIが自律的にそれらを実行してくれます。
具体的に書いている内容の例です。
- ワークフロー定義 — 複数ファイルの変更を伴うタスクではプランモードを使う、という判断基準
- セルフレビュー手順 — 実装完了後に正確性・セキュリティ・可読性を確認するチェック項目
- ビルドコマンド —
pnpm dist:mac:prodのような頻繁に使うコマンドをそのまま記載
ポイントは、AIの判断に委ねたい部分と、固定したい部分を明確に分けることです。「単一ファイルの軽微な修正はそのまま実装、複数ファイルにまたがる変更はプランモードで設計してから実装」のように、条件分岐をCLAUDE.mdに書いておくと、AIが適切に判断を切り替えてくれます。
もうひとつの工夫は、「やらなくていいこと」を明記することです。「不要なdocstringを追加しない」「変更していないコードにコメントを足さない」など、AIが過剰にやりがちなことを制限するルールは効果が大きいです。
CLAUDE.mdは環境の根幹に関わるファイルだという認識を持つのが大事です。メモリ機能やサブエージェントと並んで、AIの振る舞いを決定づける中核的な設定です。書き捨てではなく、プロジェクトの資産として継続的にメンテナンスする価値があります。
SECTION 10
まとめ：まずは3行から始めてみる
CLAUDE.mdは日本語で書いて問題なく効きます。英語にする必要があるのは技術用語だけで、説明文やルールは日本語で十分です。トークンコストを気にして英語に翻訳する時代は、少なくともClaude Codeでは過去のものになりました。
最初から完璧なCLAUDE.mdを目指す必要はありません。まずは以下の3行から始めてみてください。
- 使っている技術スタック（言語、フレームワーク、パッケージマネージャ）
- 最も重要なコーディング規約（1〜2個だけ）
- ビルドまたはテストの実行コマンド
この3行があるだけで、AIの出力精度が目に見えて変わるはずです。そこから先は、AIの出力に違和感を覚えるたびにルールを足していけば、自然と自分のプロジェクトに最適化されたCLAUDE.mdが育っていきます。
指示が効かないと感じたときは、言語のせいではなく構造のせいだと疑ってください。命令形で短く、1ルール1行、箇条書きで書く。この原則を守るだけで、CLAUDE.mdの効き方は大きく改善されます。
