diff --git a/docs/todo.md b/docs/todo.md index 34217fa..878311e 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -2,14 +2,15 @@ > **運用ルール**: 各タスクには **やろうとしたこと / 現在地 / 詰まっている箇所** を必ず書く。完了タスクは ADR か仕組みに反映後、このファイルから削除する。過去の経緯は git log で追跡可能。 > -> **本ファイル + [docs/todo2.md](todo2.md) + [docs/todo3.md](todo3.md) + [docs/todo4.md](todo4.md) + [docs/todo5.md](todo5.md) の使い分け** (PR #83 T3-2 で恒久化、2026-04-28 強化、PR #88 で todo3.md 追加、PR #96 セッションで todo4.md 追加、PR #101 セッションで todo5.md 追加): -> - **docs/todo.md**: 既存タスクの編集・完了削除と推奨実行順序サマリー table の管理専用。新規タスクの**詳細エントリ**は追加しない (~50KB 閾値内に維持し Claude Code 読み取り安定性を確保)。table への新規行追加は可 (詳細エントリは現行の追加先ファイル = docs/todo5.md に記録) +> **本ファイル + [docs/todo2.md](todo2.md) + [docs/todo3.md](todo3.md) + [docs/todo4.md](todo4.md) + [docs/todo5.md](todo5.md) + [docs/todo6.md](todo6.md) の使い分け** (PR #83 T3-2 で恒久化、2026-04-28 強化、PR #88 で todo3.md 追加、PR #96 セッションで todo4.md 追加、PR #101 セッションで todo5.md 追加、PR #123 セッションで todo6.md 追加): +> - **docs/todo.md**: 既存タスクの編集・完了削除と推奨実行順序サマリー table の管理専用。新規タスクの**詳細エントリ**は追加しない (~50KB 閾値内に維持し Claude Code 読み取り安定性を確保)。table への新規行追加は可 (詳細エントリは現行の追加先ファイル = docs/todo6.md に記録) > - **docs/todo2.md**: 既存タスクの編集・完了削除専用。**新規タスクは追加しない** (50KB に到達したため、PR #88 以降の新規エントリは todo3.md へ) > - **docs/todo3.md**: 既存タスクの編集・完了削除専用。**新規タスクは追加しない** (50KB に到達したため、PR #96 セッション以降の新規エントリは todo4.md へ) > - **docs/todo4.md**: 既存タスクの編集・完了削除専用。**新規タスクは追加しない** (50KB に到達したため、PR #101 セッション以降の新規エントリは todo5.md へ) -> - **docs/todo5.md**: 新規タスクの追加先。50KB に到達するまでは本ファイルへ追加 -> - 例外: 既存 todo.md / todo2.md / todo3.md / todo4.md タスクと **同一ファイル / 同一コンポーネント** を編集する密結合タスクは該当ファイルに追加可 (例: `~/.claude/rules/common/git-workflow.md` 配下のグローバルルール群) -> - **新セッションでは五つすべてを確認すること** +> - **docs/todo5.md**: 既存タスクの編集・完了削除専用。**新規タスクは追加しない** (50KB を超過したため、PR #123 セッション以降の新規エントリは todo6.md へ) +> - **docs/todo6.md**: 新規タスクの追加先。50KB に到達するまでは本ファイルへ追加 +> - 例外: 既存 todo.md / todo2.md / todo3.md / todo4.md / todo5.md タスクと **同一ファイル / 同一コンポーネント** を編集する密結合タスクは該当ファイルに追加可 (例: `~/.claude/rules/common/git-workflow.md` 配下のグローバルルール群) +> - **新セッションでは六つすべてを確認すること** --- @@ -78,6 +79,8 @@ | 86 | 🔧 Tier 2 | **cli-pr-monitor: state transition test の網羅追加 (順位 85 の回帰テスト) (PR #121 T2-4 採用) ★ Bundle g** | todo5.md | S | 順位 85 と同 PR (Bundle g、`(review_state, findings) → verdict` transition matrix を表形式テストで定義、`src/cli-pr-monitor/tests/` 新規作成) | | 87 | 💎 Tier 3 | **グローバルルール: Multi-PR chaining ベストプラクティスを codify (PR #121 T3-7 採用)** | todo5.md | XS | なし (PR #119→#120→#121 連鎖の dogfood 知見を `~/.claude/rules/common/git-workflow.md` に codify、独立並列実施可、順位 88 と同 PR で land 推奨) | | 88 | 💎 Tier 3 | **グローバルルール: edge case 観測頻度 3 = Tier 1 昇格基準を codify (PR #121 T3-8 採用)** | todo5.md | XS | なし (post-merge-feedback workflow の暗黙ルール明文化 + ユーザー方針との収束、`~/.claude/rules/common/development-workflow.md` 等、順位 87 と同 PR で land 推奨) | +| 89 | 💎 Tier 3 | **Experimental feature 標準パターン codify (config opt-in + kill-switch + bounded lifetime) (PR #123 T3-1 採用) ★ Bundle h** | todo6.md | XS | なし (ADR-031 / 036 / 038 等の試験運用 ADR で systemic に反復、CLAUDE.md or 別 ADR で codify、順位 90 と同 PR で land 推奨) | +| 90 | 💎 Tier 3 | **グローバルルール: ephemeral 大規模コンテンツの ADR 昇格 + config コメント lifecycle (PR #123 T3-2 採用) ★ Bundle h** | todo6.md | S | 順位 89 と同 PR (Bundle h、`~/.claude/rules/common/{docs-governance,coding-style}.md` の 2 ファイル更新、PR #94 / #110 / #111 系列の lifecycle 違反予防層を強化) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 @@ -101,6 +104,8 @@ **PR #101 (Bundle a Sub-PR 1) post-merge-feedback 反映 (2026-05-03)**: 9 件の finding を頻度評価 (過去 report 横断 + 同一 PR latent 件数) して **3 件を採用**。**順位 47 (`>` vs `>=` boundary lint)** は同一ファイル内 3 関数 (parse_listed_findings / parse_new_comments / parse_findings) で同 drift が実証済 = latent 高頻度。**順位 48 (関数長 oxlint)** は #96 / #101 で繰り返し言及 = explicit 高頻度。両者とも Bundle Z #B-α と同じ「決定論的防止層」哲学で、Bundle Z Phase 1 (Rust comment lint) の land 後に並列 deploy 可能。**順位 49 (error-path test infra)** は #99 / #101 で同型 silent fallback anti-pattern が再発、Bundle a Sub-PR 2 (順位 42 / 43 / 46) と **同一 PR で land** 推奨 (cli-pr-monitor の mock infrastructure を再利用、test 二重投資なし)。残り 6 件 (Tier 1 #1, #3, #5、Tier 2 #2、Tier 3 #1, #2) は session 1 回限りの low-frequency events として不採用。 +**Bundle h (PR #123 post-merge-feedback、experimental feature 標準パターン + ephemeral lifecycle 強化、2026-05-07)**: PR #123 (ADR-038 Phase 5: P-0 classifier opt-in + §10 ブランチ分離運用) merge 後の post-merge-feedback で 10 findings 中 **2 件採用** (Tier 3 #1, #2)。共通テーマは「ephemeral / experimental の運用パターンを global rule に codify」。**順位 89** (Tier 3 #1、Experimental feature 標準パターン = config opt-in + kill-switch + bounded lifetime) は ADR-031 / 036 / 038 で systemic 反復、本 PR が kill-switch 経路を PR body に明記した模範例から派生。**順位 90** (Tier 3 #2、ephemeral 大規模コンテンツの ADR 昇格基準 + config コメント lifecycle) は §10 (約 200 行) を ephemeral 計画書に追加した自己違反 + `pr-monitor-config.toml` のコメントが ephemeral 参照する cross-file reference lifecycle 違反の 2 観測から派生。**Sub-PR 分割不要** (Bundle h 全体で XS+S = 同 PR で land 推奨、両者とも `~/.claude/rules/common/*` および `CLAUDE.md` 系の global rule 追記で副作用最小、Adoption Risk None)。**却下** (4 件): T1 #3 (`enabled = true` 検出 lint、誤検出確実) / T1 #4 (見出し参照誤り検出 hook、NLP 必要) / T2 #2 (env var override、ROI 不成立) / T3 #4 (ADR-039 config hardcode policy、ADR-038 でカバー済)。**様子見** (4 件): T1 #1 (ephemeral 計画書参照 lint、命名規則 codify 先行) / T1 #2 (jq 括弧不均衡 lint、再発頻度低) / T2 #1 (classifier endpoint fallback integration test、takt test infra 調査依存) / T3 #3 (config コメント ADR 参照修正、XS opportunistic)。 + **Bundle g (PR #121 post-merge-feedback、monitor verdict logic + session pattern codify、2026-05-07)**: PR #121 (ADR-038 textual fix + Bundle f registration) の dogfood で post-pr-monitor の **verdict 評価ロジック** に edge case を再観測 (PR #119/#120/#121 で計 3 PR 連続)。**4 件採用** (Tier 1 #85、Tier 2 #86、Tier 3 #87/#88) で **2 軸対策**: (1) **monitor verdict guard 層** = 順位 85 (`review_state: not_found && findings: []` を pending 据置) + 順位 86 (state transition matrix の表形式テスト)、(2) **session pattern codify 層** = 順位 87 (Multi-PR chaining ベストプラクティス) + 順位 88 (edge case 3 観測 = Tier 1 昇格基準)。**Sub-PR 分割推奨**: g-1 (順位 85 + 86、Rust 実装 + test、Effort S+S、`src/cli-pr-monitor/tests/` 新規作成) / g-2 (順位 87 + 88、global rule 追記、Effort XS+XS、独立並列可)。**Bundle f との関係**: Bundle f は retry logic (rate-limit + 投稿エラー)、Bundle g は verdict logic (review_state 評価) で別軸。両者を land すると post-pr-monitor の robustness が retry/verdict/state 全方向で堅牢化。**頻度評価**: 順位 85 は 3 PR 観測済で Tier 1 妥当性確認済、順位 86 は 85 の dependent、順位 87/88 は global rule 追記で副作用最小なので並列実施可。 **Bundle f (PR #120 post-merge-feedback、cli-pr-monitor robustness、2026-05-07)**: PR #120 (ADR-038 Phase 5: cli-finding-classifier 統合) の dogfood で post-pr-monitor の wakeup state 遷移に複数の edge case を観測。**5 件採用** (Tier 1 #80/#81、Tier 3 #82、Tier 2 #83、Tier 3 #84) で **3 層対策**: (1) 実装層 = 順位 80 / 81 (rate-limit + CR 投稿エラーの auto-retry path 整理) + 順位 82 (ADR-018 設計明文化、同 PR 推奨)、(2) test 層 = 順位 83 (複合 guard の独立 variant test)、(3) ガイド層 = 順位 84 (code-review.md checklist 追記、独立並列可)。**Sub-PR 分割推奨**: f-1 (順位 80 + 81 + 82、cli-pr-monitor + ADR、Effort M+M+S、Bundle f コア) / f-2 (順位 83、test 拡充、Effort S、独立) / f-3 (順位 84、global rule、Effort XS、独立)。Bundle f はローカル LLM dogfood (ADR-038) の副産物として cli-pr-monitor の堅牢化を進める位置づけで、`docs/local-llm-offload-analysis.md` §7 (実装進捗ログ) に dogfood signal として記録。 diff --git a/docs/todo6.md b/docs/todo6.md new file mode 100644 index 0000000..a62753d --- /dev/null +++ b/docs/todo6.md @@ -0,0 +1,98 @@ +# TODO (Part 6) + +> **運用ルール** ([docs/todo.md](todo.md) と同一): 各タスクには **やろうとしたこと / 現在地 / 詰まっている箇所** を必ず書く。完了タスクは ADR か仕組みに反映後、このファイルから削除する。過去の経緯は git log で追跡可能。 +> +> **本ファイルの位置付け**: docs/todo5.md がファイルサイズ 50KB を超過したため、Claude Code の読み取り安定性 (50KB 超で不安定化) を考慮して新規エントリは本ファイルに記録する。todo.md / todo2.md / todo3.md / todo4.md / todo5.md の既存エントリは引き続き有効、相互に独立。新セッションでは六つすべてを確認すること。 +> +> **推奨実行順序**: 全タスク横断のサマリーは [docs/todo.md](todo.md#recommended-order-summary) を参照。 + +--- + +## 現在進行中 + +### Experimental feature の標準パターン codify (PR #123 T3-1 採用) ★ Bundle h + +> **動機**: PR #123 (ADR-038 Phase 5: P-0 classifier opt-in + §10 ブランチ分離運用) で採用された運用 pattern が、既存の試験運用 ADR (ADR-031 週次レビュー / ADR-036 Bundle Z / ADR-038 ローカル LLM 等) と systemic に反復するパターンであることを post-merge-feedback で観測。3 点セット (config opt-in + kill-switch + bounded lifetime) を標準化することで、今後の試験運用導入で再利用可能なテンプレートとなる。 +> +> **本タスクの位置づけ**: PR #123 post-merge-feedback Tier 3 #1 採用 (Frequency Medium / Effort XS / Adoption Risk None)。 +> +> **参照**: `.claude/feedback-reports/123.md` Tier 3 #1、ADR-031 (週次レビュー、試験運用)、ADR-036 (Bundle Z、試験運用)、ADR-038 (ローカル LLM、試験運用、本 PR の対象)、PR #123 PR body (kill-switch 経路の模範記述) +> +> **実行優先度**: 💎 **Tier 3** — Effort XS。Experimental Feature の 3 点セットを 1 箇所に codify。 + +#### 標準パターン (3 点セット) + +1. **Config opt-in**: `enabled = false` をデフォルトとし、明示有効化 (`enabled = true`) で機能発動。env var / config 値での切り替えを必ず提供 +2. **Kill-switch**: revert PR で `enabled = false` に戻す経路を PR body / ADR で明文化。crate 削除等の物理削除は dogfood 失敗判定後にまとめて実施 (本 PR の §10.6 C 採用 / 簡易版 / 完全版の階層化が参考) +3. **Bounded lifetime**: 試験期限を ADR 冒頭または計画書冒頭に明記 (例: 「6 ヶ月経過しても採用判断未達なら却下とみなす」)。retirement workflow (`docs-governance.md`) との接続を明示 + +#### 設計決定の余地 (実装時に検討) + +- **配置先**: + - **case 1**: project root の `CLAUDE.md` または global `~/.claude/CLAUDE.md` に「Experimental Features」section を直接追加 (post-merge-feedback の原案) + - **case 2**: 別 ADR (例: ADR-039 experimental-feature-standard-pattern) で codify + CLAUDE.md からリンク +- **memory `feedback_claude_md_link_only.md` ("CLAUDE.md はリンクのみ") との整合**: case 2 が memory rule に整合的。case 1 は本タスク承認で memory を override する形になるため、実装時に再確認推奨 + +#### 作業計画 + +- [ ] 配置先 (case 1 / case 2) を決定 +- [ ] 該当ファイルに Experimental Features の 3 点セットを XS で追記 +- [ ] (任意) 既存試験運用 ADR (ADR-031 / 036 / 038) から本 section へのリンク追加 +- [ ] 順位 90 と同 PR で land 推奨 (Bundle h コア、両者 XS+S) + +#### 完了基準 + +- 試験運用 ADR を新規策定する際の参考点が明文化される +- 既存試験運用 ADR (031/036/038) と新規 section の整合がとれる + +--- + +### グローバルルール: ephemeral 大規模コンテンツの ADR 昇格 + config コメント lifecycle (PR #123 T3-2 採用) ★ Bundle h + +> **動機**: PR #123 で `docs/local-llm-offload-analysis.md` (ephemeral 試験運用計画書) に §10 (約 200 行の governance / procedure content) を追加した行為は、systemic に発生しているパターン。本来は ADR 化を検討すべき「永続的に参照される運用ルール」が ephemeral 内に閉じ込められると、retirement 時に dead pointer / 知識ロスのリスクが顕在化する。同 PR で `pr-monitor-config.toml` のコメントが ephemeral 計画書 (`local-llm-offload-analysis.md §A-2 / §10`) を参照する cross-file reference lifecycle 違反も発生 (post-merge-feedback で T3 #3 として "🤔 様子見" verdict、本タスクとは別件)。両事例を予防するグローバルルールを 2 ファイルに追加する。 +> +> **本タスクの位置づけ**: PR #123 post-merge-feedback Tier 3 #2 採用 (Frequency Medium / Effort S / Adoption Risk None)。PR #94 / #110 / #111 で続いている ephemeral ↔ permanent lifecycle 違反シリーズの予防層を強化。 +> +> **参照**: `.claude/feedback-reports/123.md` Tier 3 #2、`~/.claude/rules/common/docs-governance.md` 既存 § Retirement Workflow、`~/.claude/rules/common/coding-style.md` § Cross-File Reference Lifecycle、PR #94 / #110 / #111 (関連事例)、PR #123 §10 大規模追加 (本ルールのトリガ事例) +> +> **実行優先度**: 💎 **Tier 3** — Effort S。global rule 2 ファイル更新。 + +#### 追加する 2 ルール + +##### (a) `~/.claude/rules/common/docs-governance.md`: Ephemeral 大規模コンテンツの ADR 昇格基準 + +Ephemeral artifact (`docs/*-analysis.md` 等の試験運用計画書) 内に **50 行超の governance / procedure content** を追加する場合、廃棄時に ADR (`docs/adr/adr-NNN-*.md`) への昇格を検討する判断基準を明文化: + +- **50 行超 + 「他箇所から参照される運用ルール」性格** → ADR 昇格を検討 +- **50 行超でも「1 つの試験運用 case の固有手順」** → ephemeral 内のままでよい +- **廃棄時の判断**: retirement workflow Step 1 (permanent value 移管) で ADR 昇格判断を必ず実施 + +書き先候補: 既存 § Retirement Workflow の Step 1 詳細化、または新規 § "Ephemeral 大規模コンテンツの ADR 昇格基準"。 + +##### (b) `~/.claude/rules/common/coding-style.md`: Config コメントの reference lifecycle + +設定ファイル (`*.toml` / `*.json` / `*.yaml`) のコメントから ephemeral 計画書 (`docs/*-analysis.md` / `docs/todo*.md` 等) へリンクするのは anti-pattern。理由: + +- 計画書は ephemeral lifecycle で削除される +- 設定ファイルは permanent lifecycle で長期保持される +- 永続 → ephemeral リンクは時間経過で dead pointer になる + +代替案: + +- **ADR 参照** (`# 詳細: docs/adr/adr-NNN-feature.md`) +- **インライン説明** (1-2 行で意図を直接記述) + +書き先候補: 既存 § Cross-File Reference Lifecycle の anti-pattern 例として「config コメント → ephemeral 計画書」を追加。PR #123 `pr-monitor-config.toml` の事例を inline cite。 + +#### 作業計画 + +- [ ] `~/.claude/rules/common/docs-governance.md` に (a) を追記 (Step 1 詳細化 or 新規 §) +- [ ] `~/.claude/rules/common/coding-style.md` § Cross-File Reference Lifecycle に (b) を追記 +- [ ] PR #123 `pr-monitor-config.toml` の `local-llm-offload-analysis.md` 参照を cite (anti-pattern 例) +- [ ] 順位 89 と同 PR で land 推奨 + +#### 完了基準 + +- ephemeral 計画書に大規模 content を追加する際の判断基準が明文化される +- config コメント → ephemeral 参照の anti-pattern が global rule に明記される +- 順位 89 と同 PR で land (Bundle h コア)