型付き辺: 出 8 / 入 0
ADR-0144: ADR 実装フォローアップの関連ドキュメント更新を残タスクとして半自動検知する
- Status: Accepted (PR #1861 merge = 受理の規約により 2026-06-12 受理・代表取締役判断)
- Mode: Standard
- Kruchten Type: Executive/Property
- Scope: platform
- Implementation Status: In Progress (sub 分完了 = followups 宣言形式確定〔frontmatter followups: schema/updated_at/on_done/none_reason〕+ 起案テンプレ既定値埋め + 残論点台帳 P8 + glossary。main Phase a 完了 = scripts/lib/adr_followups.mjs〔parse + validate〕+ scripts/adr-impl-followup-detect.mjs〔CLI〕+ adr-lint 2 ルール〔followups-meta filenum>159 / followups-structure filenum>144〕+ tests/adr-followups.test.mjs〔16 tests〕。main Phase b-1 完了 = 0145-0159 followups バックフィル〔15 ADR〕+ adr-lint followups-meta threshold 引き下げ filenum>144。main Phase b-2/b-3 完了 = .github/workflows/adr-followup-detect.yml〔PR/push:main/週次/dispatch の 4 トリガー + DOC-OPS backlog〔doc-ops-followup ラベル〕冪等起票 + 到達整合 close〕。main Phase c 完了 = scripts/lib/adr_status_staleness.mjs〔発火判定 pure〕+ scripts/adr-status-staleness-detect.mjs〔CLI・git 履歴注入〕+ .github/workflows/adr-status-staleness-detect.yml〔Phase b 同型 4 トリガー + doc-ops-followup-stale ラベル冪等起票 + 到達整合 close〕+ tests/adr-status-staleness.test.mjs〔21 tests〕。残 = Phase d 〔30 日記入率ゲート化〕)
- 起案者: [email protected]
- 起案日時 (JST): 2026-06-12 13:21
- 承認日時 (JST): 2026-06-12 13:39
- Deciders: [email protected] (単独)
コンテキスト
§1.1 背景
ADR のライフサイクル (受理・実装の進捗・実装完了) に伴って更新すべき関連ドキュメント — 構造正典 §G の検査所有表、残論点台帳の行更新・削除、ADR 自身の Implementation Status、相手側 ADR の逆辺、事業軸、Review After など — の反映が、人間の記憶頼みで行われ漏れる。実装・受理の完了と文書の整合 (reconciliation) が分離しており、突き合わせが手動である。
これは直近 2 件の事故ではなく、プロジェクト全体で常態化した手作業である。直近 300 コミットのうち 約 58 件が「記録反映・後修正・index 再生成」系で、67 件が ADR 一覧 (INDEX.md / adr-index.json) を手で触っている。コミットメッセージにも「受理記録反映 = flip + 台帳更新」「後修正 = 辺 11 本 + 逆辺 / business / Review After」「Implementation Status 更新」が繰り返し現れる。
§1.2 現状 (As-Is)
直近でも ADR-0141 sub 実装 (PR #1858) で本体 Implementation Status が Not Started のまま放置され台帳 Q1 も未更新 (是正に別 PR #1859 が必要)、ADR-0138 でも sub 完了後に手動更新が別途必要、と毎回発生している。受理・実装のたびに「どの文書を直すか」を起案者が覚えて手で反映している。
現状の自動化は部分的で、しかも別カテゴリを覆っている。パイプライン生成 PR の定型後修正 (frontmatter トリオ + メタ複製 + nav 登録 + index 再生成) は CI autofix (ADR-0130 系・2026-06-12) が機械化済みで、ADR 一覧の drift も adr-lint の drift-check が検知する。
§1.3 課題
ここで漏れているのは別の層 — 意味判断を伴う「ライフサイクル連動の関連文書反映」 (status flip の反映、台帳行の更新・削除、§G の「実装待ち」解消、逆辺・business・Review After の追補、Implementation Status の遷移) で、これらを「やるべきだ」と検知して可視化する仕組みは無い。autofix は構文的な複製を担うが、何をどう書くかの意味判断は機械化できず、結果として手作業に残り漏れている。認知負荷が高く取りこぼす。
§1.4 制約・要件
- 既存の残論点台帳・frontmatter の延長で宣言を置き、別系統の台帳を新設しない
- 文書本体の自動書換は行わず、意味判断は人に残す (誤更新が監査記録を汚すのを避ける)
- 検知は CI 上で実行し、LLM 追加コスト 0 円を維持
- 未処理を取りこぼさない (false negative を出さない)
§1.5 目標 (To-Be)
実装完了と文書反映の突き合わせを機械検知し、未処理 followup を残タスク (DOC-OPS backlog または issue) として可視化する。Non-Goals: 関連ドキュメントの自動書換、別系統の台帳新設。
決定
ADR に「実装完了時に更新する関連ドキュメント」を機械可読に宣言させ、Implementation Status と突き合わせて未処理を検知し、残タスク (DOC-OPS backlog または issue) へ追加する半自動の仕組みを採用する。文書本体の自動書換は行わず、意味判断を要する文書編集は人に残す。宣言の置き場は、残論点台帳が既に散文で持つ「実装完了で §G-2 の実装待ちを解消し本行を削除」のような記述を機械可読化する方向を本命とし、具体形 (ADR frontmatter の followup フィールド か、台帳行のマーカー か) は審査で詰める。
検知トリガーは「PR ごと」+「main への push 全件」+「週次フルスキャン (全 ADR の現在 Status × 宣言の突き合わせ)」の 3 系統とし、Status 遷移を書かなくても frontmatter diff から検知できる補助トリガーを併設する (盲点 1 対応)。残タスク起票先は DOC-OPS backlog に一本化 し、既存 ops-prompt-notify の issue 起票とは責務を分離する (盲点 4 対応)。導入初日から followup 宣言フィールドを起案テンプレで既定値埋め済みとし、空欄は adr-lint でエラー扱いとする (盲点 2 対応)。
判断基準 (Decision Drivers)
3.1 評価軸
| # | 軸 | 重要度 (係数) | 案件特有の解釈 |
|---|---|---|---|
| 1 | #usable | Must (×2.0) | 起案者・実装者が宣言を書く負担が小さい (既存の残論点台帳の散文を機械可読化する程度)。検知結果で何をどの文書に反映すべきかが一目で分かる |
| 2 | #reliable | High (×1.0) | 未処理 followup を取りこぼさない (false negative を出さない)。Implementation Status の遷移を確実に捕捉する |
| 3 | #maintainable | Medium (×0.5) | 宣言形式が既存の frontmatter・残論点台帳の延長で、別系統の台帳や独自フォーマットを増やさない |
K.O. criterion: Must 軸 #usable の score < 3、または検知が CI で実装できない / false negative が常態化する案は不採用。
3.2 評価軸 × 案スコア表
| 軸 | 係数 | 採択案 Z (宣言+検知+残タスク化) | 案 A (自動書換) | 案 B (現状維持) | 案 D (autofix 拡張) | 案 E (CODEOWNERS) |
|---|---|---|---|---|---|---|
#usable (Must) | ×2.0 | 4 | 2 | 5 | 3 | 4 |
#reliable (High) | ×1.0 | 4 | 2 | 1 | 2 | 3 |
#maintainable (Medium) | ×0.5 | 4 | 2 | 5 | 3 | 5 |
| 加重和 (正規化) | 0.800 | 0.400 | 0.650 | 0.500 | 0.750 | |
| K.O. 通過 (Must ≥3) | ✓ | ❌ | ✓ | ✓ | ✓ |
採択案 Z と案 E (CODEOWNERS) が拮抗するが、CODEOWNERS は「特定ファイル変更時のレビュー強制」であり、ADR 受理後に文書更新が行われていないことを検知できない (push が無いものは検知不能)。#reliable の差で案 Z を採択。
検討した代替案 (Alternatives Considered)
- 案 A (関連ドキュメントを自動で書き換える): §G の文面や台帳行の書き換えは「どう書くか」の意味判断を要する。機械化すると誤更新が監査記録 (Accepted ADR・正典) を汚すリスクが高い。不採用。
- 案 B (現状維持・散文の約束のみ): 残論点台帳が既に「実装完了で §G-2 解消・本行削除」と散文で持つが、実装完了の検知と突き合わせが無く、ADR-0141・ADR-0138 で実際に漏れた。不採用。
- 案 C (GitHub issue のみで管理): main が先日構築した
ops-prompt-notifyの issue 起票を流用する。宣言ソースが無いと issue 内容を機械生成できないため、本決定の検知部と組み合わせる (排他でなく、残タスク化先の一候補)。本決定では起票先を DOC-OPS backlog 一本化と決定するため独立採用は不採用。 - 案 D (既存の CI autofix を拡張して関連文書も自動修正): パイプライン PR の定型後修正 (frontmatter トリオ・nav・index 再生成) は CI autofix (ADR-0130 系) が既に機械化している。これを §G の文面・台帳行・逆辺へ広げる案。だが autofix が機械化できているのは「実体から構文的に複製できる」ものに限られ、§G の「実装待ち」を何と書き換えるか、台帳行を更新するか削除するかは意味判断を要する (案 A と同じ誤更新リスク)。不採用。
- 案 E (PR checklist + CODEOWNERS で代替): 特定ファイルが変更されたときに指定レビュアーを強制する枯れた仕組み。検知スクリプト保守が不要だが、ADR 受理後に文書更新が行われていないケース (= 本 ADR が解決したい中心ケース) を検知できない。
#reliableで案 Z に劣り不採用。
影響 (Consequences)
§5.1 正の影響 (Good)
- 更新漏れの構造的防止。実装フェーズ (sub / main 分割) と文書反映の整合が可視化される。
- reconciliation が手動記憶から機械検知へ移り、認知負荷が低減する。
- 残論点台帳の散文を機械可読化することで、既存の監査記録系列との連続性を保ったまま自動化できる。
§5.2 負の影響 (Bad)
- 起案・受理時に followup 宣言の記入が増える (数行・1 分未満/件)。
- 検知スクリプトと CI wiring の新規保守 (main 領分) が発生する。
- 初回スキャンで既存の未処理分が数十件一斉起票されると担当者の処理キューが飽和するため、初回導入時はバックフィル戦略 (既存分は件数上限付きバッチ起票・別ラベルで区別) を併設する (盲点 3 対応)。
§5.3 中立・トレードオフ (Neutral / Trade-offs)
- 宣言が形骸化 (誰も書かない) すると検知が空振りする → 起案テンプレの既定値埋め済み + adr-lint の宣言存在チェックを導入初日から適用する (盲点 2 対応)。
- 自動化バイアス (「機械が拾ってくれる」前提で宣言外の更新を起案者が確認しなくなる) を抑えるため、月次で完了 ADR 3 件をサンプリングし宣言の網羅性を抜き取りレビューする (盲点 8 対応)。
- 宣言の最終更新日 / バージョンフィールドを形式に含め、実装フェーズ中の対象文書変更を追跡できるようにする (盲点 5 対応)。
- 検知スクリプトの実行環境制約 (Cloudflare Workers の 30 秒 wall time・subrequest 上限 50) を考慮し、ADR 200 件超で差分のみ処理する incremental アプローチに切り替える設計を初期から織り込む (盲点 6 対応)。
撤退条件 (Rollback Plan)
- 導入後 90 日で、検知が拾った未処理 followup の実処理率が 50% 未満 (タスク化しても放置される) なら、宣言を必須化せず任意運用へ戻す。
- false negative (宣言があるのに検知漏れ) が 月 2 件以上なら検知ロジックを再設計する。
- 宣言の記入率について、導入 30 日後に確認し 70% 未満なら起案前ゲートでの宣言存在チェックを即ゲート化する (盲点 2 対応)。90 日後で 50% 未満なら任意運用へ戻す。
- ロールバック手順: 検知スクリプトを CI から外す (宣言データ・既存文書への影響なし)。宣言は人手チェック用のメモとして残置可能。
コスト試算
- 実装 (sub): followup 宣言形式の確定 + 残論点台帳・起案テンプレへの反映 + glossary 追補で 0.5 人日
- 実装 (main): 検知スクリプト (ADR の Implementation Status × 宣言の突き合わせ) + CI wiring (DOC-OPS backlog 追記) + unit test で 1〜2 人日
- 運用: 起案・受理時の宣言記入は数行・1 分未満/件。検知は CI で走り LLM 追加コスト 0 円。
- 実行時間概算: 現在の ADR 件数 (約 150 件) で frontmatter 全件パースは数秒オーダー。1 年後 300 件想定でも 10 秒以内。Cloudflare Workers の 30 秒 wall time 制約には抵触しない見込みだが、200 件超で incremental 化する設計余地を残す。
- 合計見積もり: 1.5〜2.5 人日
Confirmation
- 検証手段: 月次で「Implementation Status が遷移した ADR の件数」と「未処理 followup の検知件数・実処理件数」を集計する。CI が検知レポートを生成し、未処理分を DOC-OPS backlog へ追加する。月次で完了 ADR 3 件をサンプリングし、宣言に書かれていない更新漏れがないか目視確認する抜き取りレビューを併設する。
- 実行頻度: 検知 = PR ごと / main への push 全件 / 週次フルスキャン の 3 系統。集計・抜き取りレビュー = 月次。
- 違反時対応: 実処理率が撤退条件の閾値 (50% / 90 日) を下回ったら撤退条件評価を行う。記入率が 30 日時点で 70% 未満ならゲート化を即時実施。
- KPI: 未処理 followup の実処理率 70% 以上 / false negative 月 0 件 / 新規 ADR の宣言記入率 80% 以上 / 抜き取りレビューでの網羅漏れ 月 0 件
Review After
- 次回レビュー: 2026-12-01(導入後の実処理率・記入率の実績が揃い、自動化バイアスと初回バックフィルの影響を評価できる時期。0141/0142/0143 のレビューと同時実施)
- レビュー主体: ADR 運用の所有者(DRP 運用者。現任 = 代表取締役)
- 前倒しトリガ: ① 記入率が 30 日時点で 70% 未満でゲート化を発動した時 ② 初回バックフィルで処理キューが飽和し実処理率 KPI を初月から下回った時 ③ 宣言の置き場(frontmatter か台帳マーカーか)を実装着手時に確定した時(検知ロジックと撤退条件の現実性を再評価)
参照 (References)
- 関連 ADR:
- ADR-0137: メタデータ frontmatter 移行 — 補完 (Implementation Status の遷移が検知トリガー。宣言の置き場は frontmatter が候補)
- ADR-0130: 索引・カタログの自動生成で維持 — 並立 (「自動生成で維持」の思想と同系だが、本決定は文書を自動生成せず残タスク化に留める点が対照)
- ADR-0133: 受理後の辺の意味監査 — 補完 (⑤ 受理後層の監査と実装基盤を共有しうる。本決定は実装フェーズの reconciliation を扱う)
- ADR-0141 / ADR-0138 — 本決定が解消する更新漏れ事故の発端
- 関連 PR/Issue: PR #1858 (ADR-0141 sub 実装) / PR #1859 (是正)
- 外部資料: 構造正典 §G・残論点台帳 (本決定が機械可読化する対象)