この記事でわかること

  • CLAUDE.mdとは何か、Claude Codeがいつ読み込むのか
  • CLAUDE.mdに書くもの・書かない方がよいもの
  • 進み具合を記録するprogress.mdと、何を分けるのか
  • そのまま試せる最小テンプレートと、更新・再開のしかた

Claude Codeそのものの概要はClaude Codeとは?、使い始めの手順はClaude Codeの始め方と使い方で扱っています。

CLAUDE.mdとは:会話の最初に読まれる指示書

Claude Codeの会話は、毎回まっさらな状態から始まります。前回の会話で伝えた前提やルールは、そのままでは引き継がれません。そこで使うのがCLAUDE.mdです。

CLAUDE.mdは、プロジェクトの指示を書いておくMarkdownのファイルで、会話を始めるたびに読み込まれます。毎回説明していたことを書いておけば、同じ前提から始められます。

ただし、公式ドキュメントでは、CLAUDE.mdは強制力のある設定ではなく、文脈として扱われると説明されています。確実に止めたい操作は、権限の設定などで止めます。

置き場所によって、効く範囲が変わります。

置き場所 効く範囲 使い分け
プロジェクトの CLAUDE.md(または .claude/CLAUDE.md) そのプロジェクト チームで共有するルール。Gitで管理する
~/.claude/CLAUDE.md 自分のすべてのプロジェクト 個人の好み
CLAUDE.local.md そのプロジェクトの自分だけ 個人用のメモ。Gitに入れない

作業しているフォルダと上のフォルダのCLAUDE.mdは起動時に、下のフォルダにあるものは、そのフォルダのファイルを読んだときに追加されます。最初のひな形は /init で作れます。読み込まれたかどうかは /context で確かめられます。

CLAUDE.mdに書くもの

CLAUDE.mdに書くのは、どの会話でも変わらない前提とルールです。

  • プロジェクトの目的:何のためのプロジェクトか、誰が使うか
  • 技術構成:言語・フレームワーク・データベース、主なフォルダの役割
  • よく使うコマンド:テストや起動のコマンド
  • 恒久ルール:コーディング規約、テストの決まり、Gitの運用(コミットの単位、ブランチ)
  • 禁止事項:秘密情報を表示しない、確認なしに依存ライブラリを追加しない、など
  • 判断の基準:仕様が2通りに読めるときは質問する、など
  • 正本の場所:仕様書や進み具合の記録がどのファイルにあるか

こつは、確かめられる具体的な文にすることです。公式ドキュメントでも、「変更をテストする」ではなく「コミットの前に npm test を実行する」のように、守れたかどうかを確かめられる書き方が勧められています。

CLAUDE.mdに書かない方がよいもの

逆に、変わるものはCLAUDE.mdに書きません。

  • 今日やったこと・直近の作業結果
  • 現在どの段階(Phase)にいるか
  • 一時的なやることのメモ
  • テストの件数やコミットの番号など、毎回変わる状態
  • パスワード・APIキーなどの秘密の値
  • 一部の作業でしか使わない長い手順

毎回読み込まれるCLAUDE.mdは、公式ドキュメントでは1ファイルあたり200行未満が目安で、長いファイルは指示が守られにくくなるとされています。一部の作業だけで使う手順は、特定のフォルダで読み込まれるルールのファイル(.claude/rules/)などに分けられます。

progress.mdに書くもの

変わるものは、別のファイルにまとめます。この記事では、進み具合の記録を progress.md と呼びます。

  • 現在の段階(Phase)と、その目的
  • 完了したこと(日付・結果)
  • 未完了のこと・人の確認待ちのこと
  • 検証の結果(テストの件数と結果など)
  • 最後のコミットと、作業ツリーの状態
  • 次にやること
  • 決めたことと、その理由

なお、progress.mdはClaude Codeの公式の機能ではなく、プロジェクトで決めたファイル名です。自動で読み込まれるのはCLAUDE.mdなどの指示ファイルなので、CLAUDE.mdに「作業を始める前にprogress.mdを読む」と書いておきます。

CLAUDE.mdとprogress.mdを分ける理由

分けるのは、変わる速さが違うからです。

CLAUDE.md progress.md
書くもの 変わらない前提・ルール 現在地・経過・次にやること
変わる頻度 ルールが変わったときだけ 作業のたびに
長さ 短く保つ(200行未満が目安) 増えてよい(古い記録は残す)
読まれ方 会話の開始時に自動 CLAUDE.mdの指示で読む

混ぜると、ルールが記録の中に埋もれ、古いメモの一時的な判断が今のルールと食い違います。公式ドキュメントにも、指示どうしが矛盾するとどちらに従うかが定まらないことがあると書かれています。

よくある失敗:CLAUDE.mdに何でも書き足していく

起きやすいのは、作業のたびにCLAUDE.mdへ書き足す形です。

## ルール
- テストは pytest で実行する
- 設定ファイルは config/ に置く

## メモ
- (日付)ログイン画面を修正した。次は一覧画面
- (日付)集計のテストが3件失敗している
- (日付)集計は直った。一覧画面に戻る

