CLAUDE.mdをWindowsで作成する手順 — 5要素50行で書くプロジェクト設定

「テストコマンドは npm test です。インデントはスペース2つです。あ、前回も言いましたっけ」——Claude Codeに同じ説明を何度も繰り返していませんか。CLAUDE.mdは、その毎回の説明を1つのファイルにまとめる設定ファイルです。5つの要素を50行書くだけで、繰り返しがなくなります。この記事を読み終わる頃には、あなたのプロジェクトで動くCLAUDE.mdが1つ完成しています。

この記事でやること

Claude Codeに「テストは npm test で」「インデントはスペース2つで」と、セッションのたびに同じ説明をしていませんか。それは時間の無駄です。伝え忘れがあると、Claude Codeが勝手に推測して意図しない結果を出力することもあります。

この無駄は、CLAUDE.mdという1つのファイルにルールを書いておくだけで解消します。必要なのは5つの要素・50〜100行だけ。Markdownで書く、ただのテキストファイルです。

この記事では、その5要素を押さえたCLAUDE.mdをWindows環境で一から作成します。読み終わる頃には、あなたのプロジェクトフォルダに動くCLAUDE.mdが1つできています。

CLAUDE.mdとは — Claude Codeの「取扱説明書」

CLAUDE.mdは、プロジェクトのルールをClaude Codeに覚えさせる設定ファイルです。拡張子は .md（Markdown）。テキストエディタで開いて、普通の文章のように書けます。

家電を買った時のことを思い出してください。取扱説明書が付いてきますが、毎回全部読み直す人はいません。よく使う機能に付箋を貼って、「これさえ見ればいい」状態にするはずです。CLAUDE.mdは、まさにその付箋の役割を果たします。

CLAUDE.mdがない状態では、Claude Codeはセッションを切り替えるたびに前提条件をゼロから学び直します。「このプロジェクトはPythonを使います」「テストコマンドは pytest です」——毎回同じ説明を繰り返すことになります。

一方、CLAUDE.mdがあると、Claude Codeはセッションをまたいでその内容を参照し続けます。あなたが毎回説明する必要がなくなります。

取扱説明書を書く前に、中身は何が必要か。

事前に必要なもの

手順に入る前に、以下が揃っているか確認してください。

Windows 10 または 11 — この記事はWindows環境前提で進めます
Claude Code — インストール済みで起動できる状態
プロジェクトフォルダ — 作業対象のフォルダが存在すること（どこでも構いません）
テキストエディタ — メモ帳で大丈夫です。VS Codeなどがあれば便利ですが必須ではありません

準備ができたら、5つの要素に入ります。

必須5要素 — これだけ書けば動く

300行のCLAUDE.mdより、50行のCLAUDE.mdの方が効果的です。書く量が少ないほど、Claude Codeは迷わないからです。情報を詰め込みすぎると「どのルールを優先すべきか」が曖昧になり、出力がブレます。

では、その50行に何を書くか。必要なのは次の5つだけです。

要素1: プロジェクト概要（What）

何のプロジェクトかを1〜3行で書きます。Claude Codeが「このプロジェクトは何をするものか」を即座に理解できるようにするためです。

# プロジェクト概要
天気予報を取得して画面に表示するPythonスクリプト集。
気象庁の公開データを使い、翌日の天気をコンソールに出力する。

「Pythonスクリプト集」という1行で、Claude CodeはPython前提で回答を組み立て始めます。

要素2: よく使うコマンド（How to Run）

Claude Codeが実行する可能性のあるコマンドを書いておきます。毎回「テストはどうやりますか」と聞かれるのを防ぐためです。

# よく使うコマンド
- テスト実行: `python -m pytest`
- リント: `python -m flake8 src/`
- メイン実行: `python src/main.py`

要素3: コードスタイル・規約（Rules）

インデントや命名規則など、Claude Codeがコードを書く際に従うべきルールです。

# コード規約
- 変数名はsnake_case
- 関数にはdocstringを付ける
- 型ヒントを必ず書く

ここで「Pythonのインデントはスペース4つ」のような一般論は書きません。Claude CodeはPythonの標準を推測できるからです。書くべきは「このプロジェクト固有のルール」だけです。

