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 59733a8..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: "" --- @@ -12,6 +12,29 @@ テンプレート URL: `https://github.com/rintoHasegawa/programming-template.git` +## マージ必須ファイル (Merge-required Files) + +以下のファイルは「プロジェクト固有の内容 + テンプレートの共通ルール」のハイブリッドのため，**上書きせずマージする**．コピー処理（ステップ 5.3）に入る前に対象ファイルかを判定し，該当する場合はステップ 5.4 のマージ手順に分岐させる． + +| ファイル | 理由 | マージ方針 | +| --- | --- | --- | +| `.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` でワーキングツリーがクリーンか確認する． @@ -64,7 +87,7 @@ ## ステップ 4: 変更一覧をユーザーに提示 -取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する: +取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する．マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）に変更がある場合は，**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: 「**テンプレートに以下の変更があります:** @@ -73,54 +96,184 @@ - 削除 (D): {ファイル一覧} - リネーム (R): {旧名 → 新名} +**⚠ マージ必須ファイル（上書きせず差分マージします）:** + +- `.gitignore`（既存 {N} 行 / テンプレート {M} 行．既存の固有ルールを保持し，テンプレート側で追加されている {K} 行を追記） +- `CLAUDE.md`（既存にプロジェクト固有セクションが {L} 行．テンプレート更新セクションのみマージ） +- `docs/PROGRESS.md`（プロジェクト固有の進捗ログ．既存があれば内容を保持し，差分があれば通知のみ） +- `.gitattributes`（差分 {D} 行．処理方針をユーザーに確認） + 取り込みを開始します．」 +差分サマリーは以下で取得する（該当ファイルがマージ対象かつ既存ファイルがある場合のみ出力）: + +```bash +# 既存ファイル行数 +wc -l .gitignore CLAUDE.md docs/PROGRESS.md .gitattributes 2>/dev/null + +# テンプレート側の実効行数（.gitignore） +grep -vE '^\s*(#|$)' "$TEMP_DIR/.gitignore" | wc -l + +# 既存ファイルとテンプレート最新版の差分プレビュー +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 +``` + ## ステップ 5: ブランチ作成とファイル反映 -1. `git checkout -b chore/sync-template` でブランチを作成する - - 既に同名のブランチが存在する場合は削除してから作り直す +### 5.1 ブランチ作成 -2. 追加・変更・リネーム先を反映する: +`git checkout -b chore/sync-template` でブランチを作成する．既に同名のブランチが存在する場合は削除してから作り直す． +### 5.2 マージ必須ファイル判定ヘルパー + +以降の処理で利用する判定関数を定義する: + +```bash +MERGE_FILES=(".gitignore" "CLAUDE.md" "docs/PROGRESS.md" ".gitattributes") +SKIP_FILES=("README.md") + +is_merge_file() { + local t="$1" + for f in "${MERGE_FILES[@]}"; do + [ "$f" = "$t" ] && return 0 + done + return 1 +} + +is_skip_file() { + local t="$1" + for f in "${SKIP_FILES[@]}"; do + [ "$f" = "$t" ] && return 0 + done + return 1 +} +``` + +### 5.3 通常コピー対象の反映（マージ必須ファイル以外） + +マージ必須ファイルは後段（5.4）で個別処理するため，このループではスキップする．既存ファイルがない場合は通常どおり `cp` で配置する: + +```bash +echo "$CHANGED_ENTRIES" | while IFS=$'\t' read -r status file newfile; do + [ -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 + fi + mkdir -p "$(dirname "$file")" + cp "$TEMP_DIR/$file" "$file" + ;; + R*) + # file=旧パス, newfile=新パス + if is_skip_file "$newfile"; then + continue + fi + if is_merge_file "$newfile" && [ -f "$newfile" ]; then + continue + fi + mkdir -p "$(dirname "$newfile")" + cp "$TEMP_DIR/$newfile" "$newfile" + ;; + esac +done +``` + +### 5.4 マージ必須ファイルの個別処理 + +`$CHANGED_ENTRIES` に A/M/R* で含まれ，かつ既存ファイルが存在するマージ必須ファイルについて，以下の手順で処理する． + +**`.gitignore` のマージ手順** + +1. 既存 `.gitignore` とテンプレート `$TEMP_DIR/.gitignore` を読む +2. テンプレート側の**実効行**（コメント `#` 行・空行を除く）を抽出する: ```bash - echo "$CHANGED_ENTRIES" | while IFS=$'\t' read -r status file newfile; do - [ -z "$status" ] && continue - case "$status" in - A|M) - mkdir -p "$(dirname "$file")" - cp "$TEMP_DIR/$file" "$file" - ;; - R*) - # file=旧パス, newfile=新パス - mkdir -p "$(dirname "$newfile")" - cp "$TEMP_DIR/$newfile" "$newfile" - ;; - esac - done + grep -vE '^\s*(#|$)' "$TEMP_DIR/.gitignore" ``` +3. 抽出した各行について，既存ファイルに完全一致で含まれていないものだけを収集する +4. 収集した行がある場合，既存ファイル末尾に以下のマーカー付きブロックで追記する: + ``` + + # --- from template (sync-template) --- + {追加行} + ``` + - 既存ファイル末尾に同じマーカーが既にある場合は，マーカー以降に追記して重複マーカーを作らない +5. `git diff .gitignore` で結果を表示しユーザーに確認する -3. 削除候補（D およびリネーム元）を抽出する: +**`CLAUDE.md` のマージ手順** +同期担当エージェント（= あなた）が Read と Edit ツールを使ってセクション単位でマージする: + +1. 既存 `CLAUDE.md` とテンプレート版 `$TEMP_DIR/CLAUDE.md` を Read する +2. テンプレート側の変更箇所を特定する（初回同期は LAST_SHA がないためテンプレート全体を「更新候補」として扱う）: ```bash - DELETIONS=$(echo "$CHANGED_ENTRIES" | awk -F'\t' '$1 == "D" {print $2} $1 ~ /^R/ {print $2}') + if [ -n "$LAST_SHA" ]; then + git -C "$TEMP_DIR" show "$LAST_SHA:CLAUDE.md" 2>/dev/null > /tmp/claude_md_old || true + diff -u /tmp/claude_md_old "$TEMP_DIR/CLAUDE.md" + fi ``` +3. セクションを以下の基準で分類する: + - **共通セクション（テンプレート管理，更新対象）**: 「必須ルール」「エージェントチーム」「Git 運用」「ドキュメント」節など，テンプレートに由来する節 + - **プロジェクト固有セクション（保持対象）**: 「プロジェクト名」「開発進捗」や，プロジェクトが追加した固有規約の節 +4. テンプレート側で変更があった共通セクションのみを Edit で既存ファイルに反映する．プロジェクト固有セクションは一切触らない +5. `git diff CLAUDE.md` で結果を表示しユーザーに確認する -4. `$DELETIONS` が空でない場合，ユーザーに確認を求める: +**`docs/PROGRESS.md` のマージ手順** - 「**以下のファイルはテンプレートから削除されています:** +`docs/PROGRESS.md` はプロジェクト固有の進捗ログのため，**既存ファイルがある場合は内容を上書きしない**．テンプレート側の更新は骨組み（タイトル・案内コメント）に限定されるはずなので，差分があれば通知のみ行い手動マージを促す: - {削除候補一覧} - - プロジェクトからも削除してよいですか？（残したいファイルがあれば指定してください）」 - - ユーザー確認後，対象ファイルを `rm` で削除する．プロジェクトが独自に残したいファイルは削除対象から除外する． - -5. 同期済み SHA を記録し，一時ディレクトリを削除する: - +1. 既存 `docs/PROGRESS.md` とテンプレート版 `$TEMP_DIR/docs/PROGRESS.md` を Read する +2. 差分を表示する: ```bash - echo "$NEW_SHA" > .claude/template-sync-sha - rm -rf "$TEMP_DIR" + diff -u docs/PROGRESS.md "$TEMP_DIR/docs/PROGRESS.md" ``` +3. 差分がある場合，「⚠ テンプレート側の `docs/PROGRESS.md` 骨組みに変更があります．既存の追記内容を保持したまま骨組みを反映したい場合はファイルを直接編集してください．自動マージは行いません．」と通知する +4. 既存ファイルが無い稀なケース（テンプレートを使わずに作られた古いプロジェクト等）に限り，テンプレート版をそのまま `cp` で配置する + +**`.gitattributes` のマージ手順** + +1. 既存ファイルとテンプレート版の差分を表示する: + ```bash + diff -u .gitattributes "$TEMP_DIR/.gitattributes" + ``` +2. ユーザーに以下のいずれかを選ばせる: + - **上書き**: テンプレート版で既存を置換 + - **マージ**: 両者のルールを統合（具体的な統合内容は対話で決定） + - **スキップ**: 既存ファイルを維持 +3. 選択に応じて処理する + +### 5.5 削除候補の確認 + +削除候補（D およびリネーム元）を抽出する: + +```bash +DELETIONS=$(echo "$CHANGED_ENTRIES" | awk -F'\t' '$1 == "D" {print $2} $1 ~ /^R/ {print $2}') +``` + +`$DELETIONS` が空でない場合，ユーザーに確認を求める: + +「**以下のファイルはテンプレートから削除されています:** + +{削除候補一覧} + +プロジェクトからも削除してよいですか？（残したいファイルがあれば指定してください）」 + +ユーザー確認後，対象ファイルを `rm` で削除する．プロジェクトが独自に残したいファイルは削除対象から除外する． + +### 5.6 同期済み SHA の記録とクリーンアップ + +```bash +echo "$NEW_SHA" > .claude/template-sync-sha +rm -rf "$TEMP_DIR" +``` ## ステップ 6: 変更内容の分析 @@ -160,5 +313,8 @@ - テンプレートリポジトリへの push は行わない - コード修正はユーザーの確認なしに実行しない -- ファイルコピーによりプロジェクト固有の変更が上書きされる場合は，`git diff` で確認してユーザーに報告する +- マージ必須ファイル（`.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 8c20381..da97abe 100644 --- a/.claude/template-sync-sha +++ b/.claude/template-sync-sha @@ -1 +1 @@ -21c46e72e74f77a7dee7488d803b08e33b3c95bd +25655cd808cbc494676d576d0eab5e86126d39fb diff --git a/CLAUDE.md b/CLAUDE.md index 7e975d8..4c2a0e6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,8 @@ ## 開発進捗 -現在の進捗: Step 1〜5 完了（撮影・保存・一覧・削除の実装完了）．初期バージョンのアプリが動作する状態． -※ 撮影→保存の高速化完了（YUV→PNG 変換を Android ネイティブに移行，非圧縮 PNG + 回転統合により 15 秒 → 約 2 秒に短縮） -※ カメラ診断機能のインフラ追加完了（`DiagnosticsProvider` / `RawCaptureService.getCameraDiagnostics` / `FileService.saveDiagnosticsJson`）．UI は非表示．AQUOS sense3 のフロントカメラは **HW Level 3 + RAW (DNG) + MANUAL_SENSOR + MANUAL_POST_PROCESSING** 対応を確認． -※ **定量モード撮影機能（DNG 経路）完成**．シャッターボタンタップで `MiniTIAS_QM_YYYYMMDD_HHmmss.dng`（10-bit BGGR Bayer 3264×2448，約 16MB）＋ `MiniTIAS_QM_YYYYMMDD_HHmmss.meta.json`（撮影設定・実適用値・LSC マップ・センサ特性）を `Pictures/MiniTIAS/` に保存．Camera2 API でマニュアル制御（露光 1/60s 固定，ISO 40 固定，AE/AWB/NR/EDGE OFF，TONEMAP 線形，SHADING_MODE HIGH_QUALITY，AF OFF）．既存 PNG 経路は `captureFullResolutionPng` として温存． -※ ステップ完了時にここを更新すること． +最新: 定量モード撮影機能（DNG 経路）完成 +※ 本欄は**最新ステップ 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..05b4fb1 --- /dev/null +++ b/docs/PROGRESS.md @@ -0,0 +1,44 @@ +# 開発進捗ログ + + + +## Step 1〜5: 撮影・保存・一覧・削除の実装 + +- 状況: 初期バージョンのアプリ（撮影画面 + 一覧画面）が動作する状態に到達 +- 動機: TIAS（積分球を用いた大型装置）のスマホ版として研究メンバー向け撮影アプリを立ち上げる．PC 側で解析するため，スマホ側は撮影・保存に特化（PLAN_01 要件定義書参照） + +## 撮影→保存の高速化 + +- 状況: YUV→PNG 変換を Android ネイティブに移行．非圧縮 PNG + 回転統合により 15 秒 → 約 2 秒に短縮 +- 動機: Dart の image パッケージで PNG エンコードが遅く撮影フローが詰まっていた +- 設計判断: 非圧縮 PNG（Deflater.NO_COMPRESSION）を選択．圧縮率より速度優先．研究用途で 1 ショット数 MB は許容 +- 失敗パターン: 当初 Dart の isolate で並列化を検討したが，Plane バイトの copy オーバーヘッドで思ったほど速くならなかった + +## カメラ診断機能の追加（インフラのみ・UI 非表示） + +- 状況: `DiagnosticsProvider` / `RawCaptureService.getCameraDiagnostics` / `FileService.saveDiagnosticsJson` を追加．UI ボタンは出さず将来再利用に備えて温存 +- 動機: 定量モード撮影を実装する前提として，実機 AQUOS sense3 の Camera2 能力（HW Level・MANUAL_SENSOR/POST_PROCESSING の有無・RAW 出力可否・LSC マップ取得可否）を一度きっちり確認したかった +- 結果: AQUOS sense3 フロントカメラは **HW Level 3 + RAW + MANUAL_SENSOR + MANUAL_POST_PROCESSING** 対応．診断結果 JSON は `docs/06_TEST/camera_diagnostics_20260531_161734.json` に保存 +- 失敗パターン: `LENS_INFO_SHADING_MAP_SIZE` は hidden API でビルドエラー．`STATISTICS_INFO_AVAILABLE_LENS_SHADING_MAP_MODES` で代替判定 + 実キャプチャ後に CaptureResult から取得する設計に変更 + +## 定量モード撮影機能（DNG 経路）完成 + +- 状況: シャッターで `MiniTIAS_QM_YYYYMMDD_HHmmss.dng`（10-bit BGGR Bayer 3264×2448，約 16MB）と `.meta.json`（settings/actual/sensorCharacteristics/lscMap）を `Pictures/MiniTIAS/` に保存．既存 PNG 経路は `captureFullResolutionPng` として温存 +- 動機: SmTIAS-LightSim 側でのシミュ vs 実機の定量比較で残差 2.1× が解消しない問題．原因は MiniTIAS 通常モードが AE/AWB/NR/EDGE/TONEMAP 全自動で撮影ごとに値が揺らいでいたこと（TECH_01 参照） +- 設計判断: Camera2 マニュアル制御で `CONTROL_MODE=OFF` + AE/AWB/AF/NR/EDGE OFF + TONEMAP 線形 + 露光 1/60s 固定 + ISO 40 固定．`SHADING_MODE` は HIGH_QUALITY を採用（LSC マップ実値を取りたいため．OFF だと単位マップしか返らない）．フォーマットは DNG (RAW_SENSOR) を採用（8bit PNG では舌の色再現には情報量不足） +- 失敗パターン: ① MTP コピー直後の DNG が PC で 0 バイトに見える→「MethodChannel 16MB 転送が失敗」と誤診断．実際は MTP コピー遅延で，30 秒待てば全データあった．② `SHADING_MODE = OFF` 初回採用で LSC マップが全 1.0（Android 仕様）→ HIGH_QUALITY に変更で実値取得 +- 後段: 露光時間・ISO のキャリブ機能（白板撮影で AE 一回走らせて値を固定する半自動モード），撮影連射再現性検証 V1（CoV < 1%），他機種展開時の `getCameraDiagnostics` 再実行 + +## テンプレート同期 + +- 状況: programming-template から進捗記録の二段構成（CLAUDE.md 1 行 + PROGRESS.md 追記ログ）と関連スラッシュコマンド・ガイド更新を取り込み +- 動機: テンプレート側で進捗記録ルールが更新された．CLAUDE.md が毎ターン読み込まれることを考えると履歴を切り離す設計は合理的 +- 設計判断: `.gitignore` はテンプレート版（ミニマル）を採用せず Flutter 用エントリを温存．`CLAUDE.md` も全体上書きせず進捗欄だけ二段構成に書き換え．既存進捗エントリは本ファイルへ移植