---
paths: ["CLAUDE.md", "docs/PROGRESS.md"]
---

# 進捗記録の運用ルール (Progress Log Rules)

`CLAUDE.md` の「開発進捗」セクションと `docs/PROGRESS.md` を更新するときは本ルールに従うこと．

> ⚠ **チーム開発モード（team）では本ルールは上書きされる**．team プロジェクトでは進捗を `CLAUDE.md`・`docs/PROGRESS.md` に書かず，GitHub Issues と git 履歴で追う（[GUIDE_06](../../docs/01_GUIDE/GUIDE_06_チーム開発ルール.md)）．以下は個人開発モード（solo）の既定ルールである．team モードでは Phase 4 の進捗更新を Issue コメント（`/task-handoff` 等）に置き換える．

## 二段構成 (Two-tier Structure)

進捗記録は **2 ファイルの二段構成**で管理する．`/implement` の Phase 4 や `/setup` 中断時にこれらを更新する．

| ファイル | 役割 | 更新方法 |
| --- | --- | --- |
| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き |
| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 |

**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない．

## CLAUDE.md「開発進捗」の書き方

- **最新 1 行のみ**．古い行は上書きで消す（履歴は PROGRESS.md に残るので消えてよい）
- 基本形式: `最新: <ステップ見出し>`
- 関数名・テスト件数・実装手順詳細は書かない（PROGRESS.md と `git log` に任せる）

## docs/PROGRESS.md の書き方

`docs/PROGRESS.md` は追記型．最新エントリを**末尾に追記**する（時系列順．古いものが上，新しいものが下）．

**書く（PROGRESS.md に残す価値が高いもの）**:

以下は PROGRESS.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない．

- 状況: 何が完了したか（1 行）
- 動機・原因: なぜそれをやったか（既存の問題点・要件変更・前バージョンの欠点など）
- 重要な設計判断: 他案との比較が必要な場合のみ．「A 案ではなく B 案を選んだ理由」が将来の判断材料になるとき
- 失敗パターンの圧縮サマリ: 「① X 案 → Y で破綻 / ② Z 案で解決」のような 1〜2 行．同じ轍を踏まないための知識として残す．試行錯誤を時系列で全部書かず，本質的に異なるアプローチの失敗だけを並列項目として記録する
- 未実装・後段: 「次に何をすべきか」を思い出すための短いメモ

**書かない（コミットメッセージと `git log` に任せる）**:

以下は `git log <commit-hash>` または `git show <commit-hash>` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する．

- 関数名・引数・型シグネチャ
- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨）
- リファクタリングの手順詳細
- 撤去・新規追加の関数リスト
- 具体的な定数値・閾値（設計判断の核心に関わるものを除く）
- 数値範囲の細部（実装パラメータ等）
- 後方互換性の細かい仕様
- 「全テスト N passed」の報告（pass している前提のため不要）

**長さと書式**:

- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする
- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加
- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない
- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する

**既存エントリの長文化に気付いたとき**:

過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと．