write-adr

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が既存の意思決定を覆す・置き換える場合:

1. 旧ADR: Statusを superseded に変更し、直下に Superseded by [新ADRタイトル](新ADRファイル名) のリンクを追加する
2. 新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: 意思決定の確認

ユーザーに以下を確認する:

1. 何を決定したか: どのような技術的選択を行ったか
2. なぜその選択をしたか: 背景にある課題や動機
3. 他にどんな選択肢があったか: 検討した代替案

実装作業の直後であれば、作業内容から上記を推測して提示し、ユーザーの確認を得る。

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のトレードオフがバランスよく記述されているか

ユーザーの確認が得られたら:

1. 新ADRのStatusを accepted に更新する
2. Step 2で supersede 対象の旧ADRがある場合、このタイミングで旧ADRのStatusを superseded に変更し、新ADRへのリンクを追記する（「supersededへの変更ルール」セクション参照）