diff --git a/CLAUDE.md b/CLAUDE.md index 171e5dba..458f8db9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,6 +34,7 @@ - [ADR-030: 決定論的 Post-Merge Feedback — takt 経由の同期実行 + 失敗マーカーによる recovery](docs/adr/adr-030-deterministic-post-merge-feedback.md) *(試験運用 / Supersedes ADR-014 full, ADR-029 partial)* - [ADR-031: 週次プロジェクト全体レビューパイプライン — whole-tree review の自己改善ループ](docs/adr/adr-031-weekly-review-pipeline.md) *(試験運用)* - [ADR-033: todo.md 採番管理の簡素化 — 絶対番号は table のみに保持](docs/adr/adr-033-todo-numbering-simplification.md) *(試験運用)* +- [ADR-034: CodeRabbit 監視・対話の自動化戦略 — Bundle a 設計根拠](docs/adr/adr-034-coderabbit-auto-monitoring.md) *(試験運用)* ## Build diff --git a/docs/adr/adr-034-coderabbit-auto-monitoring.md b/docs/adr/adr-034-coderabbit-auto-monitoring.md new file mode 100644 index 00000000..62276bd8 --- /dev/null +++ b/docs/adr/adr-034-coderabbit-auto-monitoring.md @@ -0,0 +1,201 @@ +# ADR-034: CodeRabbit 監視・対話の自動化戦略 + +## ステータス + +試験運用 (2026-05-02) + +## コンテキスト + +PR #99 セッションで以下の運用痛が観測された: + +1. **CR rate-limit の手動回復**: rate-limit 発生時、cli-pr-monitor の検出ロジック gap (review state = `not_found` 時の見逃し) により自動 retrigger が機能せず、ユーザーが手動で walkthrough comment を確認 → sleep + `@coderabbitai review` 投稿が必要 +2. **CR review listing の token bloat**: `gh api .../pulls/N/reviews` + `pulls/N/comments` の重複取得で 44KB 級の生 metadata が context に乗る (cache_creation 9x で 約 400K tokens 蓄積) +3. **POST 応答の無駄**: `gh api -X POST .../replies` が 24KB の reply object を返すが、Claude は success/fail のみで十分なため body 破棄が必要 + +これらは Bundle Y2 (haiku 化、PR #98) でパイプラインが加速 (1〜2m/iter) した結果として CR への push 頻度が増えた **逆説的副作用**。 + +## 検討した選択肢 + +`docs/pipeline-token-efficiency.md` #D セクションで 4 案を検討: + +- **#D-1**: gh CLI 使用ルール (rule 追記) +- **#D-2**: `pnpm cr:findings ` wrapper script +- **#D-3**: `check-ci-coderabbit --list-findings` Rust モード +- **#D-4**: Claude 応答スタイル簡素化 rule + +## 決定 + +**#D-1 + #D-3 を Bundle a (PR #99 post-merge-feedback 由来) に統合する。** + +### Bundle a の最終構成 (4 component) + +| # | 役割 | Effort | 出典 | +|---|---|---|---| +| 1 | cli-pr-monitor の rate-limit auto-retry 実装 | M | PR #99 T2-4 | +| 2 | ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 | S | PR #99 T3-5 | +| 3 | **#D-1**: gh CLI 規則を `~/.claude/rules/common/git-workflow.md` に追記 | XS | 計画書 #D-1 | +| 4 | **#D-3**: `check-ci-coderabbit --list-findings` Rust モード (cli-pr-monitor 連携 API) | M | 計画書 #D-3 | + +### 取り下げた案 + +- **#D-2 (pnpm cr:findings wrapper)**: ❌ 取り下げ。#D-3 が機能を内包 (Rust 構造化 findings JSON は wrapper script より widely usable、ADR-022 責務分離原則にも整合) +- **#D-4 (応答スタイル簡素化)**: ⏸️ 保留。**思考連続性低下リスク** (中間出力削減で後段の context 再構築コストが増え、token カテゴリが入れ替わるだけで正味削減が縮む可能性) を考慮、Bundle Z Phase 2/3 完了後の副作用観測手段確立を待つ。再評価条件は「将来の検討事項」参照 + +## 実装方針 (2 Sub-PR 分割) + +### Sub-PR 1: token 削減層 (先行) + +- **#D-1**: `git-workflow.md` に gh CLI 使用規則を追記 (XS) +- **#D-3**: `check-ci-coderabbit --list-findings` Rust 実装 (M) + +### Sub-PR 2: rate-limit 自動化層 (主軸) + +- cli-pr-monitor の rate-limit auto-retry 実装 (Sub-PR 1 の #D-3 findings API を消費) +- ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 (= 本 ADR の改訂版を ADR-018 へ反映) + +**分割根拠**: 依存方向 (#D-3 API → cli-pr-monitor 消費) が一方向、検証段階性確保。1 PR で 4 component を land すると CR review iteration が複雑化する (PR #99 でも 4 round)。 + +## 設計詳細 + +### rate-limit detection (改善版) + +既存の `state.rate_limit` 検出は review state ベースで、`not_found` 時に rate-limit overlay を見逃す gap がある。 + +**改善**: walkthrough comment (PR の最初の CR comment) の `body` + `updated_at` を直接 polling し、`Rate limit exceeded` パターンを regex 検出する。 + +参照: memory `project_coderabbit_rate_limit_overlay.md` (PR #99 で実証された CR の rate-limit overlay 仕様) + +### auto-trigger 投稿 + +- body 内 `Please wait N minutes and M seconds` を regex 抽出 +- `updated_at` + N min M s = 解除予定時刻 +- 解除 + **1 分** の安全マージン後 `gh api -X POST issues/N/comments -f body='@coderabbitai review' > /dev/null 2>&1` を投稿 +- 1 分マージンは PR #99 セッション末で実証済 (本セッション内手動再現で確認) + +### session 超え recovery + +- `.claude/cli-pr-monitor-state.json` schema 拡張: + - `rate_limit_unlock_at`: 解除予定時刻 (ISO 8601) + - `scheduled_retry_post`: bool +- SessionStart hook (`hooks-session-start.exe`) が state file を読み、rate-limit 待機中なら cli-pr-monitor を recovery mode で再起動 +- 既存の `state.rate_limit_last_retriggered_at` dedup を継承し、複数 session での重複投稿を防止 + +### gh CLI 使用規則 (#D-1) + +`~/.claude/rules/common/git-workflow.md` に以下を追記: + +- POST 操作 (作成・更新): 応答 body 破棄 (`> /dev/null 2>&1`) +- GET 操作 (取得): `--jq` で必要 field のみ抽出 +- CR walkthrough 除外: `gh pr view --json reviews,comments` の `comments` field に CR walkthrough の base64 internal state が含まれるため `--jq 'del(.comments[].body)'` で除外 + +### 構造化 findings (#D-3) + +`check-ci-coderabbit.exe --list-findings --pr ` で以下の JSON を出力: + +```json +{ + "findings": [ + {"severity": "major", "file": "...", "line": 415, "summary": "...", "url": "..."} + ] +} +``` + +- cli-pr-monitor からも消費可能 (rate-limit auto-retry のロジックに統合) +- Claude が `gh api` 重複取得をせず、1 コマンドで構造化 findings を取得 + +## 影響 + +### Positive + +- ✅ rate-limit 完全自動回復 (ユーザー手動介入消滅) +- ✅ session 跨ぎ recovery (ユーザーが PC を閉じても OK) +- ✅ CR review listing の構造化 + token 削減 (~150-500K cache_creation tokens、全体の 1-3.7%) +- ✅ Claude のターン消費削減 (rate-limit 関連の対話が消滅) + +### Negative + +- ⚠️ 旧 Bundle Z2 に対する効果削減 (#D-4 抜きで 25-30% → 1-3.7% に縮小) +- ⚠️ CR 仕様変更 (walkthrough overlay format が変わった等) 時の fragility (regex 依存)。**個人開発向けで仕様変更時に対応する想定** (こちら側で対応する性質ではないため事前ケアしない) + +### Trade-off + +- 開発体験の質的変化 (rate-limit 手動介入消滅) を **token 削減効果より優先** +- #D-4 (応答スタイル) の保留により、潜在 2.5-4M tokens 削減を見送り + +## 別セッションでの実装に必要な情報 + +本 ADR に基づく実装を別セッションで行う場合、以下を参照: + +### 既存の関連コンポーネント + +- **`src/cli-pr-monitor/src/stages/poll.rs`**: 現行 `handle_rate_limit_retry` 実装 (PR #97 Phase 4 land 済)、本 ADR で改修 +- **`src/cli-pr-monitor/src/state.rs`**: state file schema、`rate_limit_last_retriggered_at` 等の dedup フィールド存在 +- **`src/check-ci-coderabbit/`**: Rust 実装、`--list-findings` モード追加先 +- **`src/hooks-session-start/`**: SessionStart hook、recovery 起動の起点 +- **`~/.claude/rules/common/git-workflow.md`**: #D-1 追記先 (global rule、本リポジトリ外) + +### 関連 ADR + +- **ADR-018**: cli-pr-monitor takt 化 (本 ADR で部分改訂、rate-limit retry セクション追加) +- **ADR-009**: 旧 Post-PR Monitor 設計 (Superseded by ADR-018 partial、本 ADR で navigation 注記追加) +- **ADR-022**: 自動化コンポーネントの責務分離原則 (#D-3 の Rust 側実装が ADR-022 に整合) +- **ADR-026**: Cargo workspace (`check-ci-coderabbit` は既存 member、`--list-findings` 追加で member 構成変更不要) +- **ADR-030**: Deterministic post-merge-feedback (`.failed` marker パターンを recovery 設計の参考にする) + +### 関連 memory + +- `project_coderabbit_rate_limit_overlay.md`: rate-limit 検出ロジックの根拠 (PR #99 で実証された walkthrough overlay 仕様) +- `project_coderabbit_auto_resolve.md`: `resolved:` reply での auto-resolve 挙動 + +### todo.md / todo4.md エントリ + +- `docs/todo.md` 推奨実行順序サマリー: 順位 42-45 (Bundle a 4 component) +- `docs/todo4.md`: + - cli-pr-monitor の rate-limit auto-retry + `@coderabbitai review` auto-trigger 実装 (PR #99 T2-4) + - ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 (PR #99 T3-5) + - 本 ADR で追加される #D-1 / #D-3 entry も別セッションで todo4.md に追記が必要 + +### 新セッションで最初に確認すべきこと + +1. `git log --oneline -5` で master の最新状態を確認 (Bundle Z Phase 2/3 が land 済か等) +2. `docs/todo.md` の Bundle a 関連 entry (順位 42-45) を読む +3. `docs/todo4.md` の Bundle a 詳細 entry を読む +4. 本 ADR (ADR-034) を読む +5. memory `project_coderabbit_rate_limit_overlay.md` を読む +6. **どの Sub-PR を実施するか確認**: Sub-PR 1 (#D-1 + #D-3) と Sub-PR 2 (rate-limit auto-retry + ADR-018 改訂) のどちらから着手か (推奨は Sub-PR 1 先行) + +### 完了条件 + +- Sub-PR 1 + Sub-PR 2 が両方 land +- ADR-018 に rate-limit retry ポリシーが明文化される (本 ADR の設計詳細を反映) +- dogfood で 1-2 PR 試験運用、rate-limit 自動回復が観測される +- ユーザー手動介入 (`@coderabbitai review` 投稿等) が 0 になる +- 本 ADR のステータスを「承認済み」に変更 + +## 将来の検討事項 + +### #D-4 (Claude 応答スタイル簡素化) の再評価条件 + +Bundle Z Phase 2/3 (#B-β / #B-γ) 完了後、以下が確立した時点で慎重 pilot を実施: + +- **副作用観測手段**: session 比較メトリクス (思考品質 proxy 指標 = 再 grep / 再 read 頻度の変化、修正回数の変化等) +- **段階的展開**: rule を一気に書かず、1 種類ずつ (Insight ブロック → 完了報告 → 分析テーブル) 試す +- **dogfood 比較**: 同種 PR を rule あり / なしで比較し、token 削減量と思考品質の trade-off を定量化 + +これらが揃わない限り、#D-4 は保留継続。 + +### Bundle a 着手時の前提条件 reality check + +- CR の rate-limit 仕様が変わっていないか (memory `project_coderabbit_rate_limit_overlay.md` の挙動が再現するか) を着手前に dogfood で確認 +- `gh api` の rate-limit (CR とは別、GitHub API 側) が干渉しないか観察 + +## References + +- ADR-018: cli-pr-monitor takt 化 +- ADR-009: 旧 Post-PR Monitor (Superseded by ADR-018 partial) +- ADR-022: 自動化コンポーネントの責務分離原則 +- ADR-026: Cargo workspace +- ADR-030: Deterministic post-merge-feedback +- `docs/pipeline-token-efficiency.md` #D セクション (採用判定改訂 2026-05-02) +- memory `project_coderabbit_rate_limit_overlay.md` +- PR #99 (本 ADR の起源、cli-pr-monitor の rate-limit detection gap が顕在化したセッション) diff --git a/docs/pipeline-token-efficiency.md b/docs/pipeline-token-efficiency.md index 06862c8d..78cf0f95 100644 --- a/docs/pipeline-token-efficiency.md +++ b/docs/pipeline-token-efficiency.md @@ -425,6 +425,8 @@ fix step が "All applicable findings fixed" を report に明記した場合、 ## #D: CR review query / Claude 応答スタイル > **背景**: `gh pr` / `gh api` 関連 query 76-82 回 / 303KB chars / max 47KB が Bash tool_result の最大カテゴリ。Claude (私自身) の text-only 応答が 8.5M cache_creation tokens (全体の 62%) を占める。 +> +> **採用判定 (2026-05-02、PR #99 セッション末)**: Bundle Z2 を再構成し、**#D-1 + #D-3 を Bundle a に統合**、**#D-2 は取り下げ** (#D-3 で代替)、**#D-4 は保留** (思考連続性低下リスク、Bundle Z Phase 2/3 完了後の副作用観測手段確立後に再評価)。設計根拠は ADR-034 参照。 ### 調査結果 @@ -475,7 +477,7 @@ fix step が "All applicable findings fixed" を report に明記した場合、 ### 改善案 -#### #D-1: gh CLI 使用ルールの定型化 — `~/.claude/rules/common/git-workflow.md` +#### #D-1: gh CLI 使用ルールの定型化 — `~/.claude/rules/common/git-workflow.md` ✅ **採用 (Bundle a 統合、2026-05-02)** 私 (Claude) が gh CLI を使うときの定型パターンをルール化: @@ -519,7 +521,7 @@ gh pr view 97 --json reviews --jq '.reviews | map({commit: .commit.oid[:8], stat **リスク**: ルール量が増えると AI が読み込まないリスク。`git-workflow.md` の既存セクションに追記する形で目立たせる工夫必要。 -#### #D-2: `pnpm cr:findings ` wrapper script 追加 +#### #D-2: `pnpm cr:findings ` wrapper script 追加 ❌ **取り下げ (2026-05-02、#D-3 で代替可能のため機能重複)** CR findings を私が読みやすい形で取得する shell/Node script を追加: @@ -541,7 +543,7 @@ Unresolved findings (4): - effort: S (Node/Bash script + jq クエリ) - ROI: 高 (CR review listing の繰り返し作業を 1 コマンド化) -#### #D-3: `check-ci-coderabbit --list-findings` モード追加 +#### #D-3: `check-ci-coderabbit --list-findings` モード追加 ✅ **採用 (Bundle a 統合、2026-05-02)** Rust 側で構造化 findings JSON を生成 (元案 #7 の再掲): @@ -563,7 +565,13 @@ $ check-ci-coderabbit.exe --list-findings --pr 97 **リスク**: 既存の cli-pr-monitor / check-ci-coderabbit の責務分離 (ADR-022) に抵触しないか要確認。 -#### #D-4: Claude 応答スタイルの簡素化 — `~/.claude/rules/common/coding-style.md` または専用 rule +#### #D-4: Claude 応答スタイルの簡素化 — `~/.claude/rules/common/coding-style.md` または専用 rule ⏸️ **保留 (2026-05-02)** + +**保留理由** (PR #99 セッション末のユーザー判断): + +- **思考連続性低下リスク**: 中間出力 (Insight ブロック / 完了報告 / 分析テーブル) は後続 turn の cache に乗り、Claude が「これまでの判断」を参照するソース。削減すると後段で context 再構築 (再 grep / 再 read) を招き、token カテゴリが入れ替わるだけで正味削減が縮む可能性 +- **副作用観測手段が未確立**: ルール導入で実際にどれだけ削減 / どれだけ思考品質低下するかの定量比較が困難 +- **再評価条件**: Bundle Z Phase 2/3 (#B-β / #B-γ) 完了後、副作用観測手段 (例: session 比較メトリクス、思考品質 proxy 指標) が確立してから慎重 pilot 私自身の text-only 応答パターンを抑制するガイドライン: @@ -594,22 +602,24 @@ $ check-ci-coderabbit.exe --list-findings --pr 97 - ユーザーへの説明不足で意図が伝わらない可能性 - explanatory mode との緊張 (Insight 削減 vs 教育的応答) -### 採用判定 +### 採用判定 (2026-05-02 改訂、PR #99 セッション末のユーザー判断) -| 改善案 | ROI | 実装コスト | 推奨 | -|---|---|---|---| -| **#D-1** gh CLI 規則 | ★★★★ | XS (rule 追記) | **即実施** | -| **#D-4** 応答スタイル簡素化 | ★★★★★ | S (rule 追記) | **即実施** | -| #D-2 pnpm cr:findings wrapper | ★★★ | S (script) | 中期 | -| #D-3 Rust findings mode | ★★★ | M (Rust) | 長期 | +| 改善案 | ROI | 実装コスト | 採用判定 | 移行先 | +|---|---|---|---|---| +| **#D-1** gh CLI 規則 | ★★★★ | XS (rule 追記) | ✅ **採用** | Bundle a Sub-PR 1 | +| **#D-3** Rust findings mode | ★★★ | M (Rust) | ✅ **採用** (cli-pr-monitor 連携で価値増) | Bundle a Sub-PR 1 | +| ~~#D-2~~ pnpm cr:findings wrapper | — | S | ❌ **取り下げ** | #D-3 で代替 | +| ~~#D-4~~ 応答スタイル簡素化 | — | S | ⏸️ **保留** | Bundle Z Phase 2/3 完了後に再評価 | -**Bundle 案 (Bundle Z2?)**: #D-1 + #D-4 を **1 PR で `~/.claude/rules/` に追加** 推奨。effort 合計 S。 +**Bundle 移行**: 旧 Bundle Z2 (#D-1 + #D-4) を再構成し、#D-1 + #D-3 を Bundle a (PR #99 post-merge-feedback 由来、cli-pr-monitor の rate-limit auto-retry + ADR 明文化と統合) に組み込む。設計根拠と実装方針は **ADR-034** 参照。 + +**期待累積効果 (Bundle Y2 + 縮小 Z2 統合、2026-05-02 改訂)**: -**期待累積効果 (Bundle Y2 + Z2 統合)**: - #A-1 + #C-1 (haiku 化): session あたり 15-20 分削減 + token 大削減 -- #D-1 + #D-4 (gh + 応答ルール): cache_creation **3-4M tokens 削減** (全体の 25-30%) +- #D-1 + #D-3 (Bundle a 統合): cache_creation **~150-500K tokens 削減 (1-3.7%)** + rate-limit 自動回復で手動介入消滅 - Bundle Z 再編 (#B-α + #B-β + #B-γ、3 Phase 分割): pre-push iter 数を **1-iter 固定** に構造化 (outlier 率 1/6 (16.7%) → 0% 試算) -- **合計**: rate-limit 90% 消費が 60-70% に下がる試算 (要 dogfood 確認) +- #D-4 保留分: 約 **2.5-4M tokens** の潜在削減余地 (Bundle Z Phase 2/3 完了後に副作用観測手段確立後の再評価対象) +- **合計**: rate-limit 90% 消費が ~75% / 3h に下がる試算 (#D-4 抜き、Bundle Z 完了込み) --- @@ -623,7 +633,8 @@ $ check-ci-coderabbit.exe --list-findings --pr 97 |---|---|---|---| | **Bundle Y2** | #A-1 + #C-1 (analyze facets を haiku 化、aggregate/fix/supervise は sonnet 維持) | XS (yaml 4 行) | 最即効 | | **Bundle Z (再編)** | #B-α + #B-β + #B-γ (アーキテクチャ 3 層: 決定論 comment lint / 制約付き fix / 異常検知 reviewer)、Phase 1〜3 で順次 dogfood | M+M+S (3 Phase 分割) | 段階的 (Phase 1 から) | -| **Bundle Z2** | #D-1 + #D-4 (gh CLI 使用規則 + Claude 応答スタイル簡素化 rules) | S (rules 追記) | 即効 | +| ~~**Bundle Z2**~~ (retire) | 旧案 #D-1 + #D-4 → 再構成: **#D-1 + #D-3 を Bundle a に統合** (PR #99 post-merge-feedback 統合、ADR-034 参照)、**#D-4 は保留** (思考連続性低下リスク、Bundle Z Phase 2/3 完了後に再評価) | — | — | +| **Bundle a** (新規、PR #99 post-merge-feedback 由来) | cli-pr-monitor の rate-limit auto-retry (T2-4) + ADR-018/009 rate-limit retry ポリシー明文化 (T3-5) + #D-1 (gh CLI 規則) + #D-3 (`check-ci-coderabbit --list-findings`) | M+S+XS+M (2 Sub-PR 分割) | 中期 (CR rate-limit 自動回復 + listing token 削減) | ### 期待効果 (Bundle 別) @@ -631,7 +642,9 @@ $ check-ci-coderabbit.exe --list-findings --pr 97 |---|---|---|---| | Y2 | analyze step の sonnet 利用 | session あたり 15-20 分 + sonnet → haiku で **当該 step の token cost 1/3** | post-pr-review / post-merge-feedback の avg time、当該 facets の billable input tokens | | Z (再編) | pre-push-review iter 数を構造的に固定化 | **outlier 0% 達成 + 1-iter ALL APPROVE 90% 超** (旧推定: avg iter 2.5 → 1.5 だったが、決定論層導入で 1-iter 固定が target に格上げ) | pre-push-review iter 分布 (`{1×N}` 集中度)、6-iter outlier 発生率 (target 0%)、1-iter ALL APPROVE 率 | -| Z2 | gh CLI noise + text-only response | cache_creation **3-4M tokens 削減** (現在 13.6M の 25-30%) | gh tool_result avg/max chars、text-only turn の cache_creation 占有率 | +| ~~Z2~~ (retire) | — | — | — | +| Bundle a (#D-1 + #D-3 部分) | gh CLI noise + CR review listing 重複 metadata | cache_creation **~150-500K tokens 削減** (#D-1 で gh tool_result ~70KB 削減 + #D-3 で `gh api` 重複取得消滅) + rate-limit 自動回復によるユーザー手動介入消滅 | gh tool_result avg/max chars、cli-pr-monitor の rate-limit auto-trigger 投稿成功率、CR review listing token 量比較 | +| #D-4 (保留分) | Claude text-only response (8.5M tokens、cache_creation 62%) | 潜在 **2.5-4M tokens 削減** (18-29%)、ただし副作用観測手段確立後に再評価 | Bundle Z Phase 2/3 完了後に session 比較メトリクスを設計 | ### 統合効果試算 @@ -640,10 +653,12 @@ $ check-ci-coderabbit.exe --list-findings --pr 97 - takt パイプライン総時間: **114.7 分** (セッション 63%) - rate-limit 90% を 3 時間で消費 -3 Bundle 全実装後の試算: -- 一意 cache_creation: **9-10M tokens** (Y2 + Z2 合計で 25-35% 削減) -- takt パイプライン総時間: **80-95 分** (Z + Y2 で 25-30% 短縮) -- rate-limit 消費: 90% / 3h → **60-70% / 3h** 試算 +Bundle Y2 + Z + a 全実装後の試算 (2026-05-02 改訂、#D-4 保留により縮小): + +- 一意 cache_creation: **11-12M tokens** (Y2 + Bundle a #D-1 + #D-3 で 10-15% 削減、#D-4 抜き) +- takt パイプライン総時間: **80-95 分** (Z + Y2 で 25-30% 短縮、Bundle Z Phase 2/3 で outlier 0% に収束) +- rate-limit 消費: 90% / 3h → **75% / 3h** 試算 (#D-4 込みなら 60-70% に到達余地) +- Bundle a によるユーザー手動介入: **rate-limit 解除待ち + `@coderabbitai review` 投稿が完全自動化** **注**: 上記は **各効果が独立加法的** との仮定。実際は中間効果が打ち消される可能性あり。dogfood 1-2 セッションで実測必須。 @@ -766,10 +781,10 @@ docs/pipeline-token-efficiency.md の「全体統合: Bundle 群の累積効果 | #C-1 analyze haiku 化 | 採用済 (Bundle Y2) | 2026-05-01 | #98 | | #C-2 Iter 3 短絡 | 検討 | - | - | | #C-3 rate-limit skip | 計画 | - | - | -| #D-1 gh CLI 規則 | 計画 | - | - | -| #D-2 pnpm cr:findings wrapper | 検討 | - | - | -| #D-3 Rust findings mode | 検討 | - | - | -| #D-4 応答スタイル簡素化 | 計画 | - | - | +| #D-1 gh CLI 規則 | 採用 (Bundle a Sub-PR 1) | 2026-05-02 | - | +| ~~#D-2 pnpm cr:findings wrapper~~ | 取り下げ (#D-3 で代替) | 2026-05-02 | — | +| #D-3 Rust findings mode | 採用 (Bundle a Sub-PR 1) | 2026-05-02 | - | +| ~~#D-4 応答スタイル簡素化~~ | 保留 (Bundle Z Phase 2/3 完了後再評価、ADR-034) | 2026-05-02 | — | --- diff --git a/docs/todo.md b/docs/todo.md index 44db56af..f678380d 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -55,6 +55,10 @@ | 39 | 🚀 Tier 1 | **takt workflow `model` フィールド必須化 lint rule (PR #98 T1-1)** | todo4.md | S | なし (Bundle Y2 完全性: post-pr-review.yaml supervise step の `model:` 欠落を契機に決定論的防止層を追加) | | 40 | 🚀 Tier 1 | **prepare-pr skill Step 1 bookmark 存在チェック強化 (PR #98 T1-2)** | todo4.md | XS | なし (本セッション再現の push 失敗を Step 1 fallback で早期検出。skill repo 側更新) | | 41 | 🔧 Tier 2 | **Bundle Y2 効果の定量計測 — post-merge-feedback / post-pr-review の avg time 比較 (PR #98 T2-2)** | todo4.md | M | なし (PR #97 sonnet baseline vs PR #98 以降 haiku の実測比較。Bundle Z / Z2 の ROI 判断材料、PR #98 merge 後 3-5 PR の観察ベース) | +| 42 | 🔧 Tier 2 | **cli-pr-monitor の rate-limit auto-retry + `@coderabbitai review` auto-trigger 実装 (PR #99 T2-4) ★ Bundle a Sub-PR 2** | todo4.md | M | 順位 45 と同 PR (Sub-PR 2、Sub-PR 1 の `--list-findings` API を消費) | +| 43 | 💎 Tier 3 | **ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 (PR #99 T3-5) ★ Bundle a Sub-PR 2** | todo4.md | S | 順位 42 と同 PR (Sub-PR 2 内、実装と ADR の整合確保) | +| 44 | 💎 Tier 3 | **gh CLI 使用規則を `~/.claude/rules/common/git-workflow.md` に追記 (計画書 #D-1) ★ Bundle a Sub-PR 1** | todo4.md | XS | なし (Sub-PR 1、Sub-PR 2 でも `gh api` を使うため先行 land 推奨) | +| 45 | 🔧 Tier 2 | **`check-ci-coderabbit --list-findings` Rust モード追加 (計画書 #D-3) ★ Bundle a Sub-PR 1** | todo4.md | M | なし (Sub-PR 1、cli-pr-monitor が消費する構造化 findings API を提供) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 @@ -72,6 +76,10 @@ **Bundle W (PBT + 型強化) は PR #96 で実証された flaky 実装防御の最上層**。Finding D (`saturating_sub` の silent semantic mismatch) と E (concurrency test の guard 即 drop) はどちらも「Rust 的に正しいコードがドメイン的に間違う」典型例で、advisor + takt-fix の 2 layer も貫通した。**仕様を proptest properties で明文化 + `PastTime` 等の型で invalid state を unrepresentable に** することで、ルール (ask-based) では塞げない bug class を構造的に排除する。**rate-limit 自動検出 (Phase 4 で land 済) / takt REJECT-ESCALATE を先行**し、その後 Bundle W に着手する流れがユーザー指示。 **Bundle X (cargo-mutants + stress runner) は Bundle W の後付け検証層**。L2 post-PR で変更 crate + 1-hop 依存に cargo-mutants を走らせ test の弱さを直接測定、L1 pre-push で concurrency stress N=100 を回し scheduling race を sampling。Bundle W で書いた spec / 型を後段で機械的に検証する補完関係。**L3 weekly cargo-mutants workspace 全体 + stress N=1000 は ADR-031 Phase B 週次レビューと bundle 化** することで long-tail flake と coverage 全体監査を week 単位で audit する layer に統合。 **PR #98 (Bundle Y2) post-merge-feedback 反映 (2026-05-01)**: 3 件の follow-up task を追加。**takt workflow `model` フィールド必須化 lint rule** と **Bundle Y2 効果の定量計測** は Bundle Y2 完全性確保 + ROI 検証で同系列 (lint rule 着手時に post-pr-review.yaml supervise step への `model: sonnet` 明示追加を同 PR に含める想定)。**prepare-pr skill Step 1 bookmark 存在チェック強化** は本セッション運用痛 (bookmark 未作成 push 失敗) から派生した独立 task で skill repository 側の更新となる。 +**Bundle a (PR #99 post-merge-feedback 反映、2026-05-02 拡張)**: 4 component を **2 Sub-PR で分割** land 推奨 (設計根拠は ADR-034)。共通テーマは「PR #99 で複数回発生した手動 `@coderabbitai review` 投稿の自動化」 + 「CR review query の token bloat 削減」。Bundle Y2 効果でパイプラインが加速した結果として CR rate-limit 発生頻度が増えた逆説的副作用への対策。effort 合計 M+S+XS+M (= 2 Sub-PR で M、M+S 程度に分散)。 + +- **Sub-PR 1 (token 削減層、先行)**: **gh CLI 使用規則** (`git-workflow.md` 追記) + **`check-ci-coderabbit --list-findings`** (Rust モード、cli-pr-monitor 連携 API 提供)。旧 Bundle Z2 の `#D-1` + `#D-3` を本 Bundle に統合 (旧 `#D-2` は `#D-3` で代替のため取り下げ、旧 `#D-4` は思考連続性懸念で保留、ADR-034 参照) +- **Sub-PR 2 (rate-limit 自動化層、主軸)**: **cli-pr-monitor の rate-limit auto-retry** (Sub-PR 1 の `--list-findings` API を消費) + **ADR-018 / ADR-009 の rate-limit retry ポリシー明文化**。session 超え recovery / walkthrough overlay 検出 / 解除 + 1 分マージン投稿の設計詳細は ADR-034 --- diff --git a/docs/todo4.md b/docs/todo4.md index 435cd986..0aced20d 100644 --- a/docs/todo4.md +++ b/docs/todo4.md @@ -381,3 +381,196 @@ #### 詰まっている箇所 - 計測期間 3-5 PR の間に rate-limit 不安定期 / 大規模変更 PR / docs-only PR が混在すると平均値の比較ノイズが大きい。中央値での比較や PR 性質による normalization 方式を着手時に検討。 + +--- + +### cli-pr-monitor の rate-limit auto-retry + `@coderabbitai review` auto-trigger 実装 (PR #99 T2-4) + +> **動機**: PR #99 で CR rate-limit が **複数回** 発生し、解除後の `@coderabbitai review` 再投稿が **手動必要** だった。Bundle Y2 効果でパイプラインが加速 (pre-push + post-pr takt が 1〜2m/iter) した結果、CR への commit push 頻度が増えて rate-limit に達しやすくなった逆説的副作用。本セッションで実施した手順 (1) walkthrough comment の `updated_at` から解除時刻計算 → (2) sleep + 1 分 → (3) `@coderabbitai review` 投稿 → (4) Round N+1 review trigger 確認、を `cli-pr-monitor` 内で全自動化する。 +> +> **本タスクの位置づけ**: Bundle a の **実装層**。ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 と同 PR で land 推奨 (実装と設計判断の整合確保)。Phase 4 (PR #97) で land された `handle_rate_limit_retry` は既存だが、検出 gap (review state = `not_found` 時に rate-limit を見落とす、本セッション中盤で確認) と auto-trigger 不発の改善が必要。 +> +> **参照**: `.claude/feedback-reports/99.md` Tier 2 #4、本セッション内のユーザー要望「全自動化したい」、PR #97 Phase 4 で land された rate-limit auto-retry の検出ロジック gap 観測 +> +> **実行優先度**: 🔧 **Tier 2** — Effort Medium。本セッションで明示された運用痛 (手動 `@coderabbitai review` 投稿が複数回必要) への直接対策。 + +#### 設計決定 (案) + +- **検出ロジック改善** (本セッションで判明した gap): + - CR rate-limit は **walkthrough comment (PR の最初の CR comment) を上書き** する形で表現される (memory `project_coderabbit_rate_limit_overlay.md` 参照) + - 既存の `state.rate_limit` 検出は review state = `not_found` 時に rate-limit overlay を見落とす可能性 + - 修正: walkthrough comment の body content + `updated_at` を直接 polling し、`Rate limit exceeded` パターンを検出 +- **解除時刻計算**: + - body 内の `Please wait N minutes and M seconds` を regex 抽出 + - `updated_at` + N min M s = 解除予定時刻 + - 解除 + 1 分後を auto-trigger 時刻として設定 (本セッションで実証された安全マージン) +- **auto-trigger 実装**: + - `cli-pr-monitor` に sleep + retry スケジューラ追加 (Rust `tokio` or `std::thread::sleep` ベース) + - sleep 中に session を超えても良いように `.claude/cli-pr-monitor-state.json` に解除予定時刻を永続化 + - 解除後 `gh api -X POST issues/N/comments -f body='@coderabbitai review' > /dev/null 2>&1` を実行 + - state を更新して再 polling 開始 +- **Budget 管理**: + - 既存の `max_duration_secs` (監視残り予算) と sleep 時間の比較ロジックは継続使用 + - sleep が予算超過する場合は `.claude/cli-pr-monitor-state.json` に「次セッションで再開」フラグを書いて exit、SessionStart hook で recovery + +#### 作業計画 + +- [ ] `cli-pr-monitor` の rate-limit detection ロジックを walkthrough comment ベースに改善 (review state non-依存) +- [ ] body 内 `Please wait N minutes and M seconds` パターン抽出ロジック追加 +- [ ] sleep + auto-trigger スケジューラ実装 (session 超え対応含む) +- [ ] `.claude/cli-pr-monitor-state.json` schema 拡張 (rate_limit_unlock_at, scheduled_retry_post 等) +- [ ] integration test: 模擬 rate-limit comment を walkthrough に置いて auto-trigger が発火するか確認 +- [ ] dogfood: 実 PR で rate-limit を引き起こして自動回復を観察 (1〜2 PR) +- [ ] 本 todo4.md エントリを削除 + +#### 完了基準 + +- CR rate-limit 発生時に walkthrough comment overlay が確実に検出される (review state = not_found でも) +- 解除予定時刻の 1 分後に `@coderabbitai review` が自動投稿される (session 超え含む) +- 手動 `@coderabbitai review` 投稿は不要になる (PR #99 セッションで観測された運用痛の解消) +- ADR-018 / ADR-009 (Bundle a 同 PR) で設計判断が文書化される + +#### 詰まっている箇所 + +- session 超え auto-trigger の機構選定: `cli-pr-monitor` 自身が長時間 sleep して投稿するか、SessionStart hook + state file 経由で次セッション起動時に recovery するか — 運用パターンを着手時に評価。 +- 既存 `handle_rate_limit_retry` (PR #97 Phase 4) との関係整理: 既存ロジックを拡張するか、新ロジックに置き換えるか。 + +--- + +### ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 (PR #99 T3-5) + +> **動機**: 現状の `cli-pr-monitor` 設計では rate-limit recovery が partial (PR #97 Phase 4 で land された `handle_rate_limit_retry` はあるが detection gap あり)、かつ設計判断が ADR に明文化されていないため、改修時の判断基準が不明瞭。本タスクで設計判断を ADR に記録し、cli-pr-monitor の rate-limit auto-retry 実装と整合させる。 +> +> **本タスクの位置づけ**: Bundle a の **設計判断層**。cli-pr-monitor の rate-limit auto-retry 実装 と同 PR で land 推奨。実装変更時の判断軸として後続改修者が参照する。 +> +> **参照**: `.claude/feedback-reports/99.md` Tier 3 #5、ADR-018 (cli-pr-monitor takt 化)、ADR-009 (Post-PR Monitor 旧設計、Superseded by ADR-018 部分あり) +> +> **実行優先度**: 💎 **Tier 3** — Effort Small。実装 (Bundle a 実装層) と同 PR で同時 land。 + +#### 設計決定 (案) + +- **記述する内容**: + - rate-limit detection の 2 層構造: review state ベース (既存) + walkthrough comment overlay ベース (新規追加、本タスクで明文化) + - backoff 戦略: 解除予定時刻 + 1 分の安全マージン (本セッションで実証) + - auto-trigger 投稿の冪等性確保: `state.rate_limit_last_retriggered_at` での dedup (PR #97 Phase 4 で実装済) + - `X-RateLimit-Remaining` ヘッダー監視は **対象外** (CR API は public ではないため)。walkthrough comment body parsing で代替 + - session 超え recovery: `.claude/cli-pr-monitor-state.json` の `rate_limit_unlock_at` フィールドを SessionStart hook が読み、補完的に auto-trigger +- **追記先**: + - 主: ADR-018 (cli-pr-monitor takt 移行、rate-limit auto-retry の主体) に追記 + - 従: ADR-009 (Post-PR Monitor 旧設計) は Superseded 部分の補足として「rate-limit retry ポリシーは ADR-018 で明文化」と navigation コメントを追加 +- **整合確保**: + - 実装 PR (Bundle a 実装層) と同コミット範囲で land、ADR の記述と実コードが一致することを保証 + +#### 作業計画 + +- [ ] ADR-018 に「rate-limit detection / retry / auto-trigger」セクション追加 +- [ ] ADR-009 に navigation 注記追加 (rate-limit 関連は ADR-018 を参照) +- [ ] 実装 (Bundle a 実装層) と同 PR で land、CodeRabbit / pre-push-review で整合性を check +- [ ] 本 todo4.md エントリを削除 + +#### 完了基準 + +- ADR-018 に rate-limit retry ポリシーが明記される +- 実装と ADR の記述が同期 (新たな乖離リスクなし) +- 後続改修者が ADR-018 を読めば改修方針を判断できる + +#### 詰まっている箇所 + +- なし (Effort Small、ADR-018 への追記のみで完結)。実装 (Bundle a 実装層) の設計確定後に着手するのが効率的。 + +--- + +### gh CLI 使用規則を `~/.claude/rules/common/git-workflow.md` に追記 (計画書 #D-1) + +> **動機**: PR #97 / #99 セッションで観測された gh tool_result の token bloat (POST 応答 24KB / GET 過剰 metadata 44KB) を rule で構造的に抑制する。具体的には (1) POST 操作の応答破棄漏れ (`gh api .../replies` で `> /dev/null 2>&1` 漏れによる 24KB context 汚染)、(2) GET 操作で `--jq` filter 不使用による生 JSON 全取得、(3) `gh pr view --json comments` の CR walkthrough base64 internal state 混入 — の 3 パターン。 +> +> **本タスクの位置づけ**: Bundle a の **Sub-PR 1 token 削減層**。`check-ci-coderabbit --list-findings` Rust 実装 と同 PR で land 推奨。global rule (`~/.claude/rules/common/git-workflow.md`) への追記のため本リポジトリ scope 外だが、開発体験への影響は本リポジトリで主に発生。 +> +> **参照**: ADR-034 (CodeRabbit 監視・対話の自動化戦略)、`docs/pipeline-token-efficiency.md` #D-1 セクション、PR #99 セッションで実証された rate-limit overlay (memory `project_coderabbit_rate_limit_overlay.md`) +> +> **実行優先度**: 💎 **Tier 3** — Effort XS。rule 追記のみ。Sub-PR 2 (cli-pr-monitor の rate-limit auto-retry) でも `gh api` を使うため Sub-PR 1 で先行 land 推奨。 + +#### 設計決定 (案) + +- **追記先**: `~/.claude/rules/common/git-workflow.md` の既存セクションに追加 (新規ファイル作成は避け、navigation 性確保) +- **記述する 3 規則**: + - **POST 操作 (作成・更新)**: 応答 body は破棄する (`gh api -X POST .../replies -f body='...' > /dev/null 2>&1`)。success/fail は exit code で判別 + - **GET 操作 (取得)**: `--jq` で必要 field のみ抽出する (`gh api .../comments --jq '.[] | {created_at, body_first: .body[:200]}'` 等) + - **CR walkthrough 除外**: `gh pr view --json reviews,comments` の `comments` field に CR walkthrough の base64 internal state が含まれる (1 PR で 30KB+) ため、確認時は `--jq 'del(.comments[].body)'` 等で除外 +- **記述スタイル**: BAD / GOOD のコード例ペアを併記 (既存 git-workflow.md の他セクションと整合) + +#### 作業計画 + +- [ ] `~/.claude/rules/common/git-workflow.md` の既存構造を確認し追記位置を選定 +- [ ] 3 規則 (POST 応答破棄 / GET --jq / CR walkthrough 除外) を BAD/GOOD コード例つきで追記 +- [ ] 本リポジトリでの dogfood: 1〜2 PR で実際に新規則に従って `gh api` を使い、token 削減を実測 +- [ ] 派生プロジェクト (techbook-ledger / auto-review-fix-vc) への global rule 反映確認 (rule は global なので自動的に適用、deploy 不要) +- [ ] 本 todo4.md エントリを削除 + +#### 完了基準 + +- `~/.claude/rules/common/git-workflow.md` に 3 規則が追記される +- dogfood 1〜2 PR で gh tool_result avg/max chars が削減されることを実測 (現状 max 47KB → 目標 10KB 以内) +- POST 応答 24KB の context 汚染が消失 + +#### 詰まっている箇所 + +- なし (Effort XS、global rule への追記のみで完結)。Sub-PR 1 の `check-ci-coderabbit --list-findings` 実装と同 PR で land する想定。 + +--- + +### `check-ci-coderabbit --list-findings` Rust モード追加 (計画書 #D-3) + +> **動機**: CR review listing で `gh api .../pulls/N/reviews` + `pulls/N/comments` の重複取得が発生し、44KB 級の生 metadata が context に乗る (cache_creation 9x で 約 400K tokens 蓄積)。Rust 側で構造化 findings JSON を一度で取得することで、`gh api` 重複呼び出しを消滅させる。加えて、Bundle a Sub-PR 2 (cli-pr-monitor の rate-limit auto-retry) が同 API を消費する設計のため、Sub-PR 1 で先行実装が必要。 +> +> **本タスクの位置づけ**: Bundle a の **Sub-PR 1 token 削減層 (cli-pr-monitor 連携 API 提供)**。gh CLI 使用規則追記 と同 PR で land 推奨。Sub-PR 2 (rate-limit auto-retry 実装) の前提条件。 +> +> **参照**: ADR-034 (CodeRabbit 監視・対話の自動化戦略)、`docs/pipeline-token-efficiency.md` #D-3 セクション、ADR-022 (自動化コンポーネントの責務分離原則 — Rust 側実装が ADR-022 と整合する根拠) +> +> **実行優先度**: 🔧 **Tier 2** — Effort Medium。Rust 実装 + テスト。`check-ci-coderabbit` crate (既存) への mode 追加で、新 crate 作成は不要 (ADR-026 Cargo workspace member 構成変更なし)。 + +#### 設計決定 (案) + +- **追加先**: `src/check-ci-coderabbit/` (既存 crate) +- **CLI**: `check-ci-coderabbit.exe --list-findings --pr ` で構造化 JSON を stdout 出力 +- **JSON schema (案)**: + + ```json + { + "findings": [ + {"severity": "major", "file": "src/.../main.rs", "line": 415, "summary": "...", "url": "..."} + ] + } + ``` + +- **入力ソース**: `gh api .../pulls/N/comments` + `pulls/N/reviews` を内部的に呼び、重複 metadata を除去して構造化 +- **severity 抽出**: CR の `_⚠️ Potential issue_ | _🔴 Critical_` 等のパターンから抽出 (Critical / Major / Minor / Nitpick の 4 段階) +- **outdated 解釈**: `in_reply_to_id` を辿って `resolved:` reply のあるスレッドを除外 +- **cli-pr-monitor からの消費**: Sub-PR 2 で `cli-pr-monitor` が本コマンドを spawn、構造化 findings を読んで rate-limit auto-retry のロジックに統合 +- **既存 `check-ci-coderabbit` の他モード** (CI 状態 check 等) との関係: 既存モードは保持、`--list-findings` が新規 sub-command として追加 + +#### 作業計画 + +- [ ] `src/check-ci-coderabbit/` の既存 CLI 構造を確認 (clap 定義、既存 sub-command の有無) +- [ ] `--list-findings --pr ` sub-command を追加 +- [ ] `gh api` 呼び出しを内部実装 (既存 `runner::run_gh_quiet` 等を流用) +- [ ] severity 抽出ロジック (regex で `Potential issue \| 🔴 Critical` 等のパターン) +- [ ] outdated 解釈ロジック (resolved reply のスレッド除外) +- [ ] 単体テスト (sample CR review JSON を fixture として配置、severity 抽出 / outdated 解釈の網羅) +- [ ] `package.json` の `build:check-ci-coderabbit` で release exe 生成 (既存 script、変更不要) +- [ ] dogfood: 1〜2 PR で `pnpm cr:findings ` 相当の動作を確認 (本 PR ではなく実 PR で smoke test) +- [ ] cli-pr-monitor (Sub-PR 2) からの消費を統合 (Sub-PR 2 のスコープだが、本 task の API 設計時に呼び出し側の interface も合わせて確定) +- [ ] 本 todo4.md エントリを削除 + +#### 完了基準 + +- `check-ci-coderabbit.exe --list-findings --pr ` で JSON 出力が得られる +- severity / file / line / summary / url の 5 field が揃う +- 単体テストで sample fixture から正しく findings を抽出 +- Sub-PR 2 の cli-pr-monitor が本 API を呼んで rate-limit auto-retry のロジックを完成させる +- gh api 重複取得が消滅し、CR review listing token 量が削減される (現状 4 round 計 ~20KB → 目標 ~5KB) + +#### 詰まっている箇所 + +- CR の review body format が将来変わった場合の severity 抽出 fragility (regex 依存)。**個人開発向けで仕様変更時に対応する想定** (ADR-034 の方針と整合) +- `in_reply_to_id` chain の outdated 解釈で false negative (resolved reply があるのに findings に残る) や false positive (resolved 扱いのものを未対応として出力) のチューニングが必要 — 着手時に実 CR data で評価。