CLAUDE.mdの基本解説

CLAUDE.mdは新しいセッションに渡す引き継ぎメモ 生成AI・AIツール

ClaudeCodeを使うなら、必ず設定するものがある。それがCLAUDE.mdだ。

「今さらそんな初歩的な話?」と思うかもしれない。ただ、ちょっと待って欲しい。

CLAUDE.mdは、考えなしに作ると効率が悪くなる。むしろClaudeCodeの頭を悪くすることすらある。

特に非エンジニアのプロジェクトでは、CLAUDE.mdの仕様と基本方針を押さえているかどうかで、ClaudeCodeの挙動が結構変わってくる。

今回は、非エンジニア目線でCLAUDE.mdの基本と実運用のコツを解説していこうと思う。

ClaudeCodeを触っている非エンジニアの人、ClaudeCodeの挙動を安定させたい人、コンテクストが膨らんでClaudeCodeの頭が悪くなってきたと悩んでいる人の参考になれば幸い。

CLAUDE.mdとは?

結論、CLAUDE.mdは「ClaudeCodeにこれは守って欲しい」を伝える指示書だ。

中身はただのテキストファイル。プロジェクトのフォルダに置いておくと、ClaudeCodeがセッションを始めるたびに必ず読み込んでくれる。

イメージは「新しく来た人への引き継ぎメモ」

ClaudeCodeは、セッションが変わるたびに前の会話を覚えていない状態からスタートする。毎回、記憶リセット状態の新人が来るようなものだ。

そこで、毎回読んでもらう引き継ぎメモとして置いておくのがCLAUDE.mdになる。

CLAUDE.mdは新しいセッションに渡す引き継ぎメモ

公式ドキュメントでも、CLAUDE.mdは「毎回説明し直していることを書き留めておく場所」として扱うよう案内されている。追記のタイミングの目安として挙げられているのは、たとえば次のようなケースだ。

  • ClaudeCodeが同じミスを2回した
  • 前のセッションでも打ったのと同じ訂正や補足を、またチャットに打っている
  • 新しくチームに入った人にも、同じ説明が必要になりそう

何を書くものなのか

公式ドキュメントでは、毎回のセッションで押さえておいて欲しい事実を書くよう案内されている。具体的には、作業の決まりごと、プロジェクトの構成、「必ず〇〇する」系のルールなどだ。

一方で、何ステップもある手順や、一部の作業にしか関係ない内容は、CLAUDE.mdではなくスキルなど別の仕組みに分けるよう書かれている。

CLAUDE.mdに書く内容とスキルに分ける内容

書き方は「具体的に」が基本

公式ドキュメントでは、指示はチェックできるくらい具体的に書くようすすめられている。

  • ×「ファイルをきちんと整理して」
  • ○「記事の画像は inputs/images/ に置く」

前者だと「きちんと」の基準がAI任せになる。後者なら、守れたかどうかが一目でわかる。

また、指示同士が矛盾していると、ClaudeCodeがどちらか一方を勝手に選ぶことがある、とも書かれている。これは後半の「よくぶち当たる壁」にもつながる話だ。

設定の方法

ここからは、CLAUDE.mdの設定方法を解説していく。

置き場所は主に3つ

まず押さえておきたいのが置き場所だ。置く場所によって、効く範囲が変わる。

CLAUDE.mdの置き場所と適用範囲
置き場所効く範囲向いている内容
~/.claude/CLAUDE.md自分の全プロジェクトどのプロジェクトでも共通の好み
プロジェクトのフォルダ直下の CLAUDE.mdそのプロジェクト(チームと共有できる)フォルダ構成、作業ルール
プロジェクトのフォルダ直下の CLAUDE.local.mdそのプロジェクトの自分だけ自分専用のメモや設定

非エンジニアがまず使うのは、2つ目の「プロジェクトのフォルダ直下」で十分だと思う。

ちなみに、これ以外に会社のIT部門が全社員向けに配るための置き場所もある。個人で使う分には気にしなくてOK。

作り方は3つ

作り方は次の3つがある。

①自分でファイルを作って書く

一番シンプルな方法。プロジェクトのフォルダ直下にCLAUDE.mdという名前のファイルを作って、書きたいことを書くだけだ。

中身は普通のMarkdownでいい。見出しと箇条書きで整理しておくと、ClaudeCodeも読み取りやすい。公式ドキュメントでも、長い文章で書くより見出しと箇条書きでまとめる方が従いやすいと説明されている。

②/initコマンドで作成する

ClaudeCodeを起動して/initと打つ方法。

公式ドキュメントによると、ClaudeCodeがフォルダの中身を分析して、見つけた決まりごとなどをもとにCLAUDE.mdのたたき台を作ってくれる。すでにCLAUDE.mdがある場合は、上書きせずに改善案を出してくれる。

ただ、/initで作れるのはあくまでたたき台だ。公式ドキュメントでも、ClaudeCodeが自分では気づけない指示を後から足していくよう案内されている。

③ClaudeCodeに頼んで作ってもらう

チャットで「このフォルダのCLAUDE.mdを作って」と頼む方法。

フォルダ構成や使い方を口頭で伝えながら作れるので、非エンジニアには一番とっつきやすいと思う。

ただ、任せっぱなしにすると、ClaudeCodeが気を利かせて色々書き足してくる。ここは後半の「よくぶち当たる壁」で詳しく話す。

ちゃんと読み込まれているか確認する

作ったら、ちゃんと読み込まれているかを確認しておこう。

ClaudeCodeのセッション内で/context allと打つと、今読み込まれているコンテクストの一覧が出る。その中の「Memory files」の欄にCLAUDE.mdが表示されていればOKだ。

