| name | write-adr |
| description | ADR（Architecture Decision Record）の作成を支援するスキル。アーキテクチャに関わる意思決定を `docs/adr/` に記録する。
「ADRを書く」「ADRを作成」「意思決定を記録」「write an ADR」などの明示的な指示で使用する。
機能実装やライブラリ追加・移行の作業中にアーキテクチャ上の意思決定が発生した場合にも積極的に使用し、実装完了後に「この意思決定をADRとして残しますか？」と提案すること。トリガー条件の詳細は本文「ADRを書くタイミング」セクションを参照。
|
ADR（Architecture Decision Record）作成
このプロジェクトのアーキテクチャ意思決定を docs/adr/ に記録するスキル。
ADRを書くタイミング
以下のような意思決定が発生したとき、ADRの作成を提案または実行する:
- 新しいライブラリ・フレームワークの導入（例: Playwright導入、schema-dts採用）
- 既存ツールの移行（例: ESLint/Prettier → Biome）
- レンダリング戦略やデータ処理方式の選択（例: Mermaid CSR vs ビルドタイム）
- データモデルやスキーマの設計変更（例: フロントマターのフィールド統一）
- UI/UX実装パターンの選定（例: スクロール連動型目次）
- CI/CDワークフローやオートメーションの導入（例: Claude PR自動レビュー）
- 構造化データやSEO関連の設計変更
単純なバグ修正やスタイル調整のような、アーキテクチャに影響しない変更ではADRは不要。
ステータスライフサイクル
ADRのStatusは以下の値を取り、決まった遷移パターンに従う:
proposed → accepted → superseded
→ deprecated
→ rejected
- proposed: 新規作成時の初期ステータス。レビュー待ち
- accepted: ユーザーが内容を確認し、意思決定を承認した状態
- rejected: 検討したが採用しなかった意思決定
- deprecated: かつては有効だったが、現在は推奨されない（後継のADRがない場合）
- superseded: 新しいADRによって置き換えられた。必ず後継ADRへの参照を記載する
supersededへの変更ルール
新しいADRが既存の意思決定を覆す・置き換える場合:
- 旧ADR: Statusを
superseded に変更し、直下に Superseded by [新ADRタイトル](新ADRファイル名) のリンクを追加する
- 新ADR: Contextセクションに旧ADRへの参照を含め、なぜ以前の決定を変更するのかを明記する
例（旧ADRのStatus部分）:
## Status
superseded
Superseded by [Adopt Tailwind CSS for Styling](2026-04-12-adopt-tailwind-css-for-styling.md)
ワークフロー
Step 1: 意思決定の確認
ユーザーに以下を確認する:
- 何を決定したか: どのような技術的選択を行ったか
- なぜその選択をしたか: 背景にある課題や動機
- 他にどんな選択肢があったか: 検討した代替案
実装作業の直後であれば、作業内容から上記を推測して提示し、ユーザーの確認を得る。
Step 2: 既存ADRの確認とステータス更新
docs/adr/ 内の既存ADRを確認し、今回の意思決定と関連するADRがないかチェックする。
確認すべきポイント:
- 同じ領域の過去の決定があるか: 例えば、スタイリング手法のADRが既にある状態で新しいスタイリング手法を採用する場合
- 過去の決定と矛盾しないか: 新しい決定が既存ADRの前提を覆す場合はsupersede対象
過去の決定を置き換える場合は、ユーザーに「既存の [旧ADRタイトル] を superseded にしてよいですか？」と確認する。実際のステータス変更はStep 4でユーザーが新ADRを承認した後に行う（「supersededへの変更ルール」セクション参照）。
Step 3: ADRファイルの作成
ファイル名: docs/adr/YYYY-MM-DD-title-in-kebab-case.md
- 日付は今日の日付
- タイトル部分は英語のkebab-case
以下のテンプレートに従って作成する:
# タイトル（英語、意思決定の内容を端的に表す）
## Status
proposed
## Context
この意思決定に至った背景・課題を日本語で記述する。
- なぜこの意思決定が必要になったのか
- 現状のどこに問題があったのか
- どのような要件や制約があるか
## Decision
何を決定し、どう実装するかを日本語で記述する。
### Considered Options
検討した選択肢を列挙する。採用した選択肢には「（採用）」を付記する。
**1. 選択肢A（採用）**
- 特徴や利点
- 欠点
**2. 選択肢B**
- 特徴や利点
- 欠点
### 選択理由
採用した選択肢を選んだ理由を箇条書きで記述する。
### 実装アプローチ
（必要に応じて）具体的な実装方針を記述する。
## Consequences
**より容易になったこと:**
- ポジティブな影響
**より困難になったこと:**
- ネガティブな影響やトレードオフ
テンプレートの注意点
- Considered Options: 最低2つ以上の選択肢を記載する。「現状維持」も選択肢の1つとして有効
- 言語: セクション見出しは英語（Status, Context, Decision, Consequences）、本文は日本語で記述する。「選択理由」「実装アプローチ」「より容易になったこと」「より困難になったこと」は日本語の見出しを使用する
- supersede時: Contextセクションに旧ADRへの参照と変更理由を含めること（「supersededへの変更ルール」セクション参照）
Step 4: レビューと確定
作成したADRの内容をユーザーに提示し、以下を確認する:
- 意思決定の内容が正確に記録されているか
- 検討した選択肢に漏れがないか
- Consequencesのトレードオフがバランスよく記述されているか
ユーザーの確認が得られたら:
- 新ADRのStatusを
accepted に更新する
- Step 2で supersede 対象の旧ADRがある場合、このタイミングで旧ADRのStatusを
superseded に変更し、新ADRへのリンクを追記する（「supersededへの変更ルール」セクション参照）
