Claude CodeのCLAUDE.md入門｜AGENTS.md・Skillsとの使い分け

Claude Codeに毎回「このプロジェクトではどのコマンドでテストする？」「変更してはいけない範囲は？」と説明しているなら、CLAUDE.mdを見直す価値があります。これはClaude Codeが作業時に参照する、プロジェクトの継続的な指示を置くファイルです。ただし、長い作業手順を何でも書き込めばよいわけではありません。似た名前のAGENTS.md、必要なときだけ使うSkills、Claude自身が残すauto memoryとも役割が違います。

最初から完璧な指示集を目指す必要はありません。短い初版を作り、実際の作業で繰り返し説明した部分だけを追加していく方が、古い規則の蓄積を防げます。

この記事では、置き場所を決めるところから、最小限の内容の書き方、読み込まれたかの確認、チームで共有するときの注意点までを一つの例で追います。Claude Codeの現在の公式ドキュメントに基づきますが、実際に使える機能は利用中のバージョンと設定で確認してください。

結論：CLAUDE.mdには「このリポジトリで毎回必要な前提」を短く書きます。特定の作業だけに必要な複数手順はSkillへ、ファイル種類ごとの規約はrulesへ移すと、毎回の説明を減らしながら読みやすさを保てます。

CLAUDE.mdとは何か

CLAUDE.mdはClaude Codeに対して継続的な文脈を渡すMarkdownファイルです。たとえば使用言語、リポジトリの主なディレクトリ、テストコマンド、変更時に守る設計上の制約などを書きます。次のセッションでも同じ前提を説明し直さずに済むことが狙いです。

大事なのは、これは「絶対に破れない設定ファイル」ではなく、モデルが読む指示だという点です。公式ドキュメントも、Claudeがこれらを文脈として扱うと説明しています。たとえば「本番データを削除しない」と書くことは有益ですが、不可逆な操作を技術的に禁止したい場合は、権限設定やhook、CIなど別の仕組みで守る必要があります。CLAUDE.mdの一文だけをアクセス制御の代わりにしてはいけません。

もう一つの特徴は、読み込まれる頻度です。プロジェクトのCLAUDE.mdはセッションの開始時に文脈へ入り、近い階層のファイルは作業対象に応じて読み込まれます。いつも使う規約に向いている一方、長文を増やし続けると、その分だけ会話の文脈を占めます。公式ガイドは簡潔さと具体性を重視しています。

まず書くべき情報

初版は数十行で十分です。チームの人が新しい端末でリポジトリを開いたとき、同じ作業を始めるために最低限必要な情報から書きます。

• 何を作るリポジトリか、どこに主要コードがあるか
• インストール、ビルド、テストの実際のコマンド
• コードの変更に直結する規約
• 動かしてはいけないデータや、変更の確認方法
• 判断に迷ったときに見る正本の場所

「品質を高くする」「十分にテストする」のような表現は曖昧です。「npm testを通す」「変更したAPIには既存のエラー形式を使う」と書くと確認できます。コードや手順が変わったらファイルも更新し、古いコマンドを残さないことが重要です。

CLAUDE.md、AGENTS.md、Skillsの違い

名前が似ていても、3つは同じファイルではありません。Claude Codeの公式ドキュメントはCLAUDE.mdをプロジェクトの持続的な指示として説明し、AGENTS.mdの読み込みにも対応しています。SkillsはSKILL.mdを入口とする、特定の作業で使う手順・追加資料の束です。

既にAGENTS.mdを使うチームなら、同じ規約をCLAUDE.mdへ丸ごと複製する必要はありません。どちらをClaudeが読むかはClaude Codeの設定やバージョンに依存するため、/contextで読み込まれたファイルを確かめます。複数の道具で共有する目的があるならAGENTS.mdを正本にする選択もできます。ただし、導入するだけで全ツールが同じ優先順位や構文を解釈すると想定しないでください。

境界を決める簡単な問いは「次の作業でも常に必要か」です。毎回必要なら短い共通ファイルに置きます。画像制作だけで必要な細かい工程、プラットフォーム固有の公開操作、長いチェックリストはSkillへ分けます。特定のパスだけに適用するならrulesが適しています。ログや一時的な調査結果はプロジェクトの指示ファイルに書き込まず、成果物や記録として別に残します。

プロジェクトに最小のCLAUDE.mdを置く

最初はリポジトリのルートに置くと見つけやすくなります。公式ドキュメントでは./CLAUDE.mdまたは./.claude/CLAUDE.mdがプロジェクトの置き場所として案内されています。チーム共有の前提ならGitで管理し、個人的な好みや端末固有の値は別のローカル設定へ分けます。

以下はPython製の小さなアプリを想定した例です。コマンド名とディレクトリは例なので、自分のリポジトリに実在するものだけを残してください。

# このリポジトリ

Pythonで作るデータ処理アプリ。APIは `src/api/`、処理は `src/pipeline/`。

## よく使うコマンド
- テスト: `pytest -q`
- 静的検査: `ruff check .`

