📋

【Claude Code活用】PROGRESS.md駆動開発でセッションをまたいで開発する

に公開
AI
開発手法
Claude
Claude Code
tech

セッションをまたぐ問題

Claude Code はセッションをまたいで記憶を保持しません。新しいセッションを開始すると、前回どこまで進んだか・どんな問題があったかをすべて忘れた状態から始まります。

この問題を解決するために考案したのが PROGRESS.md 駆動開発です。

PROGRESS.md の設計

agent01 の PROGRESS.md は以下の3つのセクションで構成されています。

PROGRESS.md
## 現在地

**Phase D：統合 ✅ 完了**
**全Stepの実装が完了しました。**

## 全ステップ一覧

### Phase A：土台
- [x] Step 01　Ollamaセットアップ＋LLMクライアント抽象化
- [x] Step 02　システムプロンプト設定
- [x] Step 03　ターミナルREPLループ

### Phase B：ツール化
- [x] Step 04　tool_useの仕組みを理解する
...

## 申し送り事項

### 環境
- OS：Windows 11
- Ollamaで使用するモデル：qwen2.5-coder:7b（会話用）/ llama3.1:8b（tool_use用）

### 完了済みStepの記録

### Step 01：Ollamaセットアップ＋LLMクライアント抽象化
- 完了日：2026-05-30
- 気づき・躓いた点：Windows環境でcp932エンコーディングによる文字化けが発生。
  sys.stdout.reconfigure(encoding="utf-8") で対処。
- 次のStepへの申し送り：Step 02でシステムプロンプトを設定する。

この構造のポイントは3つです。

  1. 現在地：今どこにいるかを一目で把握できる
  2. 全ステップ一覧：チェックボックスで進捗を可視化
  3. 完了済みStepの記録：気づき・躓いた点・申し送り事項を詳細に残す

実際の運用

agent01 の 13 Step 開発を通じて確立した運用サイクルは以下のとおりです。

セッション開始時：

「PROGRESS.mdとAGENT_SPEC.mdを読んでください。
 その後、Step ○○の実装指示書に従って実装を進めてください。」

この一言で Claude Code はプロジェクトの文脈を把握し、前回の申し送り事項を考慮した上で作業を開始します。

セッション終了時：

実装完了後に PROGRESS.md を更新してからコミットします。

「Step ○○が完了しました。PROGRESS.mdを更新してからコミットしてください。」

PROGRESS.md の更新内容は以下の4項目です。

  1. 該当 Step のチェックボックスを [x] にする
  2. 「現在地」を次の Step に更新する
  3. 「完了済みStep」に記録を追加する
  4. 「申し送り事項」に環境情報・気づきを記録する

CLAUDE.md との組み合わせ

CLAUDE.md には PROGRESS.md の更新ルールを明記しました。

CLAUDE.md
## PROGRESS.md の更新ルール

Stepが完了したら以下を更新する。

1. 該当Stepのチェックボックスを `[x]` にする
2. 「現在地」を次のStepに更新する
3. 「完了済みStep」に記録を追加する
4. 「申し送り事項」に環境情報・気づきを記録する

## Git運用規則

### コミットのタイミング
- Stepが完了したら必ずコミットする
- 動作確認前にコミットしない
- `PROGRESS.md` の更新は実装コードと同じコミットに含める

このルールを CLAUDE.md に書いておくことで、「Step が完了したら PROGRESS.md を更新してからコミット」という流れが自動化されました。明示的な指示がなくても Claude Code がルールを遵守するようになります。

気づき

PROGRESS.md の「気づき・躓いた点」が記事の素材になった：13 Step を通じて記録した気づき（cp932 エンコーディング問題・LLM モデルごとの tool_use 対応状況など）が、そのまま Series A の記事コンテンツになりました。開発ログと記事素材を同時に蓄積できる設計です。

コミット履歴よりも「なぜそうしたか」が詳しく残る：git log では「何を変更したか」はわかりますが「なぜそうしたか」は残りません。PROGRESS.md の申し送り事項には決定の背景も記録できるため、後から見直したときに意思決定の経緯を追えます。

新しい開発者（次のセッションの Claude Code）への引き継ぎとして機能する：PROGRESS.md は「次のセッションの Claude Code」へのオンボーディングドキュメントとして機能します。既存チームへの新メンバー参加と同様の文脈共有が、AIエージェントとの協働でも有効でした。

まとめ

PROGRESS.md 駆動開発は、Claude Code のセッション間記憶問題をシンプルなテキストファイルで解決する手法です。「セッション開始時に読む・終了時に更新する」というサイクルを CLAUDE.md に定義することで、13 Step の開発を分散したセッションで着実に進めることができました。

次回

B8 では、Claude Code で Zenn 記事を生成したフロー全体を紹介します。今まさに読んでいるこの記事もそのフローで生成されました。

シリーズリンク（Series B）

記事 タイトル
B1 Claude Codeとは・導入と初期設定
B2 ファイル読み書きを任せる
B3 コードベース探索を任せる
B4 差分確認・適用を任せる
B5 テスト実行と結果解釈を任せる
B6 複数ファイル跨ぎの修正を任せる
B7 PROGRESS.md駆動開発（本記事）
B8 Zenn記事をClaude Codeに書かせる

Discussion