Architecture Decision Records (ADR)

本ディレクトリには、bizlp-gas-accounting プロジェクトのアーキテクチャ決定記録（ADR: Architecture Decision Record）を配置する。

目的

ADR は 「なぜその選択をしたか」を未来の自分・他のメンバーに伝える ための記録である。コードの "What" は実装を読めば分かるが、"Why" は後から推測できない。重要な技術的・業務的判断は ADR として残し、将来の判断と一貫性を保つ。

核となる判断軸 (プロジェクト共通)

不確実性を自分の手の届く範囲に閉じ込めるリスクは受容し、不確実性が自分の手の届かない外部に出るリスクは受容しない。

ADR 起案時の判断軸として全 ADR が参照する。詳細は § リスク受容方針 参照。

用語定義 (Glossary)

本リポジトリの ADR / docs に登場する略号・ドメイン用語の定義は docs/architecture/glossary.md を正典 (SSoT) とする (旧: 本節の手書き表。手書き重複だったため DOC-OPS-24 ②で glossary に集約)。新規 ADR 起案時はそちらを参照し、ADR 内では用語の定義を繰り返さない (DRY 原則)。新語はまず glossary に追加する (検証: node scripts/adr-lint.mjs --check-terminology)。

リスク受容方針 (プロジェクト共通の判断軸)

本リポジトリの全 ADR の起案時にこの判断軸を適用する。新規 ADR で個別に再定義せず、本セクションを参照する。

判断軸を一文に集約:

不確実性を自分の手の届く範囲に閉じ込めるリスクは受容し、不確実性が自分の手の届かない外部に出るリスクは受容しない。

受容するリスク (共通点: 後から自分の裁量で技術的に回収できる)

• DDL・データ構造のリファクタが後払いで発生する — スプレッドシート列追加・既存列のリネーム・新規シート分割は、リリース後に PR で技術的に対処可能。setupAllSchemas の再実行 + マイグレーション関数で巻き戻し可能。
• 部分完成状態が本番に常在する — Feature Flag (PropertiesService) でユーザから隠蔽可能、フラグ ON で一括公開する制御権を握っている。
• E2E テストの不安定さ・遅さ — テスト構造の改善は手元のコードで進められる。flaky テストの隔離・並列化・モック化はすべて自分の判断で実施可能。
• 命名規則ドリフト — CI Lint で自動検知可能。検知できれば手動修正で復旧可能、ドリフトが進行する前に発見できる構造で許容。
• 採用パラダイムのレガシー化 — 半年ごとの ADR 再読 + 必要時のリファクタ PR で回収可能。
• GAS トランザクション不在による Orphan データ — GAS に RDBMS 的なトランザクションがないため部分障害で「監査ログのない業務データ」が発生し得る。Fail-Open + 日次突合バッチで受容。
• シートオーナーによる強制改ざん — シートオーナー権限による行削除・改ざんは GAS 境界内で技術的に防げないため受容。抑止力は Google Workspace アクティビティログ + 監査人による定期レビュー。

受容しないリスク (共通点: 後から自分では直せない制度的・外部的リスク)

• 監査トレーサビリティの欠如 — 「監査ログがない / 改ざん可能 / 過去操作の追跡不能」状態を一度でも作ると、指摘を受けた事実そのものが外部 (監査人・税理士・規制当局) に記録される。技術的に修正しても「過去にそういう運用をしていた」事実は消せない。
• 外部ツールへのロックイン — Linear / Notion / Jira 等への移行は、移行先のスキーマ・ID 体系・API 仕様への依存が発生する。戻れない意思決定であり、移行後に Markdown へ戻すには再度データ変換と運用ルール再構築が必要。
• 既存 ADR との非互換 — 過去決定を SUPERSEDE すると、当時の判断文脈ごと失われる。新 ADR が既存決定を拡張として位置付けられる場合は SUPERSEDE せず拡張で扱う。
• 「全体設計が正しい」前提への依存 — 「すべてを正しく分類し優先度を確定してから着手」は 1 人開発では達成不可能であり、達成したと信じて進めた場合に途中で前提が崩れたら全分類のやり直しになる。Walking Skeleton で「思い込みを形成する前に実地で確認」を構造的に強制する。