## 変更時の規約
- APIの入力は境界で検証する。
- `src/pipeline/`の変換結果は既存のテストで確認する。
- 認証情報や実データをテスト出力に含めない。

## 完了の確認
- 関連テストを通し、変更ファイルと残件を報告する。

最初から組織の全規則を書き込む必要はありません。現実の作業で同じ訂正が繰り返されるなら、その訂正を一行ずつ具体的な規約へ変えていきます。反対に、一度しか使わない臨時の依頼まで恒久ファイルへ入れると、後で別の作業を邪魔します。

/initは最終成果ではなく出発点

Claude Codeには/initで初期案を作る導線があります。生成された案は、リポジトリから推測した内容を含むため、書かれたコマンドが今も動くか、制約が実態に合うかを確認します。チームで使うなら、通常のコード変更と同じく差分をレビューしてから共有するのがよいでしょう。スラッシュコマンド全体の使い分けはClaude Codeのスラッシュコマンド一覧で整理しています。

1文を短く、検証できる形にする

「APIを丁寧に作る」より「入力境界で検証し、エラーは既存形式で返す」と書きます。「テストをしっかり実行する」より「変更したモジュールのテストと型検査を実行する」の方が実行可能です。

また、参照先だけで済む場合は本文を転記しないようにします。たとえばAPI設計書の場所が変わる可能性があるなら、正本のファイルパスを案内するだけにします。巨大な文章を貼ると、読むコストが上がるだけでなく、原本と説明文が食い違う原因になります。

置き場所ごとの有効範囲

ユーザー個人の設定と、チームで共有する設定を混ぜないことが大切です。公式ドキュメントでは、ユーザーの~/.claude/CLAUDE.md、プロジェクトの./CLAUDE.mdや./.claude/CLAUDE.md、個人用のCLAUDE.local.mdなど、スコープごとの配置を示しています。個人用ファイルは共有リポジトリにコミットしない運用が基本です。

リポジトリの下位ディレクトリにも指示ファイルを置けます。大きなモノレポでは、全体の共通ルールをルートへ置き、特定のサブプロジェクトだけの事情を近い階層へ置くと整理しやすくなります。ただし、同じ規約を複数階層にコピーすると片方だけ更新されやすいので、適用範囲を確認してから増やします。

チーム共有と個人設定を分ける例

置く場所に迷ったら、まず「誰に必要か」「いつ必要か」「対象ファイルを限定できるか」の3点で決めます。ファイル名の流行より、文書の責任範囲が一意であることの方が重要です。

rulesとSkillsへ分ける目安

プロジェクト全体のファイルが長くなると、例外や作業別手順が混ざりやすくなります。そのときは.claude/rules/を使い、特定のパスにだけ適用する規約を分けられます。公式ドキュメントは、YAML frontmatterのpathsで対象を指定する例を示しています。

---
paths:
  - "src/api/**/*.py"
---

# APIの規約
- 入力は境界で検証する。
- 既存のエラー形式を使う。

この例はAPIファイルに関係する作業へ規約を絞るためのものです。逆に「全ての変更後にテストする」のような一般ルールをここだけへ入れると、他のファイルの変更時に見落とします。対象がはっきりしているかを先に決めてください。

Skillsは、まとまった仕事の進め方を再利用したい場合に向いています。たとえば「新しいAPIを設計して、実装・試験・変更記録まで作る」という手順を1つのSkillにできます。毎セッション読む短い指示と、作業時に読む長い手順を切り分けると、長期運用で保守しやすくなります。

importを使うときの注意

CLAUDE.mdは@path/to/import形式で他のファイルを取り込めます。公式ドキュメントによれば、相対パスは取り込む側のファイルを基準に解決され、一定の深さまで再帰的に参照されます。見出しとリンクだけを書いたつもりでも、importを増やすと読み込む内容も増えます。

用途が単なる参照なら、バッククォートで囲んだパスとして記載し、取り込み構文と混同しないようにします。READMEや仕様書の全文を安易に常時取り込むと、文脈が重くなります。チームで外部ファイルをimportするときは、どの情報が読み込まれるかを確認してください。

読み込まれたかを確認する

「ファイルを作ったのに反映されない」ときは、まず推測をやめて/contextを開き、Memory filesに対象ファイルがあるかを確認します。見つからなければ、現在の作業ディレクトリ、ファイル名、下位ディレクトリの適用範囲、Claude Codeのバージョンや設定を確認します。

AGENTS.mdも使う場合は特に、どのファイルが実際に読まれているかを確認してください。両方あると、片方だけが読まれる構成や、設定によって両方が読まれる構成があります。「ファイルがある」ことと「このセッションに効いている」ことは違います。Claude Codeを複数プロジェクトで使う人は、リポジトリを切り替えるたびに読み込み元を確認すると混乱が減ります。

確認後は、短いテスト依頼で挙動を見ます。「このリポジトリのテスト方法を答えて」「変更前に確認すべき制約を挙げて」と質問し、書いた内容と一致するか確認できます。ただし、答えが一致したことだけで、危険な操作を技術的に禁止できたと解釈しないでください。