要素4: プロジェクト構造（Where）

ディレクトリツリーの簡易図を書きます。Claude Codeが「このファイルはどこにあるか」を迷わないようにするためです。

# プロジェクト構造
src/
  main.py       # エントリポイント
  weather.py    # 天気取得ロジック
  display.py    # 表示フォーマット
tests/
  test_weather.py

要素5: 注意点・禁止事項（Gotchas）

やってはいけないことや、Claude Codeが気づきにくい制約を書きます。

# 注意点
- 外部APIは気象庁の公開エンドポイントのみ使用
- 日本語の文字化けを防ぐため、ファイルはUTF-8で保存
- print文の代わりにloggingモジュールを使う

ここが一番「推測できないこと」を書く場所です。「UTF-8で保存」はClaude Codeが自動で判断できないプロジェクト固有の制約ですから、明示する価値があります。

5要素が分かったところで、Windows環境で実際に作ります。

Windows環境でCLAUDE.mdを作成する手順

ここからは手を動かします。5ステップで完成させます。

Step 1: プロジェクトフォルダを開く

エクスプローラーで、CLAUDE.mdを置きたいプロジェクトフォルダを開きます。Claude Codeを起動するフォルダと同じ場所に作成します。

Step 2: CLAUDE.mdファイルを作成する

フォルダ内で右クリック → 「新規作成」 → 「テキストドキュメント」を選びます。ファイル名を CLAUDE.md に変更してください。

ここで注意が2つあります。

拡張子の二重化に気をつける — フォルダーの設定で「ファイル名の拡張子を表示」をオンにしておきましょう。CLAUDE.md.txt になってしまうと、ただのテキストファイルとして扱われます
文字コードはBOMなしUTF-8 — メモ帳で保存する場合、「名前を付けて保存」の画面で文字コードを「UTF-8」に設定します

Step 3: 5要素を書き込む

さきほど紹介した5要素を、自分のプロジェクトに合わせて書き込みます。まだ書く内容に迷う部分があれば、空のセクション見出しだけ書いておいても構いません。

# プロジェクト概要
（ここに1〜3行で何のプロジェクトか書く）

# よく使うコマンド
- （実行コマンドを書く）

# コード規約
- （従うべきルールを書く）

# プロジェクト構造
（ディレクトリツリーを書く）

# 注意点
- （やってはいけないことを書く）

これでCLAUDE.mdの枠組みができました。

Step 4: Claude Codeを起動して動作確認する

プロジェクトフォルダでClaude Codeを起動し、CLAUDE.mdの内容を反映しているか確認します。

claude

起動後、CLAUDE.mdの内容を読み込んでいるかを確認するには、次のように聞いてみます。

このプロジェクトのルールを教えて

CLAUDE.mdに書いた内容（プロジェクト概要やコマンド）が返ってくれば、正しく読み込まれています。

Step 5: 期待される結果の確認

CLAUDE.mdに書いたコマンドや規約を、実際のやり取りで試してみます。例えば「テストを実行して」と頼んだ時に、CLAUDE.mdに書いた python -m pytest が使われれば成功です。

Claude Codeが推測して別のコマンドを使った場合は、そのコマンド名をCLAUDE.mdの該当箇所に追記します。これが「育てる」サイクルの入り口です。

作ってみたものの、これで合っているか不安かもしれません。良い例と悪い例を比べてみます。

良い例と悪い例 — 「何が問題か」を読み解く

まずは悪い例から見て、何が問題かを整理します。

悪い例のCLAUDE.md（要点抜粋）

# プロジェクト概要
このプロジェクトは、Python 3.11を使用したWebアプリケーションです。
Flaskフレームワークをベースにしています。
フロントエンドはHTML/CSS/JavaScriptを使用。
バックエンドはRESTful APIを提供。
データベースはSQLiteを使用。
（...さらに数十行の説明が続く...）

# よく使うコマンド
- インストール: pip install -r requirements.txt
- サーバー起動: python app.py
- テスト: pytest
- テスト（カバレッジ付き）: pytest --cov
- リント: flake8
- フォーマット: black .
- 型チェック: mypy src/
- マイグレーション: flask db migrate
- シード投入: python seed.py
（...さらに10行...）

