From 480eeceab8abce601127689e6cb7b4903d0668a8 Mon Sep 17 00:00:00 2001 From: aloekun Date: Mon, 4 May 2026 14:35:57 +0900 Subject: [PATCH 1/5] =?UTF-8?q?docs(todo):=20=E9=A0=86=E4=BD=8D=2059=20(AD?= =?UTF-8?q?R-035=20docs=20=E8=A9=95=E4=BE=A1=E3=83=9D=E3=83=AA=E3=82=B7?= =?UTF-8?q?=E3=83=BC=20/=20PR=20#107=20T3-1)=20=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #107 post-merge-feedback の Tier 3 #1 採用に伴い、docs/todo.md 表と todo5.md 詳細を追加。 - 順位 59 (Tier 3, M): ADR-035 docs 評価ポリシー - docs-only 変更への code review criteria 誤適用を排除する global policy - review-security.md の既存 trust boundary criterion を ADR で集約 - review-simplicity.md / analyze-coderabbit.md にも一貫展開 - false REJECT 削減 + 開発体験劣化抑制 判定根拠 (順位 58 で導入した rubric ベース): - Severity Medium / Frequency Medium / Effort M / Adoption Risk None / ✅ 採用 --- docs/todo.md | 1 + docs/todo5.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) diff --git a/docs/todo.md b/docs/todo.md index 7c82514..83f6752 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -70,6 +70,7 @@ | 55 | 💎 Tier 3 | **config 拡張 + SessionStart catch-up (Bundle b PR-3) ★ Bundle b** | todo5.md | S | 順位 53 / 54 land 後 (固定値の `monitor.toml` 化 + Claude Code 不在時に発火した wakeup を SessionStart で catch-up、AI 不在時の silent loss 防止) | | 56 | 🔧 Tier 2 | **comment-lint hook test 拡充 (PR #104 T2-1+T2-2 bundle)** | todo5.md | S | なし (UTF-8 multi-byte 5 パターン + block comment boundary 6 パターンを `locate_string_line_ranges` / `span_overlaps_ranges` の回帰テストとして体系化、PR #104 Critical/Minor fix の固定化) | | 57 | 🔧 Tier 2 | **Aggregation cap integration test (PR #105 T2-1 採用)** | todo5.md | S | なし (`collect_all_violations` の MAX_VIOLATIONS contract を test 化、将来の lint 追加時に `truncate(MAX)` 削除 regression を防止する explicit 安全網) | +| 59 | 💎 Tier 3 | **ADR-035: docs 評価ポリシー (PR #107 T3-1 採用)** | todo5.md | M | なし (PR #107 dogfood で AI が code review criteria を documentation-only PR に誤適用するパターンを確認、review-security.md の trust boundary criterion を全 reviewer facet に拡張、false REJECT 削減) | **戦略**: 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/todo5.md b/docs/todo5.md index 09463ee..bcf0969 100644 --- a/docs/todo5.md +++ b/docs/todo5.md @@ -399,3 +399,74 @@ - 順位 56 (PR #104 T2-1+T2-2 test 拡充) と同 PR で bundle するか別 PR とするか。両者とも test additions、同ファイル同 test module で scope clean、bundle 推奨。 +--- + +### ADR-035: docs 評価ポリシー (PR #107 T3-1 採用) + +> **動機**: PR #107 (順位 58 = post-merge-feedback rubric format 拡張) の dogfood で、AI reviewer が code-specific review criteria (mutation / error handling / test coverage / function length / DRY 等) を documentation-only 変更に誤適用するパターンが確認された。これにより docs / facet instruction / planning markdown の編集 PR で false REJECT が発生しやすく、開発体験劣化 + token 浪費の原因となる。 +> +> **本タスクの位置づけ**: PR #107 post-merge-feedback Tier 3 #1 採用 (Severity Medium / Frequency Medium / Effort M / Adoption Risk None / ✅ 採用)。`review-security.md` には既に "Docs-only changes: trust boundary criterion" セクションがあり (Bundle Z Phase 3 で導入)、本 task は同パターンを `review-simplicity.md` / `analyze-coderabbit.md` 等の他 reviewer facet にも一貫展開し、global policy として ADR-035 で集約する。 +> +> **参照**: `.claude/feedback-reports/107.md` Tier 3 #1、`.takt/facets/instructions/review-security.md` 既存 trust boundary criterion、PR #106 で追加した Phase 3 review facets +> +> **実行優先度**: 💎 **Tier 3** — Effort M。ADR 1 本 + 既存 facet 横断更新 + 派生プロジェクト展開。 + +#### 設計決定 (案) + +##### ADR の位置づけ + +- 番号: ADR-035 (順位 58 で言及した ADR-035 Paradigm Shift Guidance は採用見送り済、再利用可能) +- 配置: `docs/adr/adr-035-doc-evaluation-policy.md` +- 試験運用フラグなし (定着しているパターンの formalize) + +##### docs-only 変更の判定基準 (ADR で明文化) + +- **path 基準**: 編集ファイルが以下のいずれかに完全に収まる: + - `docs/**`、`*.md` (root README 等を含む) + - `.takt/facets/instructions/**` (facet instruction = AI prompt、コードではない) + - `.takt/workflows/**.yaml` の comment / description フィールドのみ変更 + - source code 内の doc comment (`///` / `//!` / `/** */` 等) のみ変更 +- **diff 内容基準**: executable code logic への変更なし (= AST 上の関数 body / 制御フロー / 変数宣言が不変) +- 両基準を満たす PR を "docs-only" と判定 + +##### 適用される評価ポリシー (docs-only PR の場合) + +- ✅ **適用する criteria**: + - 既存 `review-security.md` の trust boundary criterion (auth policy / permission scope / secret handling / API contract 等が変わるか) + - cross-reference の整合性 (リンク切れ / 廃止された path 参照 / ephemeral artifact への永続参照) + - markdown 構文 / lint (markdownlint で機械検出される範囲) +- ❌ **適用しない criteria** (false REJECT 源泉): + - mutation / immutability check + - error handling / Result / panic safety + - test coverage / test addition 要求 + - function length / nesting depth / complexity metrics + - DRY / YAGNI を code logic 視点で適用 (docs hierarchy / 計画文書例外は維持) + +##### facet instructions への反映 + +- `review-simplicity.md`: 既存 "DRY / YAGNI scope" の例外列挙を ADR-035 を引用する形に圧縮 +- `review-security.md`: 既存 "Docs-only changes: trust boundary criterion" を ADR-035 を引用 + 拡張 +- `analyze-coderabbit.md`: docs-only 判定 + code criteria 除外を新規追加 (PR #107 で発生した CodeRabbit findings の AI 適合性フィルタを支える) + +#### 作業計画 + +- [ ] `docs/adr/adr-035-doc-evaluation-policy.md` を新規作成 (path / diff 内容判定基準 + 適用 / 不適用 criteria リスト + 既存 facet との関係) +- [ ] `CLAUDE.md` の ADR index に ADR-035 を追加 +- [ ] `.takt/facets/instructions/review-simplicity.md` を ADR-035 引用に更新 (既存 DRY / YAGNI scope の docs 例外を ADR で参照) +- [ ] `.takt/facets/instructions/review-security.md` を ADR-035 引用に更新 (既存 trust boundary criterion を ADR-035 のもとへ集約) +- [ ] `.takt/facets/instructions/analyze-coderabbit.md` に docs-only 判定 + code criteria 除外を追加 +- [ ] dogfood: 次の docs-only PR (例: 完了タスク削除のみの PR) で false REJECT が発生しないこと確認 +- [ ] 派生プロジェクト (techbook-ledger / auto-review-fix-vc) の同 facet に展開 +- [ ] 本 todo5.md エントリを削除 + +#### 完了基準 + +- ADR-035 が docs-only 評価ポリシーを single source of truth として確立 +- review-{simplicity, security} + analyze-coderabbit の 3 facets が ADR-035 を参照、code criteria の docs PR への誤適用が構造的に排除 +- docs-only PR の false REJECT 率が 0% 近くに + +#### 詰まっている箇所 + +- "docs-only" の境界判定 (例: facet instruction = AI prompt は code か docs か、yaml の structural 変更 = code か docs か) で AI 解釈が揺れる可能性 → ADR で具体例を 5-10 件列挙して cluster 化を狙う +- 既存 facet との重複削除で意味が変わらないよう注意 (review-security.md trust boundary criterion を ADR-035 に移動した結果、reviewer が docs PR を素通しするバグが発生しないか dogfood で確認) + From 30717b93c36c33aebc8c235946e09881aa7cc138 Mon Sep 17 00:00:00 2001 From: aloekun Date: Mon, 4 May 2026 14:53:36 +0900 Subject: [PATCH 2/5] =?UTF-8?q?docs(efficiency):=20docs-pr-iteration-effic?= =?UTF-8?q?iency.md=20=E3=82=92=E6=96=B0=E8=A6=8F=E4=BD=9C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs-only PR の iteration 改善に関する task 分類・bundle 案を集約する index を docs/ に新規追加。各 task の作業詳細は docs/todo*.md 系列に置き、本ファイル は概要 + リンクに留める設計。 掲載内容: - 現状の課題 / ボトルネック分析 (5 観点) - 改善 task 分類 (HIGH / MEDIUM / LOW IMPACT、合計 12 順位) - 推奨 bundle 案 (Bundle 'docs PR streamline' = 順位 59+31+32 を最優先) - 関連ドキュメント (todo.md / pipeline-token-efficiency.md / ADR-019/027/035) 役割: 試験運用 (bundle が消化されたら役割を終える計画書)。pipeline-token- efficiency.md と並列の領域特化計画書として機能する。 動機: 本セッションで 「docs-only PR の iteration 改善に当たる task をピック アップしてほしい」「毎回この情報を調べるのは手間」 とのユーザー要望に対応。 分析結果を再調査せず参照可能にする。 --- docs/docs-pr-iteration-efficiency.md | 111 +++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/docs-pr-iteration-efficiency.md diff --git a/docs/docs-pr-iteration-efficiency.md b/docs/docs-pr-iteration-efficiency.md new file mode 100644 index 0000000..40bb438 --- /dev/null +++ b/docs/docs-pr-iteration-efficiency.md @@ -0,0 +1,111 @@ +# ドキュメント PR 作業効率改善 + +> **目的**: フィードバックの都度改善内容をドキュメントに反映するため、**docs-only PR を独立して早急にマージできる環境** を確立する。 +> +> **本ドキュメントの役割**: docs-only PR の iteration 改善に関する task 分類・bundle 案を集約する index。各 task の作業詳細は `docs/todo*.md` 系列に置き、本ファイルは概要 + リンクに留める。 +> +> **状態**: 試験運用 (本ドキュメントは "計画書" であり、bundle が消化されたら役割を終える) +> +> **想定読者**: 本リポジトリで docs-only PR を回す際に「どの task が iteration 短縮に効くか」を 1 ページで把握したいユーザー。 + +--- + +## 現状の課題 + +- docs-only PR が次の実装 PR に混ぜてコミットされる傾向 (= 独立 merge せず後回しになる) +- 主因はイテレーションコスト: docs PR 1 本あたり pre-push-review + post-pr-review + post-merge-feedback で 15-30 分かかる +- false REJECT (code-specific criteria を docs PR に誤適用) で iter が増える + +## ボトルネック分析 + +| ボトルネック | 現状 | 改善の方向 | +|---|---|---| +| pre-push-review time | docs-only PR でも全 criteria 適用、5-10 分 | reviewer facet に docs-only fast-approve 拡張 | +| post-pr-review time | CodeRabbit + takt analyze-coderabbit が code criteria を docs PR に誤適用、5-10 分 | analyze-coderabbit にも docs-only filter 拡張 | +| post-merge-feedback time | trivial PR skip で `*.md` only + 1 commit + < 50 行 は skip 済 (PR #102) | 既存条件で十分、追加最適化不要 | +| docs 品質 pre-write | markdown lint が手動、anchor / link drift が後段で発覚 | Stop hook lint + broken-link-check + cross-reference lint を pre-write で機械検出 | +| review false REJECT | reviewer が mutation / error handling / test coverage を docs PR に要求 | docs 評価ポリシー ADR で criteria を構造的に分離 | + +--- + +## 改善 task 分類 + +各 task の詳細 (動機 / 設計決定 / 作業計画 / 完了基準) は `docs/todo*.md` 系列を参照すること。本セクションは概要 + 効果のみ記載。 + +### 🎯 HIGH IMPACT — review acceleration + +| 順位 | Tier | タスク概要 | 効果 | 作業詳細 | +|---|---|---|---|---| +| 59 | 💎 Tier 3 | ADR-035 docs 評価ポリシー (PR #107 T3-1) | **中核**。`review-simplicity.md` / `analyze-coderabbit.md` に docs-only criterion 拡張、code criteria の docs PR 誤適用を排除 | [todo5.md](todo5.md) | +| 31 | 💎 Tier 3 | review-security.md docs-only fast-approve から `.takt/**` と `.claude/**` を明示除外 (Bundle V) | 順位 59 と同領域。fast-approve の対象を**正しく狭める** precision 向上 | [todo3.md](todo3.md) | +| 32 | 💎 Tier 3 | docs/todo.md ヘッダ「新規タスクは追加しない」表記を実態整合 (Bundle V) | 単発 cleanup。CodeRabbit が誤指摘した根因 = 運用ルールの自己矛盾を解消 | [todo3.md](todo3.md) | + +### 🛠 MEDIUM IMPACT — docs 品質 pre-write 保証 + +| 順位 | Tier | タスク概要 | 効果 | 作業詳細 | +|---|---|---|---|---| +| 4 | 🚀 Tier 1 | Stop hook の `pnpm lint:md` 統合 | Stop 時に markdown lint 自動実行 → post-write iteration 削減 (lint 違反で push 失敗 → 修正の 1 周回避) | [todo3.md](todo3.md) | +| 10 | 🔧 Tier 2 | broken-link-check + 内部アンカー検査統合 (ADR-032 PR-broken-link) | docs/ 内 link 健全性を CI で機械検出、anchor drift を pre-merge で catch | [todo2.md](todo2.md) | +| 29 | 🚀 Tier 1 | 非 docs ファイル `docs/todo` 参照検出 lint rule (Bundle U) | docs ⇄ code 間 reference lifecycle の決定論的防止層、永続成果物への ephemeral 参照を pre-write で block | [todo3.md](todo3.md) | + +### 📋 LOW IMPACT — convention グローバル明文化 + +個別効果は薄いが、bundle 化すれば XS × 6 = 1 PR に集約可能。docs convention 整合性向上に寄与。 + +| 順位 | Tier | タスク概要 | 作業詳細 | +|---|---|---|---| +| 23 | 💎 Tier 3 | 日付ベース見出しアンカー更新ルールのグローバル明文化 | [todo2.md](todo2.md) | +| 24 | 💎 Tier 3 | jj conflict リカバリ手順のグローバル明文化 | [todo2.md](todo2.md) | +| 25 | 💎 Tier 3 | `__` prefix scratch file 規約のグローバル明文化 | [todo2.md](todo2.md) | +| 26 | 💎 Tier 3 | post-pr-monitor polling 禁止のグローバル明文化 | [todo2.md](todo2.md) | +| 30 | 💎 Tier 3 | Cross-File Reference Lifecycle ルールに具体例追記 (Bundle U) | [todo3.md](todo3.md) | +| 33 | 💎 Tier 3 | code-review.md に新 verdict 経路追加時の 3 点チェックリスト追記 (Bundle V) | [todo3.md](todo3.md) | + +--- + +## 推奨 bundle + +### Bundle "docs PR streamline" (最優先) + +ユーザー目的「docs-only PR を独立して早急にマージできる環境」の最短達成パス。 + +| 含む順位 | 概要 | 工数 | +|---|---|---| +| 59 | 中核: ADR-035 docs 評価ポリシー | M | +| 31 | review-security.md fast-approve 精度向上 | XS | +| 32 | todo.md ヘッダ実態整合 | XS | + +**合計工数**: M+ (1 セッション内完了可能)、すべて docs / facet instructions 編集で scope clean。 + +**期待効果**: + +- pre-push-review が docs-only PR に対し fast-approve → review time 1 分 30 秒〜30 秒に短縮 +- post-pr-review (analyze-coderabbit) が docs-only PR で false REJECT を出さない +- 順位 32 で運用ルールの自己矛盾を解消 + +**Bundle b との独立性**: Bundle b (順位 53/54/55, CR operation 安定化) は rate-limit 対応で別領域。並行進行可。 + +### Bundle "docs quality pre-write" (補完、本 bundle 後または並行) + +| 含む順位 | 概要 | 工数 | +|---|---|---| +| 4 | Stop hook lint:md | XS | +| 29 | docs/todo 参照検出 lint | S | + +write-time に docs 品質を保証する層。docs PR が push まで到達したら **すでに lint が通っている** 状態を作る。 + +### 後回し可 (low impact bundle) + +順位 23-26, 30, 33 (XS × 6) を 1 PR に集約。convention 明文化で long-tail の品質改善。Bundle "docs PR streamline" 完了後の余裕で実施。 + +順位 10 (broken-link-check) は ADR-032 関連の他タスク (順位 6, 20, 21) との依存があり、独立着手は非効率。ADR-032 全体の進捗に追従する。 + +--- + +## 関連ドキュメント + +- [docs/todo.md](todo.md) — 推奨実行順序サマリ表 (priority table) +- [docs/pipeline-token-efficiency.md](pipeline-token-efficiency.md) — pipeline efficiency 改善計画 (関連分野、本ドキュメントは docs PR 領域に特化) +- [ADR-019: CodeRabbit レビュー運用のハイブリッド構成](adr/adr-019-coderabbit-review-hybrid-policy.md) — CodeRabbit 運用根拠 +- [ADR-027: Push-time review を simplicity に限定](adr/adr-027-push-review-simplicity-focus.md) — review scope の既存 design rationale +- ADR-035: docs 評価ポリシー (順位 59 で作成予定、本 bundle のメイン成果物) From 128cc98bdfd74b6e8165ce407770d95367d32449 Mon Sep 17 00:00:00 2001 From: aloekun Date: Mon, 4 May 2026 15:03:20 +0900 Subject: [PATCH 3/5] =?UTF-8?q?docs(efficiency):=20coderabbit-monitoring-e?= =?UTF-8?q?fficiency.md=20=E3=82=92=E6=96=B0=E8=A6=8F=E4=BD=9C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit 監視機能改善 (rate-limit 自動回復) に関する task 分類・bundle 案 を集約する index を docs/ に新規追加。各 task の作業詳細は docs/todo*.md 系列に置き、本ファイルは概要 + リンクに留める設計。 掲載内容: - 現状の課題 (CodeRabbit 無課金 = 1 時間 3 reviews 上限、47 分 rate-limit で auto-retry がバウンスする致命点) - ボトルネック分析 (6 観点: 長時間 rate-limit / polling 負荷 / silent loss / structured findings / 自動 trigger 信頼性 / ポリシー暗黙化) - 改善 task 分類 (HIGH / MEDIUM / LOW IMPACT、合計 9 順位) - 推奨 bundle 案 (Bundle 'CR auto-monitoring core' = 順位 53/54/55、 Bundle 'CR rate-limit auto-retry robustness' = 順位 42/43/46/49) - 推奨実行順序: 53 → 42-43-46-49 → 54 → 55 (1 と 2 は並行可) - 関連ドキュメント (ADR-009/018/019/034、todo.md、pipeline-token- efficiency.md、docs-pr-iteration-efficiency.md) 役割: 試験運用 (bundle 消化後に役割終了)。pipeline-token-efficiency.md / docs-pr-iteration-efficiency.md と並列の領域特化計画書として機能。 動機: 本セッションで 'CodeRabbit の監視機能改善に関する task をピックアップ してほしい'、'毎回この情報を調べるのは手間' とのユーザー要望に対応。 --- docs/coderabbit-monitoring-efficiency.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/coderabbit-monitoring-efficiency.md diff --git a/docs/coderabbit-monitoring-efficiency.md b/docs/coderabbit-monitoring-efficiency.md new file mode 100644 index 0000000..d1ac87e --- /dev/null +++ b/docs/coderabbit-monitoring-efficiency.md @@ -0,0 +1,122 @@ +# CodeRabbit 監視機能改善 + +> **目的**: 個人開発で CodeRabbit 無課金ユーザーの rate-limit (1 時間あたり 3 reviews 上限) で発生する待ち時間を、ユーザー手動介入なしに自動回復させる。「定期的に PR コメントを確認する」手間をなくし、快適な個人開発環境を整備する。 +> +> **本ドキュメントの役割**: CodeRabbit 監視機能の改善に関する task 分類・bundle 案を集約する index。各 task の作業詳細は `docs/todo*.md` 系列に置き、本ファイルは概要 + リンクに留める。 +> +> **状態**: 試験運用 (本ドキュメントは "計画書" であり、bundle が消化されたら役割を終える) +> +> **想定読者**: 本リポジトリで CodeRabbit と連携する自動 review 環境を運用するユーザー。「rate-limit に引っかかった時に手動介入を最小化したい」目的を持つ。 + +--- + +## 現状の課題 + +- **CodeRabbit 無課金**: 1 時間あたり 3 reviews 上限 +- **上限到達時の挙動**: rate-limit comment が PR に投稿され、最大 60 分の `wait_minutes` が記載される +- **既存実装** (`cli-pr-monitor`、PR #97 で land 済) の限界: + - rate-limit 自動検出 + 再トリガー機構あり + - ただし `std::thread::sleep` 同プロセス内待機 + `max_duration_secs=600s` (10 分) cap で**長時間 rate-limit にバウンス**する + - PR #104 で 47 分 rate-limit を実観測、auto-retry が機能せず `action_required` 通知 → ユーザーは手動で PR コメントをチェックして再投稿する必要 + +## ボトルネック分析 + +| ボトルネック | 現状 | 改善方向 | +|---|---|---| +| 長時間 rate-limit (>10 分) の auto-retry | `std::thread::sleep` + 600s budget cap でバウンス | **CronCreate ベース wakeup** に置換、長時間待機を構造的に可能化 | +| review 完了待ちの polling 負荷 | 45s 間隔で gh API polling + observer 5s 間隔 polling | 計算時刻 wakeup に置換、**polling 完全排除** | +| AI 離席中の silent loss | wakeup 発火しない期間に rate-limit 解除しても検知できない | **SessionStart hook で pending wakeup catch-up** | +| structured findings 取得 | CodeRabbit comment text を grep ベース parse | `check-ci-coderabbit --list-findings` で構造化取得 (Sub-PR 1 で API 提供済) | +| 自動 trigger の信頼性 | error-path test infra なし、silent fail (`unwrap_or_else` で空配列 fallback) 検出機構なし | parse_findings の error-path test 追加 | +| ポリシーの暗黙化 | rate-limit retry の判断基準が ADR-018 / ADR-009 で散在 | ADR で明文化 | + +--- + +## 改善 task 分類 + +各 task の詳細 (動機 / 設計決定 / 作業計画 / 完了基準) は `docs/todo*.md` 系列を参照すること。本セクションは概要 + 効果のみ記載。 + +### 🎯 HIGH IMPACT — rate-limit 自動回復の中核 + +| 順位 | Tier | タスク概要 | 効果 | 作業詳細 | +|---|---|---|---|---| +| 53 | 🚀 Tier 1 | rate-limit retry の CronCreate 化 (Bundle b PR-1) | **致命点解消**。47 分 rate-limit を auto-retry 可能に。同プロセス常駐モデル → スケジュール起動モデルへ転換 | [todo5.md](todo5.md) | +| 42 | 🔧 Tier 2 | cli-pr-monitor rate-limit auto-retry + `@coderabbitai review` auto-trigger 実装 (Bundle a Sub-PR 2) | `check-ci-coderabbit --list-findings` (Sub-PR 1 land 済) を消費して構造化 retry に進化 | [todo4.md](todo4.md) | +| 54 | 🔧 Tier 2 | review 完了待ちの CronCreate 化 + observer 廃止 (Bundle b PR-2) | polling 完全排除、固定値 wakeup 化 | [todo5.md](todo5.md) | + +### 🛠 MEDIUM IMPACT — 信頼性 / silent loss 防止 + +| 順位 | Tier | タスク概要 | 効果 | 作業詳細 | +|---|---|---|---|---| +| 46 | 🔧 Tier 2 | CodeRabbit rate-limit auto-retry の integration test (Bundle a Sub-PR 2) | rate-limit auto-retry の信頼性確保 | [todo4.md](todo4.md) | +| 49 | 🔧 Tier 2 | `parse_findings` 系の error-path test infrastructure (Bundle a Sub-PR 2) | silent fail (`unwrap_or_else(\|_\| empty)`) を抑止、cli-pr-monitor mock infra も流用 | [todo5.md](todo5.md) | +| 55 | 💎 Tier 3 | config 拡張 + SessionStart catch-up (Bundle b PR-3) | AI 不在時の silent loss 防止、固定値 (`monitor.toml` 化) で調整可能 | [todo5.md](todo5.md) | +| 15 | 🔧 Tier 2 | cli-pr-monitor 通知 Recovery 経路 (SessionStart hook 拡張) ★ silent loss prevention | ADR-030 L2 recovery パターンを cli-pr-monitor に適用 | [todo3.md](todo3.md) | +| 11 | 🔧 Tier 2 | cli-pr-monitor プロセス正常終了の integration test (PR #85 T2-2) | プロセス挙動の信頼性確保 (auxiliary) | [todo2.md](todo2.md) | + +### 📋 LOW IMPACT — ドキュメント整備 + +| 順位 | Tier | タスク概要 | 作業詳細 | +|---|---|---|---| +| 43 | 💎 Tier 3 | ADR-018 / ADR-009 の rate-limit retry ポリシー明文化 (Bundle a Sub-PR 2) | [todo4.md](todo4.md) | + +--- + +## 推奨 bundle + +### Bundle "CR auto-monitoring core" (Bundle b、最優先) + +ユーザー目的「rate-limit 待ち時間に手動介入なし」の最短達成パス。 + +| 含む順位 | 概要 | 工数 | +|---|---|---| +| 53 | 中核: rate-limit retry の CronCreate 化 (PR-1) | M | +| 54 | review 完了待ちの CronCreate 化 + observer 廃止 (PR-2) | M | +| 55 | config 拡張 + SessionStart catch-up (PR-3) | S | + +**依存関係**: 54 は 53 land 後、55 は 53 + 54 land 後。PR を 3 本に分けて順次 land 推奨。 + +**期待効果**: + +- 順位 53 land 後: 47 分 rate-limit でも auto-retry が動作 (= ユーザー手動介入なしに review が再開) +- 順位 54 land 後: polling 排除で Claude Code セッション稼働中の overhead 削減 +- 順位 55 land 後: AI 離席時の silent loss 解消 (起動時に pending wakeup を catch-up) + +### Bundle "CR rate-limit auto-retry robustness" (Bundle a Sub-PR 2、補完) + +| 含む順位 | 概要 | 工数 | +|---|---|---| +| 42 | auto-retry + `@coderabbitai review` auto-trigger 実装 | M | +| 43 | ADR-018 / ADR-009 明文化 | S | +| 46 | integration test | M | +| 49 | `parse_findings` error-path test infra | M | + +**依存関係**: Sub-PR 1 (順位 44/45 = PR #100/#101 で land 済) の `check-ci-coderabbit --list-findings` API を消費。1 PR で 4 順位を統合する設計 (cli-pr-monitor mock infra を 4 順位で共有)。 + +**期待効果**: 既存 grep ベース parse から構造化 findings 駆動の auto-retry へ進化。`parse_findings` の silent fail を test 化することで、rate-limit 検出漏れによる手動介入リスクを抑止。 + +### 並行進行可能性 + +- **Bundle b** と **Bundle a Sub-PR 2** は別領域 (Cron 機構 vs structured findings 消費)、**並行進行可** +- ただし dogfood 観測の signal 純度を保つため 1 PR ずつ land を推奨 + +### 推奨実行順序 (ユーザー目的の最短達成) + +1. **順位 53** (Bundle b PR-1): 致命点解消、即座に user benefit +2. **順位 42 + 43 + 46 + 49** (Bundle a Sub-PR 2): auto-retry の信頼性 + 構造化 findings 駆動化 +3. **順位 54** (Bundle b PR-2): polling 排除 +4. **順位 55** (Bundle b PR-3): silent loss 解消、polish + +並行可: 1 と 2 は別領域なので、片方の dogfood 中にもう一方を着手できる。 + +--- + +## 関連ドキュメント + +- [docs/todo.md](todo.md) — 推奨実行順序サマリ表 (priority table) +- [docs/pipeline-token-efficiency.md](pipeline-token-efficiency.md) — pipeline efficiency 改善計画 (関連分野: post-pr-review との接続) +- [docs/docs-pr-iteration-efficiency.md](docs-pr-iteration-efficiency.md) — 並列の docs PR iteration 領域 +- [ADR-009: Post-PR Monitor — push/PR作成後の CI・CodeRabbit 自動監視](adr/adr-009-post-pr-monitor.md) +- [ADR-018: cli-pr-monitor の takt ベース移行と CronCreate 廃止](adr/adr-018-pr-monitor-takt-migration.md) — Bundle b で再導入する CronCreate の設計根拠 (廃止判断と整合) +- [ADR-019: CodeRabbit レビュー運用のハイブリッド構成](adr/adr-019-coderabbit-review-hybrid-policy.md) — CodeRabbit 運用根拠 +- [ADR-034: CodeRabbit 監視・対話の自動化戦略 — Bundle a 設計根拠](adr/adr-034-coderabbit-auto-monitoring.md) — Bundle a の設計根拠 From 033445e90c3d6a4e34d1f7bedec364a71c01bc3e Mon Sep 17 00:00:00 2001 From: aloekun Date: Mon, 4 May 2026 15:27:44 +0900 Subject: [PATCH 4/5] =?UTF-8?q?docs(retire):=20pipeline-token-efficiency.m?= =?UTF-8?q?d=20retire=20=E2=80=94=20ADR-036/037=20=E5=8C=96=20+=20?= =?UTF-8?q?=E9=A0=86=E4=BD=8D=2060=20=E7=A7=BB=E7=AE=A1=20+=20=E5=89=8A?= =?UTF-8?q?=E9=99=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #97 セッション起源の計画書 docs/pipeline-token-efficiency.md (481 行) を 役割完了として retire。重要な設計決定は ADR に永続保存し、残作業 1 件のみを todo に移管した上で計画書ファイル本体を削除する。 新規 ADR (2 件): - ADR-036: Bundle Z 3 層アーキテクチャ - 決定論層 (#B-α PR #99/#105) → 制約付き修正 (#B-β PR #103) → 異常検知レビュアー (#B-γ PR #106) の 3 層スタック設計 - 'upper layer skips what lower layer catches' 原則 - 二重 miss 対策 (Calibration: avoid over-narrowing) を残置 - ADR-037: takt fix-trust shortcut (convergence_verdict 機構) - post-pr-review / pre-push-review の fix step が 'convergence_verdict: fully_resolved' で COMPLETE 直行する設計 - 'LLM が出した結果を後段で再検証しない' 原則 - Honesty constraint で安全網 bypass リスク管理 ADR-034 更新: - #D-4 (Claude 応答スタイル簡素化) を ❌ 不採用 に確定 (2026-05-04 ユーザー判断) Bundle Z Phase 2/3 完了後の再評価で副作用観測手段確立が見えないため 永続的に見送り。潜在 2.5-4M tokens 削減は採用しない - '将来の検討事項' から #D-4 再評価条件セクションを削除 - pipeline-token-efficiency.md への参照を '(削除済)' に annotate 順位 60 新規登録 (旧 #A-3、唯一の残作業): - analyze-session の transcript filter 絞り込み (Tier 3 / M) - input range を PR 作成 commit〜merge に限定し input token 30-50% 削減 ファイル削除: - docs/pipeline-token-efficiency.md (481 行) を削除 内容は git log で復元可能、主要設計は ADR-036/037 に集約 参照更新 (5 ファイル): - docs/coderabbit-monitoring-efficiency.md: 関連リンクから dead link 削除、ADR-036/037 を追加 - docs/docs-pr-iteration-efficiency.md: 同上 - docs/todo4.md: 順位 41 (Bundle Y2 効果定量計測) は動機失効を明記 (Bundle Z 完成 + Z2 不採用)、本格着手前にユーザー判断要。 順位 44/45 の参照を '(削除済)' に annotate - docs/todo5.md: 順位 51 の参照を ADR-036 に置換 - CLAUDE.md: ADR-036 / ADR-037 を index に追加 動機: ユーザー方針 '本当に必要な決定事項はADRに残し、不要になったTodoファイルや 作業計画のファイルは定期的に削除' に従い、計画書 retire の標準パターンを 本セッションで確立。今後類似の '計画書' (試験運用フラグ付き docs/) は 役割完了時に同パターンで retire する。 --- CLAUDE.md | 2 + .../adr/adr-034-coderabbit-auto-monitoring.md | 18 +- .../adr-036-bundle-z-three-layer-review.md | 104 ++++ docs/adr/adr-037-takt-fix-trust-shortcut.md | 117 +++++ docs/coderabbit-monitoring-efficiency.md | 3 +- docs/docs-pr-iteration-efficiency.md | 3 +- docs/pipeline-token-efficiency.md | 481 ------------------ docs/todo.md | 1 + docs/todo4.md | 17 +- docs/todo5.md | 46 +- 10 files changed, 285 insertions(+), 507 deletions(-) create mode 100644 docs/adr/adr-036-bundle-z-three-layer-review.md create mode 100644 docs/adr/adr-037-takt-fix-trust-shortcut.md delete mode 100644 docs/pipeline-token-efficiency.md diff --git a/CLAUDE.md b/CLAUDE.md index 458f8db..f214f46 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,6 +35,8 @@ - [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) *(試験運用)* +- [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) *(試験運用)* ## Build diff --git a/docs/adr/adr-034-coderabbit-auto-monitoring.md b/docs/adr/adr-034-coderabbit-auto-monitoring.md index 62276bd..0c74d9b 100644 --- a/docs/adr/adr-034-coderabbit-auto-monitoring.md +++ b/docs/adr/adr-034-coderabbit-auto-monitoring.md @@ -16,7 +16,7 @@ PR #99 セッションで以下の運用痛が観測された: ## 検討した選択肢 -`docs/pipeline-token-efficiency.md` #D セクションで 4 案を検討: +(削除済) `docs/pipeline-token-efficiency.md` #D セクションで 4 案を検討: - **#D-1**: gh CLI 使用ルール (rule 追記) - **#D-2**: `pnpm cr:findings ` wrapper script @@ -39,7 +39,7 @@ PR #99 セッションで以下の運用痛が観測された: ### 取り下げた案 - **#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 完了後の副作用観測手段確立を待つ。再評価条件は「将来の検討事項」参照 +- **#D-4 (応答スタイル簡素化)**: ❌ **不採用** (2026-05-04 ユーザー判断、Bundle Z Phase 2/3 完了後の再評価で確定)。**思考連続性低下リスク** (中間出力削減で後段の context 再構築コストが増え、token カテゴリが入れ替わるだけで正味削減が縮む可能性) と **副作用観測手段の継続的不在** を考慮した最終判断。潜在 2.5-4M tokens 削減は採用見送り ## 実装方針 (2 Sub-PR 分割) @@ -120,7 +120,7 @@ PR #99 セッションで以下の運用痛が観測された: ### Trade-off - 開発体験の質的変化 (rate-limit 手動介入消滅) を **token 削減効果より優先** -- #D-4 (応答スタイル) の保留により、潜在 2.5-4M tokens 削減を見送り +- #D-4 (応答スタイル) の **不採用** (2026-05-04 確定) により、潜在 2.5-4M tokens 削減は永続的に見送り ## 別セッションでの実装に必要な情報 @@ -174,16 +174,6 @@ PR #99 セッションで以下の運用痛が観測された: ## 将来の検討事項 -### #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 で確認 @@ -196,6 +186,6 @@ Bundle Z Phase 2/3 (#B-β / #B-γ) 完了後、以下が確立した時点で慎 - ADR-022: 自動化コンポーネントの責務分離原則 - ADR-026: Cargo workspace - ADR-030: Deterministic post-merge-feedback -- `docs/pipeline-token-efficiency.md` #D セクション (採用判定改訂 2026-05-02) +- (削除済) `docs/pipeline-token-efficiency.md` #D セクション (採用判定改訂 2026-05-02、本 ADR で経緯保存) - memory `project_coderabbit_rate_limit_overlay.md` - PR #99 (本 ADR の起源、cli-pr-monitor の rate-limit detection gap が顕在化したセッション) diff --git a/docs/adr/adr-036-bundle-z-three-layer-review.md b/docs/adr/adr-036-bundle-z-three-layer-review.md new file mode 100644 index 0000000..3e31999 --- /dev/null +++ b/docs/adr/adr-036-bundle-z-three-layer-review.md @@ -0,0 +1,104 @@ +# ADR-036: Bundle Z — 決定論層 + 制約付き修正 + 異常検知レビュアーの 3 層アーキテクチャ + +## ステータス + +試験運用 (2026-05-04) + +## コンテキスト + +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 つの構造的根因が判明: + +| 根因 | 例 | +|---|---| +| 1. **simplicity-review iter 1 の検出漏れ** | LLM の attention drift で What コメント S04 を見落とし | +| 2. **fix step が新 violation を introduce** | F-001 修正で `match Ok / Err` 採用 → nesting depth 7 を導入 | +| 3. **AI が What/How コメントをそもそも書く** | explanatory output style の指示があっても Claude の習性として残る | + +これらは LLM 主導 review の **本質的限界** に由来し、prompt の改良 (より詳細な checklist 等) では解消できない。LLM の attention drift と self-evaluation 不安定性は、より厳しい指示を与えるほど attention 分散して悪化する性質を持つ。 + +## 検討した選択肢 + +(削除済) `docs/pipeline-token-efficiency.md` の #B セクションで 3 案を検討 (本 ADR が代替): + +- **#B-α**: 決定論レイヤー (Rust comment lint hook、PostToolUse で AI が書く瞬間を block) +- **#B-β**: 制約付き修正 (fix step に metric diff の機械チェックを義務付け) +- **#B-γ**: 異常検知レビュアー (reviewer の責務を「lint で防げない高次違反のみ flag」に再定義) + +**個別採用ではなく 3 層スタックとして統合**することを決定。各層が前提とする状態を後段の層が信頼することで責務を狭める設計。 + +## 決定 + +**Bundle Z = 3 層スタック** で pre-push-review の review 品質と速度を両立する: + +```text +[書く瞬間] [修正の瞬間] [レビューの瞬間] +#B-α 決定論層 → #B-β 制約付き修正 → #B-γ 異常検知 +PostToolUse hook fix-metrics check review facets +ファイルが書かれた時点で fix iteration ごとに 決定論層が intercept する +violation を block metric 増加を block metric は skip、 高次違反のみ flag +``` + +### 各層の責務分担 + +| 層 | 配置 | 検出対象 | 完了 PR | +|---|---|---|---| +| **#B-α 決定論層** | `src/hooks-post-tool-comment-lint-rust/` (PostToolUse hook) | 非 doc コメント (例外マーカー除外) / 関数長 50 行超 (touch-trigger ratchet) | PR #99 (Phase 1) + PR #105 (関数長 lint 追加 = 順位 48) | +| **#B-β 制約付き修正** | `.takt/facets/instructions/fix.md` + `scripts/fix-metrics-check.ps1` | fix iteration での per-function metric 増加 (comment count / function length / nesting depth) | PR #103 (Phase 2) | +| **#B-γ 異常検知** | `.takt/facets/instructions/review-{simplicity,security}.md` | 決定論層が intercept できない高次違反 (Unexplained complexity / Inconsistent style / Hidden coupling 等) | PR #106 (Phase 3) | + +### 設計原則: 上層は下層が intercept する metric を skip する + +`review-simplicity.md` の "Determinism layer guarantees (do NOT duplicate)" セクションで明文化: + +- Comment policy → #B-α が PostToolUse で block 済 → reviewer は skip +- Function length → 順位 48 (`hooks-post-tool-comment-lint-rust`) が touch-trigger ratchet で block 済 → reviewer は skip +- Function metrics during fix → #B-β `fix-metrics-check.ps1` が pre/post diff で block 済 → reviewer は skip + +**reviewer の責務 = 「決定論層 + 制約付き修正でも防げない高次違反」のみ**。enumerate 義務を削除し、attention drift 問題を構造的に解消。 + +### 二重 miss リスクへの対策 + +`review-simplicity.md` に "Calibration: avoid over-narrowing" セクションを残置: + +- 異常検知への shift は重複作業の削減が目的、review skip ではない +- 「articulable concern」は raise する (criterion に当てはまらなくても) +- 機械的 checklist 適用なら下層がカバーしている + +## 影響 + +### Positive + +- ✅ pre-push-review iter 分布: PR #97 baseline `{1×3, 3×2, 6×1}` (avg 2.5、6-iter outlier 1 件) → 1-iter ALL APPROVE 構造化を目指す (Phase 3 実装直後の dogfood で初観測) +- ✅ attention drift 問題が構造的に消滅 (検出対象が absolute に narrow に) +- ✅ review 所要時間も短縮 (現 baseline 1m 30s〜3m → 30s〜1m 期待) +- ✅ 各層の責務が明確に分離、後続改修時の責務帰属が判断しやすい + +### Negative + +- ⚠️ 二重 miss の可能性 (決定論層の coverage gap で漏れた違反が reviewer もスルー) → "Calibration" セクションで対策 +- ⚠️ 「異常」の定義が LLM 主観で false positive が出る場合、決定論層 update (lint rule 追加) で対応する継続的メンテが必要 +- ⚠️ Rust 限定 (PoC は `tree-sitter-rust` 依存)。将来言語拡張時に決定論層の再実装が必要 + +### Trade-off + +- 設計複雑度の増加 vs 検出精度の向上 → review 効率の改善が複雑度コストを上回ると判断 +- 言語固有実装 (Rust 専用) vs 言語非依存抽象化 → PoC として Rust に絞り、言語拡張は需要発生時に判断 (YAGNI) + +## 派生プロジェクトへの展開 + +`hooks-post-tool-comment-lint-rust` は派生プロジェクト (`techbook-ledger`、`auto-review-fix-vc`) でも展開済 (PR #99 / PR #105 deploy)。 + +facet instructions (`.takt/facets/instructions/*.md`) は本リポジトリと派生プロジェクトで個別更新する運用。 + +## 関連 ADR + +- **ADR-001**: Rust 採用根拠 (#B-α / #B-β の実装言語選定根拠) +- **ADR-007**: AST 層 / 正規表現層の線引き (#B-α が AST 層で動作する根拠) +- **ADR-027**: Push-time review を simplicity に限定し architectural review は post-PR に委ねる (#B-γ の scope 設計と整合) +- **ADR-019**: CodeRabbit レビュー運用のハイブリッド構成 (post-PR 側の reviewer = CodeRabbit、pre-push 側の reviewer = takt との役割分担) + +## References + +- 元セッション: PR #97 (`6cbc5021-...jsonl`、6.18MB / 1180 turns) — 6-iter outlier の root cause 分析 +- 完了 PR: #99 (Phase 1 #B-α) / #103 (Phase 2 #B-β) / #105 (順位 48 関数長 lint) / #106 (Phase 3 #B-γ) +- (削除済) `docs/pipeline-token-efficiency.md` #B セクション — 本 ADR が代替 diff --git a/docs/adr/adr-037-takt-fix-trust-shortcut.md b/docs/adr/adr-037-takt-fix-trust-shortcut.md new file mode 100644 index 0000000..0bb8fbd --- /dev/null +++ b/docs/adr/adr-037-takt-fix-trust-shortcut.md @@ -0,0 +1,117 @@ +# ADR-037: takt fix-trust shortcut — convergence_verdict による Iter 3 短絡 + +## ステータス + +試験運用 (2026-05-04) + +## コンテキスト + +`post-pr-review` パイプラインで 3-iter outlier が発生する根因分析より、Iter 3 の analyze step が **本質的に冗長** であることが判明した: + +> Iter 3 output 例 (PR #96 の auto-fix run、10m 19s): +> 「`.takt/review-comments.json` is a snapshot captured before fix iteration 1 ran; CodeRabbit has not re-reviewed yet, so the same 2 findings appear. The previous fix step report indicates both were addressed. **I verified each by reading the current source**...」 + +つまり Iter 3 の analyze は「前 iter の fix step が言う通りに本当に修正されているか」をソースを読んで再確認している作業に過ぎない。fix step を信頼すれば不要。 + +同様の構造は `pre-push-review` パイプラインの 6-iter outlier でも観測されており、reviewers→fix→reviewers の 2 cycle 後に supervise → fix_supervisor のエスカレーションが発生する。これも fix step の自己評価を信頼できれば短絡可能。 + +LLM の self-evaluation 信頼性は本質的に揺らぐが、**機械的に検証可能な指標** (Convergence gate metrics) を fix step に emit させ、その出力を後段の routing に直接使うことで信頼性を確保できる。 + +## 決定 + +`fix.md` instruction に **convergence_verdict** マーカー emit を必須化し、workflow yaml の routing rule に「fully_resolved → COMPLETE 直行」condition を追加する。 + +### convergence_verdict 仕様 + +`fix.md` の Convergence gate (既存) は以下 4 metrics を fix step に emit させる: + +| Metric | Count | +|--------|-------| +| new (fixed in this iteration) | {N} | +| reopened (recurrence fixed) | {N} | +| persists (carried over, not addressed this iteration) | {N} | +| misdirected (suggestion pointed at a read-only zone, skipped) | {N} | + +これに加えて、fix step は report 末尾に以下のいずれかを single bare line で emit する (REQUIRED): + +- `convergence_verdict: fully_resolved` — `persists == 0` AND `misdirected == 0`、すべての findings が解決済み +- `convergence_verdict: partial` — `persists > 0` OR `misdirected > 0`、再 analyze が必要 + +### workflow yaml routing + +`post-pr-review.yaml` + `pre-push-review.yaml` の fix step rules に以下の condition を追加: + +```yaml +rules: + - condition: | + Report ends with `convergence_verdict: fully_resolved` (Convergence + gate shows persists: 0 AND misdirected: 0). All findings of this + iteration are fully resolved with no remaining work. + next: COMPLETE + - condition: | + Fixes applied but `convergence_verdict: partial` (some findings + persist or were misdirected, re-analysis needed). + next: analyze # post-pr-review の場合 / reviewers (pre-push-review の場合) + - condition: Unable to proceed with fixes + next: supervise +``` + +### Honesty constraint + +`fix.md` の convergence_verdict セクションに以下を明記: + +> **Honesty constraint**: This verdict gates whether the analyze step runs again. Reporting `fully_resolved` while leaving findings unaddressed bypasses the safety re-check. If you are uncertain whether a finding was truly resolved (e.g., you applied a fix but did not verify the build passes), emit `partial` so the analyze step can re-evaluate. + +虚偽申告 (= 未修正で fully_resolved を emit) は安全網 bypass に直結するため、不確実な場合は `partial` を選ぶよう明示。 + +## 設計哲学 + +本決定は **「LLM が出した結果を後段で再検証しない」** 原則の応用: + +- 従来: fix step → analyze step (= ソースを読んで再確認) → fix step → ... +- 改訂後: fix step → (verdict ベース routing) → COMPLETE / analyze step + +LLM 同士で互いを再評価する loop は token と時間を消費するが、信頼境界 (= verdict) を明確にすれば中間ステップを構造的に削減できる。 + +ADR-036 の Bundle Z 3 層アーキテクチャと同じ思想: + +- Bundle Z #B-γ (異常検知 reviewer): **下層が intercept した metric を上層は skip** (上層は下層を信頼) +- 本 ADR (fix-trust): **fix step が emit した verdict を analyze step は再確認しない** (analyze は fix を信頼) + +## 影響 + +### Positive + +- ✅ post-pr-review の 3-iter outlier 圧縮: 3-iter run → 2-iter (~3 分削減/run) +- ✅ pre-push-review の reviewers→fix loop 短縮: 全 finding が一発で fix された場合の 2 cycle 目を skip +- ✅ 設計原則の明文化: 「LLM 結果の信頼境界」を verdict で portable に表現 + +### Negative + +- ⚠️ fix step の自己評価信頼性に依存 (虚偽 fully_resolved → 未修正 finding land リスク) +- ⚠️ 後続 supervise step でカバーされない場合は安全網が薄くなる + +### Mitigations + +- **Honesty constraint** で安全網 bypass リスクを fix step に明示 +- 不確実な場合は `partial` を選ぶデフォルトを推奨 +- dogfood で虚偽 fully_resolved が観測されたら順位 53 系列の post-merge-feedback follow-up (T1-1: convergence_verdict gate validator) を採用検討 + +## 完了状態 + +- 完了 PR: #106 (Bundle Z Phase 3 と同梱) +- 影響範囲: `post-pr-review.yaml` / `pre-push-review.yaml` (fix step rules) + `fix.md` (Convergence verdict セクション追加) +- 派生プロジェクトへの展開: facet instructions は本リポジトリと派生プロジェクトで個別更新する運用 (ADR-036 と同じ) + +## 関連 ADR + +- **ADR-036**: Bundle Z 3 層アーキテクチャ (本 ADR と同じ「LLM 結果の信頼境界」原則を pre-push-review に適用) +- **ADR-008**: Push Pipeline ハーネスの実装 (workflow yaml 設計の前提) +- **ADR-015**: Push Pipeline を takt ベースの push-runner に移行 (workflow + facet 機構) +- **ADR-018**: cli-pr-monitor takt 化 (post-pr-review.yaml の起源) + +## References + +- 元セッション: PR #97 セッション (post-pr-review 3-iter outlier の root cause 分析) +- 完了 PR: #106 (Bundle Z Phase 3 + #C-2 同梱) +- (削除済) `docs/pipeline-token-efficiency.md` #C-2 セクション — 本 ADR が代替 diff --git a/docs/coderabbit-monitoring-efficiency.md b/docs/coderabbit-monitoring-efficiency.md index d1ac87e..b44ec59 100644 --- a/docs/coderabbit-monitoring-efficiency.md +++ b/docs/coderabbit-monitoring-efficiency.md @@ -114,8 +114,9 @@ ## 関連ドキュメント - [docs/todo.md](todo.md) — 推奨実行順序サマリ表 (priority table) -- [docs/pipeline-token-efficiency.md](pipeline-token-efficiency.md) — pipeline efficiency 改善計画 (関連分野: post-pr-review との接続) - [docs/docs-pr-iteration-efficiency.md](docs-pr-iteration-efficiency.md) — 並列の docs PR iteration 領域 +- [ADR-036: Bundle Z 3 層アーキテクチャ](adr/adr-036-bundle-z-three-layer-review.md) — pre-push-review 改善 (旧 pipeline-token-efficiency.md #B セクション) +- [ADR-037: takt fix-trust shortcut](adr/adr-037-takt-fix-trust-shortcut.md) — post-pr-review 短縮 (旧 #C-2) - [ADR-009: Post-PR Monitor — push/PR作成後の CI・CodeRabbit 自動監視](adr/adr-009-post-pr-monitor.md) - [ADR-018: cli-pr-monitor の takt ベース移行と CronCreate 廃止](adr/adr-018-pr-monitor-takt-migration.md) — Bundle b で再導入する CronCreate の設計根拠 (廃止判断と整合) - [ADR-019: CodeRabbit レビュー運用のハイブリッド構成](adr/adr-019-coderabbit-review-hybrid-policy.md) — CodeRabbit 運用根拠 diff --git a/docs/docs-pr-iteration-efficiency.md b/docs/docs-pr-iteration-efficiency.md index 40bb438..fb91ff2 100644 --- a/docs/docs-pr-iteration-efficiency.md +++ b/docs/docs-pr-iteration-efficiency.md @@ -105,7 +105,8 @@ write-time に docs 品質を保証する層。docs PR が push まで到達し ## 関連ドキュメント - [docs/todo.md](todo.md) — 推奨実行順序サマリ表 (priority table) -- [docs/pipeline-token-efficiency.md](pipeline-token-efficiency.md) — pipeline efficiency 改善計画 (関連分野、本ドキュメントは docs PR 領域に特化) +- [docs/coderabbit-monitoring-efficiency.md](coderabbit-monitoring-efficiency.md) — CodeRabbit 監視機能改善 (並列の領域特化計画書) +- [ADR-036: Bundle Z 3 層アーキテクチャ](adr/adr-036-bundle-z-three-layer-review.md) — pre-push-review 設計根拠 (旧 docs/pipeline-token-efficiency.md #B を ADR 化) - [ADR-019: CodeRabbit レビュー運用のハイブリッド構成](adr/adr-019-coderabbit-review-hybrid-policy.md) — CodeRabbit 運用根拠 - [ADR-027: Push-time review を simplicity に限定](adr/adr-027-push-review-simplicity-focus.md) — review scope の既存 design rationale - ADR-035: docs 評価ポリシー (順位 59 で作成予定、本 bundle のメイン成果物) diff --git a/docs/pipeline-token-efficiency.md b/docs/pipeline-token-efficiency.md deleted file mode 100644 index f499463..0000000 --- a/docs/pipeline-token-efficiency.md +++ /dev/null @@ -1,481 +0,0 @@ -# takt パイプライン トークン効率調査・改善計画 - -> **動機**: Claude Code Max 5x の 5 時間レートリミットの 90% を 3 時間時点で消費する事象が観測された (PR #97 セッション、2026-04-30 〜 2026-05-01 JST)。本ドキュメントは、その session log (`6cbc5021-...jsonl`、6.18MB / 1180 assistant turns) を分析した結果のうち、**未実施の改善方向のみ** を記録する。 -> -> **方針**: 各改善案は「調査結果 → 改善案 → 採用判定」の 3 セクションで管理する。実装決定後は本ドキュメントから該当セクションを削除し、ADR 化または todoX.md にタスク登録する。 -> -> **状態**: 試験運用 (本ドキュメントは "計画書" であり、残作業を消化したら役割を終える) -> -> **完了済 Bundle (履歴・調査内容は本ドキュメントから削除済)**: -> -> | Bundle | 内容 | 完了 PR | -> |---|---|---| -> | Bundle Y2 | #A-1 + #C-1 (analyze facets を haiku 化) | #98 | -> | Bundle Z Phase 1 | #B-α (Rust comment lint hook、決定論レイヤー) | #99 | -> | Bundle a Sub-PR 0 | #D-1 (gh CLI 規則 → `~/.claude/rules/common/git-workflow.md`) + ADR-034 起案 | #100 | -> | Bundle a Sub-PR 1 | #D-3 (`check-ci-coderabbit --list-findings` モード) | #101 | - ---- - -## 観測データ (PR #97 セッション、2026-04-30 〜 2026-05-01 JST) - -> **用途**: 残作業の改善効果検証時の比較ベースライン。 - -### セッション全体 - -| 指標 | 値 | -|---|---| -| Assistant turns | 1,181 | -| 一意トークン (uncached input + cache_creation) | 13.64M | -| Cache read 累積 | 350.9M | -| Output tokens | 833K | -| Cache 再生成倍率 | 約 9x | -| takt パイプライン総時間 | **114.7 分** (セッション全体の 63%) | - -### takt パイプライン別 - -| パイプライン | Runs | 総 iter | avg iter | 総時間 | avg 時間 | iter 分布 | -|---|---|---|---|---|---|---| -| pre-push-review | 6 | 15 | 2.5 | 47.9 分 | 8.0 分 | {1×3, 3×2, **6×1**} | -| post-merge-feedback | 4 | 8 | 2.0 | 35.5 分 | 8.9 分 | {2×4} | -| post-pr-review | 6 | 9 | 1.5 | 31.3 分 | 5.2 分 | {1×4, 2×1, 3×1} | - -### Bash tool_result サイズ (主な context bloat 源泉) - -| Bash サブカテゴリ | calls | chars total | avg | max | -|---|---|---|---|---| -| `gh pr` / `gh api` (CR query) | 76 | 303,697 | 4,000 | 47,980 | -| grep/head (log inspect) | 59 | 79,806 | 1,352 | 7,280 | -| tail (push log) | 35 | 71,472 | 2,042 | 7,252 | -| jj | 78 | 68,048 | 872 | 8,918 | -| cargo-test | 27 | 43,184 | 1,599 | 12,044 | - ---- - -## #A: post-merge-feedback パイプライン (残作業) - -### #A-2: trivial PR の post-merge-feedback skip 条件追加 - -doc-only PR (`.md` のみ変更) や 1-commit fix PR では post-merge-feedback の ROI が低い。`cli-merge-pipeline` 側で PR diff size を判定して skip する。 - -**変更箇所**: `src/cli-merge-pipeline/` の merge 後処理ロジック -**判定条件 (案)**: - -- diff の changed files が `*.md` のみ -- かつ commit 数 = 1 -- かつ +/- 合計 < 50 行 - -**期待効果**: doc PR で post-merge-feedback 9 分丸ごと削減。月数件の doc-only PR があれば効果大。 - -**リスク**: doc PR でも文書間 reference 整合性等の発見がありうる。skip 判定は緩めに設定し、誤 skip による学習機会損失を最小化する。 - -### #A-3: transcript filter の絞り込み強化 - -analyze-session が読む `.takt/post-merge-feedback-transcript.jsonl` には **session 全履歴** が入る。PR-related な部分のみ filter すれば input token 削減 (analyze-session の cache_read 削減)。 - -**変更箇所**: `cli-merge-pipeline` の transcript 生成ロジック -**現状**: 全 session -**改善案**: 当該 PR の作成 commit から merge までの時刻 range で filter - -**期待効果**: analyze-session の input token 30-50% 削減 (推定)。dogfood で実測必要。 - -**リスク**: PR 作成前の議論 (設計判断、却下されたアイデア) が落ちる可能性。post-merge-feedback の知見の質に影響しうる。 - -### 採用判定 - -| 改善案 | ROI | 実装コスト | 推奨 | -|---|---|---|---| -| #A-2 trivial PR skip | ★★★★ | S (Rust 判定ロジック) | 中期 | -| #A-3 transcript filter | ★★★ | M (cli-merge-pipeline 改修) | dogfood 後 | - ---- - -## #B: pre-push-review パイプライン (Bundle Z Phase 2 / 3) - -> **背景**: 6 iter / 17-18 分の outlier が PR #97 で 2 回発生 (各 round で個別)。総時間 36 分が突出 (47.9 分中 75% を消費)。 -> -> **アーキテクチャ 3 層**: 「決定論レイヤー (#B-α、PR #99 で完了) → 制約付き修正 (#B-β、Phase 2) → 異常検知レビュアー (#B-γ、Phase 3)」を Phase 1〜3 で順次実装する設計。各 Phase 完了後の dogfood で次 Phase 着手判断。 - -### Phase 2/3 着手前に把握すべき構造的問題 - -#### Workflow 構造 - -[`.takt/workflows/pre-push-review.yaml`](../.takt/workflows/pre-push-review.yaml): - -```text -reviewers (parallel: simplicity + security) → fix → (loop, threshold 2) → supervise → fix_supervisor → COMPLETE -``` - -`loop_monitors.threshold: 2` で reviewers→fix サイクル 2 周まで許容。逸脱で supervise → fix_supervisor へエスカレート。**6 iter = 2 cycles + supervise + fix_supervisor の最大 path**。 - -#### 観測された 3 つの根因 (6-iter run の解析より) - -両 run とも Iter 1 で全 finding が検出されない / fix が新たな violation を introduce することで Iter 2 が必要になり、結果として supervise + fix_supervisor のエスカレートで 6 iter に膨らんだ。 - -| 根因 | 例 | 解消手段 | -|---|---|---| -| 1. simplicity-review iter 1 の検出漏れ | LLM の attention drift で What コメント S04 を見落とし | **#B-γ で解消対象** | -| 2. fix step が新 violation を introduce | F-001 修正で `match Ok / Err` 採用 → nesting depth 7 を導入 | **#B-β で解消対象** | -| 3. AI が What/How コメントをそもそも書く | explanatory output style の指示があっても Claude の習性として残る | **#B-α (PR #99) で解消済** | - -### #B-β: 制約付き fix instruction (Phase 2) - -**設計思想**: fix step の self-check を LLM 判断ではなく **機械的指標の diff 比較** に置き換える。指標増加で fix 自身がやり直しを self-trigger。 - -**実装方法**: - -- `.takt/facets/instructions/fix.md` の Completion criteria に追加: - - ```markdown - ## Pre-completion deterministic check - - Compare metrics between pre-fix and post-fix file states for each modified file: - - max nesting depth (within modified function or change site) - - function length (lines) - - non-doc comment count (excluding `///`, `// TODO:`, `// SAFETY:` 等の例外マーカー) - - Run helper script: - - scripts/fix-metrics-check.ps1 - - If any metric increased, REJECT own fix and try alternative approach - (e.g., extract function, use early return, simplify match arm). - ``` - -- helper script `scripts/fix-metrics-check.ps1`: `rust-code-analysis` (Rust) を呼び出し metrics を JSON 出力 → diff 計算 → 増加 detected なら exit 非ゼロ -- `.takt/runs//fix-metrics.log` に記録 (audit 用) - -**PR #99 (Phase 1) との同期要件**: - -コメント数の例外マーカーリストは PR #99 で実装した [`src/hooks-post-tool-comment-lint-rust/src/main.rs`](../src/hooks-post-tool-comment-lint-rust/src/main.rs) の `ALLOWED_LINE_PREFIXES` / `ALLOWED_BLOCK_PREFIXES` 定数を **single source of truth** として参照すること。fix.md と lint hook で例外マーカー定義が乖離すると、lint で許容されたコメントが fix の non-doc comment count を増やして誤 reject となる。 - -**期待効果**: - -- 根因 2 (fix が新 violation を introduce) の **構造的排除** -- LLM 判断ではなく数値比較なので、attention drift や指示読み飛ばしの影響を受けない - -**リスク**: - -- 「適切な refactor で一時的に行数増加」のケース判定 (関数分割で個別関数長は減るが modified function 範囲では増える) - → 対策: function 単位ではなく **diff 内の change site 周辺** に scope を絞る -- metric tool の Rust 限定 (PoC は `rust-code-analysis`、将来言語拡張で別 tool 評価) - -### #B-γ: reviewer の役割を「検査」から「異常検知」へ (Phase 3) - -**設計思想**: 決定論層 (#B-α PR #99 + #B-β) を通過した状態を前提に、reviewer の責務を **「lint で防げない高次違反のみ flag」** に再定義する。enumerate 義務を削除して attention drift 問題を解消。 - -**前提条件**: Phase 2 (#B-β) 完了後に着手する。決定論層が未完成のまま reviewer 役割を絞ると、二重 miss で違反が pre-push を素通りする。 - -**変更内容**: - -- `.takt/facets/instructions/review-simplicity.md` を書き換え: - - 旧: 「6 criteria を順次チェック + ALL findings を列挙」 - - 新: 「決定論層 (#B-α + #B-β) で防げない **異常パターンのみ flag**」 - - 例: 巨大な closure / 不自然な抽象化 / 命名 ambiguity / 設計上の concern - - 例外: comment count / nesting depth / function length は **lint が保証済み** として skip -- `.takt/facets/instructions/review-security.md` も同様の方針 (security lint で防げる範囲は skip、higher-order な脅威のみ flag) - -**期待効果**: - -- attention drift 問題が消滅 (検出対象が absolute に narrow に) -- 1 iter ALL APPROVE 率が **90% 超** に到達 (決定論層で大半が intercept されるため) -- review 所要時間も短縮 (現 baseline 1m 30s〜3m → 30s〜1m 期待) - -**リスク**: - -- deterministic 層 (#B-α / #B-β) の coverage gap で漏れた違反が reviewer もスルー → 二重 miss の可能性 - → 対策: reviewer の異常検知 instruction に「過度に narrow にしすぎない」ガイドラインを残す -- 「異常」の定義が LLM 主観で false positive が出る場合、決定論層 update で対応 (lint rule 追加) - -### 採用判定 - -| 改善案 | ROI | 実装コスト | 推奨 | -|---|---|---|---| -| **#B-β 制約付き fix instruction** | ★★★★ | M (helper script + facet update) | **Phase 2** (PR #99 後の dogfood 観測完了後着手) | -| **#B-γ reviewer 役割変更** | ★★★ | S (facet instruction 書き換え) | **Phase 3** (Phase 2 dogfood 観測完了後着手) | - -**期待累積効果** (Phase 1 完了済 + Phase 2/3 完了後): pre-push iter 分布 `{1×3, 3×2, 6×1}` (PR #97 ベースライン) → `{1×N}` (1-iter ALL APPROVE 構造化)。outlier 率 1/6 (16.7%) → 0% 達成試算。 - ---- - -## #C: post-pr-review パイプライン (残作業) - -> **背景**: pre-push-review と比較すると概ね健全だが、3-iter の outlier が 1 件あり (PR #96 の auto-fix run、10m 19s)。 - -### #C-2: fix step 報告に基づく Iter 3 短絡 - -**根因**: post-pr-review の 3-iter 解析より、`review-comments.json` snapshot は fix 後も refresh されないため、Iter 3 の analyze は **同じ findings を再評価する**。Iter 3 output 例: - -> 「`.takt/review-comments.json` is a snapshot captured before fix iteration 1 ran; CodeRabbit has not re-reviewed yet, so the same 2 findings appear. The previous fix step report indicates both were addressed. **I verified each by reading the current source**...」 - -つまり Iter 3 は「fix step が言う通りに本当に修正されているか」をソースを読んで再確認している。**fix step を信頼すれば不要な作業**。 - -**実装案**: - -- `fix.md` instruction の `## Convergence gate` table の `persists` が 0 で `misdirected` が 0 なら "fully resolved" マーカーを report に書く -- workflow rule に `condition: All findings fixed (no persists)` を追加して `next: COMPLETE` - -**期待効果**: 3-iter run を 2-iter に圧縮 (~3 分削減)。年に数十回ある仮想シナリオで累積効果 - -**リスク**: - -- fix step の自己評価信頼性 (現状でも `persists: 0` を report しているが、未修正のまま 0 を書く可能性ゼロではない) -- 後続 supervise step でカバーされない場合は安全網が薄くなる - -### #C-3: rate-limit 発生時の post-pr-review skip - -**前提となる完了 PR**: PR #97 (cli-pr-monitor の rate-limit 自動検出 + 再トリガー) で rate-limit 検出機構は実装済。本作業はその検出結果を post-pr-review takt invoke の skip 判定に流用する。 - -**実装案**: `cli-pr-monitor` 側で `rate_limit.is_some()` の時 takt invoke を skip し、log のみ出力。次のセッションで再起動された時に通常 flow が走る。 - -**期待効果**: rate-limit 中に post-pr-review が空打ちする 1-2 分を完全削減。本セッションのように rate-limit が頻発する場合 (4 round) で **計 4-8 分削減** - -**リスク**: 低い。rate-limit 中に findings は得られないため skip は妥当。 - -### 採用判定 - -| 改善案 | ROI | 実装コスト | 推奨 | -|---|---|---|---| -| #C-3 rate-limit skip | ★★★★ | S (cli-pr-monitor 1 分岐) | 即実施 | -| #C-2 Iter 3 短絡 | ★★ | M (workflow + instruction 改修) | dogfood 後 | - ---- - -## #D: Claude 応答スタイル (保留) - -> **完了済の関連項目**: gh CLI 使用パターン最適化は Bundle a (PR #100 + #101) で対応済。`check-ci-coderabbit --list-findings` で構造化取得が可能になっている (#C-3 でも活用余地あり)。 - -### #D-4: Claude 応答スタイルの簡素化 ⏸️ 保留 (2026-05-02) - -**背景**: Claude (私自身) の text-only 応答が 8.5M cache_creation tokens (全体の 62%) を占める。これらは **後続全 turn の cache に乗り続ける** ため、初回の出力サイズが最終的に 9x で billable input token に膨らむ (1KB の応答 → 後続 9KB)。 - -**保留理由** (PR #99 セッション末のユーザー判断、ADR-034 参照): - -- **思考連続性低下リスク**: 中間出力 (Insight ブロック / 完了報告 / 分析テーブル) は後続 turn の cache に乗り、Claude が「これまでの判断」を参照するソース。削減すると後段で context 再構築 (再 grep / 再 read) を招き、token カテゴリが入れ替わるだけで正味削減が縮む可能性 -- **副作用観測手段が未確立**: ルール導入で実際にどれだけ削減 / どれだけ思考品質低下するかの定量比較が困難 -- **再評価条件**: Bundle Z Phase 2/3 (#B-β / #B-γ) 完了後、副作用観測手段 (例: session 比較メトリクス、思考品質 proxy 指標) が確立してから慎重 pilot - -**ガイドライン案** (採用時に `~/.claude/rules/common/coding-style.md` または専用 rule に追加): - -```markdown -## トークン効率優先の応答スタイル (rate-limit 不安定期は特に) - -### CR review listing -- 本文・suggestion・修正案の quote を **含めない** (file:line + severity + 1 行要約のみ) -- 「outdated 解釈」セクションは指摘がある場合のみ -- 各 finding 末尾の判定 (✅推奨 / ⚠️任意 / ❌不採用) は 3 文字記号のみで詳細根拠は省略 - -### 完了報告 -- PR push 完了: PR URL + commit hash + テスト結果のみ -- merge 完了: PR URL + 主要数値 (commits / iterations) のみ -- 「次のアクション」提案は user が要求した場合のみ - -### Insight ブロック -- 1 ターンに最大 1 つまで -- 真に非自明 (調査結果・予想外の挙動) のみ。一般的な感想は省略 -``` - -**期待効果**: text-only response 約 30-50% 削減 (推定 **2.5-4M cache_creation tokens 削減**) - ---- - -## 全体統合: 残作業の PR 計画 - -> **方針**: 「少ない PR で的確に + フィードバックループを活かす」を満たすため、3 PR の依存順実行とする。Bundle Z Phase 2/3 は dogfood signal の純度確保のため分割必須、その他は即時 skip 系 / fix-trust 系で thematic にバンドル。 - -### PR 計画 (3 PR、依存順) - -#### PR 1: 即時 skip バンドル (即実施可) - -| 含む項目 | 変更箇所 | 内容 | effort | -|---|---|---|---| -| #C-3 | `cli-pr-monitor` | rate-limit 検出時に post-pr-review takt invoke を skip (PR #97 の `rate_limit.is_some()` を流用) | S | -| #A-2 | `cli-merge-pipeline` | doc-only かつ commit 数=1 かつ +/-<50 の trivial PR で post-merge-feedback skip | S | - -**バンドル根拠**: 異なる crate だが両方とも「条件検出 → パイプライン skip」の単純 guard 追加。発火する PR の種類が異なる (rate-limit 中の PR vs doc-only PR) ため、後続 dogfood で誤発火が起きても帰属が明確。 - -**期待効果**: rate-limit 頻発セッションで 4-8 分削減 + doc PR 月次発生分の post-merge-feedback コスト削減 - -#### PR 2: Bundle Z Phase 2 — #B-β 単独 (PR #99 dogfood 完了後) - -| 含む項目 | 変更箇所 | 内容 | effort | -|---|---|---|---| -| #B-β | `.takt/facets/instructions/fix.md` + `scripts/fix-metrics-check.ps1` (新規) | 制約付き fix instruction (deterministic check)。例外マーカーは PR #99 の `ALLOWED_LINE_PREFIXES` / `ALLOWED_BLOCK_PREFIXES` を import | M | - -**単独 PR にする根拠**: 決定論メトリクス層は novel で、合理的 refactor の誤 reject リスクが未知。Phase 3 (#B-γ) は Phase 2 が信頼できることを前提に reviewer 役割を絞るため、**Phase 2 単独 dogfood で誤 reject 率を計測しないと Phase 3 の二重 miss リスクが評価不能**。 - -**期待効果**: pre-push-review 根因 2 (fix が新 violation を introduce) の構造的排除 - -#### PR 3: Phase 3 + fix-trust 連帯 (PR 2 dogfood 完了後) - -| 含む項目 | 変更箇所 | 内容 | effort | -|---|---|---|---| -| #B-γ | `.takt/facets/instructions/review-{simplicity,security}.md` | reviewer enumerate 義務を削除、決定論層が intercept する metric (comment count / nesting / function length) は skip、異常検知のみ flag | S | -| #C-2 | `.takt/workflows/post-pr-review.yaml` + `fix.md` の Convergence gate | fix step が `persists: 0 / misdirected: 0` を report したら Iter 3 analyze を skip して COMPLETE 直行 | M | - -**バンドル根拠**: 両方とも **「LLM が出した結果を後段で再検証しない」** という設計哲学の応用。失敗モードも共通 (fix step が誤って "fully resolved" を report → 後段でカバーされない)。同 PR で land すると「決定論層 + fix step trust」のフルシフトが 1 セッションで観測でき、効果計測も統合的。 - -**期待効果**: pre-push iter 分布 → `{1×N}` 構造化 (1-iter ALL APPROVE 90% 超) + post-pr-review 3-iter outlier 消失 - -### 実行順序 - -```text -時間 → - -PR 1 (skip バンドル) ━━━╋━━━━━━━━━━━━━━━━━ [merge → 通常 dogfood で観測] - ↓ -PR 2 (Bundle Z Phase 2) ━━━╋━━━━━━━━━━━━━━ [merge → 1-2 PR で誤 reject 率計測] - ↓ -PR 3 (Phase 3 + fix-trust) ━━━╋━━━━━━━━ [merge → outlier 0% 検証] - -任意: PR 1 と PR 2 は並列着手可 (依存なし) -必須: PR 3 は PR 2 merge + dogfood 1-2 PR 後 -``` - -### 各 PR 着手前チェックリスト - -| PR | 着手前に確認すべきこと | -|---|---| -| PR 1 | なし (即着手可) | -| PR 2 | PR #99 の `ALLOWED_LINE_PREFIXES` 定数が安定していること (PR #99 merge 後の dogfood で例外マーカー追加が落ち着いていること) | -| PR 3 | PR 2 merge 後 1-2 PR で **適切な refactor が誤 reject されていないこと** を確認 (`.takt/runs//fix-metrics.log` を観測) | - -### 番外: #A-3 transcript filter (任意タイミング) - -**判断**: PR 1〜3 のいずれにも組み込まない。**スキマ時間の単独 PR** か **#D-4 再評価セッション** に同梱が妥当。 - -**理由**: - -- 他のどの PR とも依存も共通テーマもない (analyze-session の input range filter という独立 infra 作業) -- effort M でテスト追加が要る → PR 1 に混ぜると規模が膨らむ -- Phase 3 dogfood の signal 純度を保ちたいので PR 3 にも混ぜない -- ROI ★★★ で優先度が中程度 - -### 期待効果 (残作業) - -| 項目 | 削減対象 | 想定削減量 | 検証指標 | -|---|---|---|---| -| Bundle Z Phase 2 + 3 | pre-push-review iter 数 | **outlier 0% 達成 + 1-iter ALL APPROVE 90% 超** | pre-push-review iter 分布 (`{1×N}` 集中度)、6-iter outlier 発生率 | -| #A-2 trivial PR skip | doc-only PR の post-merge-feedback 起動 | doc PR ごとに 9 分削減 | post-merge-feedback runs 数 | -| #A-3 transcript filter | analyze-session の input token | 30-50% 削減 (推定) | analyze-session の billable input tokens | -| #C-2 Iter 3 短絡 | post-pr-review iter 3 | 3-iter run を 2-iter に圧縮 (~3 分削減/run) | post-pr-review の avg iter 数 | -| #C-3 rate-limit skip | rate-limit 中の空打ち | 計 4-8 分削減/session (rate-limit 頻発時) | rate-limit 検出時の post-pr-review skip 率 | -| #D-4 (保留) | Claude text-only response | 潜在 2.5-4M tokens 削減 (18-29%)、要副作用観測 | session 比較メトリクス (要設計) | - -### 検証方法 (Bundle 実装後に実施) - -実装後セッションを 1 つ完走させた後、以下を「観測データ」セクションと比較。 - -#### ① セッション全体メトリクス比較 (全残作業共通) - -```bash -# 別セッションの jsonl path を取得 (例: ~/.claude/projects//.jsonl) -python3 - <<'EOF' -import json -totals = {'cache_creation': 0, 'cache_read': 0, 'output': 0} -turns = 0 -with open('') as f: - for line in f: - try: obj = json.loads(line) - except: continue - usage = obj.get('message', {}).get('usage') - if not usage: continue - totals['cache_creation'] += usage.get('cache_creation_input_tokens', 0) - totals['cache_read'] += usage.get('cache_read_input_tokens', 0) - totals['output'] += usage.get('output_tokens', 0) - turns += 1 -print(f'Turns: {turns}') -print(f'Cache creation: {totals["cache_creation"]:,}') -print(f'Cache read: {totals["cache_read"]:,}') -print(f'Output: {totals["output"]:,}') -EOF -``` - -**比較値 (ベースライン)**: - -- Turns: 1,181 -- Cache creation: 13,638,572 -- Cache read: 350,868,831 -- Output: 833,825 - -#### ② takt パイプライン時間比較 (#A / #C 系の検証用) - -```bash -for d in .takt/runs/-*-{pre-push-review,post-pr-review,post-merge-feedback}*; do - iter=$(grep -o '"iterations":\s*[0-9]*' $d/meta.json | head -1 | grep -o '[0-9]*') - start=$(grep -o '"startTime":\s*"[^"]*"' $d/meta.json | grep -o '[0-9TZ:.-]\{20,\}') - end=$(grep -o '"endTime":\s*"[^"]*"' $d/meta.json | grep -o '[0-9TZ:.-]\{20,\}') - echo "$(basename $d): iter=$iter start=$start end=$end" -done -``` - -**比較値 (ベースライン)**: - -| パイプライン | Runs | 総 iter | 総時間 | -|---|---|---|---| -| pre-push-review | 6 | 15 | 47.9 分 | -| post-merge-feedback | 4 | 8 | 35.5 分 | -| post-pr-review | 6-8 | 9-15 | 22-31 分 | - -#### ③ pre-push-review iter 分布比較 (Bundle Z Phase 2 / 3 検証専用) - -ベースライン: `{1×3, 3×2, 6×1}` = 6 runs (うち 6-iter outlier 1 件、avg iter 2.5) - -目標 (Phase 2/3 完了後): `{1×N}` (1-iter 固定) で 6-iter outlier 消失 (outlier 率 1/6 (16.7%) → 0%)、avg iter 2.5 → 1.0、1-iter ALL APPROVE 率 90% 超 - -### 別セッションでの作業指示 (テンプレート) - -```markdown -## 作業概要 -本セッションは docs/pipeline-token-efficiency.md の [PR 1 | PR 2 | PR 3 | 番外 #A-3] を実装する。 -含む項目と変更箇所は同ドキュメントの「PR 計画」セクションを参照。 - -## 着手前チェック -docs/pipeline-token-efficiency.md の「各 PR 着手前チェックリスト」を確認し、前提が満たされていることを確認。 - -## 実装タスク -- [ ] PR 計画に列挙された全項目の実装 -- [ ] テスト追加 (該当する場合) -- [ ] 実装 PR を作成 -- [ ] merge 後に本セッションを 1 つ完走させる (検証用 dogfood) - -## 検証方法 -docs/pipeline-token-efficiency.md の「検証方法」を実行。 -ベースライン値と比較し、想定削減量に届いているか測定。 - -## 完了基準 -- 想定削減量の 70% 以上達成 → 本ドキュメントから該当 PR セクション削除 + 進捗管理に PR 番号記録 -- 想定削減量に届かず → 原因分析を「全体統合」セクション末尾に追記し、必要なら計画再編 -``` - ---- - -## 進捗管理 - -| 改善案 | 配置 | 状態 | 採用日 | 完了 PR | 備考 | -|---|---|---|---|---|---| -| #C-3 rate-limit skip | **PR 1** | 完了 | 2026-05-03 | #102 | PR #97 の rate-limit 検出を流用 | -| #A-2 trivial PR skip | **PR 1** | 完了 | 2026-05-03 | #102 | 単独実施可 | -| #B-β 制約付き fix instruction | **PR 2** (Bundle Z Phase 2) | 完了 | 2026-05-03 | #103 | PR #99 の例外マーカー定数と同期必須 | -| #B-γ reviewer 役割変更 | **PR 3** (Bundle Z Phase 3) | 実装中 | 2026-05-04 | (進行中) | PR #103/104/105 dogfood 完了、anomaly mode に転換 | -| #C-2 Iter 3 短絡 | **PR 3** (fix-trust 連帯) | 実装中 | 2026-05-04 | (進行中) | PR 3 で #B-γ と同梱、convergence_verdict マーカー導入 | -| #A-3 transcript filter | **番外** | 計画 | - | - | スキマ時間の単独 PR か #D-4 再評価時に同梱 | -| #D-4 応答スタイル簡素化 | (保留) | 保留 (ADR-034) | 2026-05-02 | - | Bundle Z (PR 2 + PR 3) 完了後再評価 | - ---- - -## 関連 - -- 元セッション: `C:\Users\HIROKI\.claude\projects\e--work-claude-code-hook-test\6cbc5021-e5f4-420d-853b-e1b467d45ae4.jsonl` -- 前提となる完了 PR (残作業の依存先): - - **PR #97** (cli-pr-monitor rate-limit 自動検出): #C-3 の前提 — 検出機構を流用して skip 判定を追加 - - **PR #99** (Bundle Z Phase 1 — `src/hooks-post-tool-comment-lint-rust/`): #B-β / #B-γ の前提 — 例外マーカー定数 (`ALLOWED_LINE_PREFIXES` / `ALLOWED_BLOCK_PREFIXES`) を single source of truth として参照 - - **PR #100** (Bundle a Sub-PR 0 — gh CLI 規則 + ADR-034 起案): #D-4 保留判断の根拠 - - **PR #101** (Bundle a Sub-PR 1 — `check-ci-coderabbit --list-findings`): rate-limit 関連で構造化 findings 取得が可能 -- 関連 ADR: - - [ADR-015](adr/adr-015-push-runner-takt-migration.md) (push runner takt 化) - - [ADR-018](adr/adr-018-pr-monitor-takt-migration.md) (cli-pr-monitor takt 化) - - [ADR-020](adr/adr-020-takt-facets-sharing.md) (facets 共通化) - - [ADR-030](adr/adr-030-deterministic-post-merge-feedback.md) (post-merge-feedback 決定論化) - - [ADR-034](adr/adr-034-coderabbit-auto-monitoring.md) (#D-4 保留判断 + Bundle a 設計根拠) -- 関連 workflow: [.takt/workflows/](../.takt/workflows/) diff --git a/docs/todo.md b/docs/todo.md index 83f6752..1a39e20 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -71,6 +71,7 @@ | 56 | 🔧 Tier 2 | **comment-lint hook test 拡充 (PR #104 T2-1+T2-2 bundle)** | todo5.md | S | なし (UTF-8 multi-byte 5 パターン + block comment boundary 6 パターンを `locate_string_line_ranges` / `span_overlaps_ranges` の回帰テストとして体系化、PR #104 Critical/Minor fix の固定化) | | 57 | 🔧 Tier 2 | **Aggregation cap integration test (PR #105 T2-1 採用)** | todo5.md | S | なし (`collect_all_violations` の MAX_VIOLATIONS contract を test 化、将来の lint 追加時に `truncate(MAX)` 削除 regression を防止する explicit 安全網) | | 59 | 💎 Tier 3 | **ADR-035: docs 評価ポリシー (PR #107 T3-1 採用)** | todo5.md | M | なし (PR #107 dogfood で AI が code review criteria を documentation-only PR に誤適用するパターンを確認、review-security.md の trust boundary criterion を全 reviewer facet に拡張、false REJECT 削減) | +| 60 | 💎 Tier 3 | **analyze-session の transcript filter 絞り込み (旧 #A-3)** | todo5.md | M | なし (旧 docs/pipeline-token-efficiency.md #A-3、ADR-036/037 化に伴い計画書削除、本 task のみ todo に移管。analyze-session の input range を PR 作成 commit〜merge に限定して input token 30-50% 削減見込み、dogfood で実測必要) | **戦略**: 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/todo4.md b/docs/todo4.md index 3ce16e1..1a93e77 100644 --- a/docs/todo4.md +++ b/docs/todo4.md @@ -342,9 +342,9 @@ > **動機**: Bundle Y2 (PR #98) で analyze 系 step を sonnet → haiku に変更したが、ROI 根拠は `docs/pipeline-token-efficiency.md` の推定値 (PR #78 dogfood 12m13s → 並列化想定 7m30s) のみ。PR #98 セッション内観測 (post-pr-review takt 1m 13s / post-merge-feedback 8m 9s) は単発データで baseline (PR #97 セッション、avg 8.9 分) との比較が systematic にドキュメント化されていない。Bundle Z (#B-*) / Bundle Z2 (#D-*) の ROI 判断材料として PR #97 (sonnet baseline) vs PR #98 以降 (haiku) の実測比較を 3-5 PR 分集計し記録する。 > -> **本タスクの位置づけ**: Bundle Y2 効果検証層。`docs/pipeline-token-efficiency.md` の「検証方法」セクション (① jsonl セッションメトリクス + ② takt run meta.json 集計) を実行し、結果を計画書末尾に「実測検証データ」セクションとして追記。想定削減量達成時は計画書の Bundle Y2 セクションを retire し ADR 化判断の材料とする (計画書ヘッダー L5 方針)。 +> **本タスクの位置づけ**: Bundle Y2 効果検証層。**注: 動機の主軸 (Bundle Z / Z2 ROI 判断材料) は失効** — Bundle Z は PR #99/#103/#106 で完成、Bundle Z2 = #D-4 はユーザー判断で不採用 (ADR-034 参照)。本 task は obsolete 候補だが、takt パイプライン効率の継続観測としてなら価値あり。**本格着手前にユーザー判断要 (削除 vs 縮小スコープで継続)**。検証方法は (削除済) `docs/pipeline-token-efficiency.md` 「検証方法」セクションに記載されていた jsonl セッションメトリクス + takt run meta.json 集計。 > -> **参照**: `.claude/feedback-reports/98.md` Tier 2 #2、`docs/pipeline-token-efficiency.md` 「検証方法」セクション +> **参照**: `.claude/feedback-reports/98.md` Tier 2 #2、(削除済) `docs/pipeline-token-efficiency.md` 「検証方法」セクション (内容は git log で復元可能) > > **実行優先度**: 🔧 **Tier 2** — Effort Medium。3-5 PR の merge 経過後のデータ集計タスクで、即時着手ではなく観察ベース。Bundle Z / Z2 着手前のベースライン整理として有用。 @@ -355,11 +355,10 @@ - 一意 cache_creation tokens (jsonl usage 集計) - 該当 step の billable input token 削減幅 (haiku は sonnet の約 1/3 cost 想定) - **比較期間**: - - baseline: PR #97 セッション (2026-04-30 〜 2026-05-01 JST) — `docs/pipeline-token-efficiency.md` の「観測データ」セクション既値 + - baseline: PR #97 セッション (2026-04-30 〜 2026-05-01 JST) — (削除済) `docs/pipeline-token-efficiency.md` の「観測データ」セクション既値 (git log で復元可能) - 計測期間: PR #98 merge 後 3-5 PR (Bundle Z / Z2 着手前まで) - **記録先**: - - `docs/pipeline-token-efficiency.md` 末尾に「実測検証データ」セクションを追加 (計画書が retire される前の最終 update) - - 想定削減量の 70% 以上達成 → 計画書の Bundle Y2 セクション削除 → ADR 化判断材料、未達 → 原因分析を計画書末尾に追記し追加 Bundle 提案 + - **(計画書 retire 済 = 2026-05-04)** 旧計画は `docs/pipeline-token-efficiency.md` 末尾に「実測検証データ」追記、想定削減量達成判定に基づく retire / Bundle 追加提案だった。計画書削除済のため、本 task を継続する場合は本 entry 内に直接記録する設計に変更すべき #### 作業計画 @@ -368,13 +367,13 @@ - [ ] 検証方法 ② (takt run meta.json 集計) を実行 - [ ] baseline (PR #97) と比較し削減幅を表に記録 - [ ] 想定削減量 (session あたり 15-20 分削減) との乖離を分析 -- [ ] 結果を `docs/pipeline-token-efficiency.md` 末尾に追記 +- [ ] 結果を本 todo entry 内 (もしくは新規 ADR) に記録 — 旧計画は (削除済) `docs/pipeline-token-efficiency.md` 末尾追記だったが計画書 retire 済 - [ ] 想定削減量達成判定に基づき計画書 retire / 追加 Bundle 提案 - [ ] 本 todo4.md エントリを削除 #### 完了基準 -- PR #98 merge 後 3-5 PR の実測値が `docs/pipeline-token-efficiency.md` に記録される +- PR #98 merge 後 3-5 PR の実測値が本 entry または新規 ADR に記録される (旧計画は (削除済) `docs/pipeline-token-efficiency.md` 末尾追記) - baseline (PR #97) との削減幅が Bundle Y2 の想定削減量と比較され、達成 / 未達の判定がある - Bundle Z / Z2 の ROI 判断材料として活用可能なデータが揃う @@ -486,7 +485,7 @@ > > **本タスクの位置づけ**: 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`) +> **参照**: ADR-034 (CodeRabbit 監視・対話の自動化戦略)、(削除済) `docs/pipeline-token-efficiency.md` #D-1 セクション (経緯は ADR-034 で保存)、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 推奨。 @@ -525,7 +524,7 @@ > > **本タスクの位置づけ**: 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 と整合する根拠) +> **参照**: ADR-034 (CodeRabbit 監視・対話の自動化戦略)、(削除済) `docs/pipeline-token-efficiency.md` #D-3 セクション (経緯は ADR-034 で保存)、ADR-022 (自動化コンポーネントの責務分離原則 — Rust 側実装が ADR-022 と整合する根拠) > > **実行優先度**: 🔧 **Tier 2** — Effort Medium。Rust 実装 + テスト。`check-ci-coderabbit` crate (既存) への mode 追加で、新 crate 作成は不要 (ADR-026 Cargo workspace member 構成変更なし)。 diff --git a/docs/todo5.md b/docs/todo5.md index bcf0969..462fd89 100644 --- a/docs/todo5.md +++ b/docs/todo5.md @@ -100,7 +100,7 @@ > > **本タスクの位置づけ**: PR #103 セッション知見 (post-merge-feedback の Tier 3 #1 = ADR 化提案を skip し、機構で塞ぐ実装層対策を採用)。Bundle Z 3 層 (#B-α / #B-β / #B-γ) では完全に塞げない独立改善。reviewer の判定精度を構造的に改善することで 6-iter outlier の発生率を 0% 近くに抑える。 > -> **参照**: `.claude/feedback-reports/103.md` (Tier 3 #1 で同根因に別アプローチ提案、本 task で代替)、`.takt/runs/20260503-113700-pre-push-review/reports/supervisor-validation.md` (false positive 構造診断)、[docs/pipeline-token-efficiency.md](pipeline-token-efficiency.md) PR #97 / #103 の 6-iter outlier 観測データ +> **参照**: `.claude/feedback-reports/103.md` (Tier 3 #1 で同根因に別アプローチ提案、本 task で代替)、`.takt/runs/20260503-113700-pre-push-review/reports/supervisor-validation.md` (false positive 構造診断)、[ADR-036: Bundle Z 3 層アーキテクチャ](../docs/adr/adr-036-bundle-z-three-layer-review.md) (PR #97 ベースライン observation を含む、本 task は Bundle Z 3 層では塞げない独立改善) > > **実行優先度**: 🚀 **Tier 1** — Effort M。takt 設定 / pre-push-review.yaml への hook 追加。 @@ -470,3 +470,47 @@ - "docs-only" の境界判定 (例: facet instruction = AI prompt は code か docs か、yaml の structural 変更 = code か docs か) で AI 解釈が揺れる可能性 → ADR で具体例を 5-10 件列挙して cluster 化を狙う - 既存 facet との重複削除で意味が変わらないよう注意 (review-security.md trust boundary criterion を ADR-035 に移動した結果、reviewer が docs PR を素通しするバグが発生しないか dogfood で確認) +--- + +### analyze-session の transcript filter 絞り込み (旧 #A-3) + +> **動機**: `cli-merge-pipeline` が生成する `.takt/post-merge-feedback-transcript.jsonl` は **session 全履歴** を含むため、analyze-session step が読み込む input token が大きい。当該 PR に直接関連する範囲のみ filter すれば input token 削減 = post-merge-feedback の cache_read 削減。 +> +> **本タスクの位置づけ**: 旧 `docs/pipeline-token-efficiency.md` の #A-3 entry。同計画書は ADR-036 (Bundle Z 3 層) / ADR-037 (fix-trust shortcut) に主要決定を移し終了予定で、残作業として本 task のみ todo に移管。Bundle 化対象なし、独立 PR 推奨。 +> +> **参照**: (削除済) `docs/pipeline-token-efficiency.md` #A-3 セクション、`src/cli-merge-pipeline/` の transcript 生成ロジック +> +> **実行優先度**: 💎 **Tier 3** — Effort M。ROI ★★★ で優先度中程度、dogfood 実測が必要。 + +#### 設計決定 (案) + +- **filter 範囲**: 当該 PR の作成 commit (= cli-pr-monitor が PR を最初に検出した時刻、または `pnpm create-pr` 完了時刻) から merge 完了時刻までの jsonl 行のみ +- **時刻判定**: jsonl の `timestamp` field を使用 (各エントリに ISO 8601 形式で記録あり) +- **境界の扱い**: + - 開始時刻 *以降*: PR 作業中の Claude 対話 + tool 実行履歴 + - 終了時刻 *まで*: merge 完了 (= post-merge-feedback 起動の直前まで) + - 境界外 (PR 作成前 / merge 後): 除外 +- **既存挙動との互換**: 開始時刻取得失敗時 (state file なし等) は全 session フォールバック (no-regression) + +#### 作業計画 + +- [ ] `cli-merge-pipeline` の transcript 生成ロジックを特定 +- [ ] PR 作成時刻 / merge 時刻の取得経路を確定 (`.claude/cli-pr-monitor-state.json` or `gh pr view --json mergedAt` 等) +- [ ] timestamp 比較で jsonl 行を filter する logic を実装 +- [ ] 開始時刻取得失敗時のフォールバック (全 session) を保持 +- [ ] dogfood 1-2 PR で input token 削減量を実測 (analyze-session の billable input tokens で比較) +- [ ] 削減効果が想定 30-50% に届くか確認、届かない場合は filter 設計を見直し +- [ ] 派生プロジェクト (techbook-ledger / auto-review-fix-vc) への deploy +- [ ] 本 todo5.md エントリを削除 + +#### 完了基準 + +- analyze-session の input token が PR 作業範囲のみに絞り込まれる +- dogfood で 30-50% 削減を実測 (削減未達なら filter 設計を見直し) +- 開始時刻取得失敗時のフォールバックが機能 (regression なし) + +#### 詰まっている箇所 + +- 「PR 作成前の議論 (設計判断、却下されたアイデア)」が落ちる可能性 → post-merge-feedback の知見質に影響しうる。dogfood で「重要 finding が拾えなくなった」事象が出たら filter 範囲を広げる (例: PR 作成 commit から 2 時間前まで遡る等) +- transcript jsonl の structure 変更時に filter logic が壊れる risk → field name (`timestamp`) を assert する unit test を追加 + From a7c3ac46b29218770e36583ac739d58616aad23a Mon Sep 17 00:00:00 2001 From: aloekun Date: Mon, 4 May 2026 16:08:36 +0900 Subject: [PATCH 5/5] =?UTF-8?q?fix(todo):=20=E9=A0=86=E4=BD=8D=2041=20entr?= =?UTF-8?q?y=20=E3=81=AE=20retire=20=E6=B8=88=E5=89=8D=E6=8F=90=E3=81=A8?= =?UTF-8?q?=E6=97=A7=E3=83=95=E3=83=AD=E3=83=BC=E6=96=87=E8=A8=80=E3=81=AE?= =?UTF-8?q?=E4=B8=8D=E6=95=B4=E5=90=88=E3=82=92=E8=A7=A3=E6=B6=88=20(#108?= =?UTF-8?q?=20CR=20Minor)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit が PR #108 review で 'outside diff range comment' として指摘した docs/todo4.md 順位 41 (Bundle Y2 効果定量計測) の line 371/378 残存問題を修正。 - 削除: 'Line 371: 想定削減量達成判定に基づき計画書 retire / 追加 Bundle 提案' (計画書はすでに retire 済のため、retire 判定ステップが矛盾) - 削除: 'Line 378: Bundle Z / Z2 の ROI 判断材料として活用可能なデータが揃う' (Bundle Z は完成、Bundle Z2 = #D-4 は不採用で本目的の役割消滅) - 修正: '結果を本 todo entry 内 (もしくは新規 ADR) に記録 — 旧計画は ...' → '結果を本 entry または新規 ADR に記録 (= 完了)' に簡素化 判定対象を「本 entry/ADR への記録完了」に統一し、retire 済前提との整合を確保。 備考 (別観察): 本指摘は CodeRabbit が 'outside diff range comment' として review body 内に含めて投稿したため、inline comment 前提の takt analyze-coderabbit step では 0 findings 判定 (= 検出漏れ) となった。 takt analyzer の coverage gap として将来の post-merge-feedback で扱う。 --- docs/todo4.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/todo4.md b/docs/todo4.md index 1a93e77..e5d0a0e 100644 --- a/docs/todo4.md +++ b/docs/todo4.md @@ -367,15 +367,13 @@ - [ ] 検証方法 ② (takt run meta.json 集計) を実行 - [ ] baseline (PR #97) と比較し削減幅を表に記録 - [ ] 想定削減量 (session あたり 15-20 分削減) との乖離を分析 -- [ ] 結果を本 todo entry 内 (もしくは新規 ADR) に記録 — 旧計画は (削除済) `docs/pipeline-token-efficiency.md` 末尾追記だったが計画書 retire 済 -- [ ] 想定削減量達成判定に基づき計画書 retire / 追加 Bundle 提案 +- [ ] 結果を本 entry または新規 ADR に記録 (= 完了) - [ ] 本 todo4.md エントリを削除 #### 完了基準 -- PR #98 merge 後 3-5 PR の実測値が本 entry または新規 ADR に記録される (旧計画は (削除済) `docs/pipeline-token-efficiency.md` 末尾追記) +- PR #98 merge 後 3-5 PR の実測値が本 entry または新規 ADR に記録される - baseline (PR #97) との削減幅が Bundle Y2 の想定削減量と比較され、達成 / 未達の判定がある -- Bundle Z / Z2 の ROI 判断材料として活用可能なデータが揃う #### 詰まっている箇所