Claude Codeが毎回同じミスをする？CLAUDE.mdを整える3ステップ

Claude Codeへ、毎回同じテスト方法や禁止事項を説明していませんか。

先に結論をお伝えすると、プロジェクトのルートへ短いCLAUDE.mdを置き、毎回必要な前提だけを書くことで、説明の繰り返しを減らせます。

この記事は、CLAUDE.mdをどこへ置き、何を書けばよいか分からない方に向けて、最小構成から安全に始める方法を解説します。

CLAUDE.mdは「毎回必要な引き継ぎメモ」

CLAUDE.mdは、人間がClaude Codeへ渡すMarkdown形式の指示ファイルです。

たとえば、次のようなプロジェクト固有の前提を書けます。

- 使用するパッケージ管理ツール

- 正確なテストやLintのコマンド

- 変更してはいけないファイル

- 重要なフォルダと役割

- 作業を完了と判断する条件

CLAUDE.mdがなくても、Claude Codeはファイルを探し、編集し、コマンドを実行できます。

ただし、プロジェクト特有の前提を毎回プロンプトで伝える必要があります。説明を忘れたり表現が変わったりすると、Claudeが一般的な方法を選び、このプロジェクトでは不正解になることがあります。

CLAUDE.mdの役割は、Claudeの知能を上げることではなく、仕事の前提を毎回そろえることです。

最初はプロジェクトのルートへ置く

CLAUDE.mdには、組織全体、ユーザー全体、プロジェクト、個人用という適用範囲があります。

初心者が最初に作るなら、プロジェクトのルートにあるCLAUDE.mdが分かりやすい選択です。Gitで共有すれば、チームも同じ前提を使えます。

- ユーザー全体の設定：自分がすべての案件で使う共通の好み

- プロジェクトの設定：チームで共有する規約、テスト、設計判断

- 個人用の設定：個人だけが使うテストデータ

適用範囲が広い場所へ、特定顧客の情報や一案件だけの規則を入れてはいけません。

Claude Codeは、作業場所とその上の階層にあるCLAUDE.mdを足し合わせて読みます。近い場所の内容で、上の内容が設定のように確実に上書きされるわけではありません。

上位に「英語で回答する」、下位に「日本語で回答する」と書けば、矛盾する指示が同時に渡ります。

複数のCLAUDE.mdは、上書きを前提にせず、内容が矛盾しないように分けます。

適用範囲の異なる指示は足し合わせで渡されます。下位で打ち消さず、矛盾をなくします。AI生成の図解です。

書く内容は4種類に絞る

最初から長いマニュアルを作る必要はありません。

1. プロジェクトの目的を書く

何を作るリポジトリなのかを、1〜2文で示します。

2. 重要な場所を書く

アプリケーションコード、テスト、確定した設計資料、削除可能な一時ファイルなど、間違えると困る場所だけを書きます。

3. 正確な確認方法を書く

「適切にテストする」ではなく、「変更後にpnpm testを実行する」のように、行動と確認方法を具体化します。

4. 安全上の境界と完了条件を書く

秘密情報を開かない、原本を上書きしない、大量の移動前に対象一覧を示す、関連テストが成功したら完了とする、といった境界を示します。

コードを読めば分かる説明ではなく、Claudeが推測しにくい非自明な情報を優先します。

長くなったら役割ごとに分ける

公式ドキュメントが示す目安は、CLAUDE.mdを1ファイル200行未満に保つことです。

これは200行までなら必ず守られるという保証ではありません。短く、具体的で、矛盾がないほど、重要な指示を見つけやすくなります。

内容が増えたら、必要になるタイミングで分けます。

- 毎回必要な前提：CLAUDE.md

- 特定のファイルやフォルダだけの規則：Rules

- デプロイやレビューなどの長い手順：Skills

- 決まったタイミングで必ず実行・停止する処理：Hooks

指示が長くなったら、単に分冊せず「いつ必要か」で置き場所を分けます。AI生成の図解です。

別ファイルを読み込む構文は、内容の整理には使えます。ただし、読み込んだファイルも起動時のコンテキストへ入るため、分割だけでは軽くなりません。

毎回必要でない内容は、単なる分割ではなくRulesやSkillsへ移します。

Auto Memoryとは役割が違う

CLAUDE.mdは人間が決めるルールです。

Auto Memoryは、Claudeが作業中に見つけた学びや訂正、繰り返し使えるパターンを残す仕組みです。

Auto Memoryは既定では端末内に保存され、プロジェクトのCLAUDE.mdのようにGitでチーム共有されるものではありません。Claudeが書いた内容にも、古い情報や誤った推測が混ざる可能性があります。

人間が守ってほしい前提はCLAUDE.md、Claudeが仕事から得た学びはAuto Memoryと分けて考えます。

効かないときに確認する3項目

1. 読み込まれているか確認する

contextコマンドで、対象のCLAUDE.mdがMemory filesに表示されるか確認します。

2. 曖昧さと矛盾を確認する

「きれいに」「適切に」のような表現を、実行するコマンドや確認可能な条件へ変えます。上位と下位、個人用、Rulesに反対の指示がないかも確認します。

3. 不要な説明を削る

コードを読めば分かる構成説明、依存関係一覧、使わなくなったコマンドを削ります。doctorコマンドの整理提案も使えますが、採用前に差分を確認します。

指示を書いただけで完成とせず、小さな依頼で行動が変わったかを確認します。

自動化だけに任せない方がよい境界

CLAUDE.mdはコンテキストであり、強制設定ではありません。

次のような内容は、CLAUDE.mdへ書くだけでなく、権限設定、サンドボックス、Hooksなども検討してください。

- 秘密情報を確実に読ませたくない

- 特定フォルダへの書き込みを止めたい

- ファイル編集後に必ず検査を実行したい

- 削除やデータ送信を厳密に制限したい

また、実在しないテストコマンドをテンプレートからコピーしてはいけません。必ずプロジェクトの実態に合わせます。

今日から始める3ステップ

1. プロジェクトを変更せずに調べる

2. 200行未満のCLAUDE.md案を作り、人間が内容を確認する

3. 新しいセッションで読み込みと実際の行動を確かめる

最初から巨大な指示書を作る必要はありません。

次の仕事でも知っていてほしい、非自明な前提を一つずつ残すことから始めてください。

参考資料

- Claude Code公式「How Claude remembers your project」

- Claude Code公式「Best practices for Claude Code」

- Claude Code公式「Extend Claude Code」

- Claude Code公式「Hooks reference」