# コード規約
- Pythonのインデントはスペース4つ
- 文字列はシングルクォート
- セミコロンは使わない
- 行の長さは79文字以内
- クラス名はCamelCase
- 関数名はsnake_case
（...PEP 8のコピペが続く...）

何が問題なのでしょうか。

1行ずつ見ていきます。

「Python 3.11を使用」——Claude Codeは requirements.txt や app.py からPythonプロジェクトだと推測できます。バージョンまで明示する必要があるなら残しますが、単に「Pythonを使っている」だけなら省けます。

「Flaskフレームワークをベース」——これも app.py の from flask import から推測できます。

「Pythonのインデントはスペース4つ」「クラス名はCamelCase」「関数名はsnake_case」——これらはPEP 8の標準規約です。Claude CodeはPythonプロジェクトであれば標準を適用します。わざわざ書く必要はありません。

書くべきは「Claude Codeが推測できないこと」だけです。

良い例のCLAUDE.md（50〜60行程度）

# プロジェクト概要
個人の家計管理ツール。CSV出力された銀行明細を読み込み、
月ごとの支出カテゴリ別に集計してグラフ表示する。

# よく使うコマンド
- メイン実行: `python src/main.py`
- テスト: `python -m pytest tests/`

# コード規約
- グラフはmatplotlib（plotlyは使わない）
- 日本語ラベルには必ずフォント指定を入れる

# プロジェクト構造
src/
  main.py          # エントリポイント
  parser.py        # CSV読み込み
  analyzer.py      # 集計ロジック
  graph.py         # グラフ描画
tests/
  test_parser.py
  test_analyzer.py
data/              # サンプルデータ（gitignore対象）

# 注意点
- 銀行CSVはShift-JISでエンコードされている
- テストデータは `data/sample.csv` を使う
- グラフの色は青系統で統一

悪い例との違いは明確です。

「matplotlibを使う（plotlyは使わない）」——これはプロジェクト固有の判断です。Claude Codeは推測できません。書く価値があります。

「日本語ラベルにはフォント指定を入れる」——これも過去に文字化けした経験から来るプロジェクト固有の教訓です。

「銀行CSVはShift-JIS」——これも推測不可能。書かないとClaude CodeはUTF-8として読もうとします。

判断基準はシンプルです。Claude Codeがファイルの中身を見て自力で気づけるか？ 気づけるなら書かない。気づけないなら書く。

/initで生成された150行のCLAUDE.mdを50行に削る作業こそが一番大事だというのは、少し意外かもしれません。しかし、削ることでClaude Codeが迷わなくなり、出力の安定感が上がります。

ここまでで1つのCLAUDE.mdが完成しました。プロジェクトが増えた時のことも考えておきます。

スコープの使い分け

CLAUDE.mdには複数の置き場所があり、それぞれ役割が異なります。ここまでに作ったのは「Project CLAUDE.md」です。

Global（~/.claude/CLAUDE.md）

全プロジェクトで共通する好みを書きます。例えば「回答は日本語で」「コードにはコメントを付ける」など、どのプロジェクトでも当てはまるルールです。

会社に例えると「全社マナー」に当たります。

Project（./CLAUDE.md）

そのプロジェクト固有のルールを書きます。さきほど5要素で作成したものがこれです。

会社に例えると「チームのローカルルール」です。

Local（./CLAUDE.local.md）

公開しない個人的な設定を書きます。プロジェクトをGitで共有している場合、このファイルは .gitignore に入れておきます。

会社に例えると「自分専用の付箋」です。

各ファイルのWindowsでの配置パスをまとめます。

スコープ	パス	役割
Global	`C:\Users\（ユーザー名）\.claude\CLAUDE.md`	全プロジェクト共通
Project	`（プロジェクトフォルダ）\CLAUDE.md`	そのプロジェクト固有
Local	`（プロジェクトフォルダ）\CLAUDE.local.md`	個人的な設定

実務的なアドバイスです。最初はProjectだけ書けば十分です。Globalに共通設定を移すのは、2つ目のプロジェクトを始めた時で構いません。

スコープが分かったところで、/initとの関係も整理します。

