diff --git a/docs/docs-pr-iteration-efficiency.md b/docs/docs-pr-iteration-efficiency.md index 69bbb4a..fc8c22c 100644 --- a/docs/docs-pr-iteration-efficiency.md +++ b/docs/docs-pr-iteration-efficiency.md @@ -46,16 +46,7 @@ Bundle "docs quality pre-write" (順位 4 / 29) は本セッションで land ### 📋 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 "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 を一掃。 --- @@ -90,9 +81,23 @@ write-time に docs 品質を保証する層。本セッションで 2 件 land **期待効果**: 本セッションでの dogfood で `docs/todo3.md` を含む `__dogfood_lint.rs` を作成 → rule が warning 2 件発火を確認済。今後 `.rs` / `.toml` / config で ephemeral todo reference を書こうとした時点で hook が警告。 -### 後回し可 (low impact bundle) +### 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 の二層防御** を構築。 -順位 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 全体の進捗に追従する。 diff --git a/docs/todo.md b/docs/todo.md index 7740119..72c3506 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -36,14 +36,8 @@ | 20 | 💎 Tier 3 | ADR-032 PR-β: 実装 (enabled=false default) | todo2.md | 中-高 | 6, 8, 10 | | 21 | 💎 Tier 3 | ADR-032 PR-γ: enablement (1 行 flip) | todo2.md | XS | 順位 8 dogfood + 順位 20 | | 22 | 💎 Tier 3 | ADR-032 PR-δ: dogfood + メトリクス検証 | todo2.md | (運用) | 順位 21 | -| 23 | 💎 Tier 3 | 日付ベース見出しアンカー更新ルールのグローバル明文化 (PR #85 T3-1) | todo2.md | XS | なし | -| 24 | 💎 Tier 3 | jj conflict リカバリ手順のグローバル明文化 (PR #85 T3-2) | todo2.md | XS | なし | -| 25 | 💎 Tier 3 | `__` prefix scratch file 規約のグローバル明文化 (PR #85 T3-3) | todo2.md | XS | なし | -| 26 | 💎 Tier 3 | **post-pr-monitor polling 禁止のグローバル明文化 (PR #86 T3-2)** | todo2.md | XS | なし | | 27 | 🧹 Tier 4 | ADR-030 Phase E/F: 旧機構廃止 + dogfood | todo.md | 中 | なし (cleanup) | | 28 | ⏳ Tier 5 | (追って) ADR-030 の takt-test-vc 反映 | todo.md | 中 | 順位 27 Phase F | -| 30 | 💎 Tier 3 | **Cross-File Reference Lifecycle ルールに具体例追記 (PR #94 T3-2) ★ Bundle U** | todo3.md | XS | なし (Bundle U で 29 と並行 land 推奨) | -| 33 | 💎 Tier 3 | **code-review.md に新 verdict 経路追加時の 3 点チェックリスト追記 (PR #95 T3-4) ★ Bundle V** | todo3.md | XS | なし (PR #95 直接対策、verdict path 整合性) | | 34 | 🚀 Tier 1 | **property-based testing (proptest) 導入 — 仕様を executable contract で明文化 (PR #96 T1-flaky) ★ Bundle W** | todo4.md | M | 順位 19 land 後推奨 (PR #96 直接対策、AI が flaky 実装を書ける窓を spec 層で塞ぐ) | | 35 | 🚀 Tier 1 | **型で意味を表現 (PastTime newtype 等) — saturating_sub 系 silent semantic mismatch を構造的に排除 (PR #96 T1-flaky) ★ Bundle W** | todo4.md | S | 順位 34 と同 PR (Bundle W、PBT が型に守られて記述しやすくなる相補関係) | | 36 | 🔧 Tier 2 | **cargo-mutants を post-PR pipeline に統合 — test ⇄ impl 制約の機械測定 (PR #96 T2-flaky) ★ Bundle X** | todo4.md | M | Bundle W land 後推奨 (PBT properties の後付け検証層、変更 crate + 1-hop 依存 scope) | @@ -74,6 +68,8 @@ | 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 にも自動適用) | | 66 | 💎 Tier 3 | **長時間 subprocess の pipe truncate 禁止ルールをグローバル明文化 (PR #109 T3-1 採用) ★ Bundle c** | todo5.md | XS | なし (順位 65 = 決定論層、本ルール = 判断ガイド層、`~/.claude/rules/common/development-workflow.md` 等に追加) | | 67 | 💎 Tier 3 | **ADR-030 に abrupt 終了時の振る舞いを spec として明記 (PR #109 T3-2 採用) ★ Bundle c** | todo5.md | XS | 順位 63 / 64 と同 PR (実装と仕様の整合性確保、L1 in-process Drop guard + L2 out-of-process reaper の責務分離 + SLA 化) | +| 68 | 🔧 Tier 2 | **`no-ephemeral-todo-reference` self-exclusion invariant 単体テスト追加 (PR #110 T2-1 採用) ★ Bundle d** | todo5.md | S | なし (PR #110 直接対策、placeholder N 戦略の machine-enforceable 保護、TP/FP/Edge 3 軸テスト) | +| 69 | 💎 Tier 3 | **`no-ephemeral-todo-reference` の `yaml`/`yml` extensions 追加理由をコメントで明記 (PR #110 T3-1 採用) ★ Bundle d** | todo5.md | XS | なし (rule⑥ コメント欄に 1-2 行追記、設計 doc と実装の経緯保存、git blame 不要化) | **戦略**: Tier 1 を 2〜3 セッションで片付け → Tier 2 で ADR-032 の前提 + rate-limit + convergence cost 削減を進める → Tier 3 で ADR-032 を land + ドキュメント整備。Tier 4-5 は cleanup / 外部展開で daily efficiency への直接効果は小さい。 @@ -86,8 +82,7 @@ **`.failed` marker 自己文書化 task は ADR-030 soft-fail 機構の運用負荷削減** (PR #89 セッションで recovery が機能した実証から派生、Effort S)。 **takt REJECT-ESCALATE は post-pr-review fix loop の `.claude/` filter (Bundle T で land 済) の verdict-based 一般解**。path-based 解決が完了したので、本 task 着手で補完関係を完成させる。 **T3 グローバルルール 4 件 (日付ベース見出しアンカー / jj conflict リカバリ / `__` prefix scratch / post-pr-monitor polling 禁止) は `~/.claude/` 配下への XS 追記なので並列実施推奨**。 -**Bundle U (Cross-File Reference Lifecycle 強化) は PR #94 post-merge-feedback 直接対策**。非 docs ファイル `docs/todo` 参照検出 lint rule (Tier 1 = 決定論的防止) と Cross-File Reference Lifecycle ルール具体例追記 (Tier 3 = preventive guidance) を 1 PR で land 推奨。両者は同一テーマ (永続成果物→ephemeral 参照禁止の二層化) で補完関係、effort 合計 S+XS。 -**Bundle V (verdict path 整合性 + docs-only fast-approve gap 補強) は PR #95 post-merge-feedback 直接対策**。review-security.md の `.takt/**` / `.claude/**` 除外、docs/todo.md ヘッダ整合、code-review.md の 3 点チェックリスト追記の 3 件を 1 PR で land 推奨。共通テーマは「PR #95 で実証された不整合パターンへの retroactive 対策」、effort 合計 XS×3 で完結。 +**Bundle U / V / e は完了** (Bundle U の 順位 29 = PR #110、順位 30 = Bundle e、Bundle V の 順位 31/32 = PR #109、順位 33 = Bundle e で全消化)。**Bundle e (convention 明文化 long-tail、2026-05-05)**: 順位 23/24/25/26 (PR #85/#86 由来) + 順位 30 (Bundle U 残) + 順位 33 (Bundle V 残) + 順位 70 (Bundle d 残) を 1 PR で集約 land、`~/.claude/rules/common/{coding-style,git-workflow,development-workflow,code-review}.md` + `~/.claude/CLAUDE.md` の global rules に convention 7 項目を codify。XS×7 で long-tail 一掃。 **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 側の更新となる。 @@ -100,6 +95,8 @@ **Bundle c (PR #109 post-merge-feedback 堅牢化、2026-05-04)**: PR #109 で post-merge-feedback workflow が SIGPIPE で silent 中断され `.failed` marker 未生成という ADR-030 仕様違反が実証された。5 件採用 (Tier 1 #63/#64/#65 + Tier 3 #66/#67) で **3 層防御** を構築: (1) 事前防止 = 順位 65 (exe + `--help` を PreToolUse block) + 順位 66 (グローバルルールの subprocess pipe truncate 禁止)、(2) in-process recovery = 順位 63 (Drop guard / signal trap で abrupt 終了時の `.failed` marker 保証)、(3) out-of-process backstop = 順位 64 (`meta.json status=running` 5-15 分放置 reaper)。順位 67 (ADR-030 spec 拡張) は実装と同 PR で仕様/実装の整合性確保。**Sub-PR 分割推奨**: c-1 (順位 63 + 64 + 67、Rust 実装 + ADR、Effort M+M+XS、コア層) / c-2 (順位 65 + 66、hook + global rule、Effort S+XS、trigger 防止層)。c-1 と c-2 は独立に land 可能だが c-1 land 後の dogfood で recovery 機構を実証してから c-2 を入れると順位の合理性が見える順序になる。 +**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 推奨。 + --- ## 現在進行中 diff --git a/docs/todo2.md b/docs/todo2.md index 31f2874..8b919fc 100644 --- a/docs/todo2.md +++ b/docs/todo2.md @@ -462,137 +462,3 @@ Phase 2 (任意、段階的緩和) termination 残留の root cause が未調査 (タスク開始時に最初に調査が必要) -### 日付ベース見出しアンカー更新ルールのグローバル明文化 (PR #85 T3-1) - -> **動機**: PR #85 のレビューで `docs/todo2.md:7` が `docs/todo.md` の旧日付アンカー `推奨実行順序サマリー-2026-04-27-更新` を参照したまま merge されたことを CodeRabbit が指摘。日付入り見出しを更新する際にクロスファイル参照が追従しなかった。 -> -> **本タスクの位置づけ**: グローバルルール (`~/.claude/rules/common/coding-style.md` の Markdown 節) として、日付入り見出し更新時に `grep -r` でクロスファイル参照を確認するルールを追加。長期的には日付に依存しない安定識別子への移行を推奨。 -> -> **参照**: `.claude/feedback-reports/85.md` Tier 3 #1 -> -> **実行優先度**: 💎 **Tier 3** — XS 工数、グローバルなので全プロジェクト即時効果。ADR-032 PR-broken-link の anchor link CI チェックと補完関係 (CI = 自動検出、本ルール = 編集時の予防)。 - -#### 設計決定 (案) - -- 配置先: `~/.claude/rules/common/coding-style.md` の Markdown 節 (新規追加) -- ルール文 (案): - > **日付入り見出しの更新前にクロスファイル grep**: 見出しに日付を含む (例: `## 推奨実行順序サマリー (2026-04-27 更新)`) 場合、日付を更新する前に `grep -r` で他ファイルからのアンカー参照を確認する。可能なら最初から日付を含まない安定アンカー (`## 推奨実行順序サマリー`) を使う。 - -#### 作業計画 - -- [ ] `~/.claude/rules/common/coding-style.md` の Markdown 節にルール追加 (なければ新規セクション) -- [ ] memory `feedback_*.md` への参照追加 (任意) -- [ ] 動作確認: 次回類似編集時にルールが自然に参照されるか観察 -- [ ] 本 todo2.md エントリを削除 - -#### 完了基準 - -- グローバルルールに日付見出しアンカーの cross-ref 確認手順が明記される -- 次回 docs PR で anchor drift が再発しない - -#### 詰まっている箇所 - -なし - -### jj conflict 発生時のリカバリ手順のグローバル明文化 (PR #85 T3-2) - -> **動機**: PR #85 セッション中、既存 WIP commit (markdownlint) を base にした `jj rebase` が conflict を起こし、conflict marker を手動編集する経路で試行錯誤を繰り返した。最終的に `jj abandon + jj new master + 再 edit` のパターンが conflict marker 編集より高速で安全と判明したが、これを知らないと AI も人間も無駄な試行錯誤に陥る。 -> -> **本タスクの位置づけ**: jj conflict 発生時のリカバリ手順をグローバルルール (`~/.claude/rules/common/git-workflow.md` の jj Operations 節) に明記する。 -> -> **参照**: `.claude/feedback-reports/85.md` Tier 3 #2 -> -> **実行優先度**: 💎 **Tier 3** — XS 工数、知見の恒久化のみ。発生頻度は低いが、発生時の試行錯誤コストを削減。 - -#### 設計決定 (案) - -- 配置先: `~/.claude/rules/common/git-workflow.md` の jj Operations 節 (既存セクション拡張、PR #85 で追加した節の隣に新サブセクション) -- 内容: 「### jj conflict 発生時のリカバリ手順」サブセクション追加 -- 推奨パターン: - 1. conflict block の規模を確認 (`grep '<<<<<<<' ` で位置特定) - 2. 大規模なら `jj abandon + jj new master + 再 edit` を選択 - 3. 小規模 (数行) なら conflict marker 手動編集も可 -- 反パターン: 大規模 conflict block を Edit tool で削除しようとして old_string 構築に繰り返し失敗 - -#### 作業計画 - -- [ ] `~/.claude/rules/common/git-workflow.md` の jj Operations 節に追記 -- [ ] memory への参照追加 (任意) -- [ ] 本 todo2.md エントリを削除 - -#### 完了基準 - -- グローバルルールに jj conflict リカバリ手順が明記される -- 次回 conflict 発生時に試行錯誤せず正しい経路を選べる - -#### 詰まっている箇所 - -なし - -### `__` prefix scratch file 規約のグローバル明文化 (PR #85 T3-3) - -> **動機**: PR #85 で `__parse_transcripts.ps1` が jj auto-snapshot 経由で混入したインシデントから、エージェントがデバッグ用スクリプトを生成する際の命名規約 (`__` prefix = scratch / VCS 管理外) と jj 特性 (staging area なし → `.gitignore` が唯一のフィルタ) をドキュメント化する。AI エージェントが自然に `__` prefix を使うよう誘導できる。 -> -> **本タスクの位置づけ**: `.gitignore` への `__*` パターン追加は実装済 (PR #85)。本タスクは規約自体をドキュメント化することで、エージェント (Claude) と人間の両方に「scratch file には `__` を付ける」を浸透させる。 -> -> **参照**: `.claude/feedback-reports/85.md` Tier 3 #3 -> -> **実行優先度**: 💎 **Tier 3** — XS 工数、規約浸透のみ。Tier 1 #1 (`.gitignore` 追加、PR #85 で実装済) の補完。 - -#### 設計決定 (案) - -- 配置先候補: - - 第一候補: `~/.claude/CLAUDE.md` の Personal Preferences (Code Style 節 拡張) - - 第二候補: 本リポジトリの `CLAUDE.md` (プロジェクト固有として扱う) -- 内容: - - `__` prefix = scratch / VCS 管理外 (一時的なデバッグスクリプト・中間出力) - - jj 特性: staging area なし、`jj new` / `jj describe` 時に working directory 全体が auto-snapshot - - 結論: scratch file は必ず `__` prefix で命名 (`.gitignore` の `__*` でフィルタされる) - -#### 作業計画 - -- [ ] 配置先決定 (CLAUDE.md vs プロジェクト固有) -- [ ] 該当ファイルに規約追記 -- [ ] 動作確認: 次回エージェントが scratch 生成時に `__` prefix を使うか観察 -- [ ] 本 todo2.md エントリを削除 - -#### 完了基準 - -- グローバルルールに `__` prefix 規約 + jj auto-snapshot 特性が明記される -- 同種事故 (scratch file 混入) が再発しない - -#### 詰まっている箇所 - -なし - -### post-pr-monitor polling 禁止のグローバル明文化 (PR #86 T3-2) - -> **動機**: PR #85 / PR #86 のセッション中、Claude が post-pr-monitor の出力を `until grep -q ...; do sleep N; done` で polling し、takt の verbose な AI 思考ログを context に取り込んで token を浪費した。ADR-018 で「post-pr-monitor は daemon として自走」原則は既述だが、Claude 向けの操作レベル指針が不足。 -> -> **本タスクの位置づけ**: グローバルルール (`~/.claude/rules/common/development-workflow.md`) または ADR-018 補強として、Claude の操作指針を明記。 -> -> **参照**: `.claude/feedback-reports/86.md` Tier 3 #2 -> -> **実行優先度**: 💎 **Tier 3** — XS 工数、ルール明文化のみ。Polling anti-pattern 検出ルール task と補完関係 (本ルールはガイドライン、検出ルール task は決定論的防止)。 - -#### 設計決定 (案) - -- 配置先: `~/.claude/rules/common/development-workflow.md` の新規セクション (ADR-018 補強) -- ルール文 (案): - > **post-pr-monitor / cli-pr-monitor への polling 禁止**: PR 作成 URL を確認した後、post-pr-monitor の出力を Bash で polling しない (タスク完了通知 task-notification が自動配信される)。結果確認は単発 `gh pr view --json` 等の構造化データ取得のみ。背景タスクは daemon + state file 方式で自走する設計 (ADR-018)。 - -#### 作業計画 - -- [ ] `~/.claude/rules/common/development-workflow.md` にルール追記 -- [ ] ADR-018 への参照追加 (任意) -- [ ] 動作確認: 次回類似状況で polling せず単発取得に切り替えるか観察 -- [ ] 本 todo2.md エントリを削除 - -#### 完了基準 - -- グローバルルールに post-pr-monitor polling 禁止が明記される -- 次回 PR 作成後に Claude が polling せず task-notification を待機する - -#### 詰まっている箇所 - -なし diff --git a/docs/todo3.md b/docs/todo3.md index ab41ea7..f8b2c7b 100644 --- a/docs/todo3.md +++ b/docs/todo3.md @@ -364,85 +364,3 @@ prompt and prompt Claude to re-run the workflow. - takt 本体改修のため `~/.claude/projects/takt-test-vc/` 連動も視野に入れる必要あり - rate-limit 系 task (cli-pr-monitor ポーリング延長 / post-pr-review rate-limit 自動検出) の land 後に着手することで、verdict ベースの一般解として完成する。post-pr-review fix loop の `.claude/` filter (Bundle T、完了済) は path-based 解決の対 (補完関係) -### Cross-File Reference Lifecycle ルールに具体例追記 (PR #94 T3-2) - -> **動機**: `~/.claude/rules/common/coding-style.md` に Cross-File Reference Lifecycle セクションを追加した (PR #93 post-merge-feedback で採用した Tier 3 #1) が、抽象的な原則のみで具体的な誤用例が乏しい。PR #94 で 3 種類の異なるファイル (Rust ソース / `.toml` config / `.jsonc` config) で同一 pattern が発生したという実証を活かし、各ファイル種における誤用例を明記することで AI が将来類似 context で警戒できるようにする。 -> -> **本タスクの位置づけ**: Cross-File Reference Lifecycle ルールの preventive guidance 層。Bundle U として 非 docs ファイル `docs/todo` 参照検出 lint rule (Tier 1) と並行 land 推奨。両者は preventive guidance (rule) + deterministic detection (lint) の補完関係で、ルール = AI の意識化、lint = 機械的検出。 -> -> **参照**: `.claude/feedback-reports/94.md` の Tier 3 #2 finding -> -> **実行優先度**: 💎 **Tier 3** — 工数 XS。`~/.claude/rules/` への既存セクション拡充のみ。Bundle U として Tier 1 と同 PR で land すれば、ルール文 + lint pattern の整合性を 1 review で確認できる。 - -#### 背景 - -- PR #93 で `~/.claude/rules/common/coding-style.md` に Cross-File Reference Lifecycle セクションを追加 -- 原則は抽象的: 「永続成果物 → ephemeral 成果物の参照禁止」 -- PR #94 で実証された 3 ファイル種の具体的誤用例: - - Rust raw string literal (`r#"..."#`) 内の block message - - TOML コメント内の引用例文字列 - - JSONC config ファイルのヘッダーコメント -- Boy Scout 修正 (`を参照。を参照。` 重複) も raw string 編集時の典型的注意点として補完価値あり - -#### 設計決定 (案) - -- 既存セクション (Cross-File Reference Lifecycle) に `### 具体的なアンチパターン例` サブセクションを追加 -- 例 1 (Rust): block message 内の `docs/todo.md の「
」を参照` 形式 -- 例 2 (TOML): コメント内の `[label](file.md#anchor)` 形式の引用 (引用すること自体が anti-pattern を再生産する構造的問題) -- 例 3 (JSONC): `// per docs/todo.md "" task` 形式の origin 記述 → PR 番号で置換 -- raw string 編集時の補足: 編集後の重複表現 (例: `を参照。を参照。`) を grep で目視確認することを推奨手順として追記 - -#### 作業計画 - -- [ ] `~/.claude/rules/common/coding-style.md` の Cross-File Reference Lifecycle セクションに具体例追加 -- [ ] PR #94 の 3 種類のファイル例を引用 (実証ベース) -- [ ] raw string 編集時の重複表現確認手順を補記 -- [ ] 動作確認: 次セッションで類似編集時に AI が anti-pattern を回避するか観察 -- [ ] 本 todo3.md エントリを削除 - -#### 完了基準 - -- グローバルルール `~/.claude/rules/common/coding-style.md` Cross-File Reference Lifecycle セクションに 3 種類のファイル例が記載される -- raw string 編集時の重複確認手順が明記される -- Bundle U の Tier 1 lint rule と整合 (lint pattern が検出する全 case が rule 例と対応) - -#### 詰まっている箇所 - -なし - -### code-review.md に新 verdict 経路追加時の 3 点チェックリスト追記 (PR #95 T3-4) - -> **動機**: PR #95 (Bundle T) で `analyze-coderabbit.md` に新 verdict 経路 `user_decision_path` を追加した際、(1) Step 3 の severity 取得元の記述、(2) 出力テーブルの Severity 列、(3) Verdict 判定ロジックの 3 箇所が同一 commit で整合しておらず、CodeRabbit Major 指摘 (1 件目) を受けた。さらに ADR-030 と analyze-coderabbit.md の整合性も同様に乱れて Major 2 件目 / Minor 1 件目 / 表記揺れ 1 件目を誘発。同じ「3 点同期失敗」パターンが pre-push (advisor)、first CR round、second CR round、third CR round の 4 フェーズに渡って発生しており、慣習化が必要。 -> -> **本タスクの位置づけ**: Bundle V (PR #95 post-merge-feedback) の 3 件 retroactive 対策の 1 つ。コードレビュー観点 (`~/.claude/rules/common/code-review.md`) に具体的なチェックリストを追記し、AI が編集時に意識化する。 -> -> **参照**: `.claude/feedback-reports/95.md` の Tier 3 #4 finding -> -> **実行優先度**: 💎 **Tier 3** — 工数 XS。既存 code-review.md の Common Issues to Catch セクション拡充。Bundle V として 3 件並行 land 推奨。 - -#### 設計決定 (案) - -- 配置先: `~/.claude/rules/common/code-review.md` (グローバルルール、全プロジェクト適用) -- 追記内容 (案): 新規セクション or 既存「Code Quality」サブセクション拡充 - > **新 verdict 経路 / 分類カテゴリ追加時の 3 点同期チェック**: facet 指示書 / ADR / 検証ロジックを同時編集する場合、以下 3 箇所が必ず同一 commit で整合していることを確認する: - > 1. **取得元の明示**: 新カテゴリの severity / 識別子がどこから来るか (CodeRabbit field / ADR の規定 / 計算結果) を Step 1 段階で明記 - > 2. **出力フォーマットの整合**: report テーブル列・サマリー文・指示書本文が同じ取得元の同じフィールドを参照していること - > 3. **判定ロジックの整合**: verdict rule / routing logic が新カテゴリを正しくハンドルし、severity 参照が取得元と一致していること -- PR #95 を実例として `>` blockquote で例示 (`user_decision_path` 追加時の 3 点同期失敗パターン) - -#### 作業計画 - -- [ ] `~/.claude/rules/common/code-review.md` に 3 点チェックリスト追記 -- [ ] PR #95 の実例を blockquote で例示 -- [ ] 派生プロジェクトへ deploy (グローバルルールなのでセット展開) -- [ ] dogfood: 次回 verdict 経路追加 PR でチェックリストが有効に機能するか観察 -- [ ] 本 todo3.md エントリを削除 - -#### 完了基準 - -- グローバルルール `~/.claude/rules/common/code-review.md` に 3 点チェックリストが記載される -- 同種「3 点同期失敗」パターンが将来 PR で再発しない - -#### 詰まっている箇所 - -なし (Effort XS、グローバルルール 1 セクション追記のみ) diff --git a/docs/todo5.md b/docs/todo5.md index 44c382f..c00ef15 100644 --- a/docs/todo5.md +++ b/docs/todo5.md @@ -765,3 +765,88 @@ - 試験運用フラグの去就: 順位 63 / 64 で実装が完成しても、dogfood 期間が必要なら試験運用フラグは残す。本 task では仕様明記のみだが、フラグ判断と整合性を取る必要あり - SLA の妥当性: 順位 64 の閾値 (5-15 分) と同期する必要があり、閾値が決まらないと SLA も書けない (依存関係) +--- + +### `no-ephemeral-todo-reference` self-exclusion invariant の単体テスト追加 (PR #110 T2-1 採用) ★ Bundle d + +> **動機**: PR #110 で導入した `.claude/custom-lint-rules.toml` rule⑥ (`no-ephemeral-todo-reference`) は、ルール定義ファイル自身が `.toml` 拡張子で対象内になるため、message / why / example 内に concrete `docs/todoN.md` (N = digit) を書かない placeholder 戦略で self-trigger を回避している。この invariant は **naming convention 依存** で、将来の例文追記時に concrete digit を含む文字列を入れると self-trigger が発生して silent regression を起こすリスク (PR #110 pre-push reviewer OBS-3 で documented)。 +> +> **本タスクの位置づけ**: PR #110 post-merge-feedback Tier 2 #1 採用 (Severity Medium / Frequency Low / Effort S / Adoption Risk None / ✅ 採用)。machine-enforceable な invariant 保護で、将来の例文追加で self-exclusion が壊れた時に CI で即検出。 +> +> **参照**: `.claude/feedback-reports/110.md` Tier 2 #1、`.claude/custom-lint-rules.toml` rule⑥ の self-exclusion 設計コメント、PR #110 pre-push reviewer OBS-3 +> +> **実行優先度**: 🔧 **Tier 2** — Effort S。self-exclusion テストインフラの新設。 + +#### 設計決定 (案) + +- **配置先候補** (着手時に決定): + - **案 A**: `tests/custom-lint-rules/` に独立 test crate を新設し、`hooks-post-tool-comment-lint-rust` の lint engine を呼び出して assert + - **案 B**: `src/hooks-post-tool-comment-lint-rust/tests/` 配下に integration test を追加 (既存 hook crate に同居) + - 推奨: **案 B** (既存 crate の lint engine を直接 invoke でき、テスト infra 二重投資を避ける) +- **テスト内容**: + - **TP test**: 任意の `.rs` / `.toml` ファイルに `docs/todo3.md` 等の concrete digit reference を含む input → rule⑥ が warning を 1 件生成することを assert + - **FP test (self-exclusion invariant)**: `.claude/custom-lint-rules.toml` の rule⑥ 部分 (placeholder `N` を含む example.bad / message / why) を input として渡し、rule⑥ が warning を **生成しない** ことを assert + - **Edge case test**: `docs/todoN.md` (N = letter) / `docs/todo*.md` (literal asterisk) / `docs/todo[0-9]*.md` (regex source の literal) いずれも warning を生成しないこと + +#### 作業計画 + +- [ ] 配置先 (案 A / B) を `src/hooks-post-tool-comment-lint-rust/` の構造を確認のうえ決定 +- [ ] lint engine を test 経由で呼び出す API を確認 (既存 unit test があれば流用) +- [ ] 上記 3 種類のテストケースを実装 +- [ ] cargo test で 全 pass を確認 +- [ ] 派生プロジェクト (`techbook-ledger` / `auto-review-fix-vc`) で同 hook を deploy する場合のテスト追従も検討 +- [ ] 本 todo5.md エントリを削除 + +#### 完了基準 + +- self-exclusion invariant が test で機械的に保護される (将来 concrete digit を rule⑥ 内に書くと CI で fail) +- TP / FP / Edge case の 3 軸でカバー +- 既存テストとの統合が破綻しない (cargo test 全 pass) + +#### 詰まっている箇所 + +- lint engine の test 用 API 公開状況: hooks-post-tool-comment-lint-rust crate が library crate を expose していない場合、test infra 整備自体に追加 effort が発生する可能性 +- self-exclusion invariant の future-proof 性: rule⑥ の設計が変わって新しい extension が追加された場合、test fixtures の更新も必要 + +--- + +### `no-ephemeral-todo-reference` の `yaml`/`yml` extensions 追加理由をコメントで明記 (PR #110 T3-1 採用) ★ Bundle d + +> **動機**: PR #110 で `no-ephemeral-todo-reference` rule の `extensions` に `yaml` / `yml` を追加したが、`docs/todo3.md` の設計 doc には `["rs", "toml", "jsonc", "json", "ts", "tsx", "js", "jsx", "py", "ps1"]` のみ記載されていた。実装時に「YAML config もファイルパス参照を含みうる」判断で `yaml` / `yml` を含めたが、その理由が `.claude/custom-lint-rules.toml` rule⑥ コメントに残っていない。将来の rule 参照者が「なぜ yaml/yml が含まれているか」を git blame で追う必要が出る。 +> +> **本タスクの位置づけ**: PR #110 post-merge-feedback Tier 3 #1 採用 (Severity Low / Frequency Medium / Effort XS / Adoption Risk None / ✅ 採用)。Frequency Medium = spec-impl 乖離パターンは反復しがちなため、コメント追記で経緯保存することが ROI 高い。 +> +> **参照**: `.claude/feedback-reports/110.md` Tier 3 #1、`.claude/custom-lint-rules.toml` rule⑥ コメント欄、PR #110 pre-push reviewer OBS-2 +> +> **実行優先度**: 💎 **Tier 3** — Effort XS。コメント 1-2 行追記のみ。 + +#### 設計決定 (案) + +- **配置先**: `.claude/custom-lint-rules.toml` rule⑥ の既存コメント欄 (Self-exclusion 設計の上または下) +- **追記文** (案): + ```toml + # extensions の選定: + # - 設計 doc (docs/todo3.md PR #94 T1-1) では rs/toml/jsonc/json/ts/tsx/js/jsx/py/ps1 のみ + # - 実装で yaml/yml を追加: takt workflow yaml / GitHub Actions yaml 等で + # docs/todoN.md への参照を含む permanent artifact として扱う必要があるため + ``` +- 既存コメント (Self-exclusion 設計) との整合性確保。順序は「Why このルール」→「extensions 選定」→「Self-exclusion 設計」が読みやすい + +#### 作業計画 + +- [ ] `.claude/custom-lint-rules.toml` rule⑥ コメント欄に extensions 選定理由を 2-3 行追記 +- [ ] 既存 Self-exclusion コメントとの読み順整合 (どちらが先か検討) +- [ ] 派生プロジェクト deploy 時に同 rule をコピーする場合、コメントも一緒にコピーされることを確認 +- [ ] 本 todo5.md エントリを削除 + +#### 完了基準 + +- rule⑥ コメント欄に「yaml/yml は YAML config も permanent artifact として扱う」旨が 1-2 行で記述される +- git blame せずとも extensions の選定根拠が rule 定義の隣で読める + +#### 詰まっている箇所 + +なし (Effort XS、コメント追記のみ) + +--- +