decision-records

決定記録

このスキルはレジストリツール decisions.py を管理しており、リポジトリ内の scripts/decisions.py にシンボリックリンクされています （decisions.py install を実行すると、シンボリックリンクと CI チェックが設定されます）。このツールは CWD から上位ディレクトリをたどってリポジトリの docs/ を見つけるため、リポジトリ内のどこからでも実行できます。

python scripts/decisions.py build [--relink]            # regenerate INDEX.md (+ refresh links)
python scripts/decisions.py check                       # validate (CI-safe; exit 1 if stale)
python scripts/decisions.py promote <name…> [--deref] [--allow-replace]   # draft(s) -> accepted/
python scripts/decisions.py rename-draft-id <name> <NEW>                  # re-ID a draft
python scripts/decisions.py migrate-layout              # one-shot: old accepted/<type>/ -> flat
python scripts/decisions.py install [repo]              # adopt in a repo: symlink + pre-commit

ディレクトリ構成

この規約が管理するすべてのものは docs/decisions/ の下にあります。

docs/
  decisions/              # the convention's namespace (the umbrella)
    INDEX.md              # GENERATED registry over accepted/ + archived/
    README.md             # human guide to the convention (scaffolded by install)
    AGENTS.md             # agent rules: decisions are binding here (scaffolded by install)
    accepted/             # ACCEPTED numbered records — flat; `type` lives in front-matter
    archived/             # RETIRED records (superseded | deprecated) — flat
    drafts/               # WIP candidates — flat, 4-UPPERCASE-letter IDs, NOT in INDEX
  threat-model.md         # other repo docs stay siblings — still cross-reference decisions

ステージ	ディレクトリ	ID	ステータス
候補（WIP）	drafts/	ニーモニック形式の大文字4文字（CONF）	draft
決定	accepted/	グローバルカウンター（0001…）	accepted
廃止	archived/	（カウンターを維持）	superseded / deprecated

タイプは固定されていません — type には任意の小文字のスラッグを指定できます（ソフトウェア：architecture、product、security；ガバナンス：policy、legal、finance、people、compliance、operations）。これはフロントマターのみに記載し、ライフサイクルディレクトリはすべてフラットにします。使用されるタイプは、承認済みの記録に含まれるものがすべてで、INDEX はタイプ別にグループ化します。旧式の accepted/<type>/ レイアウトを使用しているリポジトリでは、python scripts/decisions.py migrate-layout を一度実行してください。ファイル名（識別子）は移動後も維持されるため、最後に実行する build --relink がすべての参照を自動修復します。また、入れ子になった記録が見つかった場合、check はこの項目を案内します。