これでは、終わった作業や古い判断まで毎回「今の前提」として渡ってしまい、肝心のルールも守られにくくなります。メモの部分はprogress.mdへ移し、CLAUDE.mdには「ルール」だけを残します。

このサイトでの分け方

このサイトでは、CLAUDE.mdの最初に「このファイルには変わらないルールだけを置く」と書き、現在地点・経緯はprogress.mdを見るように示しています。progress.mdは進捗・現在地点・次にやることの唯一の正本とし、過去の記録は書き換えずに追記する決まりです。

もともと運用のルールはprogress.mdの章として書いていて、その章から最初に読むべき恒久ルールだけを整理してCLAUDE.mdを新しく作りました。執筆時点で、CLAUDE.mdは約130行、progress.mdは約8,900行です。記録が増えても、毎回読み込まれる指示書は短いまま保てています。

progress.mdに書いた出来事が、CLAUDE.mdのルールになることもあります。新しく作ったファイルをGitの管理に入れる前にテストを実行して、問題を見落としたことがありました。経緯はprogress.mdに記録し、「commit前の全件テストは、commitする状態と同じものに対して行う」という決まりをCLAUDE.mdに加えています。

最小テンプレート

最初は次の2つを置き、必要になったら足していきます。内容は例なので、自分のプロジェクトに合わせて書き換えてください。

CLAUDE.mdの最小テンプレート

# (プロジェクト名)— 変わらないルール

このファイルには変わらないルールだけを書く。現在の進み具合は progress.md を見る。

## このプロジェクト
- 目的:社内向けの在庫集計ツール
- 構成:Python / FastAPI / PostgreSQL
- 仕様は docs/spec.md、進み具合は progress.md にある

## コマンド
- テスト:pytest

## ルール
- 変更した後は pytest を全件実行し、結果を報告する
- 新しいライブラリを追加する前に確認を取る
- .env などの秘密の値を表示・記録しない
- 仕様が2通りに読めるときは、作らずに質問する

## 作業の始め方と終わり方
- 始める前に progress.md の「現在地」と「次にやること」、git status を確認する
- 区切りがついたら progress.md を更新してからコミットする

progress.mdの最小テンプレート

# 進み具合(progress.md)

## 現在地
- 段階:Phase 2(集計の機能を作る)
- 最後のコミット:(ハッシュ)テスト全件成功
- 作業ツリー:未コミットの変更なし

## 完了したこと
- (日付)Phase 1:CSVの読み込みとテスト

## 未完了・確認待ち
- 返品を集計に含めるか(確認中)

## 次にやること
1. 集計の処理を作る
2. テストを足して全件実行する

## 決めたこと
- (日付)決めたことと、その理由

CLAUDE.mdには「どう進めるか」、progress.mdには「どこまで進んだか」を書く、と覚えておきます。

更新するタイミングと判断の目安

CLAUDE.mdは、ルールが変わったときに更新します。公式ドキュメントでは、同じ間違いが2回起きたときや、前の会話と同じ訂正をまた入力したときが、書き足す合図とされています。古いルールや食い違うルールは、定期的に見直して消します。

progress.mdは、作業の区切りごとに更新します。完了したこと・検証の結果・最後のコミット・次にやることを書いてから終えれば、次の会話はそこから始められます。同じ注意が何度も出てくるなら、CLAUDE.mdのルールへ移す合図です。

長いプロジェクトとセッションの切り替え

公式ドキュメントでは、/clear は空の状態で新しい会話を始めるコマンドで、同じ会話を要約して続けるなら /compact を使うと説明されています。

新しい会話でもCLAUDE.mdは読み込まれますが、それまでの会話の中身は残りません。そこで、切り替える前にprogress.mdを更新してコミットし、新しい会話では「progress.mdとGitの状態を読んでから再開する」ようにCLAUDE.mdに書いておきます。このサイトでも、区切りでコミットして未コミットの変更がない状態にしてから切り替え、新しい会話ではCLAUDE.mdとprogress.mdとGitの状態を読み直してから再開しています。

段階の区切り方や、会話を切り替えた後の再開のしかたは、Claude Codeで長期プロジェクトを進める方法にまとめています。

本番サーバーで使う場合

CLAUDE.mdには、止まって確認する条件も書けます。ただし本番のサーバーやデータを触る作業では、停止条件の決め方や権限の設定まで含めて考える必要があります。全体の進め方はClaude CodeでAlmaLinuxサーバーを構築・運用する方法にまとめています。

まとめ

  • CLAUDE.mdは、会話を始めるたびに読み込まれる変わらないルールの置き場所。強制力のある設定ではなく、文脈として扱われる
  • 今日の作業・現在の段階・次にやることは、progress.mdなどの別のファイルに分ける
  • CLAUDE.mdは短く、確かめられる具体的な文で書く(200行未満が目安)
  • CLAUDE.mdに「始める前にprogress.mdを読む」と書き、区切りでprogress.mdを更新してから会話を切り替える

まずは最小テンプレートの2つを置き、同じ説明を2回したら書き足すところから始めてみてください。Claude Codeでのサイト作りの例はClaude CodeでWebサイトを作る方法と公開までの流れで紹介しています。