/initとの関係 — 自動生成は「下書き」として使う

Claude Codeには /init コマンドがあり、実行するとプロジェクトを自動解析してCLAUDE.mdを生成してくれます。

便利ですが、1つ知っておくべき特徴があります。/initの出力は長くなりがちです。ディレクトリ構造の詳細、全ファイルの列挙、検出された技術スタックの羅列——丁寧ですが、そのまま使い続けるとClaude Codeが「どの情報を優先すべきか」を見失います。

/initの利点は「出発点になる」ことです。プロジェクト構造の把握や、使っている技術の検出を自動でやってくれるため、ゼロから書く手間が省けます。

欠点は「膨大になりがち」なこと。先ほど見た「悪い例」と同じ罠にはまりやすいです。

推奨アプローチをまとめます。

/init で骨組みを作る
出力された内容から、5要素に関係する部分だけ残す
「Claude Codeが推測できること」を削る
50〜100行に絞り込む

/initは最初の一回だけ使うものです。その後は、自分で使いながら育てていくのが本番です。

CLAUDE.mdの育て方 — 使いながら成長させる

CLAUDE.mdを作ったら終わり、ではありません。使っていく中で「ここが抜けていた」と気づく場面が出てきます。そのタイミングで少しずつ書き足していくのが、一番自然な育て方です。

具体的なサイクルはこうです。

Claude Codeに何かを頼む → 期待と違う結果が返る → 「なぜずれたか」を確認する → CLAUDE.mdに追記する

例えば、Claude CodeにPython 2の文法でコードを書いてきたとします。「このプロジェクトはPython 3のみ使用」という注意点をCLAUDE.mdに追記すれば、次からは同じミスが起きません。

これは「名札を書き足す」イメージです。新しい人が職場に入ってきた時、覚えておいてほしいことを名札に少しずつ書き足していく感覚です。最初から全部を名札に詰め込むと読みにくいですが、必要になったタイミングで1行ずつ追加していくと、自然に実用的な名札が出来上がります。

Progressive Disclosure（段階的開示） という考え方もあります。最初は最小限の情報だけを書き、Claude Codeとのやり取りの中で必要な情報が見えてきたら追加していく方法です。

見直すタイミングの目安です。

最初の1週間は、Claude Codeとのやり取りで「あ、これも書いておけばよかった」と思うたびに1行ずつ書き足す
1ヶ月後に全体を見直して、重複や不要になったルールを削る
プロジェクトの構造が大きく変わったタイミングで、プロジェクト構造のセクションを更新する

肥大化したら削る勇気も大切です。「これはもう推測できるかも」と思えたら、その行は消してしまって構いません。

最後に確認すること

CLAUDE.mdが完成したら、以下のチェックを通してください。

[ ] 5つの要素（概要・コマンド・規約・構造・注意点）が揃っている
[ ] 50〜100行以内に収まっている
[ ] 「Claude Codeが推測できること」を書いていない
[ ] Claude Codeを起動して、CLAUDE.mdの内容が反映されている

最後の確認方法はシンプルです。Claude Codeに「このプロジェクトのルールを教えて」と聞いて、CLAUDE.mdに書いた内容が返ってくれば、正しく読み込まれています。

CLAUDE.mdができたら、実際にClaude Codeに小さなタスクを頼んでみてください。「テストを実行して」「新しい関数を追加して」などで構いません。CLAUDE.mdに書いたコマンドや規約が反映されているか、その小さなタスクで確認できます。

この手順通りに進めれば、5つの要素を押さえたCLAUDE.mdが1つ手元にあるはずです。最初から完璧を目指さなくて大丈夫です。使いながら育てていくのが、CLAUDE.mdの正しい付き合い方です。

まとめ

CLAUDE.mdは5つの必須要素（概要・コマンド・規約・構造・注意点）を押さえ、50〜100行に絞れば、Windows初心者でも確実に書けます。最初はProject CLAUDE.mdだけで十分です。使っているうちに必要なものが見えてくるので、最初から完璧を目指さなくて大丈夫。できあがったら、小さなタスクを1つ頼んで、CLAUDE.mdのルールが反映されているか確かめてください。

Claude Codeでどこまでできる？