adr-design

name	adr-design
description	アプリケーションのアーキテクチャ決定を管理し、追記専用のADR履歴と 最新設計スナップショットを同期する。ユーザーがアーキテクチャを検討、 React + .NET Aspireのエージェントアプリを初期設計、ADRを作成・更新、 設計書を更新、代替案を比較、既存決定を置き換える場合は、skill名を 明示しなくても必ず使用する。トリガー: ADR、アーキテクチャ決定、 設計書、設計スナップショット、Aspire、React .NETエージェントアプリ。

ADR + 最新設計スナップショット

このskillは、アーキテクチャに関する議論をリポジトリに残すために使用する。 変更しないArchitecture Decision Record（ADR）の履歴と、現在の状態を示す docs/design.md を1つ管理する。

前提

• 変更案を出す前に、リポジトリ構成、既存ドキュメント、プロジェクトファイルを確認する。
• 実行環境とデプロイ制約が未記載の場合は確認する。
• リポジトリ内で確認できる事実だけを使い、仮定や未解決事項を明示する。
• Aspireソリューションでは、スナップショット作成前にAppHost、ServiceDefaults、API、 フロントエンド、インフラの責務境界を特定する。

ワークフロー

1. 現状を調査する。 関連するソース、設定、README、既存ADRを読む。既存の決定を上書きしたり、暗黙に解釈し直したりしない。
2. 依頼を分類する。
   • 新しい決定: 次の連番でADRを作成する。
   • 決定の変更: 旧ADRを残し、新しいADRで置き換える。
   • スナップショット更新: 実装または承認済み決定が変わった場合だけdocs/design.mdを更新する。
   • 初期設定: アーキテクチャの基準となる最初のADRを作成し、承認済み決定からスナップショットを作成する。
3. 編集前に代替案を整理する。 背景、判断基準、検討した選択肢、結果を記録する。重要な選択が曖昧な場合は、勝手に決めず1つの質問で確認する。
4. ADRの必要性を判定する。 長期的な影響があり、複数の妥当な選択肢から選び、後から理由を説明する価値がある決定だけをADRにする。実装上の細部、命名、単純なバグ修正、既存方針に沿った設定変更はADRにせず、コードレビューやスナップショットだけで扱う。関連する複数の小さな決定は、1つのテーマにまとめて1件のADRにする。
5. ADRを作成する。 必要な場合だけdocs/adr/NNNN-<kebab-case-title>.mdを使用する。既存ADRの最大番号に1を加える。状態はAccepted、Proposed、Superseded、Deprecatedのいずれかにする。
6. スナップショットを更新する。 docs/design.mdは簡潔かつ現在の状態に保つ。選択した構成、責務、リクエスト・データフロー、ローカル開発構成、デプロイ境界、制約を記載し、重要な選択はADRへリンクする。
7. 履歴とスナップショットを整合させる。 スナップショットは第二の決定ログではないため、未解決の代替案や過去の理由を置かない。承認済みADRと矛盾する場合は、先に後継ADRを作成する。
8. 検証する。 リンク、採番、状態遷移、ディレクトリ名、実装との整合性を確認する。変更内容を対象とする既存のドキュメント検査やテストがある場合のみ実行する。

Aspire + React + .NETエージェントの基本構成

初期アーキテクチャでは、リポジトリの制約がない限り、次の責務分離を優先する。

• Aspire AppHostはローカルリソースとサービス参照をオーケストレーションする。
• .NET APIはエージェントの実行、ツールアクセス、ポリシー適用、サーバー側シークレットを担当する。
• Reactはブラウザー画面を担当してAPIを呼び出し、プロバイダーの認証情報を受け取らない。
• ServiceDefaultsは.NETのテレメトリ、回復性、ヘルスチェックなどの共通規約を提供する。
• 外部モデル、ベクトルストア、データベース、可観測性基盤は、明示的なリソースまたは境界として記載する。
• ストリーミング、キャンセル、リトライ、会話状態は、コンポーネント図だけでなくフローと制約として記録する。

リポジトリまたはユーザーの明示的な決定で裏付けられない限り、 リソースがプロビジョニング済み、安全、可観測、本番対応済みだと断定しない。

ADRの粒度

ADRは「変更があったら必ず1件」ではなく、「重要な判断を後から説明するための記録」として使う。 次のいずれかに該当する場合を作成の目安とする。

• システム境界、主要コンポーネント、データフロー、外部サービスの採用を決める。
• セキュリティ、信頼性、コスト、運用、将来の拡張性に大きく影響する。
• 複数の妥当な案があり、選択理由を将来も保持したい。
• 後から変更すると移行コストが高く、チームの合意が必要になる。

迷う場合は、まずdocs/design.mdの更新だけで済むかを確認する。小さな決定を 無理にADR化せず、同じテーマの決定がまとまった時点で1件に統合する。

出力形式

決定に関する作業では、次を報告する。

1. 作成または更新したADRのパスと状態。
2. スナップショットのパスと変更したセクション。
3. 置き換えたADR（存在する場合）。
4. 未解決の質問または仮定（存在する場合）。

テンプレートはADR_TEMPLATE.mdと DESIGN_SNAPSHOT_TEMPLATE.mdを使う。 例は架空の内容にし、プレースホルダーをリポジトリ固有の事実に置き換える。

エラー処理

状況	必須の対応
既存ADRの採番に欠番または重複がある	履歴を保持し、最大番号の次を使用して異常を報告する。
決定が承認済みADRと矛盾する	スナップショット更新を止め、後継ADRを作成または確認する。
必要なアーキテクチャ情報が不足している	仮定として明示するか、1つの質問で確認する。実装詳細を捏造しない。
参照先のADRまたはセクションが存在しない	完了前にリンクを修正するか、ドキュメントエラーとして報告する。
ユーザーの未コミット変更がある	上書きせず、対象箇所だけ慎重に統合し、無関係な変更を残す。

参照

参照	用途
ADR_TEMPLATE.md	決定の新規作成または置き換え
DESIGN_SNAPSHOT_TEMPLATE.md	最新設計スナップショットの作成または更新

実行後の振り返り

複数ステップのワークフロー完了後は、core § 5 実行後の振り返りの手順に従う。