From bf8efe74682c64f632002143adf6abb1a7741481 Mon Sep 17 00:00:00 2001 From: aloekun Date: Wed, 24 Jun 2026 21:28:33 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs(todo):=20=E9=A0=86=E4=BD=8D=20222=20?= =?UTF-8?q?=E6=8E=A1=E7=94=A8=20(PR=20#218=20post-merge-feedback=20#5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #218 (docs PR、ファイルサイズチェックフロー改善計画 + 順位 220/221 採用) の post-merge-feedback で承認された #5 を採用: 順位 222 (💎 Tier 3、Effort XS): `~/.claude/CLAUDE.md` に「複数セッション跨ぎの計画文書作成時は AI が 先走らずユーザー確認後に方針報告し GO/NO-GO を得る」ルール追加 由来: PR #218 session 内で Plan file 作成完了報告後、AI がユーザー承認 なしに PR-W0 着手しようとして `[Request interrupted by user]` で停止 された実観測 (Severity Medium、Frequency Low 初観測、Effort XS、 Adoption Risk None)。memory `feedback_no_unauthorized_reorder` の補強 として「planning doc 作成のような大きな task 完了時は GO/NO-GO 確認待ち」 を明文化、派生プロジェクトへ `~/.claude/CLAUDE.md` 経由で自動波及。 採用しなかった項目: - #1 (weekly audit を feedback entry にも明示): 計画書 PR-W0 で既に管理 - #3 (lib-subprocess stress test): 順位 220 と完全重複 - #4 (Agent template PMF entry): 計画書 Appendix A で既に capture、却下 - #2/#6/#7: 様子見継続 --- docs/todo-summary.md | 1 + docs/todo10.md | 68 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) diff --git a/docs/todo-summary.md b/docs/todo-summary.md index 7ccf4dbd..816563e9 100644 --- a/docs/todo-summary.md +++ b/docs/todo-summary.md @@ -92,6 +92,7 @@ | 219 | 💎 Tier 3 | **`~/.claude/rules/common/development-workflow.md` § 設計 doc/実装の同期チェック に「commit description 言及 ≠ 実装完了」明文化 (PR #216 post-merge-feedback T3-3 採用)** | todo10.md | XS | なし (本 PR で「commit description で順位 N 言及 = 実装完了」naïve assumption から analyzer が 6 entry 削除計画を立てたが、grep で実体確認した結果 5 entry が正解 (順位 215 救出) の実観測、「PR commit description で順位 N や feature X を言及していても、実際のファイル変更を `jj diff` / `grep` で確認するまで completion 判定しない」guideline を追加、Frequency Low (初観測) + Severity Medium (analyzer / Claude 誤判定リスクが今後も継続)、派生プロジェクト (techbook-ledger / auto-review-fix-vc) へ global 経由で自動波及、`feedback_global_config_backup` 適用必須) | | 220 | 🔧 Tier 2 | **subprocess stress test (>64KB stdout) を ADR-031 weekly-review pipeline 経由で週次実行 (PR #217 post-merge-feedback T2-1 採用、ユーザー判断 2026-06-23 = hooks/pre-push には組み込まず週次に分離)** | todo10.md | M | なし (PR #217 で 2 module (jj_helpers.rs / todo_staleness.rs) に同型 subprocess deadlock pattern が独立観測 = Severity High + Frequency Medium、ただし手動検証困難な大 buffer 顕在化テストは毎回実行 (Stop hook / pre-push) には不適切で開発速度に影響、`#[ignore]` 付きで cargo test default skip + ADR-031 weekly workflow の rust-stress step として明示実行 (`cargo test -- --ignored --test-threads=1` 想定)、対象 = lib-subprocess の `drain_pipe_unlimited` + `wait_with_timeout_basic` 利用箇所、順位 221 (ADR docs) と test+docs の 2 層防御で相補) | | 221 | 💎 Tier 3 | **ADR-NNN (採番未確定、land 時に確定): Safe Subprocess Stdout Pattern を ADR-016 appendix or 新 ADR で codify (PR #217 post-merge-feedback T3-1 採用)** | todo10.md | S | なし (PR #217 で `Stdio::piped()` を伴う `jj` spawn が 2 module で同一 pattern 違反 (concurrent drain なし → pipe buffer 枯渇 deadlock) を independent 観測、Severity Low + Frequency Medium + None risk、解決 pattern (`spawn_stdout_drainer` + `poll_child_with_deadline` または `lib_subprocess::drain_pipe_unlimited` + `wait_with_timeout_basic` の wrap、もしくは `Command::output()` / `Stdio::null()` の 3 択) を ADR-016 § 長時間コマンド戦略 への appendix or 新 ADR として明文化、ADR-025 CwdRestore guard pattern を precedent として cite、派生プロジェクト transferability 確保、順位 220 (test 層) と 1 PR bundle 推奨) | +| 222 | 💎 Tier 3 | **`~/.claude/CLAUDE.md` に「複数セッション跨ぎの計画文書作成時は AI が先走らずユーザー確認後に方針報告し GO/NO-GO を得る」ルール追加 (PR #218 post-merge-feedback #5 採用)** | todo10.md | XS | なし (PR #218 (docs PR) 本セッション内で Plan file 作成完了報告後、AI がユーザー承認なしに PR-W0 着手しようとして `[Request interrupted by user]` で停止された実観測、Severity Medium (AI 暴走 = UX 劣化) + Frequency Low (初観測) + Effort XS + Adoption Risk None、`~/.claude/CLAUDE.md` への 1 段落追記で全プロジェクトへ自動波及、`feedback_global_config_backup` 適用必須、memory `feedback_no_unauthorized_reorder` の補強として「計画書 / planning doc 作成のような大きな task 完了時は GO/NO-GO 確認を待つ」を明文化、本 ルール採用後は Auto mode でも planning doc レベルの完了時点では明示承認待ちが必須となる) | **戦略**: 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/todo10.md b/docs/todo10.md index 4a6f258f..4d9ff6c8 100644 --- a/docs/todo10.md +++ b/docs/todo10.md @@ -834,6 +834,74 @@ ADR-039 (Experimental Feature 標準パターン) は「behavior の妥当性が --- +### `~/.claude/CLAUDE.md` に「複数セッション跨ぎの計画文書作成時は AI が先走らずユーザー確認後に方針報告し GO/NO-GO を得る」ルール追加 (PR #218 post-merge-feedback #5 採用) + +> **動機**: PR #218 (docs PR、ファイルサイズチェックフロー改善計画 + 順位 220/221 採用) のセッション内で、Plan file (`docs/file-length-enforcement-plan.md`) 作成完了報告後、AI (Claude) が **ユーザー承認なしに PR-W0 (weekly audit step 追加) の実装着手を開始** し、ユーザーが `[Request interrupted by user]` で停止 + 「勝手に作業を進めないでください」と明示的に course correction する事案が発生した。Auto mode 下でも「計画書 / planning doc 作成のような **大きな task 完了時** は GO/NO-GO の確認待ちが必須」という規範を CLAUDE.md に明文化することで、本セッション内の事例を後続セッションで再発防止する。 +> +> **本タスクの位置づけ**: PR #218 post-merge-feedback #5 採用 (Severity Medium / Frequency Low / Effort XS / Adoption Risk None、2026-06-23 ユーザー承認)。analyzer rationale: 「AI がユーザー確認なしに計画書作成を開始し `[Request interrupted by user]` で停止させた事例。Severity Medium (AI 暴走 = UX 劣化)・Effort XS・Adoption Risk None → ✅ 条件を満たす。Frequency Low だが Effort が極小なため採用コストが低い」。 +> +> **参照**: `.claude/feedback-reports/218.md` Tier 3 #5、PR #218 session transcript (Plan file 作成完了 → AI 先走り → ユーザー停止 → "勝手に作業を進めないでください" の course correction)、memory `feedback_no_unauthorized_reorder.md` (推奨実行順序の上位タスクが blocked された時点で停止し、ユーザーに pivot 可否を確認する、の補強)、memory `feedback_global_config_backup.md` (snapshot 必須)、`~/.claude/CLAUDE.md` (編集対象 global config)。 +> +> **実行優先度**: 💎 **Tier 3** — Effort XS。global config への 1 段落追記で完結、`feedback_global_config_backup` snapshot を忘れない。 + +#### 設計決定 (案) + +- **追加先**: `~/.claude/CLAUDE.md` の `## Personal Preferences` section 直後 (もしくは `## Doing tasks` 配下の sub-section) +- **rule 内容**: + + ```markdown + ### AI 先走り防止 — 計画文書作成完了時の GO/NO-GO ゲート + + 複数セッション跨ぎの計画文書 (planning doc / 設計ドキュメント) の作成完了時は、 + Auto mode の最中であっても **次の実装着手を一時停止し、ユーザーに方針報告 + + GO/NO-GO 確認を待つ**。 + + 対象となる "大きな task" の例: + + - 新規 planning doc (`docs/-plan.md` / `docs/-analysis.md` 等) の作成完了 + - ADR 起案 + - 複数 PR にまたがる作業計画の決定 + - 既存 planning doc への大規模追記 (Tier 1/2 構成変更等) + + 対象外 (= 通常 task として継続して問題ない): + + - 単一 PR scope 内の段階的 commit + - 既存計画通りの逐次実装 step + + GO/NO-GO 確認のフォーマット例: + + > Plan file 作成完了。次の step は PR-W0 (...) への着手です。進めて OK か? + + Auto mode の「prefer action over planning」原則の例外として、planning doc + レベルの完了点では明示承認待ちが必須。 + ``` + +- **由来 cite**: PR #218 session transcript で実観測した「Plan file 完了報告 → AI が PR-W0 着手 → ユーザー停止 + 'AI 先走り' 指摘」の流れを inline cite +- **memory `feedback_no_unauthorized_reorder` との関係**: 既存 memory は「task が blocked された時点で停止」を扱うが、本 rule は「task 完了時 (= 自然な区切り) で停止」を扱う = lifecycle の異なる stage を扱う相補的 rule +- **派生プロジェクト波及**: `~/.claude/CLAUDE.md` 編集のため全 project に自動波及、planning doc の頻度が高い大型 refactor PR で効果を発揮 +- **Auto mode との関係**: Auto mode 仕様の「prefer action over planning」と本 rule の「planning 完了時は停止」は scope 分離 (前者は通常作業の AI 自律性、後者は planning doc レベルの mile stone 確認) で衝突しない + +#### 作業計画 + +- [ ] `~/.claude/` snapshot 取得 (memory `feedback_global_config_backup` per) +- [ ] `~/.claude/CLAUDE.md` に新 sub-section「AI 先走り防止 — 計画文書作成完了時の GO/NO-GO ゲート」を追加 (上記設計決定の rule 内容、~30 行) +- [ ] markdownlint clean +- [ ] 本エントリ削除 + docs/todo-summary.md 行削除 + +#### 完了基準 + +- `~/.claude/CLAUDE.md` に新 sub-section が追加される (対象 task 例 / 対象外 / フォーマット例 含む) +- PR #218 事例が inline cite として記録される +- 全プロジェクト (techbook-ledger / auto-review-fix-vc 含む) に global rule として自動波及 +- Auto mode 下でも planning doc 完了時点で AI が明示承認待ちに転じることが、次回以降の planning task で確認可能 + +#### 詰まっている箇所 + +- 対象範囲の境界定義: 「計画文書」「設計ドキュメント」「大きな task」の判定基準が author に依存する余地あり。MVP は上記「対象 task の例」「対象外」リストで運用、3+ 回の dogfood で境界明確化を判断 (順位 207 mechanical lint scope 外 boundary case 追加の pattern と同様) +- Auto mode 仕様との関係明示: `~/.claude/CLAUDE.md` の Auto mode セクションが追加 or 改訂されている場合、本 rule の例外条項 (「prefer action over planning」との関係) を Auto mode セクション側にも cross-reference するか判断 + +--- + ## 既知課題 (記録のみ、本セッションで未対応) (現時点で本ファイルへの既知課題は無し。docs/todo9.md 末尾を参照。) From 591d108c2a473462ac32278c1f3da9f1165bc1eb Mon Sep 17 00:00:00 2001 From: aloekun Date: Wed, 24 Jun 2026 22:50:58 +0900 Subject: [PATCH 2/2] =?UTF-8?q?feat(weekly-review):=20file=5Flength=20scan?= =?UTF-8?q?=20=E3=82=92=20pre-LLM=20step=20=E3=81=A8=E3=81=97=E3=81=A6?= =?UTF-8?q?=E8=BF=BD=E5=8A=A0=20(PR-W0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-031 weekly-review pipeline に deterministic Rust pre-step として 800 行超 file の scan を追加。LLM facet 不要、純機械測定。 順位 147 (file_length lint) は touch-trigger ratchet で「触られた file の 編集時のみ警告」設計のため、未触り state の violation を可視化できない。 本 step は毎週 1 回 master HEAD に対して 800 行超 file を全件列挙し、 aggregate-weekly facet の input に注入して watchlist として report 化する。 PR-3a (PR #217) で 7 件の 800 行超 file が判明した経緯から、Phase 1 (file split work、PR-W1 〜 W4) の進捗 dashboard としても機能する。 全 file ≤ 800 行に到達後も恒久的に監視継続。 由来: docs/file-length-enforcement-plan.md PR-W0 (PR #218 で land)、 severity = warning (block しない、健康診断目的)。 --- .takt/facets/instructions/aggregate-weekly.md | 15 ++- .../instructions/file-length-watchlist.md | 97 +++++++++++++++++++ .takt/workflows/weekly-review.yaml | 24 +++++ docs/file-length-enforcement-plan.md | 2 +- 4 files changed, 136 insertions(+), 2 deletions(-) create mode 100644 .takt/facets/instructions/file-length-watchlist.md diff --git a/.takt/facets/instructions/aggregate-weekly.md b/.takt/facets/instructions/aggregate-weekly.md index 607d4c00..7c07bb4e 100644 --- a/.takt/facets/instructions/aggregate-weekly.md +++ b/.takt/facets/instructions/aggregate-weekly.md @@ -18,11 +18,12 @@ ADR-031 § Findings スキーマ + § 採否フロー の input source として ### Report Directory (takt が提供) -本 step (`pass_previous_response: false`) は前 step の response を受け取らない。代わりに Report Directory に保存された 3 reports を Read で読み取る: +本 step (`pass_previous_response: false`) は前 step の response を受け取らない。代わりに Report Directory に保存された 4 reports を Read で読み取る: - `simplicity-whole-review.md` — review-simplicity-whole facet の出力 - `security-whole-review.md` — review-security-whole facet の出力 - `architecture-whole-review.md` — review-architecture-whole facet の出力 +- `file-length-watchlist.md` — file-length-watchlist facet の出力 (PR-W0、deterministic 800 行超 file scan)。本 watchlist は LLM 判断による findings ではなく機械的観測のため、Phase 1 統合では findings には含めず、Phase 2 の "file_length watchlist" 専用 section として weekly report に転載する ### Context @@ -135,8 +136,15 @@ Markdown は人間 / Claude が読む summary 層。findings table を severity ### スコープ - 対象ツリー: `src/` / `scripts/` / `.claude/` / `.takt/` / `docs/` - レビューファセット: simplicity-whole / security-whole / architecture-whole +- 決定論的観測: file-length-watchlist (PR-W0) - 採否方針: Phase C skill `/weekly-review` で AskUserQuestion 経由 +### File Length Watchlist (機械的観測) + +`file-length-watchlist.md` の内容を本 section に転載する (header 行は省略、件数表示 + table 部分を再現)。0 件 (clean state) の場合は「現時点で 800 行超 file は存在しない (clean state)」を表示。 + +詳細は Report Directory の `file-length-watchlist.md` を参照。 + ### 統合 findings #### Severity: critical / high @@ -181,6 +189,11 @@ findings 全体がゼロの場合は以下を出力: ### スコープ - 対象ツリー: `src/` / `scripts/` / `.claude/` / `.takt/` / `docs/` - レビューファセット: simplicity-whole / security-whole / architecture-whole +- 決定論的観測: file-length-watchlist (PR-W0) + +### File Length Watchlist (機械的観測) + +`file-length-watchlist.md` の内容を本 section に転載する (件数表示 + table 部分)。0 件 (clean state) の場合は「現時点で 800 行超 file は存在しない (clean state)」を表示。 特筆すべき findings なし。3 facet いずれも whole-tree レビューで blocking concern を発見しませんでした。 diff --git a/.takt/facets/instructions/file-length-watchlist.md b/.takt/facets/instructions/file-length-watchlist.md new file mode 100644 index 00000000..33047eee --- /dev/null +++ b/.takt/facets/instructions/file-length-watchlist.md @@ -0,0 +1,97 @@ +# File Length Watchlist (週次 800 行超 scan) + +決定論的 scan で 800 行超 file を全件列挙する。LLM が判断する余地はなく、shell command 出力を markdown table に整形するだけの mechanical task。 + +## 背景 + +順位 147 (file_length lint、PR #202) は `hooks-post-tool-comment-lint-rust` の PostToolUse hook として実装されており、**触られた file の編集時のみ** `additionalContext` で 800 行超を警告する設計 (soft-nag、touch-trigger ratchet)。 + +このため: + +- 未触り state の violation は警告されない +- AI / 人が警告を無視して進められる +- 結果として PR-3a (#217) 時点で 7 件の 800 行超 file が累積した経緯あり (PR #218 で計画書 `docs/file-length-enforcement-plan.md` が land、PR-W0 として本 step を追加) + +本 facet は週次 1 回 master HEAD の `src/` 全体を deterministic に scan し、800 行超 file を全件列挙して watchlist として report 化する。これにより ratchet が未発火の violation も可視化でき、aggregate-weekly が weekly report の "file_length watchlist" section として記載する。 + +## Phase 1: scan 実行 + +以下の shell command を実行 (Bash tool): + +```bash +find src -name '*.rs' -not -path '*/target/*' -exec wc -l {} + 2>/dev/null \ + | awk '$1 > 800 && $2 != "total" { print $0 }' \ + | sort -rn +``` + +出力例 (PR-3a #217 land 直後の master state): + +```text +1606 src/hooks-post-tool-comment-lint-rust/src/main.rs +1432 src/cli-merge-pipeline/src/feedback.rs +1404 src/cli-pr-monitor/src/stages/poll/mod.rs + 982 src/cli-push-runner/src/stages/lint_screen.rs + 972 src/cli-pr-monitor/src/fix_commit.rs + 946 src/cli-push-runner/src/config.rs + 890 src/cli-merge-pipeline/src/main.rs +``` + +0 件のとき: command が空出力。 + +## Phase 2: markdown 整形 + +`file-length-watchlist.md` を以下の format で Report Directory に出力する。 + +### 800 行超 file が 1 件以上ある場合 + +```markdown +# File Length Watchlist (週次 800 行超 scan) + +- scan 日時: +- scan 対象: `src/**/*.rs` (`target/` 除外) +- 閾値: 800 行 (coding-style.md File Organization) +- 件数: N 件 + +## 800 行超 file 一覧 (上限 800 行を超過、N 件) + +| 行数 | ファイル | +|---|---| +| 1606 | `src/hooks-post-tool-comment-lint-rust/src/main.rs` | +| 1432 | `src/cli-merge-pipeline/src/feedback.rs` | +| ... | ... | + +## 進捗参照 + +`docs/file-length-enforcement-plan.md` の Phase 1 (PR-W1 〜 W4) で各 file の分割計画が capture されている。本 watchlist は分割 PR の land 状況を週次で可視化する役割。 + +完了条件 (本 watchlist の 0 件到達) を満たすと、計画書の削除条件 1/3 を満たす。 +``` + +### 0 件 (clean state) の場合 + +```markdown +# File Length Watchlist (週次 800 行超 scan) + +- scan 日時: +- scan 対象: `src/**/*.rs` (`target/` 除外) +- 閾値: 800 行 (coding-style.md File Organization) +- 件数: **0 件 (clean state)** + +現時点で 800 行超 file は存在しない。Phase 1 (file-length-enforcement-plan.md PR-W1〜W4) は完了状態にあるか、もしくは新規 file が制約内に収まっている。 +``` + +## Output contract + +- File: `file-length-watchlist.md` (Report Directory) +- Format identifier: `file-length-watchlist` +- 0 件 case でも file を生成 (clean state 確認のため。aggregate-weekly が常に Read 可能) + +## Completion criteria + +scan 完了 + markdown 出力で `analysis complete` を articulate (他の facet と同じ条件文字列を使用、step-level rule `all("analysis complete")` と整合)。 + +## 重要な原則 + +- **読み取り専用 (`edit: false`)**。コード修正は行わない (= watchlist 報告のみ) +- **LLM 判断の余地なし**: 命令通りに Bash を実行し、出力を整形するだけ +- **件数 0 でも file を生成**: aggregate-weekly が常に Read 可能な前提を満たすため diff --git a/.takt/workflows/weekly-review.yaml b/.takt/workflows/weekly-review.yaml index 420e11fc..535c781b 100644 --- a/.takt/workflows/weekly-review.yaml +++ b/.takt/workflows/weekly-review.yaml @@ -100,6 +100,30 @@ steps: rules: - condition: analysis complete + # 観点 ⑦ file_length watchlist (PR-W0、docs/file-length-enforcement-plan.md)。 + # 順位 147 file_length lint は touch-trigger ratchet で「触られた file の + # 編集時のみ警告」設計のため、未触り state の violation を可視化できない。 + # 本 facet は週次 1 回 master HEAD を deterministic に scan して 800 行超 + # file を全件列挙、aggregate-weekly が watchlist として weekly report に + # 統合する。LLM 判断の余地なし (Bash の find/wc/awk 出力を整形するだけ)。 + - name: file-length-watchlist + edit: false + persona: simplicity-reviewer + model: haiku + policy: review + provider_options: + claude: + allowed_tools: + - Bash + - Read + instruction: file-length-watchlist + output_contracts: + report: + - name: file-length-watchlist.md + format: file-length-watchlist + rules: + - condition: analysis complete + rules: - condition: all("analysis complete") next: aggregate-weekly diff --git a/docs/file-length-enforcement-plan.md b/docs/file-length-enforcement-plan.md index fc0fa774..e7df330d 100644 --- a/docs/file-length-enforcement-plan.md +++ b/docs/file-length-enforcement-plan.md @@ -424,7 +424,7 @@ batch mode 実装 (~50 行) + tests (~30 行) + config schema 更新。Agent 委 各 PR の status は 1 セッション内では更新可能、跨ぐ場合は本 file の status 欄を更新して残す。 ```text -PR-W0 [ ] not started +PR-W0 [in progress] @session-2026-06-24-pr-w0 PR-W1 [ ] not started PR-W2 [ ] not started PR-W3 [ ] not started