spec 1.0 · 規範

決定

決定記録は、なぜそうしたのかを日付付きで説明する、コンテキストレイヤーの文書です。アーキテクチャ上の決定、ベンダーの選定、適用範囲の境界、意図的に決定しなかったことなどを記録します。議論の蒸し返しを防ぎ、エージェントに規則だけでなく、その理由も伝えます。

決定記録は、正式な記録の下位種です（content-categories.md の「意図と記録」を参照）。本質的に記録であり、一般の記録にはない統一スキーマとライフサイクルを持ちます。生成されたインデックスのエントリには kind: record が含まれます。決定記録自体が kind キーを宣言することはありません（スキーマは閉じているため、明示的な kind は検証に失敗します）。

要件#

決定記録は、decision-record.schema.json に照らして妥当な YAML フロントマターを持つ markdown で、1 ファイルにつき 1 件です。決定のまとまりは、マニフェストが宣言する 2 つのサーフェスの和であり、コンテキストレイヤーはそのどちらか一方でも両方でも使って構いません（MAY）。宣言された記録のパス（machine.decisionRecordsPath、既定は <root>/decisions/）と、decisions カテゴリのインデックスファイルが解決するエントリです。記録は、少なくとも一方から到達できなければなりません（MUST）。
フロントマターは次を持たなければなりません（MUST）。id（安定したもの）、title、status、date。status は proposed、accepted、superseded、deprecated、rejected のいずれかです。
本文は散文で、文脈（どんな状況が決定を迫ったのか）、決定そのもの、そしてその帰結を述べなければなりません（MUST）。推奨される節の見出しは ## Context、## Decision、## Consequences です。記録は ## Alternatives を加えても構いません（MAY）。
記録は追記のみの履歴です。記録を編集して別の決定に作り変えてはなりません（MUST NOT）。決定が年を重ねるにつれて変わりうるフロントマターのフィールドは 2 つ、status（そのライフサイクル）と supersededBy（取って代わられたときに設定されます）だけです。それ以外、すなわち id、当初の title と date、宣言された適用範囲、そして散文の本文は、いったん公開されたら不変です。撤回や変更は、フロントマターに supersedes を設定した新しい記録であり、古い記録の status は superseded になって supersededBy が設定されます。取って代わりのリンクは、双方向で一貫していなければなりません（MUST）。記録 B が supersedes: A を設定したとき、記録 A は status: superseded と supersededBy: B を持ちます。また superseded の記録は、その後継を supersededBy で名指ししなければなりません（MUST）。どちらの記録も残ります。リファレンスのツールは現時点では、この双方向の取って代わりの一貫性を強制します。不変性そのもの（公開済み記録の凍結されたフィールドと本文が、基準となるリビジョンに照らして変わっていないこと）は、まだ検証しません。それは報告として行うチェックとしてロードマップにあり、まだ阻止するゲートではありません。それが出るまで、不変性はプロセスとして申告されるレビューの規律に委ねられます（conformance.md を参照）。
記録は affectedPaths と affectedCategories を宣言しても構いません（MAY）。これによりツールは、作業の適用範囲から、それを統制する決定へ経路を定められます。作業の適用範囲がどのように記録を選ぶか（重なりを踏まえたパスの包含、狭いカテゴリの照合、accepted / deprecated の拘束、そしてどちらも宣言していない記録の組織全体としての扱い）は、machine-readable-surface.md の Task routing のアルゴリズムです。
却下された提案も記録です（status: rejected）。採用しなかった決定を書き残すことは、最も低コストで議論の蒸し返しを防ぐ方法です。

ADR との互換性（非規範的）#

Leji の決定記録は、意図的に Architecture Decision Records と互換性を持たせています。既存の ADR ディレクトリでは、各記録（または今後作成する記録）にフロントマターのフィールドを追加し、マニフェストでそのディレクトリを割り当てれば、decisions の要件を満たせます。ADR ツールは必須ではありませんが、使用を妨げるものでもありません。