diff --git a/docs/todo.md b/docs/todo.md index eda92d9..e7dac65 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -2,45 +2,54 @@ > **運用ルール**: 各タスクには **やろうとしたこと / 現在地 / 詰まっている箇所** を必ず書く。完了タスクは ADR か仕組みに反映後、このファイルから削除する。過去の経緯は git log で追跡可能。 > -> **本ファイル + [docs/todo2.md](todo2.md) の使い分け** (PR #83 T3-2 で恒久化、2026-04-28 強化): +> **本ファイル + [docs/todo2.md](todo2.md) + [docs/todo3.md](todo3.md) の使い分け** (PR #83 T3-2 で恒久化、2026-04-28 強化、PR #88 で todo3.md 追加): > - **docs/todo.md**: 既存タスクの編集・完了削除専用。新規タスクは追加しない (~50KB 閾値内に維持し Claude Code 読み取り安定性を確保) -> - **docs/todo2.md**: 新規タスクの追加先。todo.md のサイズ管理のため新規エントリは原則本ファイルへ -> - 例外: 既存 todo.md タスクと **同一ファイル / 同一コンポーネント** を編集する密結合タスクは todo.md に追加可 (例: `~/.claude/rules/common/git-workflow.md` 配下のグローバルルール群) -> - **新セッションでは両方を確認すること** +> - **docs/todo2.md**: 既存タスクの編集・完了削除専用。**新規タスクは追加しない** (50KB に到達したため、PR #88 以降の新規エントリは todo3.md へ) +> - **docs/todo3.md**: 新規タスクの追加先。50KB に到達するまでは本ファイルへ追加 +> - 例外: 既存 todo.md / todo2.md タスクと **同一ファイル / 同一コンポーネント** を編集する密結合タスクは該当ファイルに追加可 (例: `~/.claude/rules/common/git-workflow.md` 配下のグローバルルール群) +> - **新セッションでは三つすべてを確認すること** --- -## 推奨実行順序サマリー (2026-04-28 更新、PR #86 post-merge-feedback 反映後) + +## 推奨実行順序サマリー (2026-04-28 更新、PR #88 post-merge-feedback 反映後) 開発環境の作業効率への貢献度を基準にした推奨実行順序。詳細は各タスク冒頭の **「実行優先度」** 行を参照。 | 順位 | Tier | タスク | ファイル | 工数 | 依存 | |---|---|---|---|---|---| -| 2 | 🚀 Tier 1 | push 前 untracked `__*` ファイル警告 hook (PR #85 T1-4) | todo2.md | Small | なし (PR #85 直接対策) | -| 3 | 🚀 Tier 1 | `cli-push-runner` jj bookmark 未設定 early-exit (PR #85 T1-3) | todo2.md | S | なし | -| 4 | 🚀 Tier 1 | PowerShell swallowed error custom_lint_rule (PR #85 T1-2) | todo2.md | XS | なし (ADR-007 拡張) | -| 5 | 🚀 Tier 1 | **Polling anti-pattern 検出ルール (PR #86 T1-1)** | todo2.md | XS | なし (PR #86 直接対策) | -| 6 | 🚀 Tier 1 | ADR-032 PR-pre: GitHub Branch Protection 整備 | todo2.md | 設定のみ | なし (依存タスクは完了済) | -| 7 | 🔧 Tier 2 | 週次レビュー (ADR-031) Phase B 実装 | todo.md | 中-高 | なし (順位 11 の compensating check 前提) | -| 8 | 🔧 Tier 2 | reviewer facet 改善 (review-simplicity / review-security の DRY/YAGNI/security 軸明文化) | todo2.md | S | なし | -| 9 | 🔧 Tier 2 | ADR-032 PR-broken-link: broken-link-check + 内部アンカー検査 統合 | todo2.md | Small-中 | なし (順位 1 完了済 = clean baseline 確立済) | -| 10 | 🔧 Tier 2 | `cli-pr-monitor` プロセス正常終了の integration test (PR #85 T2-2) | todo2.md | S | なし | -| 11 | 💎 Tier 3 | ADR-032 PR-β: 実装 (enabled=false default) | todo2.md | 中-高 | 6, 7, 9 | -| 12 | 💎 Tier 3 | ADR-032 PR-γ: enablement (1 行 flip) | todo2.md | XS | 順位 7 dogfood + 順位 11 | -| 13 | 💎 Tier 3 | ADR-032 PR-δ: dogfood + メトリクス検証 | todo2.md | (運用) | 順位 12 | -| 14 | 💎 Tier 3 | 日付ベース見出しアンカー更新ルールのグローバル明文化 (PR #85 T3-1) | todo2.md | XS | なし | -| 15 | 💎 Tier 3 | jj conflict リカバリ手順のグローバル明文化 (PR #85 T3-2) | todo2.md | XS | なし | -| 16 | 💎 Tier 3 | `__` prefix scratch file 規約のグローバル明文化 (PR #85 T3-3) | todo2.md | XS | なし | -| 17 | 💎 Tier 3 | **post-pr-monitor polling 禁止のグローバル明文化 (PR #86 T3-2)** | todo2.md | XS | なし | -| 18 | 💎 Tier 3 | **todo.md 採番管理の簡素化 ADR 起案 (PR #86 T3-3)** | todo2.md | S | なし | -| 19 | 🧹 Tier 4 | ADR-030 Phase E/F: 旧機構廃止 + dogfood | todo.md | 中 | なし (cleanup) | -| 20 | ⏳ Tier 5 | (追って) ADR-030 の takt-test-vc 反映 | todo.md | 中 | 順位 19 Phase F | - -**戦略**: Tier 1 (2〜6) を 1〜2 セッションで片付け → Tier 2 (7〜10) で D の前提を埋める → Tier 3 (11〜18) で D を land + ドキュメント整備。Tier 4-5 (19〜20) は cleanup / 外部展開で daily efficiency への直接効果は小さい。 - -**順位 8 (reviewer facet 改善) は全 PR の review 精度を即時向上させ、Tier 2 内で順位 7/9/10 と並列実施可能**。 -**順位 14-17 (T3 グローバルルール 4 件) は `~/.claude/` 配下への XS 追記なので並列実施推奨**。 -**順位 18 (採番管理簡素化 ADR) は本 table の cross-reference 維持コストを構造的に解消するメタタスク**。 +| 1 | 🚀 Tier 1 | push 前 untracked `__*` ファイル警告 hook (PR #85 T1-4) | todo2.md | Small | なし (PR #85 直接対策) | +| 2 | 🚀 Tier 1 | `cli-push-runner` jj bookmark 未設定 early-exit (PR #85 T1-3) | todo2.md | S | なし | +| 3 | 🚀 Tier 1 | PowerShell swallowed error custom_lint_rule (PR #85 T1-2) | todo2.md | XS | なし (ADR-007 拡張) | +| 4 | 🚀 Tier 1 | **Polling anti-pattern 検出ルール (PR #86 T1-1)** | todo2.md | XS | なし (PR #86 直接対策) | +| 5 | 🚀 Tier 1 | **Stop hook の `pnpm lint:md` 統合 (PR #88 T1-1)** | todo3.md | XS | なし (PR #88 直接対策、順位 1 完了済の gap closure) | +| 6 | 🚀 Tier 1 | **AI 生成一時スクリプト pattern の pre-push 検出 (PR #88 T1-2)** | todo3.md | Small | 順位 1 と関連 (要擦り合わせ) | +| 7 | 🚀 Tier 1 | ADR-032 PR-pre: GitHub Branch Protection 整備 | todo2.md | 設定のみ | なし (依存タスクは完了済) | +| 8 | 🔧 Tier 2 | 週次レビュー (ADR-031) Phase B 実装 | todo.md | 中-高 | なし (順位 15 の compensating check 前提) | +| 9 | 🔧 Tier 2 | reviewer facet 改善 (review-simplicity / review-security の DRY/YAGNI/security 軸明文化) | todo2.md | S | なし | +| 10 | 🔧 Tier 2 | ADR-032 PR-broken-link: broken-link-check + 内部アンカー検査 統合 | todo2.md | Small-中 | なし (clean baseline 確立済) | +| 11 | 🔧 Tier 2 | `cli-pr-monitor` プロセス正常終了の integration test (PR #85 T2-2) | todo2.md | S | なし | +| 12 | 🔧 Tier 2 | **`cli-pr-monitor` ポーリング延長 + 重複起動ロック (PR #88 T2-4)** ★ rate-limit critical | todo3.md | Medium | なし (順位 4 と補完) | +| 13 | 🔧 Tier 2 | **`vitest` を devDependencies に固定 (PR #88 T2-3)** | todo3.md | Small | なし | +| 14 | 🔧 Tier 2 | **`pnpm create-pr` 必須引数ヘルプ改善 (PR #88 T2-5)** | todo3.md | Small | なし | +| 15 | 💎 Tier 3 | ADR-032 PR-β: 実装 (enabled=false default) | todo2.md | 中-高 | 7, 8, 10 | +| 16 | 💎 Tier 3 | ADR-032 PR-γ: enablement (1 行 flip) | todo2.md | XS | 順位 8 dogfood + 順位 15 | +| 17 | 💎 Tier 3 | ADR-032 PR-δ: dogfood + メトリクス検証 | todo2.md | (運用) | 順位 16 | +| 18 | 💎 Tier 3 | 日付ベース見出しアンカー更新ルールのグローバル明文化 (PR #85 T3-1) | todo2.md | XS | なし | +| 19 | 💎 Tier 3 | jj conflict リカバリ手順のグローバル明文化 (PR #85 T3-2) | todo2.md | XS | なし | +| 20 | 💎 Tier 3 | `__` prefix scratch file 規約のグローバル明文化 (PR #85 T3-3) | todo2.md | XS | なし | +| 21 | 💎 Tier 3 | **post-pr-monitor polling 禁止のグローバル明文化 (PR #86 T3-2)** | todo2.md | XS | なし | +| 22 | 💎 Tier 3 | **todo.md 採番管理の簡素化 ADR 起案 (PR #86 T3-3)** | todo2.md | S | なし | +| 23 | 🧹 Tier 4 | ADR-030 Phase E/F: 旧機構廃止 + dogfood | todo.md | 中 | なし (cleanup) | +| 24 | ⏳ Tier 5 | (追って) ADR-030 の takt-test-vc 反映 | todo.md | 中 | 順位 23 Phase F | + +**戦略**: Tier 1 (1〜7) を 2〜3 セッションで片付け → Tier 2 (8〜14) で ADR-032 の前提を埋めつつ rate-limit 改善 (順位 12) → Tier 3 (15〜22) で ADR-032 を land + ドキュメント整備。Tier 4-5 (23〜24) は cleanup / 外部展開で daily efficiency への直接効果は小さい。 + +**順位 9 (reviewer facet 改善) は全 PR の review 精度を即時向上させ、Tier 2 内で順位 8/10/11 と並列実施可能**。 +**順位 12 (cli-pr-monitor polling 改善) は rate-limit 直撃のため Tier 2 内で最優先候補**。順位 4 (Polling anti-pattern 検出) と補完関係。 +**順位 5 (Stop hook の lint:md 統合) は旧順位 1 (Markdown linter hook 統合、PR #88 で merged) の gap closure**。**順位 6 (AI 生成一時スクリプト pattern 検出) は現順位 1 (push 前 untracked `__*` hook、PR #85 T1-4) と関連** (実装前に擦り合わせ要)。 +**順位 18-21 (T3 グローバルルール 4 件) は `~/.claude/` 配下への XS 追記なので並列実施推奨**。 +**順位 22 (採番管理簡素化 ADR) は本 table の cross-reference 維持コストを構造的に解消するメタタスク**。 --- @@ -52,7 +61,7 @@ > > **本タスクの位置づけ**: ADR-029 を partial supersede する新 ADR-030 を起案し、takt 経由の決定論的フィードバック機構へ移行する。本タスク完了で post-merge-feedback skill / pending file / Stop hook (hooks-stop-feedback-dispatch) はすべて廃止される。 > -> **実行優先度**: 🧹 **Tier 4 (順位 19/20)** — Phase A〜D は merged 済で workflow は機能。残る Phase E (旧機構廃止) / Phase F (dogfood) は cleanup 中心で daily efficiency への直接効果は小。Tier 1〜3 完了後の片付けタイミングで実施推奨。 +> **実行優先度**: 🧹 **Tier 4 (順位 23/24)** — Phase A〜D は merged 済で workflow は機能。残る Phase E (旧機構廃止) / Phase F (dogfood) は cleanup 中心で daily efficiency への直接効果は小。Tier 1〜3 完了後の片付けタイミングで実施推奨。 #### 背景: ADR-029 の構造的欠陥 (PR #74 dogfood で実証) @@ -234,7 +243,7 @@ dogfood では PR #74 マージ後、pending file が `dispatched` で stuck し > **参照**: 上位タスク「マージ後フィードバック機構の決定論化」の Phase F 完了が前提。元の 1-F (ADR-014 本採用化 + takt-test-vc 反映) は ADR-014 が ADR-030 で Superseded されるため scope 変更。 > -> **実行優先度**: ⏳ **Tier 5 (順位 20/20)** — 派生プロジェクトへの展開で本リポジトリへの効果はゼロ。順位 19 (ADR-030 Phase F) 完了後の任意タスク。 +> **実行優先度**: ⏳ **Tier 5 (順位 24/24)** — 派生プロジェクトへの展開で本リポジトリへの効果はゼロ。順位 23 (ADR-030 Phase F) 完了後の任意タスク。 - **やろうとしたこと**: 本プロジェクトで ADR-030 機構が安定稼働 (Phase F dogfood 完了) した後、takt-test-vc へ機構ごとバックポート - **現在地**: 上位タスクの Phase F 完了待ち @@ -248,7 +257,7 @@ dogfood では PR #74 マージ後、pending file が `dispatched` で stuck し > > **計画ファイル参照**: `~/.claude/plans/1-docs-todo-md-askuserquestion-validated-orbit.md` (本タスク策定時の plan、新セッションでも同じ判断を再現可能) > -> **実行優先度**: 🔧 **Tier 2 (順位 7/20)** — ADR-032 (docs-only fast path) の compensating check 前提。順位 11 (ADR-032 PR-β) 着手前に Phase B dogfood 1 回成功が必要。architecture facet の rubric に docs 整合性観点 (ADR/symbol drift, terminology drift, docs-code 整合, docs 重複/不整合) を含めること。 +> **実行優先度**: 🔧 **Tier 2 (順位 8/24)** — ADR-032 (docs-only fast path) の compensating check 前提。順位 15 (ADR-032 PR-β) 着手前に Phase B dogfood 1 回成功が必要。architecture facet の rubric に docs 整合性観点 (ADR/symbol drift, terminology drift, docs-code 整合, docs 重複/不整合) を含めること。 #### 背景: 既存レビューの空白 diff --git a/docs/todo2.md b/docs/todo2.md index 7009b22..e6f8e90 100644 --- a/docs/todo2.md +++ b/docs/todo2.md @@ -4,7 +4,7 @@ > > **本ファイルの位置付け**: docs/todo.md がファイルサイズ約 40KB に達したため、Claude Code の読み取り安定性 (50KB 超で不安定化) を考慮して新規エントリは本ファイルに記録する。todo.md の既存エントリは引き続き有効、相互に独立。新セッションでは両方を確認すること。 > -> **推奨実行順序**: 全タスク横断のサマリーは [docs/todo.md](todo.md#推奨実行順序サマリー-2026-04-27-更新) を参照。本ファイルに記録する ADR-032 は sub-phase ごとに Tier が分散するため、各 Phase の冒頭に個別の優先度を記載。 +> **推奨実行順序**: 全タスク横断のサマリーは [docs/todo.md](todo.md#recommended-order-summary) を参照。本ファイルに記録する ADR-032 は sub-phase ごとに Tier が分散するため、各 Phase の冒頭に個別の優先度を記載。 --- @@ -19,12 +19,12 @@ > **計画ファイル参照**: `~/.claude/plans/1-docs-todo-md-askuserquestion-validated-orbit.md` (本タスク策定時の plan、新セッションでも同じ判断を再現可能) > > **実行優先度**: タスク全体は **🚀 Tier 1 〜 💎 Tier 3 に分散** (Phase ごとに優先度が異なる、2026-04-28 採番更新)。 -> - Phase pre (branch protection): **Tier 1 (順位 6/20)** — 設定のみ、順位 1 と並列可 -> - Phase α: 既存 todo.md「週次レビュー (ADR-031)」エントリ参照 — **Tier 2 (順位 7/20)** -> - Phase broken-link: **Tier 2 (順位 9/20)** — 順位 1 (markdownlint) の clean baseline 後が望ましい -> - Phase β (実装、enabled=false): **Tier 3 (順位 11/20)** — 全前提揃ってから -> - Phase γ (enablement): **Tier 3 (順位 12/20)** — 順位 7 dogfood 後の 1 行 flip -> - Phase δ (dogfood): **Tier 3 (順位 13/20)** — 実 docs PR で検証 +> - Phase pre (branch protection): **Tier 1 (順位 7/24)** — 設定のみ、依存タスクは完了済 +> - Phase α: 既存 todo.md「週次レビュー (ADR-031)」エントリ参照 — **Tier 2 (順位 8/24)** +> - Phase broken-link: **Tier 2 (順位 10/24)** — Markdown linter (PR #88 で merged) の clean baseline 確立済のため即着手可 +> - Phase β (実装、enabled=false): **Tier 3 (順位 15/24)** — 全前提揃ってから +> - Phase γ (enablement): **Tier 3 (順位 16/24)** — 順位 8 dogfood 後の 1 行 flip +> - Phase δ (dogfood): **Tier 3 (順位 17/24)** — 実 docs PR で検証 > > **最大 payoff**: Phase γ enable 後、docs PR 所要時間 ~15min → ~30sec (30 倍速)。daily efficiency への貢献は本リポジトリ随一だが、**前提依存が多いため近道はない**。 @@ -370,7 +370,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/82.md` の Tier 3 #2-4 findings (3 件を統合) > -> **実行優先度**: 🔧 **Tier 2 (順位 8/20)** — 全 PR の review 精度を即時向上、false positive iteration の削減効果。Tier 2 内で順位 7 (週次レビュー Phase B) / 順位 9 (ADR-032 PR-broken-link) / 順位 10 (cli-pr-monitor termination test) と並列実施可能。Effort S × 3 = ~S。 +> **実行優先度**: 🔧 **Tier 2 (順位 9/24)** — 全 PR の review 精度を即時向上、false positive iteration の削減効果。Tier 2 内で順位 8 (週次レビュー Phase B) / 順位 10 (ADR-032 PR-broken-link) / 順位 11 (cli-pr-monitor termination test) と並列実施可能。Effort S × 3 = ~S。 #### 背景 @@ -420,7 +420,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 1 #4 > -> **実行優先度**: 🚀 **Tier 1 (順位 2/20)** — Small 工数、直近インシデントの直接対策。同種事故 (PR scope 外ファイル混入) の再発防止で、混入時の追加コスト (force-push + 再 review) を回避。 +> **実行優先度**: 🚀 **Tier 1 (順位 1/24)** — Small 工数、直近インシデントの直接対策。同種事故 (PR scope 外ファイル混入) の再発防止で、混入時の追加コスト (force-push + 再 review) を回避。 #### 設計決定 (案) @@ -454,7 +454,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 1 #3 > -> **実行優先度**: 🚀 **Tier 1 (順位 3/20)** — S 工数、daily efficiency への直接効果 (失敗 push 1 回あたり 2-3 分 + takt review token 消費を節約)。 +> **実行優先度**: 🚀 **Tier 1 (順位 2/24)** — S 工数、daily efficiency への直接効果 (失敗 push 1 回あたり 2-3 分 + takt review token 消費を節約)。 #### 設計決定 (案) @@ -487,7 +487,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 1 #2 > -> **実行優先度**: 🚀 **Tier 1 (順位 4/20)** — XS 工数、ADR-007 既存基盤の拡張のみ。発生頻度は低いが該当時の影響大 (debug 困難化)。 +> **実行優先度**: 🚀 **Tier 1 (順位 3/24)** — XS 工数、ADR-007 既存基盤の拡張のみ。発生頻度は低いが該当時の影響大 (debug 困難化)。 #### 設計決定 (案) @@ -522,7 +522,7 @@ Phase 2 (任意、段階的緩和) > > **参照**: `.claude/feedback-reports/85.md` Tier 2 #2 > -> **実行優先度**: 🔧 **Tier 2 (順位 10/20)** — S 工数、回帰防止が主目的。発生頻度は低いが UX への直接影響あり (手動 kill 必要)。 +> **実行優先度**: 🔧 **Tier 2 (順位 11/24)** — S 工数、回帰防止が主目的。発生頻度は低いが UX への直接影響あり (手動 kill 必要)。 #### 設計決定 (案) @@ -555,7 +555,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/85.md` Tier 3 #1 > -> **実行優先度**: 💎 **Tier 3 (順位 14/20)** — XS 工数、グローバルなので全プロジェクト即時効果。順位 9 (ADR-032 PR-broken-link) の anchor link CI チェックと補完関係 (CI = 自動検出、本ルール = 編集時の予防)。 +> **実行優先度**: 💎 **Tier 3 (順位 18/24)** — XS 工数、グローバルなので全プロジェクト即時効果。順位 10 (ADR-032 PR-broken-link) の anchor link CI チェックと補完関係 (CI = 自動検出、本ルール = 編集時の予防)。 #### 設計決定 (案) @@ -587,7 +587,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/85.md` Tier 3 #2 > -> **実行優先度**: 💎 **Tier 3 (順位 15/20)** — XS 工数、知見の恒久化のみ。発生頻度は低いが、発生時の試行錯誤コストを削減。 +> **実行優先度**: 💎 **Tier 3 (順位 19/24)** — XS 工数、知見の恒久化のみ。発生頻度は低いが、発生時の試行錯誤コストを削減。 #### 設計決定 (案) @@ -622,7 +622,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/85.md` Tier 3 #3 > -> **実行優先度**: 💎 **Tier 3 (順位 16/20)** — XS 工数、規約浸透のみ。Tier 1 #1 (`.gitignore` 追加、PR #85 で実装済) の補完。 +> **実行優先度**: 💎 **Tier 3 (順位 20/24)** — XS 工数、規約浸透のみ。Tier 1 #1 (`.gitignore` 追加、PR #85 で実装済) の補完。 #### 設計決定 (案) @@ -658,7 +658,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/86.md` Tier 1 #1 > -> **実行優先度**: 🚀 **Tier 1 (順位 5/20)** — XS 工数、daily efficiency への直接効果が極めて大 (1 セッションで rate limit 40% 浪費を防止)。順位 17 (post-pr-monitor polling 禁止 rule) と補完関係 (本タスクは決定論的防止、順位 17 はガイドライン)。 +> **実行優先度**: 🚀 **Tier 1 (順位 4/24)** — XS 工数、daily efficiency への直接効果が極めて大 (1 セッションで rate limit 40% 浪費を防止)。順位 21 (post-pr-monitor polling 禁止 rule) と補完関係 (本タスクは決定論的防止、順位 21 はガイドライン)。 #### 設計決定 (案) @@ -696,7 +696,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/86.md` Tier 3 #2 > -> **実行優先度**: 💎 **Tier 3 (順位 17/20)** — XS 工数、ルール明文化のみ。順位 5 (polling anti-pattern 検出) と補完関係 (本ルールはガイドライン、順位 5 は決定論的防止)。 +> **実行優先度**: 💎 **Tier 3 (順位 21/24)** — XS 工数、ルール明文化のみ。順位 4 (polling anti-pattern 検出) と補完関係 (本ルールはガイドライン、順位 4 は決定論的防止)。 #### 設計決定 (案) @@ -728,7 +728,7 @@ termination 残留の root cause が未調査 (タスク開始時に最初に調 > > **参照**: `.claude/feedback-reports/86.md` Tier 3 #3 > -> **実行優先度**: 💎 **Tier 3 (順位 18/20)** — S 工数、構造的負債解消。タスク数 20 超に達した現時点でリターン大 (renumber 作業時の Edit 数が桁で減る)。 +> **実行優先度**: 💎 **Tier 3 (順位 22/24)** — S 工数、構造的負債解消。タスク数 24 に達した現時点でリターン大 (renumber 作業時の Edit 数が桁で減る)。 #### 設計決定 (案) diff --git a/docs/todo3.md b/docs/todo3.md new file mode 100644 index 0000000..c651a95 --- /dev/null +++ b/docs/todo3.md @@ -0,0 +1,244 @@ +# TODO (Part 3) + +> **運用ルール** ([docs/todo.md](todo.md) と同一): 各タスクには **やろうとしたこと / 現在地 / 詰まっている箇所** を必ず書く。完了タスクは ADR か仕組みに反映後、このファイルから削除する。過去の経緯は git log で追跡可能。 +> +> **本ファイルの位置付け**: docs/todo2.md がファイルサイズ約 50KB に到達したため、Claude Code の読み取り安定性 (50KB 超で不安定化) を考慮して新規エントリは本ファイルに記録する。todo.md / todo2.md の既存エントリは引き続き有効、相互に独立。新セッションでは三つすべてを確認すること。 +> +> **推奨実行順序**: 全タスク横断のサマリーは [docs/todo.md](todo.md#recommended-order-summary) を参照。 + +--- + +## 現在進行中 + +### Stop hook の `pnpm lint:md` 統合 (PR #88 T1-1) + +> **動機**: PR #88 で `pnpm lint:md` script を導入したが `[[stop_quality.steps]]` への登録が漏れていた。PostToolUse hook は Write/Edit ツール経由の編集にのみ発火するため、jj の auto-snapshot・他 hook 生成・bulk import 等で `.md` が変更された場合に markdownlint 違反が Stop まで未検出になる。`pnpm lint` (TS oxlint) は Stop gate 登録済みだが `pnpm lint:md` は本 PR で追加されたばかりにもかかわらず未登録のまま。 +> +> **本タスクの位置づけ**: PR #88 で merged 済の Markdown linter hook 統合 (旧順位 1、現在 master) の補完作業。Stop gate は最後の安全網として PostToolUse 経由しない経路 (auto-snapshot など) もカバーする必要がある。 +> +> **参照**: `.claude/feedback-reports/88.md` の Tier 1 #1 finding +> +> **実行優先度**: 🚀 **Tier 1** — 工数 XS (1 行追記)、daily efficiency への即効性極大。Markdown linter 統合の gap closure として最優先で実施推奨。 + +#### 背景 + +- PR #88 で `pnpm lint:md` script を `package.json` に追加 +- `[post_tool_linter] extensions = ["md"]` パイプラインで Write/Edit 経由の編集はカバー済 +- ただし `[[stop_quality.steps]]` への登録は漏れた → PostToolUse 経路を通らない `.md` 変更が無検査になる +- post-merge-feedback (PR #88) が PR diff 解析で本 gap を独立検出 + +#### 設計決定 (案) + +- `.claude/hooks-config.toml` の `[stop_quality.steps]` セクションに 1 行追加: + +```toml +[[stop_quality.steps]] +name = "lint:md" +cmd = "pnpm lint:md" +``` + +- 既存の `pnpm lint` / `pnpm test` / `pnpm test:e2e` / `pnpm build` と並ぶ Stop gate ステップとして登録 +- 派生プロジェクト (techbook-ledger, auto-review-fix-vc) には Markdown linter 統合本体の deploy と同タイミングで反映 + +#### 作業計画 + +- [ ] `.claude/hooks-config.toml` に `[[stop_quality.steps]]` 追加 +- [ ] dogfood: 任意の `.md` を編集後、Stop hook で `pnpm lint:md` が走ることを確認 +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- Stop hook で `pnpm lint:md` が他の lint/test/build と並列に実行され、違反があれば Stop が FAIL +- PostToolUse 経路を通らない `.md` 変更でも Stop gate で違反検出される + +#### 詰まっている箇所 + +なし (Effort XS、追記のみ) + +--- + +### AI 生成一時スクリプト pattern の pre-push 検出 (PR #88 T1-2) + +> **動機**: PR #85 で Claude が transcript 確認用に作成した `__parse_transcripts.ps1` が `.gitignore` 漏れにより jj auto-snapshot 経由で commit に意図せず混入。CodeRabbit が発見し除去作業が必要となった。同パターン (`__*.ps1` / `_tmp_*.ps1` / `__*.py` / `_tmp_*.py` 等の AI 生成一時スクリプト) を pre-push で機械的に検出し再発を防止する。post-merge-feedback (PR #88) が同事象を transcript から再検出。 +> +> **本タスクの位置づけ**: **既存の 順位 1 (push 前 untracked `__*` ファイル警告 hook、PR #85 T1-4) と同一インシデントへの異なるアプローチによる補完**。順位 1 = working-tree の untracked file 検出 (hook 機構) / 本タスク = pre-push 時の lint ベース検出 (AI 命名 pattern 全体)。両機構を併用するか一方に統合するかは実装時に判断。 +> +> **参照**: `.claude/feedback-reports/88.md` の Tier 1 #2 finding +> +> **実行優先度**: 🚀 **Tier 1** — 工数 Small。daily efficiency への影響中 (再発リスクは低いが ADR-007 拡張で確実な再発防止)。**実装前に既存の順位 1 (PR #85 T1-4) と擦り合わせて重複か補完かを判定すること**。 + +#### 背景 + +- PR #85 で `__parse_transcripts.ps1` が混入 (Claude が transcript 解析用に作成、`.gitignore` 漏れ) +- `.gitignore` への `__*` 追加で当面の再発は防止済 +- ただし `_tmp_*` 等の他 prefix や、`.gitignore` の管理漏れ自体への保険として機械的検出が望ましい +- post-merge-feedback (PR #88) が PR #85 の transcript を解析し、本提案を独立に再生成 → 提案の妥当性が複数 source で corroborate された + +#### 設計決定 (案) + +- 候補機構 1: ADR-007 の custom_lint_rule (`.claude/custom-lint-rules.toml`) に AI 生成一時スクリプト pattern を追加 +- 候補機構 2: pre-push hook で `jj diff --name-only @` で staged file のうち `__*` / `_tmp_*` パターンに合致するものを検出 +- 候補機構 3: 既存の順位 1 (PR #85 T1-4) の hook を拡張し pattern を増やす +- 検出パターン (初稿): `__*.ps1`, `__*.py`, `_tmp_*.ps1`, `_tmp_*.py`, `__*.sh`, `__*.js`, `__*.ts` +- 警告メッセージ: 「AI 生成一時スクリプト pattern を検出: ``. `.gitignore` 漏れの可能性。意図的な commit なら override してください。」 + +#### 作業計画 + +- [ ] 既存の順位 1 (PR #85 T1-4「push 前 untracked `__*` ファイル警告 hook」) の実装状況を確認 +- [ ] 重複なら本タスクは順位 1 内へ統合 (pattern を拡張するだけ)、補完なら別実装 +- [ ] 機構決定後に `.claude/custom-lint-rules.toml` または既存 hook を拡張 +- [ ] dogfood: 試しに `__test.py` を作って commit 試行 → 警告が出ることを確認 +- [ ] 本 todo3.md エントリを削除 (順位 1 に統合した場合は順位 1 の description も更新) + +#### 完了基準 + +- AI 生成一時スクリプト pattern が pre-push で検出され警告が出る +- 既存の `__*` ファイル検出 hook と整合性が取れている (重複なし or 明示的補完) + +#### 詰まっている箇所 + +なし (Effort Small、ADR-007 既存パターンを拡張) + +--- + +### `vitest` を devDependencies に固定 (PR #88 T2-3) + +> **動機**: Stop hook の `pnpm test` → `npx vitest run` が `pnpm-lock.yaml` に vitest なしのため npx がネット DL を試みて偽陽性 FAIL する事象を観測。ネット環境・キャッシュ依存の不確実性を排除し、Stop gate を deterministic にする。 +> +> **本タスクの位置づけ**: PR #88 で markdownlint-cli2 を `--no-install` で安定化させたのと同じ思想。テスト実行が外部 DL なしで完結する状態を維持する。 +> +> **参照**: `.claude/feedback-reports/88.md` の Tier 2 #3 finding +> +> **実行優先度**: 🔧 **Tier 2** — 工数 Small。Stop gate の偽陽性 FAIL を排除する効果は中-高 (毎回の Stop で発生する潜在リスクの解消)。 + +#### 背景 + +- `package.json` の `"test": "npx vitest run"` は vitest がローカルにあれば走るが、なければ npx が DL を試みる +- ネット未接続環境やプロキシ環境で偽陽性 FAIL → 開発体験悪化 +- markdownlint-cli2 は PR #88 で `--no-install` を付けて DL を抑止、devDependencies で版固定済 → 同じパターンを vitest にも適用 + +#### 設計決定 (案) + +- 案 A: `vitest` を devDependencies に追加し `pnpm-lock.yaml` に固定。`pnpm test` script は変更不要 (`npx --no-install vitest run` とするか `vitest run` 直呼びにするかは実装時判断) +- 案 B: `pnpm test` script を `npx --no-install vitest run` に変更し、明示的にローカル参照を強制 +- 推奨: 案 A + script 側を `--no-install` 付きに変更 (二重防御) +- 既存テストが現行通り動作することを確認 (既存の vitest 設定は不変、依存固定のみ) + +#### 作業計画 + +- [ ] `vitest` の現行バージョン確認 (`npx vitest --version` 等) +- [ ] `pnpm add -D vitest` (またはインスタンス化済バージョンで固定) +- [ ] `package.json` の test script を `npx --no-install vitest run` に更新 +- [ ] `pnpm test` 動作確認 +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- `pnpm test` がローカルの vitest のみで動作 (ネット切断状態で実行可) +- Stop hook の偽陽性 FAIL が発生しなくなる +- `pnpm-lock.yaml` に vitest が固定されている + +#### 詰まっている箇所 + +なし (Effort Small、devDep 追加 + script 修正のみ) + +--- + +### `cli-pr-monitor` ポーリング間隔延長 + 重複起動防止ロック (PR #88 T2-4) + +> **動機**: PR #88 作成後の cli-pr-monitor 監視中に、Claude Code Max (5x) のレートリミットを 1 時間で 40% 消費する事象を観測。監視セッション重複起動による累積消費が推定原因。現在の `poll_interval_secs = 120` (2分) はセッション単独では問題ないが、複数セッションで監視が重複起動すると 1 分以下の頻度で polling が走り得る。 +> +> **本タスクの位置づけ**: **既存の 順位 4 (Polling anti-pattern 検出ルール、PR #86 T1-1) と補完**。順位 4 = Claude 側の polling 禁止 (preventive)、本タスク = cli-pr-monitor (tool 側) の polling 動作改善 (corrective)。両層で rate-limit を削減する。 +> +> **参照**: `.claude/feedback-reports/88.md` の Tier 2 #4 finding +> +> **実行優先度**: 🔧 **Tier 2** — 工数 Medium。**rate-limit 直撃のため daily efficiency への影響大**。Tier 2 内では最優先候補。実装前に重複起動の根本原因 (どこで複数セッションが立つか) を特定し、ロック方式を選定する必要あり。 + +#### 背景 + +- 観測: 1 セッション内で `pnpm push` → `pnpm create-pr` の流れで 2 度 cli-pr-monitor 系の処理が走った +- post-pr-review takt workflow は内部で provider (Claude API) を呼ぶため、polling 1 サイクルが重い +- `poll_interval_secs = 120` × 監視時間 (最大 600s) = 5 サイクル/セッション。複数セッション重複で更に増える +- 重複起動の原因候補: + - VSCode 上の複数 Claude Code セッションが各々 cli-pr-monitor を起動 + - daemon と --observe / --monitor-only の組み合わせが意図せず多重化 + - state file の lockless な読み書きで race + +#### 設計決定 (案) + +- 改善 1: poll_interval_secs を `120` → `180` または `240` に延長 (config 値変更のみ) +- 改善 2: 重複起動防止 file lock (`.claude/pr-monitor.lock` など、PID + start_time 記録) +- 改善 3: lock 検出時の挙動 — 既存セッションが alive なら skip (no-op exit)、stale なら lock 奪取 +- 既存設計 (ADR-018: cli-pr-monitor takt 移行) を尊重しつつ追加 +- pr-monitor-config.toml への設定追加で柔軟性確保 + +#### 作業計画 + +- [ ] 重複起動の根本原因を実測で確認 (transcript から複数 cli-pr-monitor 起動を検出) +- [ ] file lock 機構の設計 (既存 jj 環境との互換性) +- [ ] `src/cli-pr-monitor/` の lock 取得・解放ロジック実装 +- [ ] poll_interval_secs の調整 (config 経由) +- [ ] dogfood: 複数セッションを意図的に立てて重複起動が抑制されることを確認 +- [ ] rate-limit 消費が改善前後で測定可能なら比較 +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- 重複起動時に後続セッションが skip され、polling 並走が発生しない +- poll_interval_secs 延長で polling 総回数が減る +- レートリミット消費が体感で改善される (測定可能なら定量化) + +#### 詰まっている箇所 + +なし (Effort Medium、根本原因の調査が必要だが進路は明確) + +--- + +### `pnpm create-pr` 必須引数未指定時のヘルプ改善 (PR #88 T2-5) + +> **動機**: 引数なしで `pnpm create-pr` を実行すると `gh pr create` が `must provide --title and --body (or --fill or fill-first or --fillverbose)` エラーのみ出力し、使用例が示されない。今回 PR 作成時に手動ワークアラウンド (`pnpm prepare-pr-body` で `.tmp-pr-body.md` 生成 → `pnpm create-pr -- --title "..." --body-file .tmp-pr-body.md`) が必要になった。`gh` のエラーをそのまま流す現設計だと、Claude や人間が次の手を察するのに余計な往復が発生する。 +> +> **本タスクの位置づけ**: cli-pr-monitor の UX 改善。現実装は `gh pr create` への薄い wrapper だが、必須引数チェックを wrapper 側で実施することで使用例付きエラーを返せる。 +> +> **参照**: `.claude/feedback-reports/88.md` の Tier 2 #5 finding +> +> **実行優先度**: 🔧 **Tier 2** — 工数 Small。daily efficiency への影響中 (PR 作成は頻繁ではないが、エラー時の摩擦が高い)。 + +#### 背景 + +- 現実装: `cli-pr-monitor.exe` (PR 作成モード) は受け取った args をそのまま `gh pr create` に forwarding +- `gh` のエラーは英語かつ汎用的。プロジェクト固有の推奨 (prepare-pr-body スクリプトを使う等) は反映されない +- Claude / 人間の双方が「`pnpm prepare-pr-body` を先に呼ぶ」運用を覚える必要がある + +#### 設計決定 (案) + +- cli-pr-monitor の PR 作成モード入口で `--title` / `--body` / `--body-file` / `--fill*` 系のいずれかが指定されているかチェック +- 未指定なら使用例付きエラーを stderr に出力して非 0 で exit: + +```text +Error: PR title and body are required. +Usage: + pnpm create-pr -- --title "feat: ..." --body-file .tmp-pr-body.md + pnpm create-pr -- --title "feat: ..." --fill-verbose +Hint: + Run `pnpm prepare-pr-body` first to generate `.tmp-pr-body.md` from stdin. +``` + +- gh の実行は引数チェック後にのみ進む + +#### 作業計画 + +- [ ] cli-pr-monitor の PR 作成モード入口で arg validation 追加 +- [ ] エラーメッセージ作成 (上記の使用例ベース) +- [ ] dogfood: 引数なしで `pnpm create-pr` 実行 → 改善されたエラーが出ることを確認 +- [ ] 既存の正常系 (--title --body-file 指定時) が変わらず動作することを確認 +- [ ] 本 todo3.md エントリを削除 + +#### 完了基準 + +- 引数なし実行でプロジェクト固有の使用例 + Hint がエラーに含まれる +- `--title` + `--body-file` または `--fill*` 指定時は従来通り PR 作成が走る + +#### 詰まっている箇所 + +なし (Effort Small、cli-pr-monitor 入口の arg parser 拡張のみ)