この方針が個別 ADR にどう効くか (適用例)

• 進捗管理ツール = Markdown 維持 (Linear / Notion 移行を回避) → 外部ロックインを受容しない (ADR-0021)
• Walking Skeleton 必須要素に監査ログ機構 → 監査トレーサビリティ欠如を受容しない (ADR-0021)
• ADR-0018 を SUPERSEDE せず拡張 → 過去 ADR との非互換を受容しない (ADR-0021)
• DDL は後払いで OK / 部分完成は Feature Flag で隠蔽 / slice_id ドリフトは CI 検知 → 自分の裁量で回収可能なリスクは受容 (ADR-0021)

命名規則 (ADR-0023 で業界標準に整備)

docs/adr/NNNN-slug.md

• NNNN — 4 桁 ゼロパディングの連番（0000 〜 9999）
• 区切り文字 — ハイフン (-) でケバブケース
• slug — 小文字英数字 + ハイフンのみ (20 字以内推奨)、新規 ADR は動詞形を推奨 (use-X, adopt-Y, migrate-Z)
• 例: 0010-modular-monolith-numbering.md / 0023-standardize-adr-structure-nygard-madr-minimal.md

タイトルは # ADR-NNNN: タイトル要旨 とし、リンク参照時は ADR-NNNN 表記で統一する。

業界標準への準拠

本命名規則は Michael Nygard / MADR 4.0 / adr-tools / Backstage / GOV.UK 等の業界標準に準拠 (ADR-0023 で採用、RQ-041 並列調査根拠)。新規参加者が外部の ADR 解説記事と本プロジェクトの慣習を一致させて学習できる。

特殊な番号

• ADR-0000 (0000-record-architecture-decisions.md): メタ ADR (「ADR を採用する決定そのもの」)。Backstage / Kubernetes KEP の予約番号慣例
• ADR-0001〜0022: ADR-0023 マージ時に 3 桁旧形式 (NNN_*.md) から 4 桁新形式 (NNNN-*.md) へ一括 renaming 済

履歴

• ADR-0001〜0018 は手動作成 (旧 3 桁形式で運用)
• ADR-0019 で Decision Pipeline は LangGraph TS + Hono on Cloudflare Workers + adr-kit へ移行決定 (Dify 退役)
• ADR-0022 で Policy Alignment ノード追加 (会社方針適合評価ゲート)
• ADR-0023 で命名規則を業界標準化 + 既存 22 ADR を一括 renaming + メタ ADR 0000 新設 + テンプレート位置を templates/template.md に移動

ADR-0023 移行マッピング表 (旧形式 → 新形式)

PR #633/#636 で実施した一括 renaming の対応表。過去 PR / Issue / 外部参照で旧パスを使っている場合の参照用 (Gemini Parallel Review 指摘対応):

変換ロジック:

1. 番号の頭に 0 を追加 (3 桁 → 4 桁、例: 010 → 0010)
2. アンダースコア (_) を全てハイフン (-) に変換
3. ファイル名以外は不変 (タイトル / 内容 / Status / 日時)

git mv で実施したため Git 履歴の連続性は保持。git log --follow docs/adr/0010-modular-monolith-numbering.md で旧形式時代の履歴も追える。

ADR-0023 採用判断時の不採用記録 (Parallel Review 補足)

ADR-0023 起案時に検討されたが不採用となった代替案・補足:

不採用案 D: 段階移行 (新規のみ先行 → 1 ヶ月運用 → 既存移行)

Policy Alignment / Gemini Parallel Review で提案されたが、本リポジトリでは案 A (全件 renaming) を即時実施して不採用。

理由:

