diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md index bb23074..14e6d41 100644 --- a/.claude/commands/commit.md +++ b/.claude/commands/commit.md @@ -40,19 +40,23 @@ 変更内容と $ARGUMENTS（指定がある場合）をもとに，GUIDE_04 の「コミットメッセージ」セクションに従ってコミットメッセージを生成する． -## ステップ 4: CLAUDE.md 更新漏れチェック +## ステップ 4: CLAUDE.md / PROGRESS.md 更新漏れチェック -`.claude/commit-context.md` が存在し `claude_md_updated` が記録されている場合，このステップをスキップする． +`.claude/commit-context.md` が存在し `claude_md_updated` と `progress_md_updated` が記録されている場合，このステップをスキップする． -ファイルが存在しない場合（`/implement` を経由していない場合），変更内容に応じて CLAUDE.md の「開発進捗」セクションの更新が必要か判断し， -更新されていない場合は「⚠ CLAUDE.md の開発進捗の更新が必要かもしれません．確認してください．」と警告する． +ファイルが存在しない場合（`/implement` を経由していない場合），変更内容に応じて以下の更新が必要か判断する: + +- CLAUDE.md の「開発進捗」セクション（最新 1 行） +- `docs/PROGRESS.md`（追記型フルログ） + +更新されていない場合は「⚠ CLAUDE.md の開発進捗 / docs/PROGRESS.md の更新が必要かもしれません．確認してください．」と警告する． 更新自体は行わず，ユーザーの判断に委ねる． ## ステップ 5: コミット 以下を実行する: -1. `git add` で関連ファイルをステージングする（CLAUDE.md の変更がある場合はそれも含める） +1. `git add` で関連ファイルをステージングする（CLAUDE.md / `docs/PROGRESS.md` の変更がある場合はそれも含める） 2. `git commit -m "{コミットメッセージ}"` でコミットする 3. `.claude/commit-context.md` が存在する場合は削除する diff --git a/.claude/commands/implement.md b/.claude/commands/implement.md index e8bbf09..aec0281 100644 --- a/.claude/commands/implement.md +++ b/.claude/commands/implement.md @@ -75,7 +75,7 @@ ## Phase 4: ドキュメント更新 (Documentation) -GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，docs/ と CLAUDE.md を必要に応じて更新する．CLAUDE.md の進捗欄を更新する場合は GUIDE_05「CLAUDE.md 進捗欄の更新ルール」に従い簡潔に書く（`git log` で取れる詳細は書かない）． +GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を必要に応じて更新する．進捗を記録する場合は GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` に詳細を末尾追記．`git log` で取れる詳細は書かない）． Phase 4 の結果を `.claude/commit-context.md` に書き出す: @@ -83,6 +83,7 @@ # commit-context - docs_updated: true/false - claude_md_updated: true/false +- progress_md_updated: true/false - note: （更新不要の理由や更新内容の要約） ``` diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index b07d1aa..fcfb723 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -11,7 +11,7 @@ ## 基本ルール - 各フェーズの成果物をユーザーが承認してから次のフェーズに進むこと -- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗を更新して中断する +- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗（最新 1 行）と `docs/PROGRESS.md`（追記）を更新して中断する - ドキュメントは GUIDE_02（ドキュメント作成ガイド）と GUIDE_03（ファイル命名規則）に従って作成する - 成果物のドラフトを提示し，ユーザーの修正指示を反映してからファイルに書き出す - フォルダは成果物を実際に書き出すときにのみ作成する．空のカテゴリフォルダを先回りで作らない @@ -25,7 +25,7 @@ - CLAUDE.md の以下を書き換える: - 1 行目の `# プロジェクト名` → `# {確定したプロジェクト名}` - 3 行目の `` → 概要テキスト -3. CLAUDE.md の「開発進捗」を確認し，どのフェーズから再開するか判断する +3. CLAUDE.md の「開発進捗」と `docs/PROGRESS.md` を確認し，どのフェーズから再開するか判断する 4. 初回の場合はフェーズ 1 から開始する ## フェーズ 1〜6: 各フェーズの実行 @@ -72,7 +72,7 @@ ユーザーが中断を希望した場合: -1. 現在のフェーズと状態を CLAUDE.md の「開発進捗」に記録する +1. 現在のフェーズと状態を CLAUDE.md の「開発進捗」（最新 1 行に上書き）と `docs/PROGRESS.md`（末尾に追記）に記録する 2. 次回 `/setup` 実行時に続きから再開できるようにする 「**進捗を保存しました．** diff --git a/.claude/commands/sync-template.md b/.claude/commands/sync-template.md index c079dea..0e74b4a 100644 --- a/.claude/commands/sync-template.md +++ b/.claude/commands/sync-template.md @@ -20,6 +20,7 @@ | --- | --- | --- | | `.gitignore` | フレームワーク固有ルール（Flutter/Node 等）を保持する必要がある | テンプレート側の実効行で既存に含まれないもののみを追記．既存行は触らない | | `CLAUDE.md` | プロジェクト名・開発進捗・固有規約を保持する必要がある | テンプレートで変更された共通セクション（必須ルール，エージェントチーム，ドキュメント構成等）のみを Edit で更新．プロジェクト固有セクションは触らない | +| `docs/PROGRESS.md` | プロジェクト固有の進捗ログを保持する必要がある | 既存ファイルがある場合は内容を上書きしない．テンプレート側の骨組み（タイトル・案内コメント）に差分があれば通知のみ行い手動マージを促す | | `.gitattributes` | プロジェクトによって設定が異なる可能性がある | 差分を表示し，ユーザーに「上書き / マージ / スキップ」を問う | マージ処理の対象は **既存ファイルが存在する場合のみ**．初回同期（`.claude/template-sync-sha` がない状態）では全ファイルが A 扱いとなるが，これらのファイルはフレームワーク初期化（`flutter create` / `npm init` 等）や `/init` で既にプロジェクトに存在するのが通常なので，そのままマージ処理に入る．既存ファイルがない稀なケースに限り通常の `cp` で配置する． @@ -86,7 +87,7 @@ ## ステップ 4: 変更一覧をユーザーに提示 -取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: +取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: 「**テンプレートに以下の変更があります:** @@ -99,6 +100,7 @@ - `.gitignore`（既存 {N} 行 / テンプレート {M} 行．既存の固有ルールを保持し，テンプレート側で追加されている {K} 行を追記） - `CLAUDE.md`（既存にプロジェクト固有セクションが {L} 行．テンプレート更新セクションのみマージ） +- `docs/PROGRESS.md`（プロジェクト固有の進捗ログ．既存があれば内容を保持し，差分があれば通知のみ） - `.gitattributes`（差分 {D} 行．処理方針をユーザーに確認） 取り込みを開始します．」 @@ -107,7 +109,7 @@ ```bash # 既存ファイル行数 -wc -l .gitignore CLAUDE.md .gitattributes 2>/dev/null +wc -l .gitignore CLAUDE.md docs/PROGRESS.md .gitattributes 2>/dev/null # テンプレート側の実効行数（.gitignore） grep -vE '^\s*(#|$)' "$TEMP_DIR/.gitignore" | wc -l @@ -115,6 +117,7 @@ # 既存ファイルとテンプレート最新版の差分プレビュー diff -u .gitignore "$TEMP_DIR/.gitignore" | head -30 diff -u CLAUDE.md "$TEMP_DIR/CLAUDE.md" | head -50 +diff -u docs/PROGRESS.md "$TEMP_DIR/docs/PROGRESS.md" | head -30 diff -u .gitattributes "$TEMP_DIR/.gitattributes" | head -30 ``` @@ -129,7 +132,7 @@ 以降の処理で利用する判定関数を定義する: ```bash -MERGE_FILES=(".gitignore" "CLAUDE.md" ".gitattributes") +MERGE_FILES=(".gitignore" "CLAUDE.md" "docs/PROGRESS.md" ".gitattributes") SKIP_FILES=("README.md") is_merge_file() { @@ -223,6 +226,18 @@ 4. テンプレート側で変更があった共通セクションのみを Edit で既存ファイルに反映する．プロジェクト固有セクションは一切触らない 5. `git diff CLAUDE.md` で結果を表示しユーザーに確認する +**`docs/PROGRESS.md` のマージ手順** + +`docs/PROGRESS.md` はプロジェクト固有の進捗ログのため，**既存ファイルがある場合は内容を上書きしない**．テンプレート側の更新は骨組み（タイトル・案内コメント）に限定されるはずなので，差分があれば通知のみ行い手動マージを促す: + +1. 既存 `docs/PROGRESS.md` とテンプレート版 `$TEMP_DIR/docs/PROGRESS.md` を Read する +2. 差分を表示する: + ```bash + diff -u docs/PROGRESS.md "$TEMP_DIR/docs/PROGRESS.md" + ``` +3. 差分がある場合，「⚠ テンプレート側の `docs/PROGRESS.md` 骨組みに変更があります．既存の追記内容を保持したまま骨組みを反映したい場合はファイルを直接編集してください．自動マージは行いません．」と通知する +4. 既存ファイルが無い稀なケース（テンプレートを使わずに作られた古いプロジェクト等）に限り，テンプレート版をそのまま `cp` で配置する + **`.gitattributes` のマージ手順** 1. 既存ファイルとテンプレート版の差分を表示する: @@ -298,7 +313,7 @@ - テンプレートリポジトリへの push は行わない - コード修正はユーザーの確認なしに実行しない -- マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `.gitattributes`）は必ずステップ 5.4 の手順でマージする．盲目的な `cp` で上書きしない（フレームワーク固有の除外ルールやプロジェクト固有セクションが失われる） +- マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）は必ずステップ 5.4 の手順でマージする．盲目的な `cp` で上書きしない（フレームワーク固有の除外ルールやプロジェクト固有セクションが失われる） - 同期対象外ファイル（`README.md`）はテンプレート紹介用のためプロジェクトには反映しない．テンプレート側で追加・変更・削除があってもプロジェクトの該当ファイルは触らない - 通常コピー対象でもプロジェクト固有の変更が上書きされうる場合は，`git diff` で確認してユーザーに報告する - テンプレートが管理するのは `.claude/` 配下のうち `agents/`，`commands/`，`hooks/`，`settings.json`，`template-sync-sha` のみ．`.claude/plans/` や `.claude/commit-context.md` 等のプロジェクト固有ファイルはテンプレートに含まれないため同期対象外 diff --git a/CLAUDE.md b/CLAUDE.md index 0b6a649..b192f79 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,8 +4,8 @@ ## 開発進捗 -現在の進捗: GUIDE_01 に従いプロジェクト立ち上げ中 -※ ステップ完了時にここを更新する．**目次・道標として運用**: 書くことが少なければ 1 行で十分 / 関数名・テスト件数等は `git log` に任せる / 失敗パターンは「① X 案で破綻 → ② Z 案で解決」の圧縮形式．詳細は GUIDE_05「CLAUDE.md 進捗欄の更新ルール」を参照． +最新: GUIDE_01 に従いプロジェクト立ち上げ中 +※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴（動機・設計判断・失敗パターン）は [docs/PROGRESS.md](docs/PROGRESS.md) に追記する．運用ルールは GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」を参照． ## 必須ルール（コード実装時） diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" index 169055d..a6f9a0c 100644 --- "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" @@ -94,17 +94,18 @@ ### 記載すべき内容 - **プロジェクト概要**: プロジェクト名，目的，技術スタックの要約 -- **開発進捗**: 現在のステップ，次にやること +- **開発進捗**: 現在のステップ（最新 1 行のみ）．詳細な進捗履歴は `docs/PROGRESS.md` に追記する（[GUIDE_05](GUIDE_05_エージェント運用ルール.md) の「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」参照） - **必須ルール**: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点） - **ドキュメント一覧**: docs/ 内のファイルへの参照パス ### 更新タイミング -- ステップの完了時に開発進捗を更新する +- ステップの完了時に開発進捗を更新する（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` は末尾に追記） - ドキュメントの追加・削除・リネーム時に参照パスを更新する - 必須ルールに変更があった場合に反映する ### 運用上の注意 - CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する． +- 進捗記録は二段構成（CLAUDE.md = 最新 1 行 / `docs/PROGRESS.md` = 追記型フルログ）で管理する．詳細は [GUIDE_05](GUIDE_05_エージェント運用ルール.md) を参照． - プロジェクト固有のルールが増えたら，docs/ に独立ファイルとして切り出し，CLAUDE.md からはリンクで参照する． diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" index d611008..2936c2a 100644 --- "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" +++ "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -51,7 +51,7 @@ │ テスト再実行で挙動が変わっていないことを保証 │ ├─ Phase 4 ──▶ ドキュメント更新 - │ docs/ と CLAUDE.md を必要に応じて更新 + │ docs/, CLAUDE.md, docs/PROGRESS.md を必要に応じて更新 │ 更新がある場合のみ人間の確認を挟む │ 結果を .claude/commit-context.md に書き出す │ @@ -93,21 +93,21 @@ ### Phase 4: ドキュメント更新 (Documentation) -Phase 3 完了後，実装内容に応じて `docs/` と `CLAUDE.md` を更新する． +Phase 3 完了後，実装内容に応じて `docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を更新する． - **チェック観点**: - API・データ構造の変更 → `docs/04_SPEC/` の該当仕様を更新 - 環境・依存関係の変更 → `docs/02_ENV/` を更新 - - 開発ステップの進捗 → `docs/03_PLAN/` や `CLAUDE.md` の進捗欄を更新（CLAUDE.md は本ガイドの「CLAUDE.md 進捗欄の更新ルール」に従い簡潔に書く．`git log` で取れる詳細は書かない） + - 開発ステップの進捗 → `docs/03_PLAN/` や進捗記録（`CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md`）を更新（書式は本ガイドの「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う．`git log` で取れる詳細は書かない） - 規約・運用ルールの変更 → `docs/01_GUIDE/` を更新 - **該当なし**: ドキュメント更新が不要な変更（軽微なバグ修正，リファクタリングのみ等）はスキップ可． - **更新がある場合のみ**人間の確認を挟む．更新不要の場合は確認なしで完了処理に進む． -- **コミットコンテキストの書き出し**: Phase 4 の結果（更新の有無と理由）を `.claude/commit-context.md` に書き出す．このファイルは `/commit` が参照し，docs/CLAUDE.md の更新漏れチェックをスキップするために使う（`.gitignore` 対象）． +- **コミットコンテキストの書き出し**: Phase 4 の結果（更新の有無と理由）を `.claude/commit-context.md` に書き出す．このファイルは `/commit` が参照し，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` の更新漏れチェックをスキップするために使う（`.gitignore` 対象）． ### 完了処理 - `/implement` はコミットを行わない．完了後は `/commit` でコミットする． -- `/commit` は `.claude/commit-context.md` が存在する場合，docs/CLAUDE.md の更新漏れチェックをスキップする．存在しない場合（`/implement` を経由していない場合）は警告のみ行う． +- `/commit` は `.claude/commit-context.md` が存在する場合，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` の更新漏れチェックをスキップする．存在しない場合（`/implement` を経由していない場合）は警告のみ行う． ## コンテキスト受け渡し (Context Passing) @@ -136,25 +136,40 @@ ※ リファクタリングとテストは実装と一体の成果物として，まとめてコミットする．必要に応じて分割コミットも可． -## CLAUDE.md 進捗欄の更新ルール +## 進捗記録の運用ルール（CLAUDE.md / PROGRESS.md） -Phase 4 で `CLAUDE.md` の「開発進捗」セクションを更新する際は，**目次・道標（signpost）として運用する**．エントリ自体に詳細を書き込まず，「全体の流れを俯瞰したい」「あの作業の commit を辿りたい」と思った時に**どこを見ればいいか当たりがつく**ことを目的とする． +進捗記録は **2 ファイルの二段構成**で管理する．Phase 4 や `/setup` 中断時にこれらを更新する． -**背景**: CLAUDE.md は毎ターン読み込まれるためコンテキスト圧迫の原因になる．関数名・引数・テスト件数等の詳細は `git log` とコミットメッセージに完全な形で残るため，CLAUDE.md に書くと二重管理になり，どちらかが古くなる． +| ファイル | 役割 | 更新方法 | +| --- | --- | --- | +| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き | +| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 | -**書く（CLAUDE.md に残す価値が高いもの）**: +**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない． -以下は CLAUDE.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない． +### 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 ` または `git show ` で完全な情報が取れる．CLAUDE.md に書くと重複・陳腐化する． +以下は `git log ` または `git show ` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する． - 関数名・引数・型シグネチャ - テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨） @@ -168,7 +183,7 @@ **長さと書式**: - 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする -- 基本形式: `[x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 +- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 - 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない - 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md new file mode 100644 index 0000000..14ea2fc --- /dev/null +++ b/docs/PROGRESS.md @@ -0,0 +1,11 @@ +# 開発進捗ログ + +