Claude Codeを使い始めると、自然言語で指示するだけでも、ファイルの調査やプログラムの修正などを進められます。
しかし、継続して利用する場合、毎回同じ説明をするのは非効率です。
例えば「このプロジェクトではPythonを使う」「修正後はテストする」「既存データを勝手に削除しない」といったルールです。
こうした情報をClaude Codeへ伝えるための仕組みが、CLAUDE.mdです。
今回は、CLAUDE.mdの役割と、初期設定に使う「/init」、具体的な記載内容や管理方法を整理します。
この記事で分かること
- CLAUDE.mdの役割と仕組み
- /initによる初期設定方法
- CLAUDE.mdに書くべき内容
- ファイルの配置場所と管理方法
- Skillsとの違い
CLAUDE.mdとは?
CLAUDE.mdは、Claude Codeへプロジェクトの情報や作業ルールを伝えるためのMarkdownファイルです。
例えば、次のような内容を記載します。
- プロジェクトの目的
- 使用するプログラミング言語
- 重要なフォルダの構成
- テストの実行方法
- ファイル変更時の注意事項
Claude Codeは、作業時に対象となるCLAUDE.mdを読み込み、指示の参考にします。
つまり、毎回同じ説明を入力する代わりに、プロジェクト側へ共通ルールを保存しておく仕組みです。
ただし、AIモデル自体が新しい知識を学習するわけではありません。
外部ファイルの内容を作業時の前提情報として利用する、と理解すると分かりやすいでしょう。
/initでCLAUDE.mdを作成する
CLAUDE.mdは手動でも作成できますが、最初の設定には「/init」というコマンドが便利です。
Claude Codeで対象プロジェクトを開き、次のコマンドを入力します。
/init
Claude Codeがプロジェクトの構造などを調査し、CLAUDE.mdのたたき台を作成します。
基本的な流れは次のとおりです。
- 対象プロジェクトでClaude Codeを起動する
/initを実行する- 生成されたCLAUDE.mdを確認する
- 不足しているルールを追記する
- 保存して実際の作業に利用する
自動生成された内容が必ず正しいとは限りません。
特にテストコマンドや使用技術、変更禁止の範囲などは、人間が確認する必要があります。
CLAUDE.mdには何を書く?
基本的には、Claude Codeが毎回知っておいた方がよい情報を記載します。
例えば、Pythonでブログのデータを収集するプロジェクトなら、次のような内容が考えられます。
# Project Overview
ブログデータを収集・分析するシステム。
## Technology
- Pythonを使用
- SQLiteでデータを管理
## Commands
- Test: pytest
- Lint: ruff check .
## Rules
- 既存データを勝手に削除しない
- コード変更後はテストを実行する
- 大きな変更の前に影響範囲を確認する
※これは記載例です。使用技術やコマンドは、実際のプロジェクトに合わせて変更します。
曖昧なお願いより具体的なルールにする
CLAUDE.mdでは、抽象的な指示よりも、実行内容が明確なルールの方が役立ちます。
例えば「きれいなコードを書く」だけでは、何を守ればよいのか分かりません。
それよりも「関数名はsnake_caseに統一する」「変更後はpytestを実行する」と記載した方が具体的です。
特に、AIが繰り返し間違えることや、変更してほしくない部分を明文化しておくと便利です。
ただし、CLAUDE.mdに記載しただけで、すべての指示が必ず守られるわけではありません。重要な操作には権限設定や人間による確認も必要です。
CLAUDE.mdは長ければよいわけではない
プロジェクトの情報をすべてCLAUDE.mdへ書きたくなるかもしれません。
しかし、毎回参照するファイルが長くなりすぎると、重要な指示が埋もれてしまいます。
CLAUDE.mdには、基本方針や頻繁に使うコマンドなど、共通して必要な情報を優先して記載します。
特定の作業だけで使う詳細な手順は、別のドキュメントやSkillsへ分ける方法もあります。
CLAUDE.mdは詳細なマニュアルではなく、プロジェクトの基本ルールを整理する場所と考えるとよさそうです。
CLAUDE.mdはどこに保存する?
CLAUDE.mdには、用途に応じた配置場所があります。
代表的なのは、プロジェクト直下に保存する方法です。
my-project/
├── CLAUDE.md
├── src/
└── tests/
この場合、そのプロジェクト固有のルールを記載します。
一方、ユーザー共通の設定として、次の場所にも配置できます。
~/.claude/CLAUDE.md
こちらには、複数のプロジェクトで共通して利用したい指示を記載できます。
例えば「日本語で説明する」といった共通方針と、「このプロジェクトではSQLiteを使用する」といった個別ルールを分けて管理できます。
プロジェクト用のCLAUDE.mdは、Gitで管理してチーム内で共有することも可能です。
CLAUDE.mdとSkillsの違い
Claude Codeには、Skillsという拡張機能もあります。
初心者向けに整理すると、両者の違いは次のとおりです。
| 項目 | CLAUDE.md | Skills |
|---|---|---|
| 主な役割 | 共通ルールの共有 | 特定作業の手順 |
| 内容 | 基本方針・規約・コマンド | 作業方法・専門知識 |
| 利用場面 | プロジェクトの作業全般 | 関連する作業を行うとき |
例えば「変更後はテストする」という共通ルールはCLAUDE.mdに記載します。
一方、「新しいデータ取得機能を追加する際の具体的な手順」はSkillとして整理できます。
役割を分けることで、CLAUDE.mdが必要以上に大きくなることを防げます。
CLAUDE.mdは使いながら更新する
CLAUDE.mdは、一度作成すれば終わりではありません。
開発が進めば、使用技術やフォルダ構成、作業ルールも変わります。
例えば、最初はCSVへ保存していたデータを、途中からSQLiteで管理するようになるかもしれません。
その場合、古いルールを残したままでは、Claude Codeが誤った前提で作業する可能性があります。
そのため、実際の運用で気づいたことを追記し、不要になった指示は削除することが重要です。
最初から完璧な設定を目指すよりも、/initで作成し、確認しながら改善する方法が現実的だと思います。
まとめ|CLAUDE.mdはプロジェクトの基本説明書
CLAUDE.mdは、Claude Codeへプロジェクトの目的や作業ルールを伝えるための設定ファイルです。
毎回同じ説明を入力する手間を減らし、継続的な開発で共通の前提を利用できるようにします。
また、/initを使えば、既存プロジェクトを調査してCLAUDE.mdのたたき台を作成できます。
重要なのは、生成された内容をそのまま使うのではなく、自分のプロジェクトに合ったルールへ整えることです。
まずは基本的なルールを登録し、実際の作業で生じた問題をもとに更新していく。
これがCLAUDE.mdを活用する第一歩になります。
※Claude Codeの仕様やコマンドは変更される場合があります。最新情報は公式ドキュメントを確認してください。

