diff --git a/CLAUDE.md b/CLAUDE.md index 22385c8d..84750b19 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,6 +50,10 @@ - [ADR-047: pre-push review の反証（refute）facet](docs/adr/adr-047-prepush-refute-facet.md) *(試験運用)* - [ADR-048: reviewers→fix findings handoff の output-contract 標準化（markdown 統一・JSON 却下）](docs/adr/adr-048-facet-findings-handoff-markdown-contract.md) *(試験運用)* +## 開発 convention / チェックリスト + +- [開発 convention / チェックリスト](docs/dev-conventions.md) — spike 見送り (negative result) 永続化 convention (順位261)、外部 SaaS 無料枠 / 制限の調査チェックリスト (順位262) + ## Build ```sh diff --git a/docs/adr/adr-038-local-llm-finding-classification.md b/docs/adr/adr-038-local-llm-finding-classification.md index 703c789a..0660e6c1 100644 --- a/docs/adr/adr-038-local-llm-finding-classification.md +++ b/docs/adr/adr-038-local-llm-finding-classification.md @@ -260,6 +260,7 @@ classify モードの精度向上 (特に `false_positive_likely` 判定改善 - **classify モードの eval 手法**: Opus gold baseline との action 一致率 + FP 処理 + 安全軸 (human_review→auto_fix 誤送) の 3 軸評価は、将来のモデル/プロンプト再評価に再利用できる (`cli-finding-classifier` の lint-screen eval と同型)。 - **保守バイアスは分類器の安全機能**: 「迷ったら human_review」は accuracy を下げるが、誤自動修正リスクを構造的に抑える。格上げ候補は accuracy だけでなく安全軸で評価すべき。 +- **accuracy と安全軸は独立指標として評価する ([ADR-043](adr-043-security-gates-fail-closed.md) と同根、順位260)**: model evaluation では gold 一致率 (accuracy) と**安全軸 (human_review → auto_fix への誤送ゼロ)** を独立に測り、両者が trade-off するときは**安全軸を優先**する。WP-04 で accuracy 最上位 (0.69) の qwen3-coder を見送り accuracy 下位 (0.63) の mistral:7b を維持したのは本原則の適用例。これは [ADR-043](adr-043-security-gates-fail-closed.md) の fail-closed 原則 (判定不能時は安全側 = block にデフォルト) を gate 層でなく**助言/分類層に一般化**したもの ―「不確実性は楽観 (auto_fix) でなく保守 (human_review) に倒す」という同じ設計思想であり、accuracy 改善が安全後退を隠しうる tension を明示する。 - **FP 検出はプロンプト再調整の余地**: `classify.txt` は mistral 向けに tune 済み。FP 検出強化プロンプトで能力限界かプロンプト不適合かを切り分ける follow-up は順位 256。候補の VRAM/latency 実測は [ADR-040](adr-040-local-llm-context-size.md) の新 GPU 再 calibration (順位 255) にも供する。 ### 妥当性の脅威 @@ -274,3 +275,4 @@ classify モードの精度向上 (特に `false_positive_likely` 判定改善 - [ADR-034: CodeRabbit 監視・自動化戦略](adr-034-coderabbit-auto-monitoring.md) — 監視層との将来統合先 - [ADR-039: 試験運用標準パターン](adr-039-experimental-feature-standard-pattern.md) — 3 点セット (opt-in / kill-switch / bounded lifetime) の標準化 - [ADR-040: Local LLM Context Size と Resource Trade-off](adr-040-local-llm-context-size.md) — Phase A〜C num_ctx empirical data の永続記録 +- [ADR-043: Security/Quality Gate での Fail-Closed 原則](adr-043-security-gates-fail-closed.md) — WP-04 の「accuracy 向上 ≠ 安全性維持」tension が同 ADR の fail-closed 思想 (不確実性は安全側に倒す) の助言/分類層への一般化 (順位260) diff --git a/docs/adr/adr-043-security-gates-fail-closed.md b/docs/adr/adr-043-security-gates-fail-closed.md index 2311d73d..22e85cec 100644 --- a/docs/adr/adr-043-security-gates-fail-closed.md +++ b/docs/adr/adr-043-security-gates-fail-closed.md @@ -110,6 +110,14 @@ fn is_stale(behind: Option) -> bool { ただし **non-gate な計算関数** (純粋に数値を計算 / 表示用文字列を作る等) は本原則の対象外。`?` は通常通り使ってよい。 +### 原則 5: 助言/分類層への安全思想の一般化 (2026-07-06 追記、順位260) + +原則 1〜4 は block/allow を決める **gate 関数** を対象とするが、その根底にある「**不確実・trade-off 時は楽観でなく安全側にデフォルトする**」思想は、block しない **助言/分類層** の設計にも一般化できる。 + +具体例 ([ADR-038](adr-038-local-llm-finding-classification.md) § classify モデル格上げの評価と見送り、WP-04 / 2026-07-05): CodeRabbit findings classifier のモデル格上げ評価で、accuracy 最上位 (0.69) の `qwen3-coder:30b` は human_review 案件 1 件を `auto_fix` に誤送する **安全後退** を起こした。accuracy 下位 (0.63) だが「人間判断案件を一度も `auto_fix` に倒さない」`mistral:7b` を維持したのは、gate でなく助言層であっても「不確実性は保守 (`human_review`) に倒す」= 本 ADR の fail-closed 思想を優先した判断である。 + +一般原則として、model/heuristic の評価では **accuracy と安全軸 (安全側デフォルトを破らないこと) を独立指標として測り、両者が trade-off するときは安全軸を優先**する。accuracy 改善が安全後退を隠しうる (WP-04 の qwen3-coder) 点に注意する。gate 関数における「判定不能 → block」と、助言層における「不確実 → 保守側 (human_review)」は同一の設計思想の別レイヤーへの適用である。 + ## 反例の判別ヒント 関数が gate 関数か non-gate 関数かは、以下の質問で判別する: @@ -137,5 +145,6 @@ PR #194 commit `dfad56ff` で `build_todo_staleness_message` 内の `let stale = - PR #194 (`feat(hooks): merge 前 mechanical gate 強化 (clippy + 空 commit sweep)`) commit `dfad56ff`: `behind?` → `is_none_or` 修正 - CodeRabbit Major #5 (PR #194 review): 「security gate は判定不能時 fail-closed であるべき」 - ADR-021 (`jj 変更検出ロジックの設計原則`) § Revset Composability: jj 操作の fail-safe 方向との対比 +- [ADR-038: ローカル LLM による CodeRabbit findings classification](adr-038-local-llm-finding-classification.md) § classify モデル格上げの評価と見送り: 原則 5 の助言/分類層一般化の具体例 (WP-04 の accuracy vs 安全軸 trade-off、順位260) - `~/.claude/rules/common/security.md` § Mandatory Security Checks: 本 ADR が補完する global checklist - Rust 公式 doc: [`Option::is_none_or`](https://doc.rust-lang.org/std/option/enum.Option.html#method.is_none_or) (1.82+ stable) diff --git a/docs/dev-conventions.md b/docs/dev-conventions.md new file mode 100644 index 00000000..49d0eaea --- /dev/null +++ b/docs/dev-conventions.md @@ -0,0 +1,30 @@ +# 開発 convention / チェックリスト + +> CLAUDE.md (ADR index) から分離した運用 convention・チェックリスト集。index の肥大化を避けつつ、セッション横断で参照する軽量ガイドを集約する (ADR-022 の責務分離)。 + +## spike / 実験タスクの見送り (negative result) 永続化 convention (順位261) + +spike・実験タスクを見送る (採用しない) と判断したときは、negative result の知見が散逸しないよう以下の **3 点セット** を必ず実施する: + +1. **ADR に結論と実測根拠を記録** — 見送り判断・数値根拠・比較対象を該当 ADR (新規 or amendment) に永続化する。「なぜ見送ったか」を後続セッションが再構築できる粒度で書く。 +2. **計画文書の状態列を更新** — 該当タスクの計画文書 (例: `docs/harness-improvement-plan.md` 等の ephemeral 計画) の状態を「見送り / 却下」に更新し、宙吊りの検討を残さない。 +3. **再評価トリガー付き follow-up を Tier 5 todo 化** — 「どういう条件が変われば再評価するか」(新モデル出現 / プロンプト改善 / GPU 更新 等) を明示した follow-up を Tier 5 (⏳) todo として登録する。恒久見送りではなく「現時点では見送り」を表現する。 + +**確立事例** (2 例で成立): + +- WP-01 (ローカル LLM pre-push レビュアー選定) → [ADR-046](adr/adr-046-local-llm-review-spike.md) で却下記録 + follow-up を順位 255 に todo 化 +- WP-04 (classifier モデル格上げ) → [ADR-038](adr/adr-038-local-llm-finding-classification.md) § classify モデル格上げの評価と見送り で amendment 記録 + follow-up を順位 256 に todo 化 + +3 例目以降の spike 見送りも本 convention を参照して同型に処理する。 + +## 外部 SaaS 無料枠 / 制限の調査チェックリスト (順位262) + +外部サービス (CodeRabbit / LLM API / CI/CD provider 等) の無料枠・制限を調査するときは、「free tier」の一語で判断せず、以下の **各次元を個別に確認** する。単一の緩和 (例:「public リポは Pro 機能無償」) を「全制限撤廃」と誤解しないため: + +1. **月間上限** — 月あたりの総回数 / 総量の上限。 +2. **時間単位 rate limit** — 1 時間 / 1 分あたりの上限。月間上限とは **別次元** で、月間に余裕があっても時間単位で先に当たることがある。 +3. **適用単位** — per-user / per-org / per-repo のどれで計量・課金されるか。fork / 別アカウント運用で分離できるかにも関わる。 +4. **plan tier による差** — free / pro / enterprise で緩和される制限の種類。 +5. **public リポ特典の適用範囲** — public リポで無償化される「機能」と、緩和されない「rate limit」を区別する。 + +**由来** (WP-03、[ADR-019](adr/adr-019-coderabbit-review-hybrid-policy.md) § CodeRabbit クォータ設計): CodeRabbit の「public リポ向け Pro 機能無償提供」を「rate limit 撤廃」と誤解しかけたが、実際には月間上限と時間単位 rate limit は別次元で、時間単位上限 (3〜4 回 / 時) は残存していた (2026-07-04 ユーザー確認)。この誤解は LLM API・CI 等の他 SaaS 統合でも再発しうる汎用パターン。 diff --git a/docs/todo-summary.md b/docs/todo-summary.md index 3993b400..43d68f0b 100644 --- a/docs/todo-summary.md +++ b/docs/todo-summary.md @@ -123,9 +123,6 @@ | 255 | 💎 Tier 3 | **ADR-040 の実測値を新 GPU (RTX PRO 5000 48GB) で再 calibration (ADR-046 WP-01 スパイクで陳腐化を観測)** | todo13.md | S | なし (ADR-038/040 が前提とする RTX 3070 8GB は RTX PRO 5000 Blackwell 48GB に更新済み。27-31B Q4 モデルが 100% GPU で動き VRAM が制約でなくなったため、ADR-040 の VRAM/latency trade-off 表と「VRAM scarcity → model swap 制約」framing が陳腐化。ADR-046 で mistral:7b / gemma4 / qwen3-coder の VRAM・latency を実測済 → ADR-040 amendment に反映、num_ctx 選定 flow の memory 軸を latency 軸へ再重み付け) | | 256 | ⏳ Tier 5 | **classifier FP 検出強化プロンプトで格上げ候補を再評価 (WP-04 見送りの follow-up、ADR-038 amendment 由来)** | todo13.md | M | なし (WP-04 実測で全候補が FP 検出未達 = 能力限界か `classify.txt` の mistral 向け tune 不適合かが未分離。FP 検出強化プロンプト版で qwen3-coder:30b 等を再測し、能力限界と確認できれば恒久見送り、プロンプト不適合なら該当モデル + 専用プロンプトで格上げ。eval 手法・gold セットは scratchpad WP-04 資産を再利用。materially better な新モデル出現時も再評価トリガー) | | 257 | ⏳ Tier 5 | **push pipeline の `cargo test` を cargo-nextest 化 (WP-05 で Stop hook には無効と判明、push 側 follow-up)** | todo13.md | S-M | なし (WP-05 実測: Stop hook は cargo test 不在で nextest 非適用、真因は逐次実行→並列化で解決済。ただし push pipeline (cli-push-runner quality_gate) の `cargo test -- --ignored` は実測 ~80s で nextest 高速化の余地あり。ツール依存追加 = ADR-017 pinning + 派生プロジェクト配布のコスト、push が Stop より低頻度な点を踏まえた費用対効果を評価。doctest は nextest 非実行のため `cargo test --doc` 併走が必要) | -| 260 | 💎 Tier 3 | **ADR-038 × ADR-043 の「accuracy 向上 ≠ 安全性維持」tension を cross-reference で明文化 (PR #245 post-merge-feedback T3-1 採用)** | todo13.md | XS | なし (WP-04 実測で qwen3-coder は accuracy +0.06 でも human_review 1 件を auto_fix に誤分類 = 有害な自動修正リスク。downstream 安全性優先で mistral:7b 維持と判断した根拠を ADR 相互参照で恒久化しないと将来の model evaluation で同 tension が再発。順位 261/262 と 1 docs PR bundle 推奨) | -| 261 | 💎 Tier 3 | **spike 見送り (negative result) の永続化 convention を明文化 (PR #245 post-merge-feedback T3-2 採用)** | todo13.md | XS | なし (WP-01 = ADR-046 却下 + 順位 255、WP-04 = ADR-038 amendment + 順位 256 の 2 例で「見送り → ADR 結論記録 + 計画状態更新 + follow-up の Tier 5 todo 化」3 点セットが確立済み。convention 明文化で 3 例目以降を誘導。順位 260/262 と 1 docs PR bundle 推奨) | -| 262 | 💎 Tier 3 | **SaaS 無料枠の制限種別チェックリストを CLAUDE.md に追加 (PR #243 post-merge-feedback T3-1 採用)** | todo13.md | S | なし (WP-03 で CodeRabbit の「public リポ向け無償提供」を「rate limit 撤廃」と誤解しかけた実例に由来。無料枠調査時の確認次元 (月間上限 / 時間単位 rate limit / per-user vs per-org / plan tier / public リポ特典範囲) をチェックリスト化。LLM API・CI 等の外部 SaaS 統合で再発する汎用パターン。順位 260/261 と 1 docs PR bundle 推奨) | | 263 | 💎 Tier 3 | **クロスシステム設定 coupling パターンの汎化 ADR 起票 (PR #243 post-merge-feedback T3-2 採用)** | todo13.md | M | なし (.coderabbit.yaml (外部 SaaS 側、server-side 読取) × pr-monitor-config.toml [fix] trigger_review_after_push (内部 CLI) の論理 coupling は片側変更で re-review 欠落 / 二重投稿を招く構造。ランタイム cross-validation は原理的に不可 = 文書化 + 期待値組み合わせ表 + 両側同 PR 変更原則が mitigation の中心。ADR-019 の CodeRabbit 固有記述を汎化、ADR-NNN placeholder 方式 (report 原文の ADR-046 は WP-01 却下で使用済みのため不使用)) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 diff --git a/docs/todo13.md b/docs/todo13.md index e5287640..eaefe59f 100644 --- a/docs/todo13.md +++ b/docs/todo13.md @@ -772,76 +772,6 @@ --- -### ADR-038 × ADR-043 の「accuracy 向上 ≠ 安全性維持」tension を cross-reference で明文化 (PR #245 post-merge-feedback T3-1 採用) - -> **動機**: WP-04 (classifier モデル格上げ評価) の実測で、qwen3-coder:30b は accuracy +0.06 を達成した一方、**human_review 案件 1 件を auto_fix に誤分類**した (= 有害な自動修正が走るリスク)。downstream 安全性を優先して mistral:7b 維持と判断したが、「精度指標の改善が安全性後退を隠しうる」という tension が ADR レベルで恒久化されていないため、将来の model evaluation spike で同じ議論を繰り返すリスクがある。 -> -> **参照**: ADR-038 § classify モデル格上げの評価と見送り (2026-07-05 追記、WP-04)、ADR-043 (Security/Quality Gate での Fail-Closed 原則)。 -> -> **実行優先度**: 💎 Tier 3 — Effort XS。順位 261/262 と 1 docs PR に bundle 推奨。 - -#### 作業計画 - -- [ ] ADR-038 に「model evaluation では accuracy と安全軸 (human_review → auto_fix への誤送ゼロ) を独立に評価し、trade-off 時は安全軸を優先する」旨を追記し、ADR-043 へ cross-reference -- [ ] ADR-043 側にも助言層/分類層における安全軸優先の具体例 (WP-04 の qwen3-coder 判断) として back-reference を追記 -- [ ] 本 entry 削除 + todo-summary.md 行削除 - -#### 完了基準 - -- ADR-038 と ADR-043 が相互参照され、model evaluation の安全軸優先原則が明文で確認できること。 - -#### 詰まっている箇所 - -- なし (WP-04 の実測データは ADR-038 amendment に記録済み)。 - ---- - -### spike 見送り (negative result) の永続化 convention を明文化 (PR #245 post-merge-feedback T3-2 採用) - -> **動機**: WP-01 (ローカル LLM レビュアー選定 → ADR-046 で却下記録 + follow-up を順位 255 に todo 化) と WP-04 (classifier 格上げ → ADR-038 amendment で見送り記録 + follow-up を順位 256 に todo 化) の 2 例で、「見送り判断 → ① ADR に結論と実測根拠を記録、② 計画文書の状態列を更新、③ 再評価トリガー付き follow-up を Tier 5 todo 化」という 3 点セットのパターンが確立した。convention が成文化されていないため、3 例目以降の spike が同型で処理される保証がない (negative result の知見が散逸するリスク)。 -> -> **参照**: ADR-046 (WP-01 却下の記録例)、ADR-038 § classify モデル格上げの評価と見送り (WP-04 の記録例)、順位 255/256 (follow-up todo 化の例)。 -> -> **実行優先度**: 💎 Tier 3 — Effort XS。順位 260/262 と 1 docs PR に bundle 推奨。 - -#### 作業計画 - -- [ ] CLAUDE.md に spike/実験タスクの見送り時 convention (上記 3 点セット) を簡潔に追記する。CLAUDE.md が index 構造のため肥大化する場合は docs/ 配下の guide ファイルに本文を置き CLAUDE.md からリンクする形でも可 (ADR-022 の方針に整合) -- [ ] 本 entry 削除 + todo-summary.md 行削除 - -#### 完了基準 - -- 見送り時の 3 点セット (ADR 記録 / 計画状態更新 / Tier 5 todo 化) が永続文書で確認でき、次回 spike の見送り処理が本 convention を参照して実行できること。 - -#### 詰まっている箇所 - -- なし (確立済みパターンの成文化のみ)。 - ---- - -### SaaS 無料枠の制限種別チェックリストを CLAUDE.md に追加 (PR #243 post-merge-feedback T3-1 採用) - -> **動機**: WP-03 (CodeRabbit クォータ設計) で「public リポジトリ向け Pro 機能無償提供」を「レートリミット撤廃」と誤解しかけた。実際には**月間上限と時間単位 rate limit は別次元**で、時間単位上限 (3〜4 回/時) は残存していた (ユーザー確認で判明)。公式ドキュメントの曖昧な「free tier」表現に対して、確認すべき制限の次元を明示しておかないと、LLM API・CI/CD 等の他 SaaS 統合でも同じ誤解が再発する。 -> -> **参照**: ADR-019 (CodeRabbit レビュー運用、WP-03 の amendment 含む)、docs/harness-improvement-plan.md § WP-03 (誤解の経緯。ただし ephemeral 文書のため参照は本 entry 消化時点の存否に依存)。 -> -> **実行優先度**: 💎 Tier 3 — Effort S。順位 260/261 と 1 docs PR に bundle 推奨。 - -#### 作業計画 - -- [ ] CLAUDE.md に「外部サービスの無料枠/制限を調査する際の確認チェックリスト」を追加: ① 月間上限、② 時間単位 rate limit、③ per-user / per-org / per-repo の適用単位、④ plan tier による差、⑤ public リポ特典の適用範囲 (どの制限が緩和されるのか)。「free tier」の一語で判断せず制限の各次元を個別に確認する原則を明記 -- [ ] 本 entry 削除 + todo-summary.md 行削除 - -#### 完了基準 - -- チェックリストが CLAUDE.md (または CLAUDE.md からリンクされた guide) に存在し、次回の外部 SaaS 調査で参照可能なこと。 - -#### 詰まっている箇所 - -- なし。 - ---- - ### クロスシステム設定 coupling パターンの汎化 ADR 起票 (PR #243 post-merge-feedback T3-2 採用) > **動機**: `.coderabbit.yaml` (外部 SaaS 側設定、CodeRabbit が server-side で読む) と `pr-monitor-config.toml` の `[fix] trigger_review_after_push` (内部 CLI 設定) は論理的に coupled しており、**片方だけを変更すると re-review 欠落または二重投稿が発生する**構造になっている。SaaS 側が YAML を server-side で読むため、ランタイムでの cross-validation は原理的に不可能 = 文書化・期待値組み合わせ表・変更手順の規律が mitigation の中心になる。ADR-019 には CodeRabbit 固有の組み合わせ表が記録済みだが、この構造は今後の外部 SaaS 統合 (LLM service、CI provider 等) で繰り返される汎用パターンのため、汎化 ADR として横展開する。