From b0040cd00c18d0f1cf0283c70ec84b6d5ae18a35 Mon Sep 17 00:00:00 2001 From: aloekun Date: Tue, 5 May 2026 05:54:31 +0900 Subject: [PATCH] =?UTF-8?q?feat(docs):=20Bundle=20f=20+=20retirement=20?= =?UTF-8?q?=E2=80=94=20=E9=A0=86=E4=BD=8D=2062/71-74=20land=20+=20docs-pr-?= =?UTF-8?q?iteration-efficiency.md=20retire=20(PR=20#111=20post-merge-feed?= =?UTF-8?q?back)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Bundle f (PR #111 post-merge-feedback、4 件採用) + 順位 62 (Document Governance) + 計画書 retirement の 1 PR 集約 land ### 順位 62 (Document Governance、Effort XS、新規 global rule) - 新規 ~/.claude/rules/common/docs-governance.md を作成 - 3 ルール codify: 1. Document Lifecycle Classification (permanent / ephemeral) 2. Cross-File Reference Lifecycle (再掲、coding-style.md と cross-link) 3. Retirement 4-step workflow (migrate value → migrate tasks → update refs → delete file) - 本 PR 自身が retirement workflow の dogfood (docs/docs-pr-iteration-efficiency.md retire = 第一実例) ### 順位 71 (codification claims 検証手順、Effort XS) - ~/.claude/rules/common/coding-style.md の Cross-File Reference Lifecycle に新 sub-section ### Codification claims の検証手順 追加 - 「file X の section Y に codified」と書く前に grep で実在確認、階層表現 > は ambiguous なため避ける - PR #111 自己違反事例を実例引用 (Personal Preferences > Code Style 拡張 → CodeRabbit Critical 指摘) ### 順位 72 + 73 (ADR-033 拡張、Effort XS×2、同一新セクション内) - docs/adr/adr-033-todo-numbering-simplification.md に新セクション ## priority table 運用ルール 追加 - 順位 72: 「依存」列の二層追跡 (technical 依存 vs strategic 順序)、順位 10 broken-link を実例引用 - 順位 73: Bundle 分割時の land 期限明記ルール、Bundle U/V/d を過去事例として引用 - 本 PR 自身が順位 73 の dogfood (Bundle f 分割推奨を統合実行した判断記録は commit message + PR body に残す) ### 順位 74 (ADR-030 拡張、Effort XS) - docs/adr/adr-030-deterministic-post-merge-feedback.md の 入力源 / 出力 直後に新セクション ### Global rules editing の追跡 追加 - global rules (~/.claude/rules/, ~/.claude/CLAUDE.md, ~/.claude/skills/) の編集は VCS 管理外、transcript 経由で post-merge-feedback が捕捉 - PR #111 を実例引用 (5 ファイル global edit + project diff 0 行 + post-merge-feedback で全件 visible) - pre-merge 補完層として coding-style.md (順位 71) と docs-governance.md (順位 62) を cross-link ### Retirement (docs/docs-pr-iteration-efficiency.md 削除) - bundle 全消化 (Bundle docs-PR-streamline / docs-quality-pre-write / e で 12 件 land、残 順位 10 は priority table で継続追跡) で本ファイルが自己宣言した end condition 成立 - ADR-035 + global rules + lint rule + priority table 脚注で永続価値が全て分散保存済 → 新規 ADR 作成は不要 - 参照解除: docs/coderabbit-monitoring-efficiency.md:117 のリンクを ADR-035 リンクに置換 ### Cleanup - docs/todo5.md: 順位 62/71/72/73/74 の 5 詳細エントリ削除 - docs/todo.md: priority table から 5 行削除 + Bundle f 脚注を全 4 件 land + retirement 完了に更新 ## Sub-PR 分割可否の dogfood 結果 (順位 73 への self-feedback) 順位 73 が codify した「Bundle 分割時の land 期限明記」ルールを本 PR の作業計画段階で適用検討した。結果、以下の理由で **統合 1 PR を選択**: - ファイル削除 + 順位 62 (新規 global rule) + Bundle f 4 件 が全て docs-PR governance 領域で scope が完全重複 - retirement が global rule (順位 62) の dogfood として最も価値が高く、両者を分離すると意味的連続性が壊れる - 5 ファイル touch は review 容易性を著しく下げるほどではない 順位 73 ルールは「分割時に期限を書く」を default としているが、本 PR のように統合に強い意味的根拠がある場合は統合を許容する。判断プロセス自体が今後の Bundle 運用への参照記録となる。 ## 期待効果 (検証は dogfood) - 計画書 ephemeral lifecycle が global rule (順位 62) で codify され、再発時の判断ぶれ消滅 - Cross-File Reference Lifecycle の self-application 強化で PR description / commit message での codification claim が事前検証される - priority table 運用の二層追跡 + 期限管理が ADR-033 で formalize、長期滞留 detection - global rules 編集の transparency が ADR-030 で formalize、post-merge-feedback による事後検証経路が明示化 --- ...r-030-deterministic-post-merge-feedback.md | 26 ++++ .../adr-033-todo-numbering-simplification.md | 53 ++++++++ docs/coderabbit-monitoring-efficiency.md | 2 +- docs/docs-pr-iteration-efficiency.md | 113 ------------------ docs/todo.md | 3 +- docs/todo5.md | 49 -------- 6 files changed, 82 insertions(+), 164 deletions(-) delete mode 100644 docs/docs-pr-iteration-efficiency.md diff --git a/docs/adr/adr-030-deterministic-post-merge-feedback.md b/docs/adr/adr-030-deterministic-post-merge-feedback.md index 718bab1a..197e3630 100644 --- a/docs/adr/adr-030-deterministic-post-merge-feedback.md +++ b/docs/adr/adr-030-deterministic-post-merge-feedback.md @@ -120,6 +120,32 @@ skill ベースで運用していた analyze-pr / post-merge-feedback Phase 4 両方とも repository には含めない (`.gitignore` で除外、内部 artifact)。 +### Global rules editing の追跡 + +global rules (`~/.claude/rules/`、`~/.claude/CLAUDE.md`、`~/.claude/skills/` など、ユーザーホーム配下の `.claude/` 配下) の編集は **project repository VCS の管理外** であり、`jj diff` や PR diff には出現しない。しかし post-merge-feedback の analysis は **transcript 経由でこれらの編集も全件捕捉する**。 + +| 編集対象 | VCS への現れ | post-merge-feedback での visibility | +|---|---|---| +| project files (`docs/`, `src/`, `.claude/hooks-config.toml` 等) | `jj diff` / PR diff に出現 | `analyze-pr` (PR data) と `analyze-session` (transcript) の双方で見える | +| global rules (`~/.claude/rules/**`, `~/.claude/CLAUDE.md`, `~/.claude/skills/**`) | **VCS に出現しない** | `analyze-session` (transcript) のみで見える | + +仕組み: Claude Code session transcript には全 Edit / Write 操作が記録される (`tool_use_input` field に file path と new content)。`cli-merge-pipeline` が transcript filter で当該 PR の merge 時刻 range で抽出するため、PR スコープの global rules 編集も merge 後の analysis 対象に含まれる ([transcript 抽出戦略](#transcript-%E6%8A%BD%E5%87%BA%E6%88%A6%E7%95%A5-phase-0-%E8%AA%BF%E6%9F%BB%E7%B5%90%E6%9E%9C%E5%8F%8D%E6%98%A0) 参照)。 + +結論: **global rules の透明性は VCS ではなく post-merge-feedback workflow が担保する**。pre-merge レビュー (pre-push-review / CodeRabbit) では global rules 編集は見えないが、post-merge レビュー (post-merge-feedback) では完全に visible。 + +#### 実証 + +PR #111 (Bundle e、2026-05-04 merged) は `~/.claude/rules/common/{coding-style,git-workflow,development-workflow,code-review}.md` + `~/.claude/CLAUDE.md` の **5 ファイル** を編集したが、project diff は 0 行。にもかかわらず post-merge-feedback report (`.claude/feedback-reports/111.md`) には全 5 ファイルの編集内容が反映され、10 件の findings (うち 4 件採用) が抽出された。 + +#### Pre-merge 補完層の必要性 + +global rules 編集の pre-merge 検証は本 ADR の scope 外だが、補完層として: + +- [coding-style.md § Codification claims の検証手順](file:///~/.claude/rules/common/coding-style.md) — claim と実体の事前同期 +- [docs-governance.md § Cross-File Reference Lifecycle](file:///~/.claude/rules/common/docs-governance.md) — permanent ↔ ephemeral 参照の正しさ + +これらが pre-merge の人間/AI レビューで先回り防止し、post-merge-feedback が事後検証する二段構え。 + ### transcript 抽出戦略 (Phase 0 調査結果反映) ```text diff --git a/docs/adr/adr-033-todo-numbering-simplification.md b/docs/adr/adr-033-todo-numbering-simplification.md index bd230dad..7cff8cce 100644 --- a/docs/adr/adr-033-todo-numbering-simplification.md +++ b/docs/adr/adr-033-todo-numbering-simplification.md @@ -115,6 +115,59 @@ grep -nE "順位 [0-9A-Za-z_-]+" docs/todo.md docs/todo2.md docs/todo3.md \ # ADR の本文中で「絶対番号を示唆する placeholder を本文に書かない」方針を機械検証する。 ``` +## priority table 運用ルール (PR #111 post-merge-feedback で追加) + +本 ADR 採用後の運用で発見された 2 件の暗黙的設計を明文化する。 + +### 「依存」列の二層追跡 — technical 依存 vs strategic 順序 + +priority table の「依存」列 と、領域特化計画書 (例: `docs/coderabbit-monitoring-efficiency.md`) や Bundle 脚注に記録する依存関係は、**別レイヤ** を表す。両者が乖離していても矛盾ではない。 + +| 種別 | 記録先 | 意味 | 例 | +|---|---|---|---| +| **technical 依存** | priority table の「依存」列 | そのタスクが land する前に **technically blocking** な前提タスク。前提が land しないと本タスクが破綻する | `順位 20 ADR-032 PR-β` の依存 = `6, 8, 10` (前提 PR がないと実装不可) | +| **strategic 順序** | 領域特化計画書 / Bundle 脚注 | technical 依存はないが **bundle 化推奨 / 効率的な land 順** という soft な指示。違反しても破綻はしないが iteration コストが上がる | 順位 10 broken-link-check は table 上「依存なし」だが、計画書では「ADR-032 全体 (6/20/21) と bundle 化推奨」 | + +両者は **読み手が別** で読まれる: + +- priority table の「依存」列は **着手判断** に使う (依存が解けたか?) +- 領域特化計画書は **bundle 化判断** に使う (この task だけ単独 land して efficient か?) + +priority table 単独で見て「依存なし」だからといって即着手できるわけではない場合がある。**領域特化計画書 (もし存在すれば) を併読して strategic 順序を確認する** のがレビュー手順。 + +### Bundle 分割時の land 期限明記ルール + +Bundle を Sub-PR に分割する際 (例: Bundle d → d-1 / d-2、Bundle a → Sub-PR 1 / 2)、**残り片方の land 期限を明示する**。期限なしで分割すると、片方が long-tail に滞留しても priority table から検知しにくい。 + +#### 期限フォーマット + +Bundle 脚注 / strategy テキスト内で以下のいずれかで記述する: + +- 具体日付: `(land 期限: 2026-05-15)` +- 関連 PR: `(land 期限: 次 docs PR で集約)` / `(land 期限: 次セッション)` +- 戦略保留: `(保留: <理由>)` — 期限を設けない場合は理由を明示 + +#### 期限超過時の運用 + +期限を過ぎても land しない残存タスクは、Bundle 名から派生命名に変えて再可視化する: + +- `Bundle d` (順位 70 が land、68/69 残) → 期限超過したら `Bundle d-followup` に rename +- 「Bundle 分割の名残」ではなく「独立した task 群」として priority table 内で見える状態にする + +これにより priority table 脚注を見るだけで「どの Bundle が滞留中か」が把握できる。 + +#### 保留 Bundle のケース + +戦略的に保留する場合 (例: 上流依存待ち、外部条件待ち) は、Bundle 脚注で保留理由を明示する。期限を設けないが「なぜ保留か」を残すことで、後日読み返した時の判断材料が消えない。 + +#### 由来 + +- Bundle U (順位 29 = PR #110、順位 30 = Bundle e で land) は分割消化に約 1 週間 +- Bundle V (順位 31/32 = PR #109、順位 33 = Bundle e で land) は 2 件先行 land + 1 件後追いで運用上問題なし +- Bundle d (順位 70 = Bundle e で land、順位 68/69 残) は intermediate state を経由 + +これら過去 split は事後的にトレース可能だが、新規分割時には「期限を書く」を default ルールとすることで滞留を可視化する。 + ## アンチパターン ### 「table 内まで採番除去」してはならない diff --git a/docs/coderabbit-monitoring-efficiency.md b/docs/coderabbit-monitoring-efficiency.md index b44ec59b..8d209fb3 100644 --- a/docs/coderabbit-monitoring-efficiency.md +++ b/docs/coderabbit-monitoring-efficiency.md @@ -114,7 +114,7 @@ ## 関連ドキュメント - [docs/todo.md](todo.md) — 推奨実行順序サマリ表 (priority table) -- [docs/docs-pr-iteration-efficiency.md](docs-pr-iteration-efficiency.md) — 並列の docs PR iteration 領域 +- [ADR-035: docs-only PR 評価ポリシー](adr/adr-035-doc-evaluation-policy.md) — docs PR iteration 改善の核 (旧 docs-pr-iteration-efficiency.md は retire 済、本 ADR に集約) - [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) diff --git a/docs/docs-pr-iteration-efficiency.md b/docs/docs-pr-iteration-efficiency.md deleted file mode 100644 index fc8c22c9..00000000 --- a/docs/docs-pr-iteration-efficiency.md +++ /dev/null @@ -1,113 +0,0 @@ -# ドキュメント 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 - -Bundle "docs PR streamline" (順位 59 / 31 / 32) は本セッションで land 済 → [ADR-035](adr/adr-035-doc-evaluation-policy.md) として集約。残るタスクは下記 MEDIUM / LOW IMPACT のみ。 - -### 🛠 MEDIUM IMPACT — docs 品質 pre-write 保証 - -Bundle "docs quality pre-write" (順位 4 / 29) は本セッションで land 済 → `.claude/hooks-config.toml` に `lint:md` Stop step 追加 + `.claude/custom-lint-rules.toml` に `no-ephemeral-todo-reference` rule 追加。残るは下記 順位 10 のみ (ADR-032 系列待ち)。 - -| 順位 | Tier | タスク概要 | 効果 | 作業詳細 | -|---|---|---|---|---| -| 10 | 🔧 Tier 2 | broken-link-check + 内部アンカー検査統合 (ADR-032 PR-broken-link) | docs/ 内 link 健全性を CI で機械検出、anchor drift を pre-merge で catch | [todo2.md](todo2.md) | - -### 📋 LOW IMPACT — convention グローバル明文化 - -Bundle "e" (順位 23 / 24 / 25 / 26 / 30 / 33 / 70) は本セッションで land 済 → `~/.claude/rules/common/{coding-style,git-workflow,development-workflow,code-review}.md` + **global** `~/.claude/CLAUDE.md` に 7 項目 codify (プロジェクトローカルの `CLAUDE.md` ではなく、ユーザーグローバルの `~/.claude/CLAUDE.md`)。convention 明文化の long-tail を一掃。 - ---- - -## 推奨 bundle - -### Bundle "docs PR streamline" ✅ 完了 - -ユーザー目的「docs-only PR を独立して早急にマージできる環境」の最短達成パス。本セッションで 3 件 land。 - -| 含む順位 | 概要 | 反映先 | -|---|---|---| -| 59 | 中核: ADR-035 docs 評価ポリシー | [ADR-035](adr/adr-035-doc-evaluation-policy.md) + `review-simplicity.md` / `review-security.md` / `analyze-coderabbit.md` 引用 | -| 31 | review-security.md fast-approve 精度向上 | `review-security.md` Excluded paths (`.takt/**` / `.claude/**`) 追記 | -| 32 | todo.md ヘッダ実態整合 | `docs/todo.md` 冒頭運用ルール | - -**期待効果** (検証は本 PR merge 後の dogfood で実施): - -- 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" ✅ 完了 - -write-time に docs 品質を保証する層。本セッションで 2 件 land。 - -| 含む順位 | 概要 | 反映先 | -|---|---|---| -| 4 | Stop hook lint:md | `.claude/hooks-config.toml` `[[stop_quality.steps]]` に `lint:md` 追加 | -| 29 | docs/todo 参照検出 lint | `.claude/custom-lint-rules.toml` rule⑥ `no-ephemeral-todo-reference` (severity warning、`docs/todo[0-9]*\.md` を `rs` / `toml` / `jsonc` / `json` / `yaml` / `ts` / `py` / `ps1` 等で検出) | - -**期待効果**: 本セッションでの dogfood で `docs/todo3.md` を含む `__dogfood_lint.rs` を作成 → rule が warning 2 件発火を確認済。今後 `.rs` / `.toml` / config で ephemeral todo reference を書こうとした時点で hook が警告。 - -### Bundle "e" (convention long-tail) ✅ 完了 - -順位 23-26 + 30 + 33 + Bundle d 残の 順位 70 を 1 PR に集約。convention 明文化で long-tail の品質改善。本セッションで 7 件 land。 - -| 含む順位 | 概要 | 反映先 | -|---|---|---| -| 23 | 日付ベース見出しアンカー安定識別子優先 | `~/.claude/rules/common/coding-style.md` Markdown 節新設 | -| 24 | jj conflict リカバリ手順 | `~/.claude/rules/common/git-workflow.md` jj Operations 節拡張 | -| 25 | `__` prefix scratch file 規約 | `~/.claude/CLAUDE.md` Personal Preferences > Code Style 拡張 | -| 26 | post-pr-monitor polling 禁止 | `~/.claude/rules/common/development-workflow.md` 「背景タスクの待機方針」節新設 | -| 30 | Cross-File Reference Lifecycle 具体例 | `~/.claude/rules/common/coding-style.md` の同セクションに 3 種類のファイル例 + raw string 編集時補助 | -| 33 | 新 verdict 経路追加時の 3 点同期チェック | `~/.claude/rules/common/code-review.md` Multi-point synchronization 節新設 | -| 70 | 設計 doc / 実装の同期チェック | 同上 (33 と同セクション内、相補項目) | - -**期待効果**: AI / 人間の共通言語として global rules に codify されたため、新セッションでも convention が自動参照される。Bundle "docs quality pre-write" の決定論層 (lint rule) と本 bundle の preventive guidance (rule) で **machine + guideline の二層防御** を構築。 - -### 保留中 - -順位 10 (broken-link-check) は ADR-032 関連の他タスク (順位 6, 20, 21) との依存があり、独立着手は非効率。ADR-032 全体の進捗に追従する。 - ---- - -## 関連ドキュメント - -- [docs/todo.md](todo.md) — 推奨実行順序サマリ表 (priority table) -- [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/todo.md b/docs/todo.md index 72c3506a..3d03ec86 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -62,7 +62,6 @@ | 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 安全網) | | 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 で実測必要) | | 61 | 🔧 Tier 2 | **post-PR 検証フローに CR review.body 手動スキャン step 追加 (PR #108 T2-1 採用)** | todo5.md | XS | なし (PR #108 で analyze-coderabbit が review body の outside diff range comment を検出漏れし line 371/378 の修正が後追い、blind spot の暫定緩和策として手動 checklist を整備) | -| 62 | 💎 Tier 3 | **Document Governance: docs lifecycle 区分明文化 (PR #108 T3-1 採用)** | todo5.md | XS | なし (PR #108 dogfood で本セッションが暗黙的に運用した docs/todo*.md = ephemeral / ADR / docs/ = permanent の区分を `~/.claude/rules/common/` に codify、ephemeral artifact 参照禁止 + retirement 2-step workflow を明文化) | | 63 | 🚀 Tier 1 | **cli-merge-pipeline に Drop guard / signal handler 追加 (PR #109 T1-1 採用) ★ Bundle c** | todo5.md | M | なし (PR #109 SIGPIPE 事故で ADR-030「失敗マーカーによる recovery」仕様の構造的違反が実証、Pre-emptive marker + signal trap で abrupt 経路を多層防御) | | 64 | 🚀 Tier 1 | **orphan run reaper (`meta.json status=running` 5-15 分放置検出 + 自動再起動) (PR #109 T1-2 採用) ★ Bundle c** | todo5.md | M | なし (順位 63 で救済不可の致命系 = kill -9 / SIGKILL / power loss / OOM の backstop、SessionStart hook または cli-pr-monitor 経路で実装) | | 65 | 🚀 Tier 1 | **exe + `--help` を PreToolUse でブロックして src/ Read に誘導 (PR #109 T1-3 採用) ★ Bundle c** | todo5.md | S | なし (PR #109 SIGPIPE の直接トリガ = AI が `cli-merge-pipeline.exe --help` 実行 → exe は --help 未対応で merge 本体実行を構造的に防止、今後追加 exe にも自動適用) | @@ -97,6 +96,8 @@ **Bundle d (PR #110 post-merge-feedback、2026-05-04)**: PR #110 (Bundle "docs quality pre-write") merge 後の post-merge-feedback で 6 findings 中 3 件採用。共通テーマは「PR #110 で導入した `no-ephemeral-todo-reference` rule (順位 29 採用分) の robustness 強化 + 設計 doc / 実装の乖離 ガード」。**順位 68 (T2 self-exclusion test)** は placeholder N 戦略の機械的保護で OBS-3 (fragile naming convention) 対策、**順位 69 (T3 yaml/yml コメント)** は OBS-2 (spec-impl 乖離) 対策。順位 70 (code-review checklist) は Bundle e で land 済。残り順位 68 (test infra) と 順位 69 (config コメント) は scope 異なるため独立 PR 推奨。 +**Bundle f + retirement (PR #111 post-merge-feedback + 計画書 retire、2026-05-05)** ✅ 完了: PR #111 (Bundle e) merge 後の post-merge-feedback で 10 findings 中 4 件採用 (順位 71/72/73/74 = Tier 3 XS×4) + 順位 62 (Document Governance) + `docs/docs-pr-iteration-efficiency.md` retirement を **1 PR で集約 land**。Sub-PR 分割推奨ルール (順位 73 自身が codify する内容) を本 PR で **dogfood**: 順位 73 が land する PR 自身が「分割 vs 統合」判断対象 → ファイル削除 + 順位 62 + Bundle f を統合した結果、scope は 5 ファイル touch (global rules 2 + ADR 2 + 削除 1) + cleanup で clean、Bundle 分割で得られる review 容易性より統合 PR の atomic な lifecycle 完結性が勝った。共通テーマ: 「PR #111 自己違反事例 → self-application 強化」 + 「Document Governance を global rule に codify」 + 「計画書 retirement を実例化」の 3 layer 同時 land。 + --- ## 現在進行中 diff --git a/docs/todo5.md b/docs/todo5.md index c00ef151..294e2319 100644 --- a/docs/todo5.md +++ b/docs/todo5.md @@ -490,52 +490,6 @@ --- -### Document Governance: docs lifecycle 区分明文化 (PR #108 T3-1 採用) - -> **動機**: PR #108 のセッションで「`docs/todo*.md` (ephemeral) と ADR / `docs/` (permanent) の lifecycle 区分」「ephemeral artifact から permanent artifact への参照禁止」「計画書 retirement 2-step workflow (entry 削除 → ファイル削除)」等の docs governance ルールが暗黙的に運用された。これらは memory ベース (例: `coding-style.md` の Cross-File Reference Lifecycle セクション) に分散して記録されているが、AI / 人間が一貫した判断を下せるよう **single source of truth** として codify が必要。 -> -> **本タスクの位置づけ**: PR #108 post-merge-feedback Tier 3 #1 採用 (Severity Low / Frequency Medium / Effort XS / Adoption Risk None / ✅ 採用)。Frequency Medium = docs PR 系で繰り返し前提として参照されるため、Effort XS で codify する ROI が高い。Document Governance の集約は将来の Cross-File Reference Lifecycle 違反 / 計画書 retirement 漏れを防ぐ防御層となる。 -> -> **参照**: `.claude/feedback-reports/108.md` Tier 3 #1、`~/.claude/rules/common/coding-style.md` の "Cross-File Reference Lifecycle" セクション、PR #108 commit chain (`okwntwwy` = pipeline-token-efficiency.md retire パターン) -> -> **実行優先度**: 💎 **Tier 3** — Effort XS。global rule への新セクション追加。 - -#### 設計決定 (案) - -- **配置先**: `~/.claude/rules/common/` 配下、以下の 2 案から着手時に選定: - - **案 A**: 新規 `docs-governance.md` を作成 (専用ファイル、navigability 高い) - - **案 B**: 既存 `coding-style.md` の "Cross-File Reference Lifecycle" セクションを拡張 (関連トピック集約、ファイル数増加なし) - - 推奨: 案 A (Document Governance 関連項目が今後増える前提で navigability を優先) -- **記述する 3 ルール**: - - **Lifecycle 区分**: `docs/todo*.md` 系列 = ephemeral (entry が完了 / 失効で削除される)、ADR / `docs/.md` (試験運用フラグなし) = permanent (削除しない、supersede のみ) - - **Cross-File Reference Lifecycle (既存ルール再掲 + 強化)**: permanent artifact から ephemeral artifact への参照禁止、ephemeral 同士は OK - - **Retirement 2-step workflow**: 計画書 (試験運用フラグ付き docs/) を retire する場合の標準手順 — (1) 重要決定を ADR 化、(2) 残作業を todo*.md に移管、(3) 参照を更新、(4) ファイル削除 -- **既存 rules との関係**: - - `coding-style.md` の "Cross-File Reference Lifecycle" は本ルールの根拠の一つ → 重複排除のため本ファイル新設時は cross-link - - 本リポジトリ固有の retirement 例 (PR #108 commit `okwntwwy`) は global rule から本リポジトリ docs/ にリンクで誘導 - -#### 作業計画 - -- [ ] 案 A / B のどちらを採用するか決定 (着手時 grep で類似 rule の配置を確認) -- [ ] `~/.claude/rules/common/docs-governance.md` (案 A) または `coding-style.md` 拡張 (案 B) で 3 ルールを codify -- [ ] 既存 `coding-style.md` の "Cross-File Reference Lifecycle" セクションから新ファイル / セクションへの cross-link を追加 -- [ ] CLAUDE.md / claude_md_rule からの参照経路を確認 (新ファイル発見可能か) -- [ ] 派生プロジェクト (techbook-ledger / auto-review-fix-vc) で global rule 反映を確認 (rule は global なので自動適用、deploy 不要) -- [ ] 本 todo5.md エントリを削除 - -#### 完了基準 - -- `~/.claude/rules/common/` 配下に Document Governance の 3 ルール (lifecycle 区分 / Cross-File Reference Lifecycle / retirement 2-step) が codify される -- 既存 `coding-style.md` Cross-File Reference Lifecycle セクションと整合 -- 次回 docs retirement / lifecycle 判断時に本ルールが参照される (= AI / 人間の判断ぶれ消滅) - -#### 詰まっている箇所 - -- 案 A vs B の選定: 専用ファイル化のメリット (navigability) vs ファイル数抑制 (locality)。Document Governance 関連項目が今後増えるかの予測に依存 -- 派生プロジェクト (Python ベース) で global rule の適用範囲がどこまで及ぶか (rule は markdown text のため自動適用想定だが念のため確認) - ---- - ### cli-merge-pipeline に Drop guard / signal handler を追加し abrupt 終了時に `.failed` marker を保証 (PR #109 T1-1 採用) ★ Bundle c > **動機**: PR #109 merge 直後の post-merge-feedback workflow が SIGPIPE で silent 中断され、`.takt/runs/.../reports/` が空 + `.claude/feedback-reports/109.md` 未生成 + `.failed` marker も無いという fail mode が実証された。原因は `feedback::run()` が `Result::Err` を返した場合のみ `write_failed_marker` を書く実装で、Rust default の SIGPIPE 動作 (parent process abrupt 終了) では Result::Err 経路に到達しない。ADR-030「失敗マーカーによる recovery」仕様を構造的に違反。 @@ -847,6 +801,3 @@ #### 詰まっている箇所 なし (Effort XS、コメント追記のみ) - ---- -