よくぶち当たる壁

CLAUDE.mdを使っていると、だいたい次の3つの壁にぶち当たる。

何を書けばいいのかわからない

仕様はわかっても、自分で書こうとすると何が最適なのかわからない。

あれもこれも追加したくなる。「これでいいのか」「もっといい書き方があるんじゃないか」と悩み始めて、放浪の旅が始まる。

コンテクストが肥大化してくる

CLAUDE.mdは毎回読まれる重要な指示だ。そう聞くと、あれもこれも書き足したくなる。

その結果、作業のたびに追記を重ねて、ルール同士が矛盾したり、ルールが多すぎて制御できなくなったりする。

AIにCLAUDE.mdの編集を任せているほど、この傾向は強くなる。とりあえず追加、とりあえず追加、で膨らんでいく。

指示の追加でCLAUDE.mdが肥大化する流れ

意図しない動きや注意事項が増えてくる

コンテクストの肥大化とつながる話なんだけど、CLAUDE.mdが長くなると、ClaudeCodeが意図しない動きをし始める。

あまり意味のない注意事項まで律儀に守ろうとして、結果的に頭が悪くなる。

これもClaudeCodeに編集を任せたときの「あるある」だ。作業のたびに注意書きが1行ずつ増えていく。(気づいたら誰も読まない社内規定みたいになってる。)

おすすめの運用方法

結論から言うと、押さえて欲しいのは次の3点だ。

  • あまり作り込まない
  • 説明はディレクトリ構成に留めておく
  • 必ず守らせたいルールはhooksで対応する

以下の動画でも軽く触れているので、あわせて見てもらえると嬉しい。

Claude Codeは作り込むな。非エンジニアが仕事で成果を出す「サイクルの回し方」

あまり作り込まない

CLAUDE.mdは、書く内容を絞って作り込みすぎないことが大事だ。

というのも、CLAUDE.mdに万人向けの正解は存在しないから。ベストプラクティスや公式のテンプレートのようなものはある。ただ、最適なCLAUDE.mdはプロジェクトごとに違う。

最適解を作り込もうとすると、沼にハマって肝心の作業が進まなくなる。それは時間のロスだし、本質的じゃない。

僕は、先にディレクトリ構成を作ってしまって、それを後からCLAUDE.mdに書く方がいいと思っている。

説明はディレクトリ構成に留めておく

前提として、CLAUDE.mdに書く内容は極力少なくした方がいい。

理由は、毎回必ず読み込まれるから。文字数が多いほどコンテクストを圧迫するし、余計な情報も乗る。トークンも勿体無い。

公式ドキュメントでも、CLAUDE.mdは1ファイルあたり200行以内を目安にするよう案内されている。長いファイルはコンテクストを消費し、指示が守られにくくなるとのこと。

じゃあ何を書くべきか。個人的には、ディレクトリ構成を書いておくのがおすすめだ。

というのも、構成を書いておくと、その後のセッションで雑に情報を渡しても、ClaudeCodeが「これはここに置くもの」と判断して、きれいに整理してくれるから。

CLAUDE.mdに書いたディレクトリ構成と各フォルダの役割

他に追加するとしたら、次のあたりだと思う。

  • 作業中に気になった口調・文体の注意
  • セキュリティ対策

ただ、このあたりも後述のhooksで対応していいんじゃないかとは思っている。

必ず守らせたいルールはhooksで対応する

ここまで、CLAUDE.mdは毎回読まれる重要な指示だと説明してきた。ただ、実は拘束力は確実なものじゃない。

あくまでAIに「お願い」している感覚で、守るかどうかは最終的にAIに委ねられている。公式ドキュメントでも、CLAUDE.mdは強制的な設定ではなくコンテクストとして扱われる、と説明されている。

一方で、100%従わせたい挙動があるなら、hooksを使うのがおすすめだ。たとえば、生成後に毎回チェックをかけたいときや、特定の操作を禁止したいときなど。

hooksは、ClaudeCodeが指定した動きをしたときに必ず発火する仕組みだ。プログラムで処理するので、AIモデルの判断に関係なく決めた処理を実行できる。

CLAUDE.mdによる指示とhooksによる処理の違い

hooksの使い方は前に記事を書いているので、こちらもぜひ参考にして欲しい。

【非エンジニア向け】Claude Code hooksの使い方|通知・削除確認の設定例

まとめ ~重要事項こそ整理整頓せよ~

最後に、今回の内容を振り返っておく。

  • CLAUDE.mdは、毎回必ず読み込まれる「守って欲しいこと」の指示書
  • 作り込みすぎると、矛盾や肥大化でClaudeCodeの頭が悪くなる
  • 書く内容は絞って、まずはディレクトリ構成を中心にする
  • 公式の目安は1ファイル200行以内
  • 絶対に守らせたいルールは、CLAUDE.mdではなくhooksで対応する

毎回読まれる大事な場所だからこそ、何でも詰め込むんじゃなくて、整理整頓しておくのが大事だと思う。

CLAUDE.mdに悩んでいる人の、運用を見直すヒントになれば嬉しい。

東京在住の25歳。
後先は考えないタイプで、高校受験、東大受験(現役・浪人)ともに併願なしで挑んでました。
東京大学文科1類に運良く合格。法学部に進みましたが、一番面白かったのはICT系・芸術の授業でした。
興味が続かずに弁護士にはならず、ITベンチャー企業で働いています。
動画編集、プログラミング、最近はAIなど色々やってます。

yuta|生活を豊かにするAI・自動化をフォローする
生成AI・AIツール
シェア・ご感想などお待ちしております!
yuta|生活を豊かにするAI・自動化をフォローする
タイトルとURLをコピーしました