ADR作成スキル

このスキルは、Architecture Decision Record (ADR) を作成するためのワークフローです。ADRは、プロジェクトにおける重要な技術的・機能的判断を記録した「判例」であり、以下の目的を持ちます：

•過去の判断の経緯と理由を明確に記録する
•同じ議論の繰り返しを防ぐ
•新しいメンバーやLLMが判断基準を理解する助けとなる
•特に「実装しない」という判断を明確に残す

ADR作成の心構え

ADRが必要な場面

以下のような判断を行った際は、ADRを作成してください：

•
機能の実装を見送る判断（最も重要）
- •提案された機能をプロダクト哲学に基づき却下する
- •「あったら便利かも」だが追加しないと決定する
- •ユーザーからの要望を意図的に実装しないと決める
•
技術的な選択
- •ライブラリやフレームワークの選定
- •アーキテクチャパターンの採用・不採用
- •パフォーマンス最適化の方針
•
設計上の制約
- •意図的に選択した制限事項
- •トレードオフの結果として受け入れた欠点
•
プロダクト方針
- •UXに関する重要な決定
- •ワークフローの設計方針
- •セキュリティ・プライバシーに関する判断

ADRを書く際の原則

•客観的に記述する — 感情的な表現を避け、事実と論理的な理由を記載する
•コンテキストを明確にする — なぜその判断が必要だったのか、背景を詳しく説明する
•プロダクト哲学との関連を示す — CLAUDE.mdの原則とどう関連するかを明記する
•将来の変更可能性を残す — 状況が変わった場合の再検討の余地を示す
•簡潔かつ具体的に — 長すぎず、かつ判断を再現できる十分な情報を含める
•今回固有の判断と一般原則を区別する — このケース特有の状況と、今後も適用できる原則を明確に分けて記述する
•今後の判断への影響を考慮する — この決定が将来の類似判断にどのような影響を与えるかを意識して書く

ADRを書いてはいけない場合

以下のような軽微な判断にはADRは不要です：

•日常的なバグ修正
•コーディングスタイルの統一
•依存パッケージの通常のバージョンアップ
•既存の方針に沿った実装の詳細

ADRの構造

すべてのADRは以下の構造に従います：

markdown

# ADR-XXXX: [判断の簡潔なタイトル]

## ステータス

[決定済み/提案中/廃止] (YYYY-MM-DD)

## コンテキスト

[この判断が必要になった背景と状況を説明]

- 何が問題だったのか
- どのような提案があったのか
- なぜこの判断が必要だったのか

## 決定

[何を決定したのかを明確に記述]

## 理由

### [理由1のタイトル]

[理由の詳細な説明]

### [理由2のタイトル]

[理由の詳細な説明]

### 判断基準の適用

[CLAUDE.mdの判断基準をどう適用したかを記載]

- **それがなくても目的は達成できないか？** → [回答]
- **説明なしで使い方がわかるか？** → [回答]
- **ユーザーの思考を中断させないか？** → [回答]

## 影響

[この決定によって何が変わるか、何をしない/する必要があるか]

## 代替案（オプション）

[検討した他の選択肢とそれを採用しなかった理由]

ADR作成ワークフロー

以下のステップを順番に実行してください。

ステップ1: 既存ADRの確認

新しいADRを作成する前に、必ず既存のADRを確認してください。

bash

ls -la docs/adr/

既存のADRファイルをすべて確認し、同様のトピックが既に記録されていないかチェックしてください。重複する内容がある場合は、既存のADRを更新するか、新しいADRで参照してください。

ステップ2: ADR番号の決定

ADRファイルは連番で管理されます。既存の最大番号を確認し、次の番号を割り当ててください。

例：既存のADRが0001〜0005の場合、新しいADRは0006になります。

ステップ3: コンテキストの整理

判断に至った背景を整理してください。以下の情報を集めます：

•GitHub Issueの番号と内容（該当する場合）
•提案された内容の詳細
•なぜこの判断が必要になったのか
•関連する技術的制約や要件

ステップ4: 判断の明確化

何を決定したのかを一文で明確に表現してください。

良い例：

•「この機能を実装しない」
•「y-websocketのデフォルト挙動に委ねる」
•「カスタムCursorBuilderを使用する」

悪い例：

•「検討する」（判断ではない）
•「様子を見る」（曖昧）

ステップ5: 理由の記述

なぜその判断をしたのか、複数の観点から理由を記述してください：

技術的理由

•既存ライブラリの機能との重複
•パフォーマンスへの影響
•メンテナンス性
•セキュリティ

プロダクト哲学との整合性

•ノイズの排除
•ミニマリズム
•ユーザー体験への影響
•学習コストの増加

判断基準の適用

CLAUDE.mdに記載された3つの判断基準を必ず適用してください：

•それがなくても目的は達成できないか？
•説明なしで使い方がわかるか？
•ユーザーの思考を中断させないか？

ステップ6: 影響の記述

この決定によって何が変わるかを明確にしてください：

•対応しないGitHub Issueがあれば番号を記載
•実装する/しないコードの範囲
•将来の再検討が必要になる条件

ステップ7: ADRファイルの作成

docs/adr/ ディレクトリに新しいADRファイルを作成してください。

ファイル名の形式：XXXX-short-description.md

例：0006-no-markdown-preview-mode.md

ファイル名は以下のルールに従ってください：

•番号は4桁（例：0001, 0023, 0156）
•説明は英語で、ハイフン区切り
•簡潔で内容が分かるタイトル

ステップ8: 検証とフォーマット

作成したADRを確認してください：

•構造の確認 — 必須セクションがすべて含まれているか
•明確性の確認 — 第三者が読んで判断を理解できるか
•プロダクト哲学との整合性 — CLAUDE.mdの原則と矛盾していないか
•文体の確認 — 客観的で明確な表現になっているか

確認後、Prettierでフォーマットを整えます：

bash

npm run format

ステップ9: コミットとレビュー依頼

ADRを作成したら、変更をコミットしてください。

コミットメッセージの例：

code

docs: add ADR-0006 for markdown preview mode decision

補足：ADRの更新と廃止

ADRの更新

既存のADRの内容を変更する必要がある場合：

•元のADRファイルは変更しない
•新しいADRを作成し、「ADR-XXXX を更新」と明記する
•元のADRのステータスを「廃止 (YYYY-MM-DD) - ADR-XXXX により更新」に変更する

ADRの廃止

過去の判断を覆す場合：

•新しいADRで新しい判断を記録する
•古いADRのステータスを「廃止 (YYYY-MM-DD) - ADR-XXXX により廃止」に変更する
•新しいADRで、なぜ過去の判断を覆すのかを説明する

よくある質問

Q: 些細な判断でもADRを作るべきか？

A: いいえ。日常的なコーディングの判断にはADRは不要です。「なぜこの判断をしたのか」が3ヶ月後に分からなくなりそうな重要な判断にのみADRを作成してください。

Q: 「実装しない」決定だけでもADRを作るべきか？

A: はい。むしろ「実装しない」判断こそADRが最も価値を発揮します。将来同じ提案が出た際に、過去の議論を繰り返さずに済みます。

Q: GitHub IssueとADRの違いは？

A: Issueは「これからやること」を管理し、ADRは「すでに決めたこと」を記録します。Issueがクローズされても、その判断の理由はADRに残り続けます。

Q: 判断が間違っていたと分かったら？

A: ADRを廃止し、新しいADRで新しい判断を記録してください。過去の判断を隠すのではなく、なぜ変更したのかを明確に記録することが重要です。