• bizlp 規模 (23 ADR) では段階移行のメリット (リスク分散) より、二重採番期間 (3 桁旧 + 4 桁新) の混乱コストの方が大きい
• git mv + Python ワンライナーで 1.5 時間で完了したため、段階分割の事務コストが本作業を上回る
• 影響範囲計測 (PR #636) で過去 PR 内参照 269 件を可視化済、リスクが想定内に収まることを事前確認

不採用: 既存 ADR タイトルの動詞形化

Gemini Parallel Review で提案されたが不採用。理由:

• 既存 ADR 22 本の名詞ベースタイトル (例: modular-monolith-numbering) を動詞形 (use-modular-monolith-numbering) に変えても、本質的な情報は増えない
• タイトル変更は Git 履歴の連続性は保持できるが、外部参照 (PR descriptions / commit messages) の検索性を分断するデメリットが大きい
• 新規 ADR-0024 以降のみ動詞形を推奨 (§命名規則の通り) で十分

未実施: Decision Pipeline 採番のハイフン形式動作確認 (ADR-0023 DoD #7)

次回 ADR 起案時に実地で確認する。動作不良時の対応:

1. drp/src/nodes/slug.ts または numbering.ts の slug 生成ロジックを修正
2. 新形式 (4 桁ハイフン) で再起案

これは ADR-0023 の決定撤退ではなく、Pipeline 側の小規模修正で対応する想定。

Status 遷移

起案フロー（移行期: 2026-05-08〜）

ADR-0019 で Decision Pipeline の刷新が決定した。Dify Phase 1 (Triage v0.2 / Scoring v0.1) は 退役確定、Phase 2a (GitHub PR 自動生成) は 未着手のまま LangGraph 実装に置換 する。並行稼働期間はない。

現状（LangGraph 実装着手まで）

[起案者]
   ↓ docs/adr/templates/template.md をコピーして手動起草
[起案者]
   ├─ NNNN を採番（既存連番 + 1、4 桁）
   ├─ slug を kebab-case で命名 (動詞形推奨)
   └─ Status: Proposed で PR 作成
   ↓
[オーナー（代表取締役）]
   レビュー → マージ（Status を Accepted へ手動更新）

補助ツール: DRP 操作手順の正典は .claude/skills/drp-ops/SKILL.md（リポスコープ Skill / ADR-0115 適用第 1 号）。lint は自製 scripts/adr-lint.mjs（ADR-0038）。かつて導入予定とされた adr-kit (rvdbreemen/adr-kit) は未導入で実体が存在せず（2026-06-04 実査・ユーザースコープにも無し）、参照を本 Skill へ付け替えた — リポ内文書からユーザースコープ資産への参照は禁止（ADR-0115 決定 2 / agent_knowledge_layers.md）。

将来（LangGraph 実装後）

[起案者]
   ↓ Web UI (Hono on Cloudflare Workers) に投入
[Decision Pipeline (LangGraph TS)]
   ├─ Triage / Scoring / 本文生成 / Slug 生成 各 node
   └─ LiteLLM Gateway (GCP Cloud Run) 経由で GPT / Gemini / Claude をノード単位切替
   ↓ Webhook
[GitHub Actions]
   └─ NNNN-slug.md を生成し PR 作成（Status: Proposed）
   ↓
[adr-lint (CI)] → [オーナーレビュー] → マージ時に GitHub Actions が Status: Accepted へ自動更新

実装手順: ../_internal/03_decisions/decision_pipeline/langgraph_migration/main_workspace_checklist.md 退役対象 Dify 系設計書の処遇: ../_internal/03_decisions/decision_pipeline/langgraph_migration/migration_overview.md

テンプレート

新規 ADR は templates/template.md をベースに作成する (ADR-0023 で _template.md → templates/template.md へ移動)。adr-kit の canonical-seven-section テンプレへの移行は採用しない。

主要セクション (Nygard + MADR 4.0 ミニマル統合):

• §1 コンテキスト — 何を解決するか、なぜ今か (現状 / 課題 / 要求 / 前提条件 / 制約条件)
• §2 判断基準 (Decision Drivers) — 何を最適化すれば良い決定と言えるかの評価軸
• §3 検討した代替案 (Considered Options) — 最低 2 つ、各案を Good, because ... / Bad, because ... で評価
• §4 決定 (Decision Outcome) — 採用方針 + 一文の本質的根拠
• §5 影響 (Consequences) — ポジティブ・ネガティブ・ニュートラルすべて、Bad, because ... は必ず 1 行
• §6 撤退条件 / 再評価トリガー (More Information) — 前提が変わったら見直す条件
• §7 参照 — 関連 ADR / PR / RQ / 外部資料

書くべき / 書かなくていい判断基準

ADR は**「6〜12 ヶ月後にもう一度議論しそうな決定」**だけを記録する。それ以外はコメント or README or 設計メモで十分 (ADR の冗長化 = Decision Documentation Theater 回避)。

書くべき決定 (典型例)

• データストア選定 (Sheets / PropertiesService / CacheService / 外部 DB)
• 認証・権限モデル (OAuth scope / Service Account)
• パフォーマンス対応 (6 分制限への分割 / Trigger 設計)
• セキュリティ方針 (シークレット管理 / 入力検証 / 監査ログ)
• データモデル・スキーマの根本設計
• コーディング規約・命名規約 (ADR-0010 数値プレフィックス / ADR-0011 ヘッダー名ベース列参照 等)
• リトライ・エラー処理・冪等性の方針 (ADR-0012)
• 外部 API 連携方式
• 開発プロセス・組織化パラダイム (ADR-0021)

書かなくていい決定 (典型例)

• 単一関数のリファクタ
• 変数名の選択
• 明らかにそれしかない選択肢
• 実験的な PoC
• 公式ドキュメントに従うだけの設定

簡便なルール

「将来の開発者に Why を伝えたい場面なら ADR、そうでないならスキップ」 — Joel Parker Henderson

粒度の判断基準（1 ADR にまとめるか分割するか）

1 つの決定として起案するか複数に分割するかは、「将来どの単位で覆るか」 で判断する。

一問判定:

「半年後にこの決定を覆すとき、別の ADR で supersede する必要があるか？」— Yes なら ADR、No なら conventions.md か runbook。

「whether と what は 1 ADR にまとめてよい」: 両者が論理的に結合している場合は分割しない（例: リファクタリングするかどうかは、何を採用するかを決めずには答えられない）。一方、構造（何を）と移行戦略（どう進めるか）は後者だけ変わりうるため別 ADR にする。

アンチパターン警告 (Olaf Zimmermann)

ADR が形骸化しないために、起案時に以下を自己チェック:

詳細チェックリストは templates/template.md の「起案前チェックリスト」を参照。

イミュータブル原則

業界標準 (Nygard / Log4brains): Accepted になったら本文を編集しない。決定が変わったら新しい ADR を作って古い方を Superseded by ADR-NNNN とマークする。

例外 (個人開発で許容):

• 誤字・リンク切れ修正は Git コミットで履歴を残せば OK
• 決定そのものの変更だけ Supersede で新規起案

Mode の使い分け（Triage v0.2 準拠）

Mode 別の §1 / §5 構造粒度 (ADR-0024 で正式採用)

ADR テンプレートの §1 コンテキスト / §5 影響セクションを Mode によってサブ見出しの粒度を変える:

§1 / §5 サブ見出し運用ルール 3 件 (ADR-0024 で正式採用)

1. 1〜2 文ルール: 各サブ項目の本文は 1〜2 文を目安。Critical Mode は柔軟性を優先し 1〜2 段落まで許容。3 文以上に膨張する場合は別 ADR への分割を検討 (Mega-ADR / Blueprint in Disguise アンチパターン回避)
2. 該当なし削除ルール: 該当なしの項目はサブ見出しごと削除する。「該当なし」と本文に書いたり、空欄のまま見出しを残すのは禁止 (思考停止のサインになり、Blueprint in Disguise 化を招く)
3. 歯抜け番号許容ルール: §1.1 → §1.3 → §1.5 のように番号が歯抜けになっても番号は前詰めしない。歯抜け自体が「この項目について判断した結果削除した」という記録として機能する

既存 ADR との 3 層併存 (注意)

ADR-0024 採用後、既存 ADR は以下の 3 層が併存する (イミュータブル原則により遡及修正しない):

• ADR-0001〜0020: 単一節 (旧形式)
• ADR-0021: §1.1〜§1.6 構造 (先行事例、Initial Master ADR 相当)
• ADR-0024 以降: §1.1〜§1.5 / §5.1〜§5.3 (本ガイド準拠)

2026-10 入社予定の Jr エンジニア / 副業協力者 / 業務委託エンジニアへのオンボーディング時は、この経緯を口頭または別途のドキュメントで補足することを推奨。

Kruchten 3 分類ガイド (ADR-0030 で採用)

ADR の 主題索引として Philippe Kruchten (2004) "An Ontology of Architectural Design Decisions in Software-Intensive Systems" の 3 分類を採用。Mode (規模軸) と直交し、組み合わせで立体検索可能 (例: grep "Mode.*Critical" AND grep "Kruchten.*Executive" で Critical な技術選定 ADR を網羅)。

3 分類の定義

学術用語の取り扱い (ADR-0030 §決定): 日常運用は英語 3 用語 (Existence / Property / Executive) のみ。ギリシャ語原語は本ガイドの語源説明と外部資料リンクのみで言及し、メタデータ欄・検索クエリでは使わない (認知負荷低減)。

判定チェックリスト

排他的フローではなく、Q1-Q3 を独立判定して 1-3 個のラベルを付与:

• Q1: その決定は新しい要素 (コンポーネント・データ構造・モジュール) を導入するか? → YES なら Existence
• Q2: その決定は複数の対象に適用される横断ルール・規約・制約を定めるか? → YES なら Property
• Q3: その決定は技術・ライブラリ・プラットフォーム・プロセスを選定するか? → YES なら Executive
• すべて NO の場合 → ADR 対象外の運用変更の可能性 (Triage で再確認)

複数該当時のガイダンス

1 つの ADR が 2-3 分類に該当する例: 「OAuth 採用」= Executive (規格選定) + Existence (認可サーバー配置) + Property (Bearer トークン認証ルール)。この場合は §5.1 (Existence 影響) / §5.2 (Property 影響) / §5.3 (Executive 影響) で分解記述する。「とりあえず全部該当」を避けるため、Pipeline scoring node で 3 該当時は §5.1/§5.2/§5.3 全節記述を必須化。

Pipeline 3 LLM ラベル不一致時の単純裁定ルール (ADR-0030 §決定)

Consistency Gate に新ノードは追加せず、優先順位で 1 ラベルを自動採用:

1. 起案者が input に明示した Kruchten Type があればそれを最終採用 (起案者裁量優先)
2. 起案者明示なしで Pipeline body_generation が生成した場合、3 LLM (Gemini/Claude/GPT-4o) の Parallel Review で過半数 (2/3 以上) が一致したラベルを採用
3. 過半数不一致 (3 LLM が全て異なるラベルを提案) の場合、起案者に Slack 通知して手動裁定を促す (Pipeline は INFO で通過させる)

Implementation Status ガイド (ADR-0032 で採用)

ADR の 実装ライフサイクルを表すメタデータ。Status (意思決定ライフサイクル: Proposed/Accepted/Rejected/Superseded) と直交する別軸。

値定義

更新運用

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

検索ユースケース

• grep "Implementation Status.*In Progress" docs/adr/00*-*.md — 現在実装中の ADR 一覧
• grep "Implementation Status.*Reverted" docs/adr/00*-*.md — リバート済 ADR
• grep "Implementation Status.*Not Started" docs/adr/00*-*.md — 実装着手前 ADR (放置リスク監視)

impl_detail 節で詳細を分離する (ADR-0162 で採用)

実装が段階的で進捗を詳しく書きたい ADR は、本文太字メタ欄の Implementation Status を短縮形 (6 値のいずれか) に保ち、詳細を専用の ## 実装状況詳細 (impl_detail) 節へ分離する。INDEX.md の「Impl状況詳細」列はこの節の内容を派生ビューとして掲載するため、本文と派生索引の二重管理を機械的に防げる。

使う条件 (推奨): implementation_status の追加情報部分 (例: In Progress (PR #1703 = 辺語彙... 残: ...)) が 100 文字を超える、または 段階的実装 (Phase 1/2 等) を伴う ADR。

マーカー仕様 (PR #2026 試行・ADR-0162 で正式化):

- **Implementation Status**: In Progress

## 実装状況詳細 (impl_detail)

<!-- impl_detail:start 派生・非規範: ADR本文ではない / 後から差し替え可 -->
> Phase 1 Done: PR #NNNN
> 残: Phase 2
<!-- impl_detail:end -->

ルール (機械担保):

• 節を持つ ADR の implementation_status は 6 値のいずれかに完全一致 (adr-lint impl-detail-implies-short-status が error で検査)
• adr-lint の本文構造検査 (必須 H2 等) は impl_detail 節を本文外として扱いスキップ (false positive 0)
• コンテンツ品質検査 (リンク切れ・用語統一) は impl_detail 節も対象 (2 段階スキップ方針)
• 節は 任意。使わない ADR は従来通り implementation_status の括弧部分に詳細を書ける

既存 ADR 一覧

全 ADR の一覧は INDEX.md (自動生成索引・ADR-0107 / ADR-0130) を参照。node scripts/adr-index.mjs が全 ADR の太字メタ欄から生成し、機械可読の元データは adr-index.json。旧: 本節の手書き表 (31 本で停止・実体と乖離) — 旧形式 ADR (0001〜0018) の Mode 推定値は git 履歴 (本節を置換した PR の親コミットまでの手書き表) に残り、メタデータバックフィル (ADR-0031 経路) で各 ADR 本文へ移す。新規 ADR は ADR-0019 形式 (- **Status**: ... / **Mode**: ... メタデータブロック) で起案する。

関連ドキュメント

現行（ADR-0019 移行設計）

• LangGraph 移行 — main session 実装手順書
• LangGraph 移行 — Dify 既存設計書の処遇対応表
• adr-kit セットアップ素材 (bizlink-domain.md / langgraph-adrkit-boundary.md / migration_mapping.md)
• RQ-038 調査レポート

退役対象（履歴として残置）

• Decision Pipeline 全体像 (Dify 前提)
• Phase 2a 設計書 (Dify 前提)
• プロンプト検証用テストケース集 (Dify 前提)
• 起案者向け運用ルール (Dify 前提)

退役対象 docs への退役マーク追加は main session で実施予定（ADR-0019 起案 changelog 記録参照）。

Confirmation セクション (ADR-0036)

ADR-0036 (Accepted 2026-05-14) により、全 ADR に ## Confirmation (準拠確認 / Fitness Function) セクションが必須化された。

3 要素 (fitness function の構成)

1. 検証手段: 具体的なツール / コマンド / テスト名を 1 行で明示
2. 実行頻度: PR ごと / Nightly (日次バッチ) / 月次 / 四半期 / 起案時のみ
3. 違反時の対応: 自動 fail / Slack 通知 / 月次レビューで集計

検証手段マッピング (既存 ADR 遡及用)

ADR-0031 解釈拡張の準拠根拠

ADR-0036 で既存 36 ADR への Confirmation セクション遡及追加を実施するが、これは ADR-0031 で確立した「業界標準準拠メタデータ後付け = 誤字修正範疇」の運用解釈に準拠する:

• Confirmation セクションは ADR の decision そのもの ではなく、継続検証メカニズムへのポインタ (どの CI / lint / test で守られているか)
• ADR-0030 (Kruchten 分類)・ADR-0031 (遡及追加許可)・ADR-0032 (Implementation Status) で確立した「業界標準準拠 metadata 後付け」と同性質
• これに同意できない場合は誤字修正範疇とせず、「ADR-0036 で全 36 ADR を Superseded by ADR-0036」とする別解釈を取る (議論があれば別 ADR で起案)

形骸化対策 (Rollback 補助)

• 月次サンプリングで「scripts/adr-lint.mjs と書くだけで実検証が動かない」ADR の検出
• 形骸化 30% 超時の補助対応: テンプレから Confirmation 必須化を解除し推奨化に縮退 (Light Mode + 純ドキュメント ADR は省略可)、Standard / Critical Mode は必須維持