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_03）．以下は個人開発モード（solo）の既定ルールである．team モードでは Phase 4 の進捗更新を Issue コメント（/task-handoff 等）に置き換える．

二段構成 (Two-tier Structure)

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

背景: 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 にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと．