← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0032type: adrstatus: accepted
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Done (PRproposed_at: 2026-05-13 20:14approved_at: 2026-05-13 20:19deciders: [email protected] (単独)business: meta
型付き辺: 出 7 / 入 2
関連: ADR-0033 ADR-0018 ADR-0030 ADR-0031 ADR-0023 ADR-0054 ADR-0163 細分化された: ADR-0162 前提とされる: ADR-0038全体は INDEX →

ADR-0032: ADR テンプレートに Implementation Status メタデータを追加 — 実装ライフサイクルの可視化

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Existence/Property
  • Scope: platform
  • Implementation Status: Done (PR #673)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-13 20:14
  • 承認日時 (JST): 2026-05-13 20:19
  • Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景

ADR-0023 (構造業界標準化) で Status フィールドが Proposed/Accepted/Rejected/Superseded の 意思決定ライフサイクルを表現するようになり、ADR-0030/0031 で Kruchten Type が 主題分類を表現するようになった。しかし「決定はされたが、コードに反映されているか」を示す 実装ライフサイクルを表すフィールドが存在しない。

たとえば本日 (2026-05-13) マージされた ADR 群を見ると:

  • ADR-0027 (Walking Skeleton 計測基盤): Accepted、計測シート + Utils 関数は実装済か?
  • ADR-0028 (全体 6 段ワークフロー): Accepted、Step 7 (scripts/2.5 等) はブランチ feat/adr-0029-impl-step7 で進行中
  • ADR-0029 (Spec/Impl Pipeline 詳細): Accepted、同上
  • ADR-0030 (Kruchten 採用): Superseded by ADR-0031 (部分)、実装 PR #663 はマージ済

が、これらの 実装が main に反映されたかどうか を ADR メタデータから即時確認できない。

1.2 現状 (Current State / As-Is)

bizlp-gas-accounting の 32 ADR (0000-0031) で Implementation Status の表現状況:

  • Implementation Status フィールド保有: 0/32 本 (0%)
  • 実装 PR/commit への明示リンク保有: 約 8/32 本 (25%、最近の ADR-0024〜0031 周辺で参照欄に PR 番号を記載した例のみ)
  • Jr 入社後 (2026-10) に「ADR-0021 の監査ログ機構は実装済か?」を確認する手段: コード grep で 000_infra / 400_domain を確認する以外なし
  • Pipeline body_generation.ts で実装状態を生成時に未トラック

1.3 課題 (Problem)

  1. 「Accepted = 実装済」の誤認: 起案 → 受諾までを Status で追跡できるが、その後の「実装着手 / 進行 / 完了 / リバート」が ADR から見えない。本日 ADR-0028/0029 を Accepted 化した時点で「実装は別 PR」と明記したが、実装 PR がマージされたかどうかは ADR を読んでも判定不可能。
  2. 検索ユースケース未対応: 「現在 In Progress の ADR 一覧」「実装が Reverted された ADR」を grep で取得できない。AKM (Architecture Knowledge Management) の検索漏れリスクが Kruchten Type 採用で改善した同じ問題が、実装ライフサイクル軸でも発生中。
  3. Jr 入社後のオンボーディング負担: 32 ADR を読む際に「これは実装済か / 実装されていないか」を ADR からは判定できず、コード側を grep する往復が発生 (1 ADR あたり 2-3 分の往復、32 ADR × 2.5 分 = 約 1.3 時間)。

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0001〜0031 の本文への遡及追加を許可 (ADR-0031 で運用解釈明確化済: 業界標準準拠のメタデータ後付けは誤字修正範疇)
  • 既存 Status / Mode / Kruchten Type フィールドと直交する別軸
  • Pipeline body_generation.ts での自動付与必須
  • Jr の学習コスト ≤ 15 分 (README ガイドで完結、Kruchten Type 30 分より軽量)

1.5 目標 (Goals / To-Be)

  • Implementation Status フィールドを ADR テンプレートに追加し、各 ADR で実装ライフサイクル状態を可視化
  • 既存 32 ADR への遡及追加 (ADR-0031 確立パターン踏襲)
  • Implementation Status 値の grep で「In Progress」「Reverted」を即時抽出可能に
  • ADR ライフサイクル全体 (意思決定 + 実装) を 4 フィールド (Status / Mode / Kruchten Type / Implementation Status) で立体管理

2. 決定

ADR テンプレートに Implementation Status メタデータフィールドを Kruchten Type 直下に新規追加し、値は Not Started / In Progress / Done / Partial / Reverted / N/A の 6 値とする。各値の後ろに実装 PR/commit リンクを最大 3 件併記し、N/A の場合は理由を 1 行併記する。Pipeline body_generation.ts で新規 ADR は Not Started で初期化し、実装 PR の作成/マージ/リバート時に起案者が本文を更新する (誤字修正範疇)。既存 ADR-0000〜0031 (32 本) には ADR-0031 確立パターンで遡及追加する。

2.1 Implementation Status の値定義

値意味典型例
Not StartedAccepted されたが実装着手前ADR Accepted 直後、実装 PR 未作成
In Progress実装 PR が open or 部分実装中Step 7 等の段階実装、複数 PR にまたがる長期実装
Done実装が main にマージ済完了した機能・ルール・規約
Partial一部実装済だが残作業あり (注釈で範囲明示)フェーズ分け実装、Walking Skeleton 等
Reverted実装が試行され撤退した撤退条件発火後の縮退、技術的不可逆性で revert
N/A実装不要の ADR (governance / process / 純ドキュメント)ADR-0018 (TODO 管理) / ADR-0020 (Triage 根拠) 等

2.2 メタデータ表記

各 ADR のメタデータブロックに以下を追加:

- **Implementation Status**: Done (PR #663, #665)

> Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

値の後ろに 括弧書きで実装 PR/commit リンクを最大 3 件併記する (4 件以上は "等" で省略)。N/A の場合は理由を 1 行併記。

2.3 ADR テンプレ更新箇所

  • docs/adr/templates/template.md: メタデータブロックに **Implementation Status**: を Kruchten Type 直下に追加
  • docs/adr/README.md: 値定義 + 検索ユースケース + 既存 ADR 一覧表に Implementation Status 列追加
  • drp/src/nodes/body_generation.ts: SYSTEM_PROMPT に **Implementation Status**: {{impl_status}} 必須化 (新規 ADR は Not Started で起案、その後手動更新)
  • 既存 ADR-0000〜0031 (32 本): 遡及追加 (ADR-0031 パターン)

2.4 値の更新運用

  • 新規 ADR 起案時: Pipeline body_generation が Not Started で初期化
  • 実装 PR 作成時: 起案者が ADR 本文を編集して In Progress (PR #NNN) に更新 (誤字修正範疇)
  • 実装 PR マージ時: 起案者が ADR 本文を編集して Done (PR #NNN) に更新
  • リバート時: Reverted (PR #NNN, 撤退理由: ...) に更新 + Status は別途検討

3. コスト試算

項目工数金額
template.md / README.md / body_generation.ts 更新1 時間LLM API $0.5
既存 32 ADR を Implementation Status 分類 + 遡及追加 (Python スクリプト)1.5 時間LLM API $1.6 (32 × $0.05 確認用)
Decision Pipeline 投入 + Accepted 化 + マージ1 時間LLM API $3
動作確認 (新規 ADR で自動付与確認、grep 検索ユースケース実走)0.5 時間$0
合計約 4 時間約 $5 (≈ [MASKED:AMOUNT])

機会費用換算: 4 時間 × Jr 想定時給 [MASKED:AMOUNT]/h = [MASKED:AMOUNT] + LLM [MASKED:AMOUNT] ≈ [MASKED:AMOUNT] 投資

年間削減効果 (想定):

  • Jr の ADR 実装確認時間: 月 2 件想定 × 2.5 分削減 × 12 ヶ月 = 60 分/年 ≈ [MASKED:AMOUNT]/年
  • 「In Progress ADR の取りこぼし」防止: 実装中 ADR を月次レビューで漏らさず追跡可能、月 1 件想定 × 0.5 時間機会費用 = 6 時間/年 ≈ [MASKED:AMOUNT]/年
  • 合計: 年間 約 [MASKED:AMOUNT] 削減見込み (投資回収 約 7 ヶ月)

4. 検討した代替案 (Alternatives Considered)

  • 案 A (採用): Implementation Status (Not Started/In Progress/Done/Partial/Reverted/N/A) を ADR テンプレに新規メタデータとして追加 + 既存 32 ADR に遡及付与。

    • Good: Status (意思決定軸) と直交する実装ライフサイクル軸が可視化される。
    • Good: Kruchten Type と組み合わせて 4 軸立体検索 (Status × Mode × Kruchten × Impl Status) が可能になる。
    • Good: ADR-0031 で確立した遡及追加パターンを再利用、追加コスト最小。
    • Bad: 手動更新運用のため形骸化リスク (撤退条件で監視)。
    • Bad: 実装 PR/commit リンクが broken link になる可能性 (CI で監視)。

  • 案 B: 現状維持 (実装状態は ADR 本文の参照セクションに PR 番号を記載する慣習で済ます) — 不採用理由: 構造化されていないため grep 検索不可、Jr の往復コスト固定化。

  • 案 C: GitHub Issues / Linear 等の外部ツール上で実装状態を管理 (ADR 本文には書かない) — 不採用理由: bizlp の「外部ツールロックイン受容不可」方針 (Policy Alignment) に抵触。ADR-0018 で GitHub Issues 移行を保留した判断と矛盾。

  • 案 D: Status フィールドに値を追加 (Accepted-NotImplemented / Accepted-InProgress / Accepted-Done 等の派生) — 不採用理由: ADR-0023 で採用した業界標準 Status 値 (Nygard / MADR 準拠の 4 値) を破る。Backstage / adr-tools 等の業界エコシステムとの互換性消失。

  • 案 E: 別ファイル (docs/_internal/implementation_status_tracker.md) で集中管理 (本文不変) — 不採用理由: ADR-0030/0031 で既に「個別 ADR ページで即視可能にする」方針を採用済、ここで方針反転は混乱を招く。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • Status (意思決定) と Implementation Status (実装) を直交軸で可視化、ADR ライフサイクル全体が立体管理可能に。
  • 4 軸 (Status × Mode × Kruchten × Implementation Status) で grep 検索可能、AKM 検索漏れリスク低減。
  • Jr 入社後 (2026-10) のオンボーディングで「実装済 ADR / 未実装 ADR」を即時判定可能、32 ADR × 2.5 分 = 約 1.3 時間の往復コスト削減。
  • 新規 ADR は Pipeline body_generation で自動初期化、起案者の手作業ゼロ。
  • ADR-0031 確立の遡及追加パターン再利用、追加学習コストなし。
  • 年間 約 [MASKED:AMOUNT] 削減見込み、投資回収約 7 ヶ月。

5.2 負の影響 (Bad)

  • 手動更新運用のため形骸化リスク。実装 PR マージ時に ADR 本文更新を忘れると実態と乖離 (6 ヶ月後の撤退条件で監視)。
  • 実装 PR/commit リンクが PR クローズ・リネーム等で broken link になる可能性 (CI markdown-link-check で監視)。
  • 既存 32 ADR への遡及追加で 1.5 時間 + LLM API $1.6 の初期コストが発生。
  • Status と Implementation Status の整合性矛盾 (例: Status=Rejected で Implementation Status=Done) が起こりうる、CI でのバリデーション追加が将来必要。

5.3 中立・トレードオフ (Neutral / Trade-offs)

  • ADR メタデータブロックが 1 行増える (4 フィールド → 5 フィールド相当の視認負荷増)。Jr 学習コスト ≤ 15 分以内の想定。
  • 将来的に GitHub Actions で実装 PR マージ時の自動更新を ADR-0033 候補として検討余地あり (6 ヶ月後 Review After で判定)。
  • 影響範囲: 4 ファイル変更 (template.md / README.md / body_generation.ts / CLAUDE.md 参照更新) + 32 既存 ADR 本文遡及追加。
  • 自身のメタデータ: Implementation Status = Not Started で起案、本 PR マージ後 In Progress、実装 PR マージ後 Done に更新。

6. 完了条件 (定量メトリクス)

  1. テンプレに Implementation Status フィールド存在: grep "Implementation Status" docs/adr/templates/template.md → match
  2. README に値定義 + 検索ユースケース存在: grep -cE "Not Started|In Progress|Done|Partial|Reverted|N/A" docs/adr/README.md → >= 6
  3. README 一覧表に Implementation Status 列追加 (空欄ゼロ)
  4. 既存 32 ADR に Implementation Status 行存在: for f in docs/adr/00[0-3][0-9]-*.md; do grep -q '^- \*\*Implementation Status\*\*:' $f || echo MISSING; done → 出力ゼロ
  5. Pipeline body_generation.ts に Implementation Status 必須化: grep -c "Implementation Status" drp/src/nodes/body_generation.ts → >= 1
  6. CI markdown-link-check PASS

7. 撤退条件 (Rollback Plan)

判定指標閾値判定タイミング対応revert 手順
Implementation Status の更新が ADR ごとに遅延6 ヶ月後の月次集計で更新遅延 ADR が 30% 超6 ヶ月後 Review Afterフィールド必須化を解除、任意運用に縮退git revert <commit SHA>
実装 PR/commit リンクが broken link 量産CI markdown-link-check で 5 件超エラー月次 CI自動更新スクリプト追加 or リンク併記を任意化フィールド維持、リンク部のみ削除

Review After:

  • 1 ヶ月後 (2026-06-13): 新規 ADR 1-2 本で運用感確認
  • 3 ヶ月後 (2026-08-13): Implementation Status の手動更新運用が形骸化していないか確認
  • 6 ヶ月後 (2026-11-13): 自動化 ADR (ADR-0033 等) の必要性判定 + Jr 入社後の運用感ヒアリング

長期影響 (6 ヶ月後の負債化リスク):

  1. Implementation Status の手動更新忘れで実態と乖離 → GitHub Actions で実装 PR マージ時に自動更新する仕組みが必要 (ADR-0033 候補)
  2. Status (意思決定) と Implementation Status (実装) の整合性矛盾 → CI でバリデーション追加

観測指標:

  • Implementation Status の更新ラグ: 実装 PR マージから本文更新までの時間、目標 < 1 日
  • 「In Progress」状態の ADR の月次レビュー実施率: 目標 100% (月次 changelog で集計)

Confirmation (準拠確認 / Fitness Function)

本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。

  • 検証手段: scripts/adr-lint.mjs の規約チェック + 手動レビュー
  • 実行頻度: PR ごと
  • 違反時の対応: 自動 fail

参照 (References)

  • 関連 ADR:
    • ADR-0023 (構造業界標準化 / Status フィールド業界標準準拠)
    • ADR-0030 (Kruchten Type 採用) / ADR-0031 (Kruchten Type 運用解釈、遡及追加パターン確立)
    • ADR-0024 (§1/§5 サブ見出し構造)
    • ADR-0027 (Walking Skeleton 計測基盤) / ADR-0028 (全体 6 段ワークフロー) / ADR-0029 (Spec/Impl Pipeline 詳細)
    • ADR-0018 (TODO 管理 / GitHub Issues 移行保留) / ADR-0020 (Triage 根拠)
    • ADR-0033 (将来候補: GitHub Actions による Implementation Status 自動更新)
  • 関連 PR/Issue: PR #663 (ADR-0030 実装、遡及追加パターン参考)
  • 外部資料:
    • Nygard "Documenting Architecture Decisions" (Status 業界標準)
    • MADR (Markdown Any Decision Records) テンプレート
    • Backstage / adr-tools エコシステム