Claude Codeを使い始めたのに、毎回同じ説明をしているなら、先に整えるべきなのは会話ではなくCLAUDE.mdです。

Claudeはこのファイルをセッション開始時に読み込み、プロジェクトの前提、命名、コマンド、禁止事項を保持します。つまり、うまく書けたCLAUDE.mdは、AIに毎回事情を説明する手間を減らし、出力のぶれも抑えます。

この記事では、CLAUDE.mdに何を書くべきか、何を入れないべきか、どう運用すると効果が出るかを整理します。

  • CLAUDE.mdの役割
  • 入れるべき項目と削るべき項目
  • すぐ使える運用の考え方
Give Claude context: CLAUDE.md and better prompts | Claude Help Center
support.claude.com

CLAUDE.mdはプロジェクトの記憶です

Claudeのヘルプセンターでは、CLAUDE.mdは各ディレクトリでClaudeが自動的に読むプレーンなMarkdownファイルだと説明されています。ポイントは「プロンプトで都度渡すもの」ではないことです。ファイルがあれば、Claudeは最初から読んだ前提で動きます。

この設計の価値は単純です。毎回の指示を短くできます。さらに、長い説明を会話に散らさず、プロジェクトのルールを1か所に集約できます。人間の新人に渡す引き継ぎメモと同じで、最初に読ませる情報が整っているほど、後工程が安定します。

CLAUDE.mdは全体の憲法ではありません。実務では、頻繁に変わる作業指示ではなく、変わりにくい前提だけを置くのが正解です。ここを誤ると、ファイルが長くなるだけで効果が薄れます。

入れるべきなのは、作業に効く情報だけです

Claudeの公式案内では、CLAUDE.mdに向いているのはコマンド、規約、構成の説明、強い制約、よくある落とし穴です。逆に、詳細なAPI仕様や変更履歴、見れば分かるツリー情報は不要です。

ここで大事なのは、AIが迷う場面を先回りして潰すことです。たとえば次のような項目は効果が高いです。

  • ビルド、テスト、起動コマンド
  • ディレクトリごとの役割
  • 命名規則
  • 使う技術と使わない技術
  • 本番DBに触ってはいけない、といった制約
  • 仕様が揺れやすい箇所の注意点

逆に、何でも入れると逆効果です。長すぎるCLAUDE.mdは、読みやすさよりもノイズの増加が先に来ます。Claudeの公式ヘルプでも、短く信号密度の高いファイルに保つべきだと案内されています。目安は数百行ではなく、実務で必要な情報に絞ることです。

まず書くべきは3つです

最初の版では、完璧を目指す必要はありません。最低限、次の3種類があれば十分に機能します。

  1. プロジェクトの前提
  2. 使うコマンド
  3. 守るべきルール

前提には、何のプロダクトか、主な言語、主要ディレクトリ、外部サービスを短く書きます。コマンドには、install、test、lint、devを入れます。ルールには、手を入れてよい範囲と、触ってはいけない領域を書きます。

この3点だけでも、Claudeの質問回数はかなり減ります。AIは「何を作るか」より「どの前提で作るか」が分からないと止まりやすいからです。

更新は仕様変更のたびにやるべきです

CLAUDE.mdは一度作って終わりではありません。Claudeの公式ガイドでも、実際に間違いが続いたときや、コマンドや規約が変わったときに更新する運用を勧めています。

更新の判断基準はシンプルです。

  • Claudeが同じミスを2回した
  • 新しいフレームワークやテストランナーを入れた
  • ディレクトリ構成を変えた
  • 手戻りの原因が毎回同じ

この運用にすると、CLAUDE.mdはただの設定ファイルではなく、プロジェクトの失敗履歴を反映する文書になります。実際のミスに合わせて1行ずつ改善したほうが、最初から理想形を狙うより強いです。

生成された草案はそのまま使わないほうがいいです

Claudeの公式ガイドには、/initでコードベースを走査し、CLAUDE.mdの下書きを作る流れが案内されています。これは出発点としては有効ですが、そのまま採用すると抜けが出ます。

特に見直すべきなのは、次の3つです。

  • 実際には使っていないコマンドが混じっていないか
  • すでに廃止したルールが残っていないか
  • チーム全員が守れる内容になっているか

AIが自信満々に書いた文面でも、現場の運用とずれていれば無意味です。CLAUDE.mdはAI向けである前に、チームの実態を正しく写す必要があります。

どこまで細かく書くかで品質が決まります

CLAUDE.mdの強みは、曖昧な期待を具体化できることです。たとえば「テストを書く」より「変更したファイルに対応するテストを追加する」と書いたほうが効きます。「安全に対応する」より「本番DBへの書き込みは禁止」と書いたほうがぶれません。

この差は小さくありません。AIは抽象語に弱く、具体語に強いです。だからこそ、ふわっとした理想論より、実際の判断基準をそのまま書くほうが成果につながります。

一方で、実装の細部を全部書く必要はありません。コードを読めば分かることまで書くと、保守コストだけが増えます。CLAUDE.mdは説明書ではなく、判断の迷いを消すための基準表です。

まとめると、これはAI用の引き継ぎ台本です

CLAUDE.mdの価値は、Claudeを賢く見せることではありません。毎回の説明を減らし、同じ誤りを減らし、チームの暗黙知を固定化することにあります。

Claude Codeを本気で使うなら、最初にやることはプロンプトの工夫ではなく、CLAUDE.mdの整備です。ここが弱いと、AIは毎回ゼロから推測します。ここが強いと、AIはプロジェクトの前提を持った状態で仕事を始めます。

新しく導入するなら、まずは短く作って、実際の失敗に合わせて直す。これが最短で効く運用です。