affaan-m/architecture-decision-records

アーキテクチャ決定記録

コーディングセッション中にアーキテクチャ決定を構造化ドキュメントとして記録します。決定がSlackスレッド、PRコメント、または誰かの記憶にのみ存在する代わりに、このスキルはコードと並行して存在する構造化ADRドキュメントを生成します。

アクティベーション時期

• ユーザーが明示的に「この決定を記録しよう」または「このADRを作成しよう」と言う
• 重要な代替案の選択（フレームワーク、ライブラリ、パターン、データベース、API設計）
• ユーザーが「私たちは...を選択した」または「YではなくXをしている理由は...です」と言う
• ユーザーが「なぜXを選んだのか」と尋ねる（既存のADRを読む）
• アーキテクチャ上のトレードオフが検討される計画段階

ADR形式

Michael Nygardによって提案されたADR形式を、AI支援開発向けに調整したものを使用します：

# ADR-NNNN: [決定タイトル]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [関係者]

## Context

この決定または変更を促すどのような問題や状況が見られるのか？

[2～5文で状況、制約条件、作用する力について説明]

## Decision

提案または実施する変更は何か？

[決定を明確に述べる1～3文]

## Alternatives Considered（検討された代替案）

### Alternative 1: [名前]
- **Pros**: [利点]
- **Cons**: [欠点]
- **Why not**: [この選択肢が拒否された特定の理由]

### Alternative 2: [名前]
- **Pros**: [利点]
- **Cons**: [欠点]
- **Why not**: [この選択肢が拒否された特定の理由]

## Consequences（結果）

この変更により、何がより簡単になり、何がより難しくなるか？

### Positive
- [利点1]
- [利点2]

### Negative
- [トレードオフ1]
- [トレードオフ2]

### Risks
- [リスクと軽減策]

ワークフロー

新しいADRをキャプチャする

決定の瞬間が検出されたとき：

1. 初期化（初回のみ） — docs/adr/が存在しない場合、ユーザーの確認を得た上でディレクトリ、インデックステーブルヘッダーでシードされたREADME.md（下記のADRインデックス形式を参照）、手動使用用の空白のtemplate.mdを作成します。明示的な同意なしにファイルを作成しないでください。
2. 決定を特定する — 行われている中核的なアーキテクチャの選択を抽出する
3. コンテキストを収集する — この問題を起こした背景は？存在する制約条件は？
4. 代替案をドキュメント化する — どの他のオプションが検討されたか？ なぜ拒否されたか？
5. 結果を述べる — トレードオフは何か？何がより簡単/難しくなるか？
6. 番号を割り当てる — docs/adr/内の既存のADRをスキャンして増分する
7. 確認して書き込む — レビュー用のドラフトADRをユーザーに提示します。明示的な承認後にのみdocs/adr/NNNN-decision-title.mdに書き込みます。ユーザーが辞退した場合、ファイルを書き込まずにドラフトを破棄します。
8. インデックスを更新する — docs/adr/README.mdに追記する

既存のADRを読む

ユーザーが「なぜXを選んだのか」と尋ねたとき：

1. docs/adr/が存在するかチェック — 存在しない場合、「このプロジェクトでADRが見つかりません。アーキテクチャ決定の記録を始めたいですか？」と応答
2. 存在する場合、関連エントリのdocs/adr/README.mdインデックスをスキャン
3. 一致するADRファイルを読み、ContextとDecisionセクションを表示
4. 一致が見つからない場合、「その決定についてのADRが見つかりません。今すぐ記録しますか？」と応答

ADRディレクトリ構造

docs/
└── adr/
    ├── README.md              ← すべてのADRのインデックス
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← 手動使用用の空白テンプレート

ADRインデックス形式

# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |

決定検出シグナル

会話の中でアーキテクチャ決定を示すこれらのパターンに注意：

明示的なシグナル

• 「Xにしよう」
• 「YではなくXを使うべき」
• 「トレードオフは...だから価値がある」
• 「このをADRとして記録して」

暗黙的なシグナル（ADRの記録を提案する — ユーザーの確認なしに自動作成しない）

• 2つのフレームワークまたはライブラリを比較して結論に達する
• 述べられた根拠を持つデータベーススキーマ設計の選択をする
• アーキテクチャパターン（モノリス対マイクロサービス、REST対GraphQL）の間で選択する
• 認証/認可戦略を決定する
• 代替案を評価した後、デプロイインフラストラクチャを選択する

良いADRとは

すること

• 具体的に — 「ORMを使う」ではなく「Prisma ORMを使う」
• 根拠を記録する — 根拠は何よりも重要です
• 拒否された代替案を含める — 将来の開発者は何が検討されたかを知る必要があります
• 結果を正直に述べる — すべての決定にはトレードオフがあります
• 短く保つ — ADRは2分で読めるべき
• 現在時制を使う — 「Xを使う」ではなく「私たちはXを使う」

しないこと

• 些細な決定を記録する — 変数名またはフォーマット選択はADRを必要としません
• エッセイを書く — contextセクションが10行を超える場合は長すぎます
• 代替案を省略する — 「単に選んだ」は有効な根拠ではありません
• マーキングなしでバックフィルする — 過去の決定を記録する場合は元の日付を注記
• ADRを古い状態にする — 置き換えられた決定は置き換えを参照する必要があります

ADRライフサイクル

proposed → accepted → [deprecated | superseded by ADR-NNNN]

• proposed: 決定が検討中であり、まだコミットされていない
• accepted: 決定が有効であり、フォローされている
• deprecated: 決定は関連性がなくなった（例：機能が削除された）
• superseded: 新しいADRがこれを置き換える（常に置き換えをリンク）

記録する価値のある決定カテゴリ

| Category | Examples | |----------|---------| | Technology choices | フレームワーク、言語、データベース、クラウドプロバイダ | | Architecture patterns | モノリス対マイクロサービス、イベント駆動、CQRS | | API design | REST対GraphQL、バージョニング戦略、auth機構 | | Data modeling | スキーマ設計、正規化決定、キャッシング戦略 | | Infrastructure | デプロイメントモデル、CI/CDパイプライン、監視スタック | | Security | Auth戦略、暗号化アプローチ、シークレット管理 | | Testing | テストフレームワーク、カバレッジ対象、E2E対統合のバランス | | Process | ブランチング戦略、レビュープロセス、リリースケーデンス |

他のスキルとの統合

• Planner エージェント: プランナーがアーキテクチャ変更を提案するとき、ADRの作成を提案
• Code reviewer エージェント: 対応するADRなしでアーキテクチャ変更を導入するPRにフラグを立てる