recording-architecture-decisions

アーキテクチャ決定の記録

目的

現在の状態のベースラインを閉じずに、長期にわたって有効なアーキテクチャ決定を記録します。ADR は決定に至った理由を記録し、ベースラインはその決定後のアーキテクチャを記録します。

このスキルは、必要に応じて利用するタスク固有のワークフローです。verification-before-completion に代わるものではなく、完了を承認する権限を与えるものでも、権威ある GateDecision や PolicySnapshot の出力を生成するものでもありません。

必須の参照資料

判断または記述を行う前に、次の資料から関連する最小限の範囲を読みます。

• docs/adr/ADR-CREATION-GATE.md
• docs/current/AEGIS_ADR_AUTO_BACKFILL.md
• 影響を受けるアーキテクチャ領域を管理する、対象プロジェクトの現在の ADR、ベースライン、または権威あるドキュメント

Aegis リポジトリに変更を加える場合は、このリポジトリの docs/adr/ と docs/current/ の権威性の順序に従います。対象プロジェクトに独自の ADR システムがある場合は、同じ決定を docs/aegis/adr/ に重複して記録せず、そのプロジェクトの管理者に従います。

使用する場面

次のことをユーザーから求められた場合に、このスキルを使用します。

• ADR の作成、記述、更新、修正、置き換え、または評価
• アーキテクチャ決定記録が必要かどうかの判断
• 長期にわたって有効なアーキテクチャ決定または決定ログの記録
• ADR に関連するアーキテクチャ変更後のベースライン同期の完了
• ADR に関する対応によってアーキテクチャのベースラインが古くなっていないことの確認

単純な文言の編集、通常の README の整理、テストのみのカバレッジ改善、リスクの低い単一ファイルの変更、既存のベースラインを復元するだけのバグ修正には使用しないでください。

判断の流れ

1. 決定候補と根拠となる情報源を特定します。
2. ADR 作成ゲートを実行します。
   • 取り消しが困難
   • 背景がなければ意外に感じられる
   • 実質的なトレードオフがある
3. 遡及／記憶フィルターを適用します。
   • 実行済みの長期的な決定は、ADR またはベースラインの記録にできます。
   • 未実行のアイデアは、承認済みのアーキテクチャ記録に含めません。
   • 現在のアーキテクチャ状態を変更しないプロセス上のメモには、より簡易な記録を使用できます。
4. ADR に関する対応を「作成」「修正」「置き換え」「スキップ」から必ず 1 つ選びます。
5. 管理対象の領域を選びます。プロジェクトの docs/adr/、docs/aegis/adr/、既存の ADR、または簡易な記録のいずれかです。
6. ベースライン同期の完了処理を実行します。
7. ファイルを記述する場合は、その場で定められている ADR の規約に従い、構成を確認します。

ヘルパーを使った書き込み手順

管理対象の領域が対象プロジェクトの docs/aegis/adr/ の場合、場当たり的にファイルを作成せず、共有ワークスペースヘルパーを使用します。

• create -> <aegis-workspace-helper> new-adr --root <target-project-root> ...
• amend -> <aegis-workspace-helper> amend-adr --root <target-project-root> --path docs/aegis/adr/ADR-####-<slug>.md ...
• supersede -> <aegis-workspace-helper> supersede-adr --root <target-project-root> --path docs/aegis/adr/ADR-####-<slug>.md ...

ヘルパーで書き込みを行った後、次を実行します。

• <aegis-workspace-helper> check --root <target-project-root>

ヘルパーが管理するのは、ファイル形式、ADR の番号、置き換えを示すマーカー、INDEX.md での網羅性のみです。アーキテクチャ上の正しさ、ADR ゲートを通過したかどうか、ベースライン同期が意味的に十分かどうかは判断しません。

ADR ゲートまたは管理対象の領域に関する判断が「スキップ」であれば、ヘルパーがあるというだけで ADR ファイルを作成または修正しないでください。設計や計画にある ADR のシグナルは、後で完了するためのメモであり、ADR ファイルではありません。実行済みの長期的な決定に対してのみ ADR を作成、修正、または置き換えます。既存の ADR がすでにその決定領域を扱っている場合は、関連する ADR を新たに作成せず、既存の ADR を修正します。

ベースライン同期の締めくくり

ADR のアクションが作成、修正、または置換の場合は、ベースライン同期を確認する必要があります。

判断によって以下のいずれかが変更または確認される場合、ベースライン同期が必要です。

• 正規の所有者または所有権マップ
• パブリック API、スキーマ、成果物の形状、または動作契約
• 依存関係の方向、または許可されるモジュール間の関係
• 信頼できる情報源の所有者
• ホスト互換性戦略、またはインストール／検出の契約
• メソッドパックとランタイムコアの境界
• ランタイム対応成果物の境界、またはエビデンスモデル
• 維持されるフォールバック、アダプター、互換性経路、重複する所有者、または廃止 スケジュール
• アーキテクチャ範囲の実装ドリフトとして受け入れたもの
• 今後の貢献者が誤解する可能性のあるリリースまたは配布戦略

ベースラインへの書き戻しを行わない場合は、既存のベースラインが引き続き有効である理由を明記してください。 作成、修正、または置換の後に、ベースライン同期を暗黙のままにしないでください。

簡潔な出力要件

Aegis Visibility:
- Why executed-decision filtering, ADR gate, owner surface, or baseline sync matters now:

Decision Candidate:
- Summary:
- Evidence source:

ADR Gate:
- Hard to reverse: yes | no | unknown
- Surprising without context: yes | no | unknown
- Real trade-off: yes | no | unknown

Retro / Memory Filter:
- Classification: executed durable decision | unexecuted idea | process note
- Memory action: record | skip | lighter record
- Reason:

ADR Action:
- create | amend | supersede | skip
- Reason:

Owner Surface:
- Target:
- Existing ADR / baseline checked:

Baseline Sync:
- Required: yes | no | unknown
- Target:
- Action: create snapshot | update baseline | cite unchanged | blocked
- Reason:

Boundary:
- Advisory method-pack signal only; not completion authority.

よくある間違い

• ゲートを通過しないにもかかわらず、トピックが重要に感じられるという理由で ADR を作成する。
• ADR に理由を記録する一方で、ベースラインに記載された現在の状態を古いままにする。
• ドリフトが意図的で ADR に値するかを判断する前に、ドリフトに合わせてベースラインを更新する。
• 明示的なミラー関係がないまま、同じ判断をプロジェクトの docs/adr/ と docs/aegis/adr/ の両方に重複して記録する。
• ADR またはベースライン同期を、作業が完了した証拠として扱う。