adr-authoring

ADR の作成

設計上の根拠を記録するためのアーキテクチャ決定記録（ADR）です。ADR は、構造のみを示すビュー（C4）では捉えられない時間的な側面、つまり時間の経過に伴う決定を補います。

リポジトリの規約から始める

1. 作成に取りかかる前に、リポジトリのエージェント向け指示、コントリビューションガイド、ADR インデックス、テンプレート、および最近の記録をいくつか読みます。既存の配置場所、番号付け、見出し、ステータスの用語、承認プロセス、改訂方針を踏襲します。
2. このスキルのレイアウトやテンプレートは、あくまで代替案として扱います。このスキルに合わせるために、既存の ADR を移動、採番し直し、改名、書き換えしないでください。ローカルの規約と異なる場合は、既存の記録を維持し、規約を変更する前に具体的な相違点を明らかにします。
3. 規約がない場合は、フラットな docs/adr/ ディレクトリ、変更されない連番の識別子、小規模なインデックス、および簡潔な Nygard テンプレートを使用します（選択肢の分析により詳しい構成が必要な場合は MADR を使用します）。新しい決定ログを作成する場合に限り、references/project-setup-guide.md を読みます。
4. プロジェクトですでにアーティファクトピラミッドを使用している場合、またはユーザーがその構成を求めている場合に限り、references/adr-to-pyramid-mapping.md を読みます。インデックスのリンクで、正式な記録を移動せずに階層的なナビゲーションを提供できます。

決定、承認、証拠

リポジトリに既存のフィールドやリンクされた記録があれば、それらを使って次の 3 つの事実を区別します。

• 提案： 推奨事項、その理由、代替案、結果、および未解決の質問です。草案や推奨事項は、承認された決定ではありません。
• 決定権者と適用範囲： 誰が、いつ、どの環境または段階について何を承認したかです。実験の承認は、範囲を限定した実験を許可するものです。本番環境への導入を承認するものではありません。適用範囲が明記されていれば、承認済みの ADR が許可するのは実験のみの場合もあります。決定権者、日付、またはより広い範囲の承認を捏造しないでください。
• 実装の証拠： 変更、チェック、観測された結果、および残る課題へのリンクです。承認されたことは実装の証明にはなりません。プロトタイプのチェックに合格したことも、本番環境に対応できる証明にはなりません。結果が出るまでは、検証計画を「計画中」と明記します。

たとえば、「隔離したデータベース試行を承認した」という事実が裏付けるのは、試行に限定した決定です。復元リハーサルの成功は、テストした復旧シナリオの証拠になります。どちらの事実も、それだけでは「データベースを本番環境に導入した」ことを意味しません。

ADR のライフサイクル

ローカルのライフサイクルと改訂ルールを使用します。定められていない場合は、proposed → accepted | rejected とし、承認済みの決定は後に、リンクされた後継 ADR によって deprecated または superseded になります。

承認済みの根拠を維持します。原則として、決定を変更する場合は新しい ADR を作成します。古い記録の識別子と配置場所を維持したまま、ステータスと後継へのリンクを更新します。リポジトリで更新型ドキュメントを使用している場合は、その方針に従って、日付と変更者を明記した改訂を行います。変更不可のログに変更可能性を持ち込んだり、更新型ドキュメントのプロセスを変更不可のものに置き換えたりしないでください。

却下と置き換えの理由を記録し、インデックスを維持してリンクを保持します。形式や会議の長さはチームのプロセスに従います。承認に必要なのは、該当する決定権者による決定の証拠であり、必須の儀式ではありません。

テンプレートの選択

まずリポジトリのテンプレートを使用します。この表は、既定のテンプレートがない場合にのみ適用されます。

場合	テンプレート	セクション
迅速な決定、根拠が 1 つ	Nygard	ステータス、背景、決定、結果
複数案のトレードオフ分析	MADR	決定要因、検討した選択肢、メリット／デメリット、リンク
重大な影響、規制、コンプライアンス	Tyree & Akerman	12 のセクション：課題、立場、論拠、影響など
ベンダー／調達の決定	Business Case	評価基準、コスト／SWOT、推奨事項
QA／契約主導の環境	Planguage	タグ、要旨、優先度、ステークホルダー、リスク

