majiayu000 ADR（Architecture Decision Record）管理スキル
このスキルはdocs/adr/内のArchitecture Decision Recordsを、プロジェクト固有のルールに従って管理します。
プロジェクト固有のルール
ADRディレクトリ構造
docs/adr/
├── 0001-security.md
├── 0002-realtime.md
├── 0003-cost.md
├── 0004-services.md
├── 0005-centralize-runtime-config.md
├── 0006-transcript-subscription-simplification.md
├── 0007-orchestrator-browser-interaction.md
├── 0008-chime-media-pipelines-for-server-side-transcription.md
├── 0009-third-party-meeting-service-integration.md
└── 0011-sqs-fifo-for-transcript-streaming.md
ADRファイル命名規則
- ファイル名:
[4桁番号]-[ケバブケース説明].md - 例:
0001-security.md,0011-sqs-fifo-for-transcript-streaming.md - 番号は連番だが、欠番があってもOK（削除・スキップされたADRの場合）
ADRメタデータフォーマット
各ADRファイルは以下のメタデータを含む必要があります：
# ADR 0001: タイトル
- Status: Proposed | Accepted | Rejected | Superseded | TBD
- Date: YYYY-MM-DD
- Owners: プロジェクトチーム名 または 個人名
Statusの意味:
- Proposed: 提案段階（レビュー中）
- Accepted: 承認済み（実装中または実装済み）
- Rejected: 却下
- Superseded: 別のADRに置き換えられた
- TBD: 未決定（調査中、議論中）
ADR構造テンプレート
# ADR [番号]: タイトル
- Status: [Status]
- Date: [YYYY-MM-DD]
- Owners: [チーム名]
## 背景 / Context
[意思決定が必要になった背景、問題、要件]
## 決定 / Decision
[何を決定したか。明確に、簡潔に]
## 影響 / Consequences
[この決定によって生じる影響（ポジティブ、ネガティブ両方）]
## 代替案 / Alternatives Considered
[検討した他の選択肢とその理由]
## 参考 / References
[関連リンク、ドキュメント、関連ADR]
言語
- 日本語で記述: セクション見出しは「背景 / Context」のように日英併記
- 技術用語は英語でもOK（Kinesis, SQS, Lambda等）
- コード例、構造図は英語でOK
関連ADRの参照
ADR間で関連がある場合、明示的に参照する：
## 参考 / References
### 関連ADR
- ADR 0002: リアルタイム性（レイテンシ要件）
- ADR 0003: コスト（コスト最適化方針）
- ADR 0007: Orchestratorとブラウザの連携
使用シナリオ
新規ADRの作成
- 番号の確認: docs/adr/ディレクトリをGlobで確認し、未使用の次の番号を決定
- テンプレート適用: 上記のADR構造テンプレートを使用
- メタデータ設定:
- Status: 通常は"Proposed"または"TBD"でスタート
- Date: 今日の日付（YYYY-MM-DD形式）
- Owners: デフォルトは"timtam PoC チーム"
- ファイル作成: Writeツールで新規ファイルを作成
既存ADRの読み込み
- 番号で検索: Globで
docs/adr/[番号]*.mdパターンで検索 - キーワード検索: Grepで内容を検索
- 全ADR一覧: Globで
docs/adr/*.mdを一覧表示
既存ADRの更新
- Readで読み込み: 対象ADRファイルを読み込む
- メタデータ更新:
- Status変更（Proposed → Accepted等）
- Date更新（最終更新日）
- 内容更新: Editツールでセクションを追加・修正
- Superseded設定: 別のADRに置き換えられた場合、古いADRのStatusを"Superseded"に変更し、参照を追記
ADR索引の確認
現在は専用のREADME.mdは存在しないが、全ADRを一覧する場合：
Glob: docs/adr/*.md
で一覧を取得し、ユーザーに提示する。
作業フロー
- 読み込み: docs/adr/ディレクトリの現在の状態を確認（Glob使用）
- 番号確認: 最新のADR番号を確認し、次の番号を決定
- テンプレート適用: プロジェクト固有のフォーマットとメタデータを適用
- 内容作成: ユーザーの要件に基づいて各セクションを記述
- 実行: WriteまたはEditツールでファイルを作成・更新
例
良い例：新規ADR作成時
ユーザー: 「SQSの使用について新しいADRを書いて」
- Glob で
docs/adr/*.mdを確認 - 最新番号が0011なので、次は0012を使用
- テンプレートを適用:
# ADR 0012: SQS使用方針
- Status: Proposed
- Date: 2025-12-25
- Owners: timtam PoC チーム
## 背景 / Context
[SQS導入の背景]
## 決定 / Decision
[SQS使用の決定]
## 影響 / Consequences
[影響分析]
## 代替案 / Alternatives Considered
[他の選択肢]
## 参考 / References
[関連情報]
- Write で
/home/yattom/work/timtam/docs/adr/0012-sqs-usage-policy.mdを作成
良い例：既存ADRの更新
ユーザー: 「ADR 0011のStatusをAcceptedに変更して」
- Read で
docs/adr/0011-*.mdを読み込む - Editでメタデータを更新:
- Status: Proposed
+ Status: Accepted
- Date: 2025-12-25
+ Date: 2025-12-26
良い例：ADR検索
ユーザー: 「Kinesisに関するADRを教えて」
- Grep で
pattern: "Kinesis",path: docs/adr/を検索 - 該当するADRファイルをリストアップ
- ユーザーに提示
悪い例：番号の重複
❌ 既存のADR番号を再利用しない ❌ 番号を遡って挿入しない（0001と0002の間に0001.5を作らない） ✅ 常に最新番号+1を使用
悪い例：メタデータの省略
❌ Statusを省略 ❌ Dateフォーマットが不統一（2025/12/25等） ✅ 必須メタデータ（Status, Date, Owners）を必ず含める
ユーザー依頼例
- 「新しいADRを作成して」
- 「ADR 0011をAcceptedに変更して」
- 「Kinesisに関するADRを探して」
- 「最新のADRを教えて」
- 「ADR 0008の内容を読んで」
- 「ADRの一覧を見せて」
パス指定の注意
常に絶対パスを使用：
- ✅
/home/yattom/work/timtam/docs/adr/0001-security.md - ❌
docs/adr/0001-security.md
補足：ADRのベストプラクティス
いつADRを書くか
- アーキテクチャに影響する重要な技術選択をした時
- 複数の選択肢があり、トレードオフを検討した時
- 将来の意思決定者が「なぜこうしたのか」を知る必要がある時
ADRに含めるべき内容
- 背景: なぜこの決定が必要になったか
- 決定: 何を選択したか（明確に）
- 理由: なぜその選択をしたか
- トレードオフ: 何を得て、何を失うか
- 代替案: 検討した他の選択肢と却下理由
ADRに含めなくてよい内容
- 実装の詳細（コードで表現すべき）
- チュートリアル（ドキュメントで表現すべき）
- 変更履歴（Gitで管理されている）