よくある失敗と対処

何を書いても覚えてくれない

まず読み込みの有無を確かめます。次に、指示が抽象的すぎないか、別の指示と矛盾していないかを見ます。複数の階層に同じテーマの指示があると、どれを優先するか分かりにくくなります。短いテストで確認し、必要なら指示を一つにまとめます。

ファイルが長くなりすぎた

毎回必要な前提と、特定の作業だけで必要な手順を分けます。バージョン番号、古いリリース手順、1回だけの障害記録は恒久ルールから外します。コピーした仕様書は参照先だけ残し、長いフローはSkillへ移します。削った後も、作業の完了条件が分かるか確かめてください。

個人の秘密情報が混ざった

認証情報、トークン、顧客データ、端末固有のパスを共有ファイルに書かないでください。誤ってコミットした場合は、ファイルを削るだけでなく、漏れた認証情報の失効や履歴の扱いを検討する必要があります。共有可能な規約と秘密情報の保存場所は分けます。

エージェントの作業を必ず止めたい

指示ファイルだけではアクセス制御にはなりません。認証や権限、ツールの設定、テスト環境での制限、実行前の確認など、操作の性質に応じた保護を用意します。CLAUDE.mdには「何を確認するか」を書き、実際の制限は別の仕組みで担保します。

AGENTS.mdとCLAUDE.mdの内容が違う

どちらかを正本に決め、重複箇所を減らします。Claude Codeがこのセッションで何を読んでいるかを/contextで見てから修正します。複数のAIツールで使うなら、共通の短い規約と、ツール固有の手順を分けると管理しやすくなります。

既存の長い指示ファイルを整理する順番

すでに数百行の指示ファイルがある場合、全部を一度に書き直すと、重要な例外まで消してしまいがちです。まず各段落を「いつ読むべきか」で印を付けます。毎回、特定のファイルだけ、特定の作業だけ、一度限りの4種類で十分です。毎回の項目だけを短い共通ファイルへ残し、特定のファイルだけに関係する内容はrules、特定の作業だけに必要な工程はSkillへ移します。一度限りの障害メモや過去の判断は記録へ移し、通常の指示から外します。

次に、同じ意味の指示を探します。「テストを実行する」「変更後にテストする」「完成前にテストする」は、対象と確認方法が同じなら一つにできます。一方、「本番の外部書き込み前に状態を確認する」は目的が異なるので残します。文字数を減らすこと自体を目標にせず、何をすれば完了かが一読で分かるようにするのが整理の基準です。

最後に、実際の小さな変更で試します。Claude Codeが指示ファイルを読み込んだこと、関連するコマンドを正しく提案したこと、不要な手順を勝手に混ぜなかったことを確認します。期待と違えば、まず指示が読み込まれたか、次に内容が具体的か、最後に別の指示と競合していないかを順に調べます。ファイルを増やして対処する前に原因を分けると、後の管理が楽になります。

変更履歴を残すときの粒度

共有ファイルの変更は、小さな差分としてレビューできると安全です。「テストコマンドを変更した」「新しいパス限定ルールを追加した」のように理由を一つずつ説明できる単位にします。指示の変更はコードの動作を直接変えなくても、次回以降のエージェントの判断を変えます。したがって、使わなくなった手順を消すときも、関連する現行の代替手順があるか確認します。

複数人で使う場合は、個人の成功体験をそのまま全員の必須手順にしないことも重要です。「この環境では有効だった」という知見と、「このプロジェクトで全員が守る」という規約は別です。共通ファイルには、チームで再現し、検証できる内容を優先しましょう。

実運用前のチェックリスト

• □ プロジェクトで本当に使うコマンドを確認した
• □ 共通指示と個人設定を分けた
• □ 同じ規約を複数ファイルに重複させていない
• □ 1回だけの作業手順はSkillへ移した
• □ /contextで読み込み元を確認した
• □ 秘密情報を共有ファイルに書いていない
• □ 指示だけに安全を依存せず、必要な権限や検証も用意した

まとめ

CLAUDE.mdは、Claude Codeに毎回説明していた前提を短く共有するための入口です。プロジェクト全体で必要な内容を中心にし、特定の作業に使う長い手順はSkillへ、パス限定の規約はrulesへ置きます。AGENTS.mdを併用する場合は、何が実際に読み込まれたかを/contextで確認することが大切です。

最初から完璧な指示ファイルを作る必要はありません。何度も繰り返した訂正を、検証できる一文へ変えるところから始め、作業が変われば文書も見直します。設定を増やすことより、次のセッションで同じ説明と誤解が減ることを目標にしてください。

関連記事

• Claude Codeのスラッシュコマンド一覧
• MCPとFunction Callingの違い
• AIエージェントとは？生成AI・RAGとの違い

公式資料

• Claude Code: How Claude remembers your project
• Claude Code: Extend Claude Code