各セクションの詳しいガイダンスを含む完全なカタログは、references/adr-format.md にあります。

ファイル命名規則

まずローカルの規則に従います。新しいログには、現在形の命令形の動詞句を使い、小文字とハイフンで構成し、拡張子に .md を付けます。

001-choose-database.md
002-format-timestamps.md
003-manage-secrets.md

ステータスはファイル名ではなくドキュメントのヘッダーに記載します。ステータスが変わっても、名前を変更する必要はありません。

チームワークとガバナンス

• 作成できる人： ADR プロセスのドキュメントを読んだチームメンバーなら誰でも作成できます
• 正当化される内容： 将来の「なぜ」に影響する決定、チーム間の調整、長期的な保守性、外部インターフェース
• 通常、該当しない内容： すでに標準で定められている定型的な変更。権限、制約、または影響について、永続的に残す根拠が必要な場合は、範囲を限定した実験を記録します。
• ADR ごとの役割： 主担当者、副担当者、責任を負うチーム
• 改訂： リポジトリのポリシーに従い、決定の履歴を保持し、新たな証拠と決定の変更を区別します。

ガバナンスモデル全体とチームワークに関する質問については、references/adr-format.md を参照してください。

適合性関数による確認

適用対象： ADR に、コード、設定、実行時テレメトリ、定期監査、または範囲を限定した人によるレビューで検証できる主張が含まれる場合に使用します。

references/fitness-functions.md を読み、関数の範囲、頻度、証拠、しきい値、担当者、例外処理、廃止ルールを選択します。運用記録には templates/fitness-function-record.md を使用します。永続的な決定と確認へのリンクは ADR に保持し、実装と実行はプロジェクトのテスト、CI、テレメトリ、またはガバナンスのシステムで管理します。

完了条件と境界

依頼された ADR またはレビューがローカルの規則に従い、根拠のない内容を加えずに決定の範囲と権限を特定し、履歴を保持し、観測された証拠と予定されている確認を区別できた時点で完了です。承認が未確定の場合は、提案する記録を提出し、承認済みと主張するのではなく、未決定の内容を明示します。

使用しない場合

システム全体のアーキテクチャと変更の順序付けは software-architecture に、特定のツールの実装は関連する運用スキルに振り分けます。このスキルが担うのは、決定の根拠と確認へのリンクであり、実装の実行や、一般的なオブザーバビリティプログラムではありません。

目次

• references/adr-format.md — テンプレートカタログ（11 種類の形式：Nygard、MADR、Tyree & Akerman、Business Case、Planguage、Alexandrian、ITD、arc42、EdgeX、Gareth Morgan、NHS Wales）、テンプレート選択の判断ツリー、ライフサイクルの段階、ファイル命名、チームガバナンス、例の参照
• references/adr-to-pyramid-mapping.md — active→L2、superseded→L3、利用者への振り分け
• references/fitness-functions.md — ADR の主張を永続的な証拠につなげる確認の選択、運用、解釈、レビュー、廃止の方法
• references/decision-sustainability.md — 承認前に ADR の品質を評価するための、持続可能性に関する 5 つの基準と 8 つのガイドライン
• references/project-setup-guide.md — 新規プロジェクトで ADR を開始する手順：ディレクトリの設定、README インデックス、CONTRIBUTING.md/AGENTS.md のドキュメント、実例付きの課題起点の PR ワークフロー
• templates/fitness-function-record.md — 適合性関数の選択、運用、レビュー、廃止に再利用できる記録
• references/source-index.md — このスキルの出典情報と統合の範囲

標準リファレンス

• Architecture Decision Record コミュニティリポジトリ — https://github.com/architecture-decision-record/architecture-decision-record
• Michael Nygard、「Documenting Architecture Decisions」 — https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

移植性

このスキルは、特定のホストに依存しないよう意図的に設計されています。ここに記載されたリファレンス、テンプレート、スクリプトの読み込みには、エージェントの通常の仕組みを使用してください。特定のプロファイルシステム、タスクオーケストレーター、メモリサービス、応答引き渡し形式を前提としないでください。