proposed ステータスはありません。「提案する」とは、ドラフトを昇格させる PR を作成することです。ドラフト ID は自分で付与してください（トピックを表すニーモニックを使用します）。check が形式と一意性を検証します。相互参照には、単独の ID をインラインコードとして記述します（決定の場合は `0006`、ドラフトの場合は `CONF`）。パスを手動で記述してはいけません。build --relink がすべての docs/*.md（記録、ドラフト、threat-model.md などのその他のドキュメント）にわたるリンクを生成し、自動修復します。

origin/main との ID の衝突は警告されますが、処理はブロックされません。 一意性は単一のツリーに対して検証されるため、2 つのブランチがそれぞれ 0044 を付与しても、両者が合流するまではどちらも問題なく通ります。そのため check は、ディスク上にある origin/main も読み取り、そこで異なるファイルに同じ ID が付いている場合は、次に使用可能なカウンターとともに WARN 行を出力します。フェッチは行わず、実行を失敗させることもありません。また、その参照が存在しない場合は何も出力しません。新規クローンやオフラインのマシンは問題として報告されません。

promote は origin/main が保持している番号より先の番号を付与します。 ID の付与は書き込みを伴います。つまり、記録の名前を変更し、H1 を書き換え、すべての被リンクのパスを変更します。そのため promote は、後から状況を報告するのではなく、参照を読み取り、飛び越えたカウンターを出力します。そこで生じる空き番号は欠番ではありません。check は origin/main が保持するカウンターを未使用ではなく使用済みとして扱い、リベースによって番号の連続性が回復します。どちらのツリーにも存在しない番号は引き続き失敗となり、ディスク上に参照がない場合は、どちらも以前とまったく同じように動作します。

廃止された記録への引用は警告されますが、処理はブロックされません。 記録は後継の記録によって廃止されますが、これまでは、その記録を引用しているドキュメントを再確認する仕組みはありませんでした。そのため、0019 に置き換えられた後も、0007 に依拠するルールブックはそのままでした。check（および build）は、現行のドキュメントにある該当する引用ごとに、後継の記録を示す WARN を出力します。言及が意図的に歴史的なものの場合もあるため、実行を失敗させません。アーカイブされた記録は変更されない履歴であり、任意の記録を引用できます。また、古い記録に取って代わる記録が、当然ながら古い記録を示すこともあります。

作成

drafts/_template.md、これが唯一のテンプレートです。記録は下書きとして作成され、accepted/ に入る唯一の方法は promote です。これはカウンターを割り当て、ステータスを切り替え、H1を書き換えます。そのため、承認済み記録用テンプレートを用意しても、承認プロセスを迂回する手段が増えるだけです。

議論ではなく、判断を記してください。

• 言い直すのではなく、引用してください。 議論全体はリンク先のスレッド、メモ、ログにあります。記録には判断、その時点での根拠、そして「参照」に記載する参照先を含めます。
• 書くことがないセクションは削除してください。 判断を繰り返す「根拠」、論拠のない代替案の表、内容を水増しした結果の一覧は、削除するほうが適切です。テンプレートでは削除可能なセクションを示しています。check も同じ印を読み取ります。テンプレートで削除可能とされていないセクションが下書きから欠けている場合は、検査に失敗します。スクリプトによる編集でセクション全体が消えると、ほかに痕跡が残らないためです。テンプレートはリポジトリごとにコピーして使うものなので、印を移動するのは各自の判断です。
• すべての文に役割を持たせてください。 事実を述べる簡潔な一文は、事実を演出する段落に勝ります。ひとつの言葉の工夫は語り口になりますが、各段落にひとつずつあれば、わざとらしく見えます。
• ひとつの記録につき、ひとつの判断にしてください。 増え続ける記録は、たいてい複数の判断がひとつのファイルを共有しています。分割してください。

意図的に長さの規則は設けていません。純粋な判断の記録は数十行で収まることがよくありますが、仕様も兼ねる記録は、リポジトリによっては、承認済み記録がそのままリリース内容の仕様となるため、数百行になることも正当です。長さは見極めるための兆候であって、取り締まるための数値ではありません。上記の箇条書きが取り除くのは、どのような長さでも現れる水増しです。

下書きの承認

承認には、人間による明示的な承認が必要です。 承認は最終確定にあたる半ば不可逆な操作です（承認済み記録は確定された状態に保たれます。方針を変更するには、書き換えではなく後継記録が必要です。ただし、明確さ、古さ、記録間の一貫性に関する、判断者が承認した保守編集は認められます）。下書きの作成、編集、検証は自由に行えますが、このターンでユーザーから明示的な許可を得るまでは、promote も、その後続処理（命名用プレースホルダーの置換、スレッドの解決、INDEX.md の再生成）も決して実行しないでください。隣接する選択（スコープに関する回答、チェックリストの完了）から承認を推測しないでください。判断に迷う場合は、質問してください。

承認済みの判断は、下書きを参照してはなりません。 promote はこれを強制します。違反する記録セットは拒否し、修正方法（同時承認、--deref、または --allow-replace）と、コピーして貼り付けられるプロンプトを正確に表示します。承認を行う前、または後継記録を作成する前に、ツールが拒否した場合の対応も含め、仕組みについて references/promotion.md を確認してください。

承認時には記録の ID とディレクトリの両方が変わり、promote はツリー全体でそれらを反映します。対象はH1、相対リンクすべて（drafts/ と accepted/ は同じ階層にあります）、本文中の略称、下書きファイルへの明記されたパスです。docs/ で処理を止め、コードは編集しません。4文字の略称は識別子としても読めます。docs/ 外の記載箇所は実行後に一覧表示されるので、手作業で対応してください。名前が同じというだけの識別子は変更しないでください。コミット時に mdformat が書き換えられた段落を再整形します。

リポジトリへの導入

対象リポジトリで、このスキルの decisions.py install [repo] を実行します（repo のデフォルトは現在のディレクトリです。install はその場所にセットアップし、親ディレクトリを検索しません）。このコマンドは冪等で、不足しているものだけを補い、INDEX.md を再生成します。実行内容は次のとおりです。

• <repo>/scripts/decisions.py をこのスキルのコピーへのシンボリックリンクにし、そのパスを gitignore に追加します（.gitignore がない場合は作成します）。シンボリックリンクはマシン固有のため、コミットするのではなく、各クローンで install を実行して再作成します。
• docs/decisions/ をひな形から作成します。accepted/、archived/、テンプレートを含む drafts/（テンプレートはこれだけです）、人間向けの README.md、エージェント向けの AGENTS.md が含まれます。
• INDEX.md を生成します（これはビルド成果物であり、ひな形ではありません）。
• ルートのエントリーポイントを設定します。リポジトリにルートの README.md または AGENTS.md がない場合（新規または空のリポジトリ）は、それぞれひな形へのリンクを含むプレースホルダーを作成し、ユーザーやエージェントが見つけられるようにします。既存のファイルには手を加えません（以下を参照してください）。
• git リポジトリでは、decisions.py check を実行する pre-commit フックを追加します。CI でも同じコマンドを実行してください。

リポジトリにこれらのエントリーポイントがすでにある場合、install は変更しません。ユーザーやエージェントがひな形を見つけられるよう、以下を自分で設定してください。

• ひな形として作成された docs/decisions/README.md を、リポジトリのコントリビューター向けドキュメント（CONTRIBUTING.md、またはコントリビューター向けの内容がある場合に限り README.md。ユーザー向けの README は対象外）からリンクし、採用済みの決定事項を参照できるよう、コントリビューターを docs/decisions/INDEX.md に案内します。
• リポジトリのルートにある AGENTS.md／CLAUDE.md から docs/decisions/AGENTS.md をリンクし、このリポジトリでは決定事項が拘束力を持つことをエージェントが把握できるようにします。

各リンクには、それが何を示すものかを説明する1行の注記を添えてください。