diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md index 1610d69..14e6d41 100644 --- a/.claude/commands/commit.md +++ b/.claude/commands/commit.md @@ -1,6 +1,6 @@ --- name: commit -model: sonnet +model: inherit description: "GUIDE_04 に従い，変更内容の確認 → コミットを行う．" argument-hint: "<コミット内容の補足（省略可）>" --- @@ -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 07f1c21..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 を必要に応じて更新する． +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 9e42dde..fcfb723 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -11,9 +11,10 @@ ## 基本ルール - 各フェーズの成果物をユーザーが承認してから次のフェーズに進むこと -- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗を更新して中断する +- ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗（最新 1 行）と `docs/PROGRESS.md`（追記）を更新して中断する - ドキュメントは GUIDE_02（ドキュメント作成ガイド）と GUIDE_03（ファイル命名規則）に従って作成する - 成果物のドラフトを提示し，ユーザーの修正指示を反映してからファイルに書き出す +- フォルダは成果物を実際に書き出すときにのみ作成する．空のカテゴリフォルダを先回りで作らない ## 前提確認 (Pre-check) @@ -24,7 +25,7 @@ - CLAUDE.md の以下を書き換える: - 1 行目の `# プロジェクト名` → `# {確定したプロジェクト名}` - 3 行目の `` → 概要テキスト -3. CLAUDE.md の「開発進捗」を確認し，どのフェーズから再開するか判断する +3. CLAUDE.md の「開発進捗」と `docs/PROGRESS.md` を確認し，どのフェーズから再開するか判断する 4. 初回の場合はフェーズ 1 から開始する ## フェーズ 1〜6: 各フェーズの実行 @@ -45,6 +46,10 @@ 修正点があれば指示してください．OKであれば {保存先} に保存して次のフェーズに進みます．」 +### フォルダ作成の注意 + +成果物を書き出すフォルダのみ作成する．GUIDE_03 のカテゴリ表は「あり得るカテゴリの一覧」であり，立ち上げ時に全カテゴリのフォルダを scaffold するものではない．GUIDE_01 の立ち上げフェーズで成果物が発生するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` のみ．`05_TECH/`（技術設計）と `06_TEST/`（テスト）は立ち上げ時には成果物が無いため，空フォルダを作らない（実装フェーズで必要になった時点で作成する）． + ### フェーズ 3（環境構築）の注意 外部サービスの設定（アカウント作成，コンソール操作等）はユーザー自身が行う．手順書に記載するが，AI が実行しないこと． @@ -67,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 0372706..0e74b4a 100644 --- a/.claude/commands/sync-template.md +++ b/.claude/commands/sync-template.md @@ -1,6 +1,6 @@ --- name: sync-template -model: sonnet +model: inherit description: "テンプレートリポジトリから最新の変更を取り込み，ルール変更に伴うコード修正を行う．" argument-hint: "" --- @@ -20,10 +20,21 @@ | --- | --- | --- | | `.gitignore` | フレームワーク固有ルール（Flutter/Node 等）を保持する必要がある | テンプレート側の実効行で既存に含まれないもののみを追記．既存行は触らない | | `CLAUDE.md` | プロジェクト名・開発進捗・固有規約を保持する必要がある | テンプレートで変更された共通セクション（必須ルール，エージェントチーム，ドキュメント構成等）のみを Edit で更新．プロジェクト固有セクションは触らない | +| `docs/PROGRESS.md` | プロジェクト固有の進捗ログを保持する必要がある | 既存ファイルがある場合は内容を上書きしない．テンプレート側の骨組み（タイトル・案内コメント）に差分があれば通知のみ行い手動マージを促す | | `.gitattributes` | プロジェクトによって設定が異なる可能性がある | 差分を表示し，ユーザーに「上書き / マージ / スキップ」を問う | マージ処理の対象は **既存ファイルが存在する場合のみ**．初回同期（`.claude/template-sync-sha` がない状態）では全ファイルが A 扱いとなるが，これらのファイルはフレームワーク初期化（`flutter create` / `npm init` 等）や `/init` で既にプロジェクトに存在するのが通常なので，そのままマージ処理に入る．既存ファイルがない稀なケースに限り通常の `cp` で配置する． +## 同期対象外ファイル (Skip-on-sync Files) + +以下のファイルはテンプレート紹介専用であり，テンプレートから作られた各プロジェクトには反映しない．コピー・上書き・削除のいずれも行わない． + +| ファイル | 理由 | 方針 | +| --- | --- | --- | +| `README.md` | テンプレートの README は GitHub の repo ページ向けのテンプレート紹介用．各プロジェクトは独自の README を持つべき | プロジェクト側にコピー・上書きしない．テンプレート側の追加・変更・削除も無視する | + +判定はステップ 5.3 のループ内でマージ必須ファイル判定より先に行う． + ## ステップ 1: 事前確認 `git status` でワーキングツリーがクリーンか確認する． @@ -76,7 +87,7 @@ ## ステップ 4: 変更一覧をユーザーに提示 -取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: +取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: 「**テンプレートに以下の変更があります:** @@ -89,6 +100,7 @@ - `.gitignore`（既存 {N} 行 / テンプレート {M} 行．既存の固有ルールを保持し，テンプレート側で追加されている {K} 行を追記） - `CLAUDE.md`（既存にプロジェクト固有セクションが {L} 行．テンプレート更新セクションのみマージ） +- `docs/PROGRESS.md`（プロジェクト固有の進捗ログ．既存があれば内容を保持し，差分があれば通知のみ） - `.gitattributes`（差分 {D} 行．処理方針をユーザーに確認） 取り込みを開始します．」 @@ -97,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 @@ -105,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 ``` @@ -119,7 +132,8 @@ 以降の処理で利用する判定関数を定義する: ```bash -MERGE_FILES=(".gitignore" "CLAUDE.md" ".gitattributes") +MERGE_FILES=(".gitignore" "CLAUDE.md" "docs/PROGRESS.md" ".gitattributes") +SKIP_FILES=("README.md") is_merge_file() { local t="$1" @@ -128,6 +142,14 @@ done return 1 } + +is_skip_file() { + local t="$1" + for f in "${SKIP_FILES[@]}"; do + [ "$f" = "$t" ] && return 0 + done + return 1 +} ``` ### 5.3 通常コピー対象の反映（マージ必須ファイル以外） @@ -139,6 +161,10 @@ [ -z "$status" ] && continue case "$status" in A|M) + # 同期対象外ファイルは完全にスキップ（コピーも上書きもしない） + if is_skip_file "$file"; then + continue + fi # マージ必須ファイルで既存ファイルがある場合は 5.4 で処理 if is_merge_file "$file" && [ -f "$file" ]; then continue @@ -148,6 +174,9 @@ ;; R*) # file=旧パス, newfile=新パス + if is_skip_file "$newfile"; then + continue + fi if is_merge_file "$newfile" && [ -f "$newfile" ]; then continue fi @@ -197,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. 既存ファイルとテンプレート版の差分を表示する: @@ -272,7 +313,8 @@ - テンプレートリポジトリへの 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` 等のプロジェクト固有ファイルはテンプレートに含まれないため同期対象外 - `chore/sync-template` ブランチは他の作業ブランチと混ぜず，作成後は速やかにマージすること．複数の作業ブランチで `/sync-template` を実行すると `.claude/template-sync-sha` がコンフリクトする．コンフリクト時は新しい（HEAD 側の）SHA を採用すること． diff --git a/.claude/template-sync-sha b/.claude/template-sync-sha index 49722ad..da97abe 100644 --- a/.claude/template-sync-sha +++ b/.claude/template-sync-sha @@ -1 +1 @@ -edf620587f1798319fa8412e55e7b99bf17528a4 +25655cd808cbc494676d576d0eab5e86126d39fb diff --git a/CLAUDE.md b/CLAUDE.md index 6afd396..431845d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,8 +4,8 @@ ## 開発進捗 -現在の進捗: ステップ 2（MiniTIAS 照明均一性評価）完了．次はステップ 3 -※ ステップ完了時にここを更新すること． +最新: ステップ 2（MiniTIAS 照明均一性評価）完了．次はステップ 3 +※ 本欄は**最新ステップ 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 b3b8893..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" @@ -15,6 +15,8 @@ | 開発計画 | ステップを分割し，開発順序を決める | `PLAN_02_開発ステップ.md` | | 実装開始 | 開発計画に沿って実装を進める | ソースコード | +※ 立ち上げフローで作成するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` カテゴリの成果物のみ．`05_TECH`（技術設計）・`06_TEST`（テスト）は実装フェーズで必要になった時点で作成し，立ち上げ時に空フォルダを作らない． + ## 方針決定 (Direction) プロジェクトの全体像を明確にする． @@ -38,26 +40,6 @@ - **前提条件**: 以下のツールは全プロジェクト共通で導入する． - `git` — バージョン管理（[GUIDE_04](GUIDE_04_Git運用ルール.md) で運用ルールを定義） - `gh` — GitHub CLI（PR 作成・マージ等に使用） -- **テンプレートからのプロジェクト作成**: - 以下の手順でテンプレートをコピーし，履歴を引き継がない新規リポジトリとして初期化する． - - ```bash - # 1. プロジェクトディレクトリを作成して移動 - mkdir - cd - - # 2. カレントディレクトリにテンプレートをクローン（末尾の . に注意） - git clone https://github.com/rintoHasegawa/programming-template.git . - - # 3. 現在のテンプレート SHA を記録（以降の /sync-template で差分同期するため） - git rev-parse HEAD > .claude/template-sync-sha - - # 4. テンプレートの git 履歴を削除し，新しいリポジトリとして初期化 - rm -rf .git - git init -b main - ``` - - 以降，テンプレートの更新を取り込むときは `/sync-template` を実行する． - **基本方針**: 環境の再現性を重視し，手順書だけに頼らず構築を自動化・コード化できる方法を優先する（例: Docker，Dev Containers，Windows Sandbox，IaC ツール等）． - **人間が決めること**: 開発マシンの選定，クラウドサービスのアカウント作成，環境構築方法の選択 - **AI に依頼できること**: 環境構築手順書の作成，設定ファイルの生成，`.gitignore` の作成，Dockerfile や devcontainer.json 等の構築用ファイルの作成 @@ -112,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 9a30190..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` の進捗欄を更新 + - 開発ステップの進捗 → `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) @@ -135,3 +135,58 @@ パイプライン完了後は `/commit` でコミットする．コミットメッセージのタグ等は [GUIDE_04](GUIDE_04_Git運用ルール.md) に従う． ※ リファクタリングとテストは実装と一体の成果物として，まとめてコミットする．必要に応じて分割コミットも可． + +## 進捗記録の運用ルール（CLAUDE.md / PROGRESS.md） + +進捗記録は **2 ファイルの二段構成**で管理する．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 ` または `git show ` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する． + +- 関数名・引数・型シグネチャ +- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨） +- リファクタリングの手順詳細 +- 撤去・新規追加の関数リスト +- 具体的な定数値・閾値（設計判断の核心に関わるものを除く） +- 数値範囲の細部（実装パラメータ等） +- 後方互換性の細かい仕様 +- 「全テスト N passed」の報告（pass している前提のため不要） + +**長さと書式**: + +- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする +- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 +- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない +- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する + +**既存エントリの長文化に気付いたとき**: + +過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと． diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md new file mode 100644 index 0000000..fb9f89d --- /dev/null +++ b/docs/PROGRESS.md @@ -0,0 +1,14 @@ +# 開発進捗ログ + + + +- [x] **ステップ 2: MiniTIAS 照明均一性評価 完了**: 照明均一性の評価指標算出・可視化を実装し，REPORT_01（照明均一性評価報告書）を作成済み．次はステップ 3． + - 注: 本エントリはテンプレート同期で PROGRESS.md を新設した際の移記ベースライン（詳細経緯は `git log` を参照）．以降の進捗は本ファイル末尾に追記する．