docs(todo): PR #81 post-merge-feedback の知見反映 + ADR-032 (docs-only fast path) タスク化#82
docs(todo): PR #81 post-merge-feedback の知見反映 + ADR-032 (docs-only fast path) タスク化#82
Conversation
PR #81 マージ後の post-merge-feedback report (.claude/feedback-reports/81.md) で挙げられた以下 2 件を採用し、docs/todo.md の「現在進行中」に追加。 - Tier 1: Markdown linter (markdownlint-cli2) の PostToolUse hook 統合 ADR-002 の linter composition を .md に拡張。push pipeline 統合では なく hook 方式を採用し edit 時の自動 --fix で違反が CodeRabbit に 届く前に解消する。 - Tier 3: グローバルルール git-workflow.md の jj 運用節更新 todo.md 完了タスク削除を独立 commit で行う手順を明記。本セッション でユーザーから明示指示を受けた事象を恒久化し、全プロジェクトの新 セッションで同判断を再現可能にする。
docs/todo.md がファイルサイズ約 40KB に達し、Claude Code の読み取り 安定性 (50KB 超で不安定化) を考慮して新規タスクは分割ファイルに記録。 todo2.md の初回エントリとして「docs-only PR 高速パスの導入 (ADR-032 起案 + 実装)」を追加。本セッションで策定した plan (~/.claude/plans/1-docs-todo-md-askuserquestion-validated-orbit.md) の要点を背景・設計決定・作業計画・前提情報・完了基準として記録。 Phase pre → α → broken-link → β → γ → δ の sequential 依存と、 新セッションで最初に確認すべきファイル一覧を含めることで、別セッション での作業再開を容易にする。
開発環境の作業効率への貢献度を基準にした推奨実行順序を整理し、両ファイル に明示する。新セッションでも次に何をすべきかが一目で判断できるようにする。 - docs/todo.md 冒頭に「推奨実行順序サマリー」表 (順位 1〜10) を追加 - docs/todo2.md 冒頭に todo.md サマリーへの相互参照を追加 - 各タスクの metadata に「実行優先度: Tier N (順位 X/10)」行を追加し、 Tier 判断の根拠 (依存・工数・即効性) を簡潔に記載 - ADR-032 は Phase ごとに Tier が分散するため、sub-phase 別の順位 (PR-pre/α/broken-link/β/γ/δ) を一覧化 順位の決定基準: - 工数の小ささ × 即効性 × 依存の少なさ → Tier 1 (1〜3) - ADR-032 の前提条件として必要 → Tier 2 (4, 5) - payoff は最大だが前提依存が多い → Tier 3 (6〜8) - daily efficiency への直接効果が小さい cleanup → Tier 4 (9) - 派生プロジェクト展開で本リポジトリへの効果なし → Tier 5 (10)
…ttern) ユーザーフィードバック: 個人開発 + コーディングエージェント前提では Required reviewers (人間レビュー必須) は anti-pattern。実装/テスト/ PR 作成が AI で自動化される一方、人間レビューだけが唯一の同期処理と して律速になるため、ブロックは CI (Required status checks) に集約 する。 主な変更: - Phase pre から「Required reviewers: 人間 (or 自分) を最低 1」を削除 - 役割分担を明記: 即時 CI / 非ブロッキング CodeRabbit (センサー) / 遅延・包括 ADR-031 週次レビュー / event-driven 人間レビュー - Phase 2 の検討余地として「path-based selective review」「強制条件 追加 (codecov 等)」を追記 - 関連箇所の整合性確保: 「GitHub のマージ制御の正しい分離」セクション と「ユーザー判断記録」テーブルを同じ方針で更新 設計の本質:「全変更をレビューする」ではなく「リスクの高い変更だけ 止める」。機械で止められるものは全部機械に寄せる。
📝 WalkthroughWalkthroughタスク追跡と実行ガイダンスの新規ドキュメントを追加します。 Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ 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. Comment |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/todo.md`:
- Around line 410-419: docs のブロック引用内で空行があり markdownlint の MD028
(no-blanks-blockquote) を発生させているので、該当する「Markdown linter (markdownlint-cli2) の
PostToolUse hook 統合」節中の blockquote
パラグラフ(現在空行がある箇所)を修正してください:空行を削除して段落を詰めるか、空行をブロック引用のまま保持する必要がある場合は各空行を `>`(または `>
`)で始めるように統一して MD028 を解消してください。該当箇所は同節内のブロック引用(コメントで指摘されている箇所と 459–468
領域に相当)を対象に行ってください。
In `@docs/todo2.md`:
- Around line 317-319: Fix the Japanese particle omission in the list item that
currently reads "`[docs/todo.md](todo.md) と本 todo2.md を両方読む`": change it to
include the object particle and read "`[docs/todo.md](todo.md) と本 todo2.md
の両方を読む`" (or at minimum "`...両方を読む`") so the sentence reads naturally; update
the line containing that exact phrase in the todo2.md content.
- Around line 343-359: The fenced code block in the snippet is missing a
language tag which triggers MD040; update the opening fence (the ``` block that
contains the Phase pre ... Phase 2 lines) to include a language identifier such
as text (e.g., change ``` to ```text) so the markdown linter accepts it and
retains the block content unchanged.
- Around line 184-191: The Markdown blockquote table (the lines starting with ">
| フェーズ | チェック | 性質 | 役割 |" and its following rows) violates MD058 by lacking
blank lines before and after the table; fix it by inserting a single empty
blockquote line (a line containing only ">") immediately before the table and
another empty blockquote line immediately after the table so the table is
separated from surrounding blockquote text.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8c47afa6-d0a9-4eb2-8d64-9384d189b359
📒 Files selected for processing (2)
docs/todo.mddocs/todo2.md
| ### Markdown linter (markdownlint-cli2) の PostToolUse hook 統合 | ||
|
|
||
| > **動機**: PR #81 の CodeRabbit が `docs/todo.md:221` の MD040 (fenced-code-language) 違反を Nitpick で指摘。同種の違反 (Fenced code block の言語指定子不足) は過去にも度々発生しており、人間レビューでは見落としやすい。本プロジェクトでは markdownlint を意図的に外していたわけではなく、存在を認識していなかっただけと判明。post-merge-feedback (PR #81) も Tier 1 (決定論的防止) として独立に同提案を生成。 | ||
| > | ||
| > **本タスクの位置づけ**: ADR-002 の PostToolUse linter composition (Biome + oxlint) を `.md` ファイルに拡張する。push pipeline 統合ではなく **hook 方式** を採用することで edit 時の自動 `--fix` を実現し、ユーザーに違反が見える前に修正完了させる。 | ||
|
|
||
| > **参照**: `.claude/feedback-reports/81.md` の Tier 1 finding (post-merge-feedback による独立提案) | ||
| > | ||
| > **実行優先度**: 🚀 **Tier 1 (順位 2/10)** — daily efficiency への即効性が極大。`.md` 編集毎に自動 `--fix` で CodeRabbit Nitpick が消え、PR レビュー時間も間接短縮。**ADR-032 (docs-only fast path) の前提条件** (push 前に markdownlint 違反が解消されることが docs-only skip の前提)。順位 1 と並列または直後に実施推奨。 | ||
|
|
There was a problem hiding this comment.
> ブロック内の空行で MD028 が発生しています
Line 415 と Line 464 付近で blockquote 内に空行があり、markdownlint-cli2 で MD028 (no-blanks-blockquote) warning になります。> を維持した空行にするか、段落を詰めて warning を解消してください。
修正例
>
->
+>
> **本タスクの位置づけ**: ADR-002 の PostToolUse linter composition (Biome + oxlint) を `.md` ファイルに拡張する。push pipeline 統合ではなく **hook 方式** を採用することで edit 時の自動 `--fix` を実現し、ユーザーに違反が見える前に修正完了させる。 >
->
+>
> **本タスクの位置づけ**: グローバルルール (`~/.claude/rules/common/git-workflow.md`) への追記。本プロジェクトに閉じない普遍的な jj 運用規約として扱う。本タスク完了で全プロジェクトの新セッションで自動的に同じ判断ができるようになる。Also applies to: 459-468
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 415-415: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/todo.md` around lines 410 - 419, docs のブロック引用内で空行があり markdownlint の
MD028 (no-blanks-blockquote) を発生させているので、該当する「Markdown linter (markdownlint-cli2)
の PostToolUse hook 統合」節中の blockquote
パラグラフ(現在空行がある箇所)を修正してください:空行を削除して段落を詰めるか、空行をブロック引用のまま保持する必要がある場合は各空行を `>`(または `>
`)で始めるように統一して MD028 を解消してください。該当箇所は同節内のブロック引用(コメントで指摘されている箇所と 459–468
領域に相当)を対象に行ってください。
| > **役割分担**: | ||
| > | フェーズ | チェック | 性質 | 役割 | | ||
| > |---|---|---|---| | ||
| > | push 時 (即時) | CI / lint / test / build | ブロッキング (Required status checks) | 「壊れる変更」を止める | | ||
| > | PR 時 | CodeRabbit | 非ブロッキング | センサー (異常検知のみ、ゲートキーパーではない) | | ||
| > | 週次 (遅延) | ADR-031 全体レビュー | 包括 | cross-PR drift / semantic drift 補完 | | ||
| > | 任意 | 人間レビュー | event-driven | バグ発生時 / 大きい変更 / 設計変更 (ADR 絡み) のみ | | ||
| > |
There was a problem hiding this comment.
blockquote 内テーブルの前後に空行が不足しています
Line 185 付近の表が MD058 (blanks-around-tables) 対象です。> 付きで表の前後に1行ずつ空行を入れてください。
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 185-185: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/todo2.md` around lines 184 - 191, The Markdown blockquote table (the
lines starting with "> | フェーズ | チェック | 性質 | 役割 |" and its following rows)
violates MD058 by lacking blank lines before and after the table; fix it by
inserting a single empty blockquote line (a line containing only ">")
immediately before the table and another empty blockquote line immediately after
the table so the table is separated from surrounding blockquote text.
| 1. `git log --oneline -10` で master 最新確認 | ||
| 2. [docs/todo.md](todo.md) と本 todo2.md を両方読む | ||
| 3. `~/.claude/plans/1-docs-todo-md-askuserquestion-validated-orbit.md` を読む (本タスク策定時の plan) |
There was a problem hiding this comment.
日本語の助詞抜けで読みづらくなっています
Line 318 は「両方読む」より「両方を読む」の方が自然です。
🧰 Tools
🪛 LanguageTool
[uncategorized] ~318-318: 文法ミスがあります。"を読む"の間違いです。/.claude/plans/1-docs-todo-...
Context: ...r 最新確認 2. docs/todo.md と本 todo2.md を両方読む 3. `
(MEISI_YOMU)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/todo2.md` around lines 317 - 319, Fix the Japanese particle omission in
the list item that currently reads "`[docs/todo.md](todo.md) と本 todo2.md
を両方読む`": change it to include the object particle and read
"`[docs/todo.md](todo.md) と本 todo2.md の両方を読む`" (or at minimum "`...両方を読む`") so
the sentence reads naturally; update the line containing that exact phrase in
the todo2.md content.
| ``` | ||
| Phase pre (branch protection) | ||
| ↓ | ||
| Phase α (ADR-031 Phase B、既存 todo.md タスク) | ||
| ↓ | ||
| Phase broken-link (quality_gate 拡張) | ||
| ↓ | ||
| Phase β (ADR-032 起案 + 実装、enabled = false default) | ||
| ↓ | ||
| Phase γ (enablement flip) | ||
| ↓ | ||
| Phase δ (dogfood) | ||
| ↓ | ||
| Phase 観測 (4-6 週) | ||
| ↓ | ||
| Phase 2 (任意、段階的緩和) | ||
| ``` |
There was a problem hiding this comment.
fenced code block に言語指定が必要です
Line 343 のコードフェンスが MD040 対象です。text などの言語指定を付けると lint を通せます。
修正例
-```
+```text
Phase pre (branch protection)
↓
...
Phase 2 (任意、段階的緩和)</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 343-343: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/todo2.md` around lines 343 - 359, The fenced code block in the snippet
is missing a language tag which triggers MD040; update the opening fence (the
``` block that contains the Phase pre ... Phase 2 lines) to include a language
identifier such as text (e.g., change ``` to ```text) so the markdown linter
accepts it and retains the block content unchanged.
…化 + ファイルサイズ調整 (#83) * docs(todo): PR #82 post-merge-feedback の Tier 1 / Tier 3 finding をタスク化 PR #82 マージ後の post-merge-feedback report (.claude/feedback-reports/82.md) で挙げられた以下 3 件を採用。 T1-1 + T1-2 (markdownlint hook 統合の補強): - 既存の markdownlint task に MD028 / MD040 / MD058 の初期 rule set 明示を追記 - 新規タスク化ではなく既存タスクの作業計画に吸収 T3-1 (個人開発ブランチ保護方針 ADR/グローバルルール明文化、新規): - 「Required reviewers は個人開発 + AI エージェント前提では anti-pattern」 判断を ~/.claude/rules/common/git-workflow.md に明文化 - 計画フェーズで 7 回のフィードバック反復を要した経緯を恒久化 - 順位 1 (git-workflow.md jj 運用節更新) と同一ファイル編集のため並列実施可 - Tier 1 順位 2/12 T3-combined (reviewer facet 改善、新規、Tier 3 #2-4 統合): - review-simplicity.md に DRY スコープ + YAGNI スコープ規定を追記 - review-security.md に docs-only 判定軸 (trust boundary 変化有無) を追記 - 全 PR の review 精度向上、false positive iteration 削減 - Tier 2 順位 6/12 その他: - 推奨実行順序サマリー表を 10 件 → 12 件に拡張、順位を再採番 - 既存タスク 5 件の実行優先度 line を新採番に更新 - 戦略コメントに「順位 1-2 グローバルルール並列可」「順位 6 reviewer facet 改善は Tier 2 内で並列可能」を追記 * docs(todo): T3-combined (reviewer facet 改善) を todo.md → todo2.md へ移動 前 commit で 2 タスク追加した結果 docs/todo.md が 52KB に達し、ユーザー 指定の 50KB 閾値 (Claude Code 読み取り安定性) を超過。T3-combined は 既存 todo.md content との結合度が低いため独立移動が容易と判断。 変更内容: - todo.md から「Reviewer facet 改善 (PR #82 T3-combined)」セクションを削除 - todo2.md 末尾に同セクションを追加 (内部の「本 todo.md エントリを削除」 → 「本 todo2.md エントリを削除」に修正) - todo.md 推奨実行順序サマリー表の順位 6 行のファイル参照を todo.md → todo2.md に更新 結果: - todo.md: 52KB → 49KB (閾値内に復帰) - todo2.md: 21KB → 29KB (余裕あり) T3-1 (ブランチ保護方針 ADR/グローバルルール明文化) は順位 1 (git-workflow.md jj 運用節更新) と同一ファイル編集のため、結合度が高く todo.md に残置。
… 登録 (#95) * feat(takt): Bundle T (reviewer facet 改善 + .claude/ filter) + Bundle U 登録 token 削減 Phase 2 (Bundle T) の本実装と、Bundle U の todo 登録を同梱する。 両者は token-reduction 系で論理的近接 + rate-limit 不安定期の PR 数最小化方針による同居。 ## Bundle T 本実装 (順位 9 + 14) ### 順位 9: Reviewer facet 改善 (PR #82 T3-combined) `.takt/facets/instructions/review-simplicity.md`: - Scope of DRY / YAGNI セクション追加 - DRY 適用範囲: コードロジックのみ。docs 階層化や docs/code 重複は対象外 - YAGNI 適用範囲: 実装 only。"Phase 2 検討" 等の計画書記述は対象外 `.takt/facets/instructions/review-security.md`: - Docs-only changes: trust boundary criterion セクション追加 - trust boundary 不変な docs 変更 (ポリシー説明・用語定義等) は APPROVE 即判定 - trust boundary 関連 (権限境界の再定義等) は通常 review ### 順位 14: post-pr-review fix loop の `.claude/` filter + ADR-030 制約明記 `.takt/facets/instructions/analyze-coderabbit.md`: - Sensitive-file protection filter 追加 (`.claude/**` → `user_decision_path`) - Scope mismatch を `.git/`, `.jj/`, `node_modules/`, `target/` まで拡張 - Verdict rule: `user_decision_path` は severity 問わず `user_decision` 経路へ - Output Format に User Decision Path テーブル追加 `docs/adr/adr-030-deterministic-post-merge-feedback.md`: - 「post-pr-review fix loop の対象外パス」セクション追加 - 3 カテゴリ documented: Claude sensitive-file / VCS 内部 / 依存物 - PR #91 で実証された 8 step 空費 pathological loop の採用根拠 - Verdict ルールの整合表と関連 ADR への参照 ## Bundle U 登録 (順位 29 + 30) `docs/todo.md`: - 順位 29 (Tier 1): 非 docs ファイル `docs/todo` 参照検出 lint rule - 順位 30 (Tier 3): Cross-File Reference Lifecycle ルールに具体例追記 - narrative に Bundle U 説明追加 `docs/todo3.md`: 上記 2 件の詳細エントリ追加 ## todo cleanup - todo.md table から順位 9, 14 削除 - todo2.md から順位 9 詳細削除 - todo3.md から順位 14 詳細削除 - 関連 narrative を完了状態に更新 ## 期待効果 - false positive iteration 削減: docs PR で simplicity/security の DRY/YAGNI 誤検出ゼロ - pathological loop 防止: `.claude/` 配下に finding が出る PR で 8 step 空費が再発しない - review report の透明性向上: User Decision Path として明示分類 ## 検証 - markdown lint: 全ファイル 0 errors - jj diff --stat: 7 files changed - 実装テスト: facet 変更は dogfood まで定量検証不能 (LLM 挙動)、初回適用 PR で観察 * fix(takt): CodeRabbit 指摘 2 件への対応 (PR #95) Finding #1 (Major, analyze-coderabbit.md): Step 3 と新規 User Decision Path テーブルの severity 列の整合性を解消。Step 3 を「Severity は CodeRabbit の severity field から取得 (`applicable` と `user_decision_path` 共通)」に明記し、 理由 (user の優先度判断に有用) を補足。`not_applicable` は severity 不要と 明記。 Finding #2 (Minor, ADR-030 line 315): LanguageTool 文法指摘に従い 「設計。」を「設計である。」に変更 (DOUSI_DEHA rule)。 * fix(adr): ADR-030 と analyze-coderabbit.md の整合性を解消 (PR #95) CodeRabbit 再レビューで検出された Major × 2 件への対応: Finding A (line 286-287): 「すべての除外 path は user_decision_path」記述が 実装と乖離していた。実装では `.claude/**` のみ user_decision_path で、 VCS/依存物は not_applicable (別経路、Step 2 でフィルタ)。本 commit で 2 種類の分類を明示。前回 commit で Scope mismatch を 4 path に拡張した際の ADR テキスト更新漏れの drift を解消。 Finding B (line 310-313): Verdict テーブルヘッダ「.claude/ etc. (対象外 path)」 が verdict routing に参加する全 path を示すよう誤読されるため、 「.claude/ (user_decision_path)」に変更。テーブル前に「verdict routing に 参加する applicable と user_decision_path のみを示す」注記を追加し、 not_applicable が verdict に関与しないことを明記。 両者とも CodeRabbit suggestion 準拠 (commit_id c983377 を root とする 分類整合性問題、本 commit で完全に整合)。 * fix(adr): ADR-030 line 325 の ADR-018 表記を 'cli-pr-monitor takt 移行' に統一 (PR #95) CodeRabbit 再レビュー指摘 (Minor) への対応。本文 line 35 / References line 365 で既に 'cli-pr-monitor' 表記に統一されていたが、本 PR の前 commit で追加した '関連 ADR' セクションのみ 'post-pr-monitor 移行' と誤記。post-pr-monitor は workflow 名で ADR-018 の対象 tool ('cli-pr-monitor') と異なる概念のため事実誤認。 実 ADR-018 タイトル ('cli-pr-monitor の takt ベース移行と CronCreate 廃止') に 合わせて統一。
Summary
Commit 構成
tkvvmwvqsyxvkusqnlzspnvnmrmmzyrl主な変更点
1. PR #81 post-merge-feedback の知見をタスク化
post-merge-feedback workflow が PR #81 マージ後に独立に挙げた以下 2 件を採用:
.md編集時の自動--fixで CodeRabbit Nitpick を解消git-workflow.mdの jj 運用節更新 — todo.md 完了タスク削除手順を恒久化2. docs/todo2.md 新設 (サイズ管理)
todo.md が ~40KB に達し、Claude Code の読み取り安定性 (50KB 超で不安定化) への配慮として todo2.md を新設。両ファイルは独立、新セッションでは両方確認が必要。
3. ADR-032 (docs-only PR 高速パス) 計画策定
PR #81 自身が示した「docs only PR で 15 min かかる」課題への対応設計:
quality_gateのみ維持--full-reviewoverride + PR サイズ guard4. 推奨実行順序 (Tier 1〜5)
5. ADR-032 Phase pre 修正 (Required reviewers 削除)
ユーザーフィードバックを反映:「個人開発 + コーディングエージェント前提では Required reviewers (人間レビュー必須) は anti-pattern。実装/テスト/PR 作成が AI で自動化される一方、人間レビューだけが唯一の同期処理として律速になる」
Required reviewers: 人間 (or 自分) を最低 1を削除Test plan
.claude/feedback-reports/81.md) との整合性確認 (Tier 1 + Tier 3 が反映済)後続作業 (本 PR では実施しない)
関連
Summary by CodeRabbit
リリースノート