docs(adr): ADR-042 ルール vs 仕組み化の境界基準 + 関連 todo 整備 + docs 50KB 超過解消

[aloekun]

Summary

ルール vs 仕組み化の境界基準を ADR-042 として codify + 関連する todo system 仕組み化方針切替 + ドキュメントサイズ 50KB 超過解消の 3 commit 構成の docs-only PR。

PR #172 (順位 144 = jj-message-required PreToolUse hook) の dogfood 成功事例を受け、rule docs → mechanism の体系的移行哲学を ADR レベルに昇格。本セッション中の 6 件採用 + 3 件保留判定を実例として記録。

Commits

1. nw docs(adr): ADR-042 ルール vs 仕組み化の境界基準

• docs/adr/adr-042-rule-vs-mechanism-boundary.md 新設 (試験運用、採用判定 2026-11-25 目安)
• CLAUDE.md ADR list に ADR-042 link 追加
• 3 step 判定 (mechanizable / FP 緩和 / cost-benefit) + decision matrix を codify
• memory rules 3 件 (feedback_no_unenforced_rules / feedback_pipeline_over_rules / feedback_dogfood_evals_two_phase) を ADR レベルに昇格
• 既存 ADR-022/036/039 と直交 scope、独立 meta-decision criteria として独立

2. rt docs(todo): 仕組み化方針切替 — todo9.md 新設 + 順位 142-151 群追加 + 順位 44/61/122 hook 化転換

• 順位 142-145 entry 追加: PR feat(cli-pr-monitor): 順位 141 land — fix_push_time 固定 + RATE_LIMIT_BUT_MERGEABLE signal (順位 140 entry 追加) #170/test(hooks): UTF-8 boundary + aggregation cap 拡充 (順位 125 + 57 + 91) #171/feat(hooks-pre-tool-validate): jj-message-required preset で jj new / jj split の -m 必須化 (順位 144) #172 post-merge-feedback 採用分
• 順位 146-151 entry 新規追加 (Bundle 既存ルール仕組み化): Secret detection / File length lint / Test coverage CI gate / Subprocess pipe truncate hook 拡張 / Magic number lint / PR diff lines check
• 順位 44 (gh CLI 規則): docs 追記 → PreToolUse gh-token-efficiency preset 化に方針転換
• 順位 61 (CR review.body 手動 scan): docs 追記 → check-ci-coderabbit CLI 拡張に方針転換
• 順位 122 (新 todo 着手前の既実装確認): 順位 136 (working copy staleness hook) に統合
• docs/todo9.md 新設 (todo8.md 50KB 接近のため、新規追加先を移行)
• docs/todo-summary.md 更新方針 + table 整備 + Bundle 171 タグ整理

3. sw chore(todo): land 済 entry 削除 + bundle-history 分離 (size 50KB 超過解消)

