Claude Codeで長期プロジェクトを進める方法|Phaseの区切り・進捗の記録・/clear後の再開
Claude Codeで数日・数週間にまたがる長期プロジェクトを進める方法を解説します。Phaseでの区切り方、区切りで進捗を記録して状態を確定する手順、/compactと/clearの使い分け、新しいセッションでの再開と照合を紹介します。
目次
この記事でわかること
- Claude Codeで長期プロジェクトを進めるときに、どこで作業を区切るか
- 区切りで何を記録し、どうやって状態を確定するか
- /compactと/clearの違いと使い分け
- 新しいセッションで再開するときに、何を読み、何と照合するか
CLAUDE.mdとprogress.mdにそれぞれ何を書くかは、CLAUDE.mdの書き方で扱っています。この記事は、その2つのファイルを使って長い作業を続けていく流れが中心です。
Claude Codeで長期プロジェクトを進めるときにつまずきやすいこと
Claude Codeの会話は、毎回新しいコンテキストから始まります。前の会話で決めたことでも、ファイルに書いていなければ次の会話には引き継がれません。
同じ会話を長く続ける場合にも注意が要ります。公式ドキュメントでは、コンテキストが埋まってくると、前の指示を忘れたり、間違いが増えたりすることがあると説明されています。
数日・数週間にまたがる作業では、次のようなことが起きやすくなります。
- 前に決めた方針とは違う進め方を始める
- どこまで終わったのか、会話を読み返さないと分からない
- どの時点の変更なのか分からず、戻す場所を決められない
どれも、作業の状態が会話の中にしかないことが原因です。状態はファイルとGitに置き、会話はいつ切り替えても続きを始められる形にしておく。これがこの記事の考え方です。
長い作業はPhaseで区切る
長い作業は、Phase(段階)に分けて進めます。区切りは時間の長さではなく、「何ができたら終わりか」で決めます。
架空の例として、社内の申請フォームを作る作業なら、次のように分けられます。
| Phase | やること | 終わりの条件 |
|---|---|---|
| 1 調査 | 既存のファイルと要件を確かめる | 分かったことと未確定の点が記録されている |
| 2 設計 | 画面・データ・処理の分け方を決める | 決めたことと理由が記録されている |
| 3 実装 | 設計どおりに作る | 全件テストが通る |
| 4 検証 | 実際の使い方で確かめる | 確かめた項目と結果が記録されている |
1つのPhaseが大きいときは、Phaseの中にチェックポイントを置きます。このサイトでは、日次運用の仕組みを作ったPhaseを、手元で作る2つのチェックポイントと、本番へ反映する3つ目のチェックポイントに分けて進めました。
Phaseの区切りで何をするか
区切りでは、次の順で状態を確定します。
- progress.mdを更新する(終わったこと・検証の結果・次にやること)
git statusで、変更したファイルと新しく作ったファイルを確かめる- コミットするファイルをすべてステージする
- その状態で全件テストを実行する
- コミットする
- もう一度
git statusで、未コミットの変更が残っていないことを確かめる
3と4の順番には理由があります。このサイトでは、新しく作ったファイルをGitに追加する前に全件テストを実行し、コミットした後の状態ではテストが1件失敗していたのを見落としたことがありました。Gitで管理しているファイルを対象にする検査が、まだ追加していない新しいテストファイルを見ていなかったためです。
いまは、コミットするファイルをすべてステージしてから全件テストを実行する決まりにしています。大事なのは、テストした中身とコミットする中身をそろえることです。
区切りで実行するテストが、守りたい不具合を本当に検出できるかを確かめる方法は、Claude Codeにテストを書かせる方法で扱っています。
progress.mdに何を残すか
progress.mdはClaude Codeの公式の機能ではありません。進み具合を残すために、プロジェクトで決めたファイル名です。
長いプロジェクトで再開に必要なのは、次の項目です。
- 現在のPhaseと、その終わりの条件
- 終わったことと、検証の結果
- 途中のこと・人の確認を待っていること
- 最後のコミットと、未コミットの変更の有無
- 次にやること
書く場所の決め方や最小のひな形は、CLAUDE.mdの書き方にまとめています。このサイトでは、過去の記録は書き換えずに書き足していきます。あとから、どの時点で何を決めたのかをたどれるようにするためです。
/compactと/clearをどう使い分けるか
ここは公式の仕様です。
/compact は、ここまでの会話を要約してコンテキストを空けるコマンドです。要約で残してほしいことを指示として添えることもできます。上限に近づくと自動でも圧縮されます。圧縮の後も、プロジェクト直下のCLAUDE.mdはファイルから読み直されます。ただし、会話の中だけで伝えた指示は要約で失われることがあります。
/clear は、空のコンテキストで新しい会話を始めるコマンドです。前の会話の内容は使えなくなりますが、プロジェクトのメモリ(CLAUDE.mdなど)は残ります。同じ会話を続けたまま空けたいときは/compactを使う、と公式ドキュメントは案内しています。
| /compact | /clear | |
|---|---|---|
| 会話 | 要約して続ける | 新しい会話を始める |
| 向いている場面 | 同じ作業を続けたいが、やり取りが長くなった | 区切りがついて、次の作業へ移る |
| 前提 | 要約に残らない細部があってもよい | 状態をファイルとGitに確定してある |
公式ドキュメントは、関係のない作業へ移るときに/clearを使うよう勧めています。長いプロジェクトだから必ず/clearする、というものではありません。
このサイトでは、Phaseの区切りで状態を確定したあと、会話が長くなっていれば/clearで新しい会話に切り替えています。/clearは人が判断して実行しています。Claude Codeが自分で実行するコマンドではないためです。
新しいセッションでどう再開するか
/clearの後は、前の会話を前提にしません。保存しておいた情報から状態を戻します。
- CLAUDE.md(新しい会話の最初に自動で読み込まれる)
- progress.mdの現在地と、次にやること
- 次のPhaseに関係する設計書
git logとgit status
CLAUDE.mdは新しい会話の最初に読み込まれますが、progress.mdや設計書は自動では読まれません。最初の依頼で読ませます。このサイトでも、新しい会話ではこの順に読み直してから再開しています。
作業を再開します。まだファイルの変更はしないでください。
CLAUDE.md・progress.md・関係する設計書を読み、git log と git status で実際の状態を確かめてください。
記録と実際の状態が食い違っていたら、その点を報告して止まってください。
現在のPhase、終わったこと、次にやることを短くまとめて、私の確認を待ってください。
記録と実際の状態を照合する
progress.mdは、人とClaude Codeが書いた記録です。書き忘れや、古いままの記述が残っていることもあります。読むだけで信じず、実際の状態と照合します。
- 記録にある最後のコミット ↔
git log - 「未コミットの変更なし」 ↔
git status - 「全件テスト成功」 ↔ 必要ならテストを実行し直す
このサイトでは、再開のたびに、記録にあるコミットと作業ツリーの状態が実際と同じかを確かめ、結果を「記録どおり」と書き残しています。再開の指示に書かれていた状態が古く、実際には記録より先まで作業が進んでいたこともあります。そのときは実際の状態を優先して、続きを決めました。
このサイトで実際に使っている進め方
このサイトでは、別のプロジェクトをまとめる作業を、U1からU10までの10のPhaseに分け、9月26日から10月3日にかけて進めました。その後の日次運用の仕組みづくりも、D0からD6のPhaseに分けています。
このサイトでは、区切りの手順をprogress.mdに書いています。会話を切り替えるときは、Claude Codeが記録とコミットまで終え、未コミットの変更がないことを確かめてから案内します。そのあと、人が/clearを実行して「続きを進めて」と入力します。
長期プロジェクトを始めるときは、最初の依頼で進め方を決めておくと、毎回説明し直さずに済みます。
このプロジェクトはPhaseに分けて進めます。
各Phaseの最初に、終わりの条件を提案して私の確認を待ってください。
Phaseが終わったら、progress.mdを更新してください。
次に、コミットするファイルをすべてステージしてから全件テストを実行し、結果を報告してください。
コミットは私が確認してから行ってください。
会話を切り替えた後は、前の会話を前提にしないでください。
CLAUDE.md・progress.md・関係する設計書・git log・git status を確かめてから、次のPhaseを始めてください。
この記事の進め方を実際の作業で使えるよう、開始・Phaseの完了・会話の切り替え・/clear後の状態の復元までの依頼文とチェックリストを、有料の記事「Claude Code長期プロジェクト運用の実践セット」にまとめています。
進め方を見直す判断の目安
- 1つのPhaseの途中で、何度も圧縮が必要になる → Phaseを小さく分ける
- 同じ注意を毎回伝えている → CLAUDE.mdのルールへ移す
- 再開のたびに、記録と実際の状態がずれている → 記録の更新を区切りの手順に入れる
- 同じ問題で何度も訂正しているときは、会話を続けるより/clearして指示を書き直す(公式ドキュメントの勧め)
なお、Claude Codeには会話と変更を前の時点へ戻すチェックポイントの機能もあります。ただ、公式ドキュメントは、これを会話単位のすばやい戻しのためのものとし、恒久的な履歴はGitで残すよう案内しています。
本番サーバーで使う場合
本番のサーバーやデータを扱う作業では、バックアップの取り方や、止まって人が確かめる条件も、Phaseを始める前に決めておきます。サーバーの構築から運用までの進め方は、Claude CodeでAlmaLinuxサーバーを構築・運用する方法で紹介しています。
まとめ
- Claude Codeで長期プロジェクトを進めるときは、状態を会話ではなくprogress.mdとGitに置く
- Phaseは「何ができたら終わりか」で区切る
- 区切りでは、ステージ → 全件テスト → コミット → 確認の順で状態を確定する
- /compactは同じ作業を続けるとき、/clearは区切りで切り替えるとき。必ず/clearするわけではない
- 再開したら記録を読み、実際の状態と照合してから次のPhaseへ進む
Claude Codeそのものの概要はClaude Codeとは?、使い始めの手順はClaude Codeの始め方と使い方で紹介しています。
よくある質問
長いプロジェクトでは、毎回/clearしたほうがよいですか?
毎回である必要はありません。同じ作業を続けるなら/compactで会話を要約して続けられます。このサイトでは、Phaseの区切りで記録・テスト・コミットまで終えた状態を作り、会話が長くなっていれば/clearで新しい会話に切り替えています。
/clearと/compactはどう使い分けますか?
/compactは、同じ作業を続けたままコンテキストを空けたいときに使います。/clearは、空の状態で新しい会話を始めるときに使い、前の会話の内容は引き継がれません。切り替える前に、次の会話で必要な状態をファイルとGitに残しておきます。
/clearした後に、前の会話へ戻ることはできますか?
できます。前の会話は/resumeや claude --continue で再開できます。ただ、長いプロジェクトでは、前の会話に頼らずにprogress.mdとGitから状態を戻せるようにしておくと、どの会話からでも続きを始められます。
Phaseはどのくらいの大きさで区切りますか?
時間ではなく、終わったかどうかを確かめられる単位で区切ります。1つのPhaseの途中で会話が長くなりすぎるなら、Phaseを分けるか、Phaseの中にチェックポイントを置きます。
新しいセッションでは、何を最初に確認しますか?
CLAUDE.md、progress.mdの現在地と次にやること、関係する設計書を読み、git logとgit statusで実際の状態を確かめます。記録と実際の状態が食い違っていたら、作業を始める前にその理由を確かめます。
