diff --git a/CLAUDE.md b/CLAUDE.md index d65566aa..bd820ef1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,7 @@ - [ADR-036: Bundle Z — 決定論層 + 制約付き修正 + 異常検知レビュアーの 3 層アーキテクチャ](docs/adr/adr-036-bundle-z-three-layer-review.md) *(試験運用)* - [ADR-037: takt fix-trust shortcut — convergence_verdict による Iter 3 短絡](docs/adr/adr-037-takt-fix-trust-shortcut.md) *(試験運用)* - [ADR-038: ローカル LLM による CodeRabbit findings classification](docs/adr/adr-038-local-llm-finding-classification.md) *(試験運用)* +- [ADR-039: Experimental feature 標準パターン (config opt-in + kill-switch + bounded lifetime)](docs/adr/adr-039-experimental-feature-standard-pattern.md) *(試験運用)* ## Build diff --git a/docs/adr/adr-031-weekly-review-pipeline.md b/docs/adr/adr-031-weekly-review-pipeline.md index 3b958e55..9ced6441 100644 --- a/docs/adr/adr-031-weekly-review-pipeline.md +++ b/docs/adr/adr-031-weekly-review-pipeline.md @@ -4,6 +4,8 @@ 試験運用 (2026-04-27) +> 本 ADR の運用パターンは [ADR-039 (試験運用標準パターン)](adr-039-experimental-feature-standard-pattern.md) で標準化された 3 点セット (config opt-in / kill-switch / bounded lifetime) の対象。本採用判定または却下時に ADR-039 の retirement workflow に従う。 + ## コンテキスト ### 問題: 既存 3 パイプラインの review scope の空白 diff --git a/docs/adr/adr-036-bundle-z-three-layer-review.md b/docs/adr/adr-036-bundle-z-three-layer-review.md index 3e31999a..98e98f8a 100644 --- a/docs/adr/adr-036-bundle-z-three-layer-review.md +++ b/docs/adr/adr-036-bundle-z-three-layer-review.md @@ -4,6 +4,8 @@ 試験運用 (2026-05-04) +> 本 ADR の運用パターンは [ADR-039 (試験運用標準パターン)](adr-039-experimental-feature-standard-pattern.md) で標準化された 3 点セット (config opt-in / kill-switch / bounded lifetime) の対象。本採用判定または却下時に ADR-039 の retirement workflow に従う。 + ## コンテキスト PR #97 セッション (2026-04-30 〜 2026-05-01) で `pre-push-review` パイプラインに **6 iter / 17-18 分の outlier** が 2 回観測された。総時間 36 分 (47.9 分中 75% を消費)。両 run の root cause 分析より、3 つの構造的根因が判明: diff --git a/docs/adr/adr-038-local-llm-finding-classification.md b/docs/adr/adr-038-local-llm-finding-classification.md index 1a2e0a31..9fe85922 100644 --- a/docs/adr/adr-038-local-llm-finding-classification.md +++ b/docs/adr/adr-038-local-llm-finding-classification.md @@ -4,6 +4,8 @@ 試験運用 (2026-05-06) +> 本 ADR の運用パターンは [ADR-039 (試験運用標準パターン)](adr-039-experimental-feature-standard-pattern.md) で標準化された 3 点セット (config opt-in / kill-switch / bounded lifetime) の対象。本採用判定または却下時に ADR-039 の retirement workflow に従う。 + ## コンテキスト Claude Code セッションにおける反復作業の token 消費を抑える目的で、[docs/local-llm-offload-analysis.md](../local-llm-offload-analysis.md) で 3 層構造 (思考層 / 実行層 / 制御層) のオフロード戦略を提案した。GTX 3070 + Ollama (mistral:7b) でローカル推論可能な範囲を切り出す。 diff --git a/docs/adr/adr-039-experimental-feature-standard-pattern.md b/docs/adr/adr-039-experimental-feature-standard-pattern.md new file mode 100644 index 00000000..07b34bc6 --- /dev/null +++ b/docs/adr/adr-039-experimental-feature-standard-pattern.md @@ -0,0 +1,102 @@ +# ADR-039: Experimental feature 標準パターン (config opt-in + kill-switch + bounded lifetime) + +## ステータス + +試験運用 (2026-05-10) + +## コンテキスト + +本プロジェクトでは試験運用 ADR が systemic に蓄積している (本表は **lineage = 過去の試験運用 ADR の網羅列挙**、本 ADR を land する際の遡及 cross-link は **本 ADR では行わない** = §帰結 「欠点 / 留意点」参照): + +| ADR | 試験対象 | 開始 | +|---|---|---| +| [ADR-014](adr-014-post-merge-feedback.md) | post-merge-feedback ループ | 2026-04-22 | +| [ADR-023](adr-023-coderabbit-reject-thread-skill.md) | CodeRabbit reject thread skill | — | +| [ADR-025](adr-025-cwd-restore-drop-guard.md) | CwdRestore Drop guard | — | +| [ADR-029](adr-029-post-merge-feedback-auto-trigger.md) | Post-Merge Feedback 自動起動 | — | +| [ADR-030](adr-030-deterministic-post-merge-feedback.md) | takt 経由の同期実行 | — | +| [ADR-031](adr-031-weekly-review-pipeline.md) | 週次プロジェクト全体レビュー | 2026-04-27 | +| [ADR-033](adr-033-todo-numbering-simplification.md) | todo 採番管理の簡素化 | — | +| [ADR-034](adr-034-coderabbit-auto-monitoring.md) | CodeRabbit 監視自動化 | — | +| [ADR-036](adr-036-bundle-z-three-layer-review.md) | Bundle Z 3 層 review | — | +| [ADR-037](adr-037-takt-fix-trust-shortcut.md) | takt fix-trust shortcut | — | +| [ADR-038](adr-038-local-llm-finding-classification.md) | ローカル LLM finding classification | 2026-05-06 | + +> **本 PR で back-link を追加した範囲**: 上記 11 ADR のうち、**ADR-031 / ADR-036 / ADR-038** の 3 件のみに本 ADR への blockquote 参照を冒頭に追加した (**§ 既存試験運用 ADR で観測される共通パターン** で適合状況を分析した 3 ADR)。残り 8 ADR への遡及更新は **後続 PR で個別追補** とする (§ 帰結 / 欠点 参照)。 + +各試験運用 ADR は個別判断で導入されてきたが、PR #123 (ADR-038 Phase 5: P-0 classifier opt-in + §10 ブランチ分離運用) の post-merge-feedback で、**3 点セット** (config opt-in / kill-switch / bounded lifetime) が systemic に反復していることが確認された (Tier 3 #1 採用)。 + +### 既存試験運用 ADR で観測される共通パターン + +| 観点 | ADR-031 | ADR-036 | ADR-038 | +|---|---|---|---| +| **Config opt-in** | 週次トリガはデフォルト disabled | gate を flag で制御 | `[lint_screen] enabled = false` (default OFF) | +| **Kill-switch** | レビューパイプ停止可能 | gate 経路を revert で停止 | revert PR で `enabled = false` | +| **Bounded lifetime** | 「採用判定で本採用に昇格」 | dogfood 完了で判定 | `local-llm-offload-phase-d-guide.md` で 3-5 PR 後に採否判定 | + +3 点とも個別 ADR で都度設計されてきたが、**新規試験運用 ADR を策定するたびに同じ判断を再発明している**。 + +## 決定 + +試験運用 feature を導入する際の **標準パターン** として 3 点セットを以下の通り規定する。新規試験運用 ADR は本 ADR を **参照** し、3 点を満たすことを default とする。 + +### 1. Config opt-in (デフォルト無効) + +- 設定ファイル (`*.toml`) または env var で `enabled = false` をデフォルトとする +- 明示有効化 (`enabled = true`) で feature 発動 +- env var / config 値での切り替えを必ず提供 (config-only より env override 可能な方が望ましい) +- 派生プロジェクト (techbook-ledger / auto-review-fix-vc 等) への deploy 時にも default OFF が継承されるよう、`[feature]` section の追加を必須化 + +### 2. Kill-switch (停止経路の事前明文化) + +- revert PR で `enabled = false` に戻す経路を **PR body / ADR で明文化** +- crate / module の物理削除は **dogfood 失敗判定後にまとめて実施**。途中段階での部分削除は機械的損傷の risk が高い +- ADR-038 §10.6 の C 案 (採用 / 簡易版 / 完全版の階層化) が良いテンプレ +- kill-switch 経路の table を ADR / PR body に必ず含める (項目: 起動経路 / 停止コマンド / 影響範囲) + +### 3. Bounded lifetime (試験期限と採否判定基準) + +- 試験期限を **ADR 冒頭** または **計画書冒頭** に明記 + - 例: 「6 ヶ月経過しても採用判定未達なら却下とみなす」 + - 例: 「3-5 PR で dogfood 後に採否判定」(ADR-038 / Phase d) +- retirement workflow (`~/.claude/rules/common/docs-governance.md`) との接続を明示 + - **採用**: 試験運用 → 本採用に昇格 (新規 ADR 不要、本 ADR の status 更新) + - **却下**: revert PR で feature 削除 + 本 ADR を「却下」に更新 + 計画書 (`docs/-analysis.md`) を retirement workflow で削除 + - **継続**: 期限内に判定が出ない場合、計画書側に新たな期限と判定基準を記述 (1 回まで延長可) +- bounded lifetime を欠いた試験運用は「永遠の試験運用」化し、累積複雑度の温床になる + +## 帰結 + +### 利点 + +- 新規試験運用 ADR の判断が標準化され、設計議論の重複が削減される +- kill-switch 経路の事前明文化で、dogfood 失敗時のロールバックが decision-free に進む +- bounded lifetime で試験運用の「忘却された負債化」を防ぐ + +### 欠点 / 留意点 + +- 既存試験運用 ADR (014/023/025/029/030/031/033/034/036/037/038) の 3 点セット適合状況は再評価対象。本 ADR の land 後、各 ADR の reflect は **後続 PR での追補** として進める (本 ADR では遡及更新しない) +- 本 ADR 自体も試験運用扱い: 3-5 個の新規試験運用 ADR で本パターンを適用し、適合率と運用負荷を確認後に本採用に昇格する + +### 想定される運用 + +新規試験運用 ADR (例: 仮称 ADR-040) を策定する際は ADR 冒頭近くに以下を記載: + +```markdown +## ステータス + +試験運用 (YYYY-MM-DD) + +> 本 ADR は [ADR-039 (試験運用標準パターン)](adr-039-experimental-feature-standard-pattern.md) に従う。 +> Config opt-in / kill-switch / bounded lifetime の 3 点を満たす。 +``` + +PR body にも kill-switch table を含める (起動経路 / 停止コマンド / 影響範囲)。 + +## 関連 + +- [ADR-031](adr-031-weekly-review-pipeline.md) — 試験運用、3 点セット部分適合 +- [ADR-036](adr-036-bundle-z-three-layer-review.md) — 試験運用、3 点セット部分適合 +- [ADR-038](adr-038-local-llm-finding-classification.md) — 試験運用、3 点セット完全適合 (本 ADR の trigger 事例) +- `~/.claude/rules/common/docs-governance.md` — Document Lifecycle Classification / Retirement Workflow +- `~/.claude/CLAUDE.md` — グローバルルール index diff --git a/docs/local-llm-offload-analysis.md b/docs/local-llm-offload-analysis.md index 05495cda..36394d77 100644 --- a/docs/local-llm-offload-analysis.md +++ b/docs/local-llm-offload-analysis.md @@ -204,7 +204,7 @@ cargo test -p cli-finding-classifier --test lint_screen_evals -- \ | Order | 構成 | Effort | Diff Profile | dogfood signal | |---|---|---|---|---| - | P-1 | Bundle h (順位 89+90) + Bundle g-2 (順位 87+88) | M | global rules markdown 4 file | docs-only で `informational` 期待、false-positive 検証 baseline | + | P-1 | Bundle h (順位 89+90) + Bundle g-2 (順位 87+88) | M | global rules markdown 4 file (うち project diff には ADR-039 + cross-link + todo cleanup のみ) | docs-only で `informational` 期待、false-positive 検証 baseline。**本 PR では config switch を commit に乗せない方針 (Phase d guide §1) のため pipeline 経由の lint_screen は未実行、cli-finding-classifier 直叩きでの classifier preview のみ取得**: latency 23s / findings 0 / fallback (JSON parse error: missing field `screen_decision`) — 順位 98 (`num_ctx` overflow detection) の必要性を再確認する signal。real pipeline 経由の P-1 metric は後続 dogfood で取得 (P-2 移行時に再検討) | | P-2 | Bundle j-1 (順位 94 — `../docs/` 相対パス detect lint rule) | S | TOML config + 軽い Rust regex | 小規模 mixed diff | | P-3 | Bundle g-1 (順位 85+86 — cli-pr-monitor verdict guard + transition test) | M | Rust impl + Rust test | 中規模 Rust、`auto_fix` 期待 | | P-4 | Bundle d (順位 68 — no-ephemeral-todo-reference self-exclusion test) | S | Rust test only | 狭 scope test diff | diff --git a/docs/todo-summary.md b/docs/todo-summary.md index 29763fac..ac0c2b43 100644 --- a/docs/todo-summary.md +++ b/docs/todo-summary.md @@ -62,10 +62,6 @@ | 84 | 💎 Tier 3 | **グローバルルール: code-review.md に「early-return guard テスト分離」チェックリスト追記 (PR #120 T3-1 採用)** | todo5.md | XS | なし (順位 83 の知見を global rule に codify、`~/.claude/rules/common/code-review.md`、独立並列実施可) | | 85 | 🚀 Tier 1 | **cli-pr-monitor: monitor state machine guard 強化 (`review_state: not_found && findings: []` を pending 据置) (PR #121 T1-1 採用) ★ Bundle g** | todo5.md | S | なし (PR #119/#120/#121 で 3 PR 連続観測、Frequency Medium 閾値到達済み、Severity High = 誤 approved リスク、Bundle f #80 と関連だが verdict logic 側) | | 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 違反予防層を強化) | | 91 | 🔧 Tier 2 | **`[lint_screen]` config parse テスト (PR #132 T2-#4 採用) ★ Bundle i** | todo6.md | S | なし (PR #132 で追加した push-runner-config.toml の `[lint_screen]` section に対する toml::from_str テスト、CodeRabbit nitpick 起点、silent field rename 防止) | | 92 | 🔧 Tier 2 | **scale-aware eval fixtures (200+ 行) — Phase d 投入前の必須 infrastructure (PR #132 T2-#5 採用) ★ Bundle i** | todo6.md | M | 順位 91 と同 PR 推奨 (Bundle i コア、PR #132 smoke で観測した mistral:7b 大規模 diff JSON 不完全 (`missing field 'screen_decision'`) を fixture 化、Phase d 着手前の改善 ループ reference point 確保) | | 93 | 💎 Tier 3 | **`coding-style.md` Cross-File Reference Lifecycle に partial fix 例を追記 (PR #132 T3-#8 採用)** | todo6.md | XS | なし (PR #94 / #111 / #132 で反復した「変更差分外ファイルへの partial fix 再発」パターンを anti-pattern 例として codify、独立並列実施可) | @@ -74,6 +70,7 @@ | 96 | 🔧 Tier 2 | **Markdown cross-reference validator CI step (PR #133 T2-#3 採用) ★ Bundle j** | todo6.md | M | 順位 10 (ADR-032 PR-broken-link) と方向性が近接、fold-in 検討の余地あり。順位 94 (regex 規約) + 順位 95 (count 照合) と組み合わせて docs/ 整合性の多層検証 | | 97 | 🔧 Tier 2 | **`with_num_ctx(X)` override 値 serialization 検証テスト (PR #136 T2-#1 採用)** | todo6.md | S | なし (PR #136 で追加した builder method の wiring を mockito で seal、Phase d で num_ctx tweak する局面の silent degrade 防止、CodeRabbit が見逃した test gap を post-merge-feedback agent が独立発見) | | 98 | 🚀 Tier 1 | **`num_ctx` overflow detection — JSON parse error 検知時の context window 診断ログ (PR #137 T1-#1 採用)** | todo6.md | M | なし (PR #136 で誤診 pivot を発生させた blind spot を decisive に塞ぐ runtime hint、`lib-ollama-client` の response validation 層に warn log 追加、`prompt_eval_count` ≈ `num_ctx` cap で truncation を即診断) | +| 99 | 💎 Tier 3 | **ADR-038 に PR #138 learning 2 件を追記 (cost-aware 実装層選択 + attention dilution pitfall) (PR #138 T3-#1+#2 採用)** | todo6.md | S | なし (lint_screen が takt facet → Rust stage に pivot した cost 根拠 + Phase b' v2 の diff header full 追加で agreement 75%→50% 33pt 低下した attention dilution 観測の 2 件を ADR に codify、次回 LLM 系 feature 開発時の prior assumption に) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 @@ -97,9 +94,9 @@ **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 h (PR #123 post-merge-feedback、experimental feature 標準パターン + ephemeral lifecycle 強化、2026-05-07)** ✅ 完了: 順位 89 (Experimental feature 標準パターン = ADR-039 として codify) + 順位 90 (ephemeral 大規模 content の ADR 昇格基準 + config コメント lifecycle anti-pattern を `~/.claude/rules/common/{docs-governance,coding-style}.md` に追加) で land。**却下** (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 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 追記) は land 済 — Bundle h と同 PR で codify 完了**。**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。 **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/todo5.md b/docs/todo5.md index b2912075..ea66aeee 100644 --- a/docs/todo5.md +++ b/docs/todo5.md @@ -287,48 +287,3 @@ --- -### グローバルルール: Multi-PR chaining ベストプラクティスを codify (PR #121 T3-7 採用) - -> **動機**: PR #119 (init) → #120 (integrate) → #121 (organize) の 3 連鎖が dogfood で有効に機能。「各 PR は論理的ユニット (init/integrate/organize) を担当し、diff サイズは 250–800 lines を推奨」を再利用可能なガイドラインとして codify。 -> -> **参照**: PR #119 / #120 / #121 セッション、`.claude/feedback-reports/121.md` Tier 3 #7 -> -> **実行優先度**: 💎 **Tier 3** — Effort XS、Frequency Medium (3 PR で実証)、Adoption Risk なし。 - -#### 作業計画 - -- [ ] `~/.claude/rules/common/git-workflow.md` の PR Workflow セクションに 3-5 行追記: - - 「複数 PR 連鎖時は init / integrate / organize 等の論理ユニットで分割」 - - 「1 PR あたり diff size 目安: 250-800 lines」 - - 「(参照) PR #119/#120/#121 で実証された 3 連鎖パターン」 -- [ ] 順位 88 と同 PR で land 可能 (どちらも XS、独立性高) - -#### 完了基準 - -- git-workflow.md にガイドラインが記載される -- 次回複数 PR 連鎖時にレビュー基準として参照可能になる - ---- - -### グローバルルール: edge case 観測頻度 3 = Tier 1 昇格基準を codify (PR #121 T3-8 採用) - -> **動機**: post-merge-feedback workflow が暗黙的に適用している「同じ edge case が 3 PR 観測されたら Tier 1 に昇格」基準を明文化。ユーザーが直前で示した「新規フィードバックは頻度が確認できるまで優先しない」方針と同根、両者の収束で frequency 判定の再現性が向上。 -> -> **参照**: 本セッション (PR #119/#120/#121) で発生した Bundle f #80 の 3 観測昇格判定、`.claude/feedback-reports/121.md` Tier 3 #8 -> -> **実行優先度**: 💎 **Tier 3** — Effort XS、Frequency Medium (繰り返し適用される暗黙ルール)、Adoption Risk なし。 - -#### 作業計画 - -- [ ] `~/.claude/rules/common/development-workflow.md` または `docs-governance.md` 等に 3-5 行追記: - - 「edge case が 3 観測に達したらタスクを Tier 1 に昇格して優先実装」 - - 「観測カウントは feedback report で `Frequency Medium 閾値到達` と明示」 - - (参照) Bundle f 順位 80 の昇格事例 -- [ ] 順位 87 と同 PR で land 可能 - -#### 完了基準 - -- 該当 rule に頻度閾値が明記される -- 次回 post-merge-feedback workflow が報告した「Frequency Medium 到達」が rule 側から逆引き可能になる - - diff --git a/docs/todo6.md b/docs/todo6.md index 1028761f..6bdb8b02 100644 --- a/docs/todo6.md +++ b/docs/todo6.md @@ -10,95 +10,6 @@ ## 現在進行中 -### 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 コア) - ---- - ### `[lint_screen]` config parse テスト (PR #132 T2-#4 採用) ★ Bundle i > **動機**: PR #132 (Phase c MVP) で `push-runner-config.toml` に新 section `[lint_screen]` を追加したが、`config.rs` の test module には parse テストが不在。CodeRabbit nitpick で指摘 (`config_parses_with_diff` 相当が `[lint_screen]` には未存在)。serde TOML は field name の完全一致を要求するため、parse テストがないと将来の field rename / 追加で silent `None` fallback が発生し、機能が無音で停止するリスクがある。 @@ -427,3 +338,53 @@ config.rs + push-runner-config.toml + review-simplicity.md + ADR で family_tag - **派生プロジェクト deploy 戦略**: `lib-ollama-client` が本リポ専用なら deploy なし、共有 crate 化するなら別 repo への copy / git submodule / cargo registry の判断が必要。Phase d 着手判定と合わせて検討 - **log destination**: `eprintln!` (cli 用途で十分) vs `tracing` / `log` crate 統合 (既存の cli-* との一貫性)。本 lib は現状 ureq + serde_json のみで logging crate なし、初期は `eprintln!` で warn 接頭辞付け、将来必要なら crate 統合という段階導入が自然 + +--- + +### ADR-038 に PR #138 learning 2 件を追記 (cost-aware 実装層選択 + attention dilution pitfall) (PR #138 T3-#1+#2 採用) + +> **動機**: PR #138 (Phase d kickoff prep) 関連セッションで観測された 2 件の重要 learning が ADR-038 未記録。両者とも次回 LLM/Ollama 系 feature 開発時に再発可能性が高く、ADR に codify することで以下を構造的に防ぐ: +> +> 1. **cost-aware 実装層選択**: lint_screen を当初 `takt facet` (Sonnet 動作) として ADR-038 に記述していたが、実装段階で「Sonnet 動作はコスト削減という主目的と矛盾」と判明し `cli-push-runner` の Rust stage (mistral 直呼び) へ pivot。判断根拠が ADR-038 に未記録のため、後続の §8.F (PR body draft) 等で同型の選択を再検討する際に学習が再現されない +> 2. **attention dilution pitfall**: Phase b' v2 で eval prompt example に diff header (`--- a/` `+++ b/`) を full に追加した結果、agreement rate が **75% → 50% に 33pt 低下** した実証データ。anti-hallucination preamble の効果が context scarcity で打ち消される pattern で、再発すると prompt tuning コストが大きい +> +> **本タスクの位置づけ**: PR #138 post-merge-feedback Tier 3 #1 + #2 採用 (Tier 3 #1: Severity Low / Frequency Medium / Effort S / Adoption Risk None / Tier 3 #2: Severity Medium / Frequency Low / Effort S / Adoption Risk None)。両者とも ADR-038 への追記で 1 ファイル編集、bundle land 推奨。 +> +> **参照**: `.claude/feedback-reports/138.md` Tier 3 #1 + #2、`docs/adr/adr-038-local-llm-finding-classification.md`、`docs/local-llm-offload-history.md` (Phase b' v2 の attention dilution 観測) +> +> **実行優先度**: 💎 **Tier 3** — Effort S。次の LLM 系 feature (§8.F PR body draft 等) 着手前 or Phase d 完了集約 PR と同 timing で land 推奨。 + +#### 設計決定 (案) + +- **配置先**: `docs/adr/adr-038-local-llm-finding-classification.md` 内に 2 つの新 section を追加 +- **#1 cost-aware 実装層選択**: `## Architecture decision: takt facet vs Rust stage trade-off` (or 既存 §architecture を拡張) + - takt facet (Sonnet) を選ぶ条件: 意味的判断が必要、コスト感度低 + - Rust stage (local mistral) を選ぶ条件: コスト削減が主目的、決定論的判定が可能、latency 許容範囲 + - lint_screen の実例: 当初 takt facet → コスト矛盾検出 → Rust stage に pivot +- **#2 attention dilution pitfall**: `## Prompt engineering: attention dilution case study` (or §prompt engineering 拡張) + - 観測: Phase b' v2 で diff header full 追加 → agreement 75% → 50% (33pt 低下) + - 根因: anti-hallucination preamble の効果が context scarcity で打ち消される + - 教訓: prompt examples は最小 viable diff snippet で記述、metadata は省略 + +#### 作業計画 + +- [ ] `docs/adr/adr-038-local-llm-finding-classification.md` の構造確認 (既存 section header の慣習に合わせる) +- [ ] #1 architecture decision section を追加 (lint_screen pivot 根拠 + 一般化) +- [ ] #2 prompt engineering pitfall section を追加 (Phase b' v2 観測値 + 教訓) +- [ ] 既存 section との整合性確認 (重複説明の有無) +- [ ] markdownlint clean 確認 +- [ ] 本 todo6.md エントリを削除 + +#### 完了基準 + +- ADR-038 に 2 つの learning が permanent record として codify される +- 後続 LLM 系 feature 開発時に「過去の選択根拠 / pitfall」を git log でなく ADR で参照可能になる +- markdownlint clean + +#### 詰まっている箇所 + +なし。Effort S、ADR への追記のみで副作用最小。 + +#### 参考: 不採用理由 (Tier 3 #4) + +`~/.claude/rules/common/coding-style.md` §Markdown に「重複表現 grep チェック手順」を追加する提案 (#3-4) は **ユーザー判断で見送り**。理由: 重複ワードのバリエーションが多すぎて grep pattern 列挙では網羅できないため、`feedback_no_unenforced_rules.md` 方針 (機械検知不可なルールは追加しない) と整合的に却下相当。週次レビュー (ADR-031) や reviewer の主観判断で対処する位置づけを維持。