• docs/todo8.md から land 済 3 entry 削除: 順位 125 (PR test(hooks): UTF-8 boundary + aggregation cap 拡充 (順位 125 + 57 + 91) #171 で land) / 順位 139 (PR feat(cli-pr-monitor): 順位 141 land — fix_push_time 固定 + RATE_LIMIT_BUT_MERGEABLE signal (順位 140 entry 追加) #170 で land) / 順位 141 (PR feat(cli-pr-monitor): 順位 141 land — fix_push_time 固定 + RATE_LIMIT_BUT_MERGEABLE signal (順位 140 entry 追加) #170 で land)
• docs/bundle-history.md 新設: todo-summary.md の Bundle 解説 16 paragraph (~25KB) を migrate
• docs/todo-summary.md から Bundle 解説 paragraph 削除 + bundle-history.md reference 化、table 内 land 済行 (125/139/141) 削除

memory rule feedback_todo_no_history.md 適用 (land 済 entry 削除) + ADR-042 § rule docs 縮小効果 を本セッション内で dogfood (todo-summary.md の index 責務回復)。

変更ファイル

• CLAUDE.md: ADR-042 link 追加 (+1 行)
• docs/adr/adr-042-rule-vs-mechanism-boundary.md: 新設 (+183 行)
• docs/bundle-history.md: 新設 (+172 行)
• docs/todo-summary.md: index 責務集中 + table 整理 (51,659 → 25,376 bytes、-51%)
• docs/todo4.md: 順位 44 mechanization 転換
• docs/todo7.md: 順位 61 mechanization 転換
• docs/todo8.md: land 済 削除 + 統合 + preamble 更新 (62,010 → 46,369 bytes、-25%)
• docs/todo9.md: 新設 (+310 行、順位 146-151 + 既存ルール仕組み化バンドル)

Test plan

• markdownlint: 全ファイル clean
• AI review (takt pre-push-review): simplicity APPROVE + security APPROVE (1 iteration)
• ADR-035 docs-only PR 適用: code-logic criteria (mutation / DRY / test coverage 等) は適用外
• 全 docs ファイル 50KB 切り達成 (todo-summary: 25KB / todo8: 46KB / bundle-history: 26KB / todo9: 24KB)

関連

• PR feat(hooks-pre-tool-validate): jj-message-required preset で jj new / jj split の -m 必須化 (順位 144) #172 (順位 144 = jj-message-required PreToolUse hook): ADR-042 起案の直接 trigger
• ADR-039 (Experimental feature 標準パターン): 試験運用基準 (config opt-in / kill-switch / bounded lifetime) を本 ADR にも適用
• ADR-022 / ADR-036 (関連 ADR): 本 ADR criteria と直交 scope
• memory: feedback_no_unenforced_rules.md / feedback_pipeline_over_rules.md / feedback_dogfood_evals_two_phase.md を ADR-042 で昇格

Out of scope

• 順位 146-151 の実装 (todo entry のみ追加、実装は別 PR)
• 順位 44 / 61 / 136 の実装 (方針転換のみ、実装は別 PR)
• ADR-042 採用判定 (6 ヶ月後 2026-11-25 目安)
• 派生プロジェクト (techbook-ledger / auto-review-fix-vc) への deploy (本リポジトリ先行 dogfood 後判断)

Summary by CodeRabbit

リリースノート

• Documentation

  • 設計判断の判定基準に関する新しいドキュメントを追加しました。
  • Bundle完了状況と反映経緯を追跡するための履歴ドキュメントを追加しました。
  • TODO管理ドキュメントの体系を整理し、スケーラビリティを向上させました。

• Chores

  • 内部プロセス管理ドキュメントを整備し、運用効率化を進めました。

[coderabbitai]

📝 Walkthrough

Walkthrough

ADR-042とドキュメント再編成を含む本PRは、rule vs mechanism の決定枠組みを新規定義し、Bundle採用履歴を追跡し、TODO計画文書を分割・再構成しながら、PR #172 由来の 6 件の仕込み化タスク（Secret detection PreToolUse hook、File length lint、Test coverage 80% CI gate、subprocess pipe truncate 拡張、Magic number lint、PR diff lines check）を checklist で進捗管理する。

Changes

ドキュメント体系の拡充と TODO 計画の段階的実行

Layer / File(s)	Summary
ADR-042: ルール vs 仕込み化の境界基準 CLAUDE.md, docs/adr/adr-042-rule-vs-mechanism-boundary.md	新規 ADR-042 により、rule docs・mechanism・memory rule のどちらで知見を codify するか判定する 3 step 基準（機械検知可能性・false positive 緩和・コスト頻度リスク）と decision matrix を規定。試験運用の kill-switch・bounded lifetime、却下時の物理削除、採用昇格/不採用発火基準、派生プロジェクト展開方針を定める。
Bundle 採用履歴の時系列記録 docs/bundle-history.md	Bundle 単位での採用判定・Post-merge-feedback 反映経緯を時系列蓄積。Bundle 1 ～ B follow-up まで、採用件数・内訳、Sub-PR 構成、retirement 条件、ADR 番号確定プロセス、artifact relocation と recovery 手順を記載。
TODO 文書の分割と推奨実行順序表の更新 docs/todo-summary.md, docs/todo8.md	docs/todo8.md が 60KB 超に達したため新規エントリを docs/todo9.md に移行する方針を明記。推奨実行順序テーブルで順位 44〜61（gh-token-efficiency、check-ci-coderabbit review.body 検出、MultiEdit 対応など）と順位 128〜151（working-copy staleness、ADR 番号 placeholder、preset matrix test、PR #172 仕込み化タスク）を新規追加・置き換え。
進行中タスク 6 件の計画更新と追跡 docs/todo4.md, docs/todo7.md, docs/todo8.md, docs/todo9.md	docs/todo4.md で gh CLI token 効率化を PreToolUse hook preset へ転換（BlockedPattern・exception・feedback 文言を具体定義）。docs/todo7.md で PR #108 を post-PR 手動 → check-ci-coderabbit プログラム検出へ全面置換。docs/todo8.md で working-copy staleness（2 段構え）・ADR 番号 placeholder・preset matrix test を追加。docs/todo9.md で Secret detection・File length lint・Test coverage 80% gate・subprocess pipe truncate・Magic number lint・PR diff lines check の 6 タスクを checklist で進捗管理。

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• aloekun/claude-code-hook-test#162: working-copy staleness 検出 hook（順位 ~136）の docs/todo8.md エントリ追加が重なる
• aloekun/claude-code-hook-test#158: ADR 番号ハードコード廃止と ADR-NNN プレースホルダ運用、ADR-041 整合のドキュメント更新領域が同一
• aloekun/claude-code-hook-test#133: docs/todo-summary.md 追加と todo*.md ファイル分割・参照切替の運用が直接関連

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	タイトルは PR の主要な 3 つの成果（ADR-042 新設、todo 系再編、docs 50KB 超過解消）を簡潔かつ具体的に要約しており、変更内容とよく対応している。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/bundle-history.md (1)

172-173: ⚡ Quick win

リカバリー手順のドキュメント化を推奨

artifact relocation ステップ（report copy + marker 削除）が未文書化である点を「follow-up 候補」として観測していますが、これを todoN.md の追跡タスクとして明示的に登録することを推奨します。次回の類似復旧時の摩擦を低減できます。

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/bundle-history.md` around lines 172 - 173, ドキュメント化されていない artifact
relocation ステップ（`.takt/runs/<run>/reports/feedback-report.md` を
`.claude/feedback-reports/<PR>.md` にコピーし、pre-emptive marker `168.md.failed`
を削除する手順）を明確な追跡タスクとして登録してください: `hooks-user-prompt-feedback-recovery` と
`post-merge-feedback` の再起動手順（`pnpm exec takt -w post-merge-feedback`）に続く manual
cleanup を todoN.md に追加し、実行手順、必要コマンド、確認ポイント（コピー先パスと marker
名、削除方法）を箇条書きで記載しておいてください。

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/bundle-history.md`:
- Around line 172-173: ドキュメント化されていない artifact relocation
ステップ（`.takt/runs/<run>/reports/feedback-report.md` を
`.claude/feedback-reports/<PR>.md` にコピーし、pre-emptive marker `168.md.failed`
を削除する手順）を明確な追跡タスクとして登録してください: `hooks-user-prompt-feedback-recovery` と
`post-merge-feedback` の再起動手順（`pnpm exec takt -w post-merge-feedback`）に続く manual
cleanup を todoN.md に追加し、実行手順、必要コマンド、確認ポイント（コピー先パスと marker
名、削除方法）を箇条書きで記載しておいてください。

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0c0e785e-0b8a-42be-b3c4-01314d6420a4

📥 Commits

Reviewing files that changed from the base of the PR and between a6670c7 and 7beb1de.

📒 Files selected for processing (8)

• CLAUDE.md
• docs/adr/adr-042-rule-vs-mechanism-boundary.md
• docs/bundle-history.md
• docs/todo-summary.md
• docs/todo4.md
• docs/todo7.md
• docs/todo8.md
• docs/todo9.md