ADR スキル

哲学

このスキルで作成されるADRは、コーディングエージェントのための実行可能な仕様です。人間が決定を承認し、エージェントがそれを実装します。ADRには、エージェントが追加の質問をせずに正しいコードを書くために必要なすべての情報が含まれている必要があります。

つまり、以下を意味します。

制約は明示的かつ測定可能でなければならず、雰囲気で決めてはいけません。
決定は行動に移せるほど具体的である必要があります（「データベースを使う」ではなく「PostgreSQL 16をpgvectorと共に使う」）。
影響は具体的なフォローアップタスクにマッピングできる必要があります。
スコープクリープを防ぐために、非目標を明示する必要があります。
ADRは自己完結型である必要があります。暗黙の知識を前提としてはいけません。
ADRには実装計画を含める必要があります。どのファイルを変更するか、どのパターンに従うか、どのテストを書くか、決定が正しく実装されたことをどのように検証するかを記述します。

ADRを作成すべき時

以下の場合にADRを作成します。

システムの構築方法や運用方法を変更する場合（新しい依存関係、アーキテクチャパターン、インフラストラクチャの選択、API設計など）。
決定を元に戻すのが困難な場合。
後日このコードベースで作業する他の人やエージェントに影響を与える場合。
検討されたが却下された現実的な代替案がある場合。

ADRを作成してはいけない場合：

確立されたパターン内での日常的な実装の選択。
バグ修正やタイポ修正。
既存のADRで既に捕捉されている決定（代わりにそれを更新してください）。
リンターやフォーマッターで既にカバーされているスタイルの好み。

迷った場合：将来このコードベースで作業するエージェントが、この選択が行われた理由を知ることで利益を得られるなら、ADRを作成してください。

プロアクティブなADRトリガー（エージェント向け）

リポジトリでコーディングしているエージェントが以下の状況に遭遇した場合、一旦停止し、続行する前にADRを提案してください。

プロジェクトにまだ存在しない新しい依存関係を導入しようとしている。
他のコードが従う必要がある新しいアーキテクチャパターン（新しいエラー処理方法、新しいデータアクセス層、新しいAPI規約）を作成しようとしている。
2つ以上の現実的な代替案の間で選択を行おうとしており、トレードオフが自明ではない。
既存の承認済みADRと矛盾するものを変更しようとしている。
「理由」を説明する長いコードコメントを書いていることに気づいた — その推論はADRに属します。

提案方法：人間にどのような決定に遭遇したか、なぜそれが重要なのかを伝え、それをADRとして記録するかどうか尋ねてください。はいの場合、完全な4フェーズワークフローを実行します。いいえの場合、決定をコードコメントに記し、先に進みます。

ADRの作成：4フェーズワークフロー

すべてのADRは4つのフェーズを経ます。フェーズをスキップしないでください。

フェーズ0：コードベースのスキャン

質問をする前に、リポジトリからコンテキストを収集します。

既存のADRを見つけます。 contributing/decisions/、docs/decisions/、adr/、docs/adr/、decisions/ を確認し、既存のレコードを探します。それらを読みます。以下に注意します。
- 既存の規約（ディレクトリ、命名、テンプレートスタイル）
- 現在の決定に関連する、または制約する決定
- この新しい決定が置き換える可能性のあるADR
技術スタックを確認します。 package.json、go.mod、requirements.txt、Cargo.toml、または同等のファイルを読みます。関連する依存関係とバージョンに注意します。
関連するコードパターンを見つけます。 決定が特定の領域（例：「認証の処理方法」）に関係する場合、既存の実装をスキャンします。決定によって影響を受ける特定のファイル、ディレクトリ、パターンを特定します。
コード内のADR参照を確認します。 コメントやドキュメント内のADR参照を探します（下記の「コード↔ADRリンク」を参照）。これにより、どの既存の決定がコードベースのどの部分を管理しているかが明らかになります。
見つけたことを記録します。 このコンテキストをフェーズ1に引き継ぎます。これにより質問がより明確になり、ADRが既存の決定と矛盾するのを防ぎます。

フェーズ1：意図の捕捉（ソクラテス的質問）

人間にインタビューして決定領域を理解します。質問は一度に1つずつ、前の回答に基づいて行います。質問のリストを一気に投げかけないでください。

中核となる質問（おおよそこの順序で行い、コンテキストやフェーズ0から既に明らかなものはスキップします）：

何を決定していますか？ — 短く具体的なタイトルを取得します。「Xを選択」、「Yを採用」、「ZをWに置き換え」などの動詞句を推奨します。
なぜ今なのですか？ — 何が壊れたのか、何が変わっているのか、何もしなければ何が壊れるのか。これがトリガーです。
どのような制約がありますか？ — 技術スタック、タイムライン、予算、チーム規模、既存コード、コンプライアンス。具体的にしてください。フェーズ0で見つけたことを参照します（「既にXを使っているようですが、それはこれに制約を与えますか？」）。
成功はどのように見えますか？ — 測定可能な結果。「うまくいく」を超えて、具体的な内容（レイテンシ、スループット、開発者体験、メンテナンス負担）を引き出します。
どのような選択肢を検討しましたか？ — 少なくとも2つ。それぞれについて、中核となるトレードオフは何ですか？選択肢が1つしかない場合、なぜ代替案が却下されたのかを明確にするのを支援します。
現在のあなたの意向は？ — 初期の直感を早い段階で捕捉します。しばしば、述べられていない優先順位が明らかになります。
誰が知る必要があり、承認する必要がありますか？ — 意思決定者、相談を受ける専門家、情報提供を受けるステークホルダー。
エージェントがこれを実装するには何が必要ですか？ — 影響を受けるファイル/ディレクトリは？どの既存パターンに従うべきか？何を避けるべきか？何が正しく機能していることを証明するテストになるか？これは直接的に実装計画に反映されます。

適応的なフォローアップ質問：回答に基づいて、決定が曖昧なところをより深く掘り下げます。一般的なフォローアップ：

「この決定が間違っていた場合の最悪の結果は何ですか？」
「6ヶ月後に再検討するきっかけは何ですか？」
「明示的にやらないことを選択していることはありますか？」
「これは、コードベース内のどの既存の成果物やパターンと関連していますか？」
「[既存のADR/パターン] を見つけました — この新しい決定はそれと相互作用しますか？」

いつ止めるか：実装計画を含むADRのすべてのセクションを、何も作り上げることなく埋められるようになった時点です。どのセクションについて推測している場合は、別の質問をしてください。

意図サマリーゲート：フェーズ2に進む前に、捕捉した内容の構造化されたサマリーを提示し、人間に確認または修正を求めます。

ADR に記録する内容は以下の通りです：

タイトル：{タイトル}

トリガー：{なぜ今か}

制約：{リスト}

選択肢：{選択肢1} vs {選択肢2} [vs ...]

意向：{どの選択肢とその理由}

非目標：{明示的にスコープ外のもの}

関連ADR/コード：{これと相互作用する既存のもの}

影響を受けるファイル/領域：{コードベース内でこれが及ぶ場所}

検証：{正しく実装されたことをどのように確認するか}

あなたの意図を捉えていますか？追加や修正はありますか？

人間がサマリーを確認するまで、フェーズ2に進まないでください。

フェーズ2：ADRのドラフト作成

ADRディレクトリを選択します。
- 既存のものがある場合（フェーズ0で発見）、それを使用します。
- ない場合、contributing/decisions/（contributing/ が存在する場合）、docs/decisions/（MADRデフォルト）、または adr/（よりシンプルなリポジトリ）を作成します。
ファイル名戦略を選択します。
- 既存のADRが日付プレフィックス（YYYY-MM-DD-...）を使用している場合、それを続けます。
- そうでない場合、スラグのみのファイル名（choose-database.md）を使用します。
テンプレートを選択します。
- 単純明快な決定（明確な勝者が1つ、トレードオフが最小限）には assets/templates/adr-simple.md を使用します。
- 複数の選択肢を構造化された長所/短所/推進要因とともに文書化する必要がある場合は、assets/templates/adr-madr.md を使用します。
- ガイダンスについては references/template-variants.md を参照してください。
確認された意図サマリーからすべてのセクションを埋めます。 プレースホルダーテキストを残さないでください。すべてのセクションに実際のコンテンツが含まれているか、削除されている必要があります（オプションセクションのみ）。
実装計画を記述します。 これはエージェントファーストのADRにとって最も重要なセクションです。次のエージェントに正確に何をすべきかを伝えます。構造についてはテンプレートを参照してください。
検証基準をチェックボックスとして記述します。 これらは、エージェントがプログラム的または手動で各項目をチェックできるほど具体的である必要があります。
ファイルを生成します。
- 推奨：scripts/new_adr.js を実行します（ディレクトリ、命名、オプションのインデックス更新を処理します）。
- スクリプトを実行できない場合、assets/templates/ からテンプレートをコピーし、手動で埋めます。

フェーズ3：チェックリストに基づくレビュー

ドラフト作成後、references/review-checklist.md のエージェント対応チェックリストに対してADRをレビューします。

レビューをサマリーとして提示し、生のチェックリストのダンプとしては提示しません。形式は以下の通り：

ADR レビュー

✅ 合格：{リスト — 例：「コンテキストは自己完結型、実装計画は影響を受けるファイルをカバー、検証基準はチェック可能」}

⚠️ 発見されたギャップ：

{具体的なギャップ1 — 例：「実装計画にテストファイルが記載されていない — どのテストスイートがこれをカバーすべきか？」}

{具体的なギャップ2}

推奨：{リリースする / 先にギャップを修正する / さらなるフェーズ1の作業が必要}

失敗と注目すべき強みのみを表面化させ、合格したすべてのチェックボックスを読み上げないでください。

ギャップがある場合、具体的な修正を提案します。問題を指摘するだけでなく、解決策を提案し、人間に承認を求めます。

ADRがチェックリストに合格するか、人間が明示的にギャップを受け入れるまで、確定しないでください。

ADRの参照（読み取りワークフロー）

エージェントは、ADRが存在するコードベースで変更を実装する前に、既存のADRを読む必要があります。これはADR作成ワークフローの一部ではなく、どのエージェントでも実行できる独立した操作です。

ADRを参照すべき時

アーキテクチャに影響を与える機能（認証、データ層、API設計、インフラストラクチャ）の作業を開始する前。
コード内のパターンに遭遇し、「なぜこの方法で行われているのか」と疑問に思った時。
既存の決定と矛盾する可能性のある変更を提案する前。
人間が「ADRを確認して」または「これについては決定がある」と言った時。
コードコメント内でADR参照を見つけた時。

ADRの参照方法

ADRディレクトリを見つけます。 contributing/decisions/、docs/decisions/、adr/、docs/adr/、decisions/ を確認します。また、インデックスファイル（README.md または index.md）も確認します。
タイトルとステータスをスキャンします。 インデックスを読むか、ファイル名を一覧表示します。accepted のADRに焦点を当てます — これらはアクティブな決定です。
関連するADRを完全に読みます。 タイトルだけでなく、コンテキスト、決定、影響、非目標、および実装計画を読んでください。実装計画は、どのパターンに従うべきか、どのファイルがこの決定によって管理されているかを示します。
決定を尊重します。 承認されたADRが「PostgreSQLを使用する」と述べている場合、それを置き換える新しいADRを作成せずにMongoDBへの移行を提案しないでください。コードが行っていることとADRが述べていることの間に矛盾を見つけた場合、それを人間に報告します。
実装計画に従います。 ADRによって管理されている領域でコードを実装する場合、その実装計画で指定されたパターンに従います。計画が「すべての新しいクエリは src/db/ のデータアクセス層を経由する」と述べている場合、その通りにします。
作業にADRを参照します。 コードコメントとPRの説明にADR参照を追加します（下記の「コード↔ADRリンク」を参照）。

コード↔ADRリンク

ADRは、管理するコードと双方向にリンクされるべきです。

ADR → コード（実装計画内）

実装計画セクションでは、特定のファイル、ディレクトリ、パターンに名前を付けます。

## 実装計画

- **影響を受けるパス**：`src/db/`、`src/config/database.ts`、`tests/integration/`
- **パターン**：すべてのデータベースクエリは `src/db/client.ts` を経由する

コード → ADR（コメント内）

ADRに導かれてコードを実装する場合、それを参照するコメントを追加します。

// ADR: テストデータベースに better-sqlite3 を使用
// 参照: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

これらは軽量に保ちます — エントリポイントに1つのコメントで、すべての行に付ける必要はありません。目標は発見可能性です。将来のエージェントがこのコードを読んだとき、その推論を見つけることができます。

なぜこれが重要なのか

src/db/ で作業するエージェントは、その領域を管理するADRを見つけることができます。
ADRを読むエージェントは、それを実装するコードを見つけることができます。
ADRが置き換えられた場合、コード参照により、更新が必要なすべてのコードを簡単に見つけることができます。

その他の操作

既存のADRの更新

意図を特定します。
- 承認 / 却下：ステータスを変更し、最終的なコンテキストを追加します。
- 非推奨化：ステータスを deprecated に変更し、代替パスを説明します。
- 置き換え：新しいADRを作成し、双方向にリンクします（旧→新、新→旧）。
- 学びの追加：日付スタンプ付きで ## 詳細情報 に追加します。履歴を書き換えないでください。
ステータス変更には scripts/set_adr_status.js を使用します（YAMLフロントマター、箇条書きステータス、セクションステータスをサポート）。

承認後のライフサイクル

ADRが承認された後：

実装タスクを作成します。 実装計画の各項目と影響の各フォローアップは、追跡可能なタスク（課題、チケット、TODO）になる必要があります。
PRでADRを参照します。 PRの説明にADRへのリンクを貼ります。例：「contributing/decisions/2025-06-15-use-sqlite-for-test-database.md を実装」。
コード参照を追加します。 主要な実装ポイントにADRパスコメントを追加します。
検証基準を確認します。 実装が完了したら、検証チェックボックスを順に確認します。結果を ## 詳細情報 にADRを更新します。
トリガーが発生したら再検討します。 ADRが再検討条件を指定している場合（「Xが発生した場合、再検討する」）、それらの条件を監視します。

インデックス

リポジトリにADRインデックス/ログファイル（多くの場合、ADRディレクトリ内の README.md または index.md）がある場合、それを最新に保ちます。

推奨：scripts/new_adr.js --update-index に任せます。そうでない場合：

新しいADRの箇条書きエントリを追加します。
順序を一貫させます（番号付きの場合は数値順、スラグの場合は日付順またはアルファベット順）。

ブートストラップ

ADRが全くないリポジトリにADRを導入する場合：

node /path/to/adr-skill/scripts/bootstrap_adr.js

これにより、ディレクトリ、インデックスファイル、および実際の内容を含む最初のADR（「アーキテクチャ決定記録の採用」）が作成され、チームがADRを使用している理由が説明されます。機械可読な出力を得るには --json を使用します。ディレクトリ名を上書きするには --dir を使用します。

カテゴリ（大規模プロジェクト向け）

多数のADRがあるリポジトリの場合、サブディレクトリで整理します：

docs/decisions/
  backend/
    2025-06-15-use-...
  frontend/
    2025-06-20-adopt-react-query.md
  database/
    ...

各カテゴリには独自のインデックスが必要です。新しく scripts/new_adr.js は --category フラグをサポートしていません（現在）ので、ファイルを手動で整理します。

参考資料

assets/templates/adr-simple.md — 単純な決定用テンプレート
assets/templates/adr-madr.md — 複数選択肢の構造化されたADR用テンプレート
references/review-checklist.md — エージェント対応チェックリスト
references/template-variants.md — テンプレート選択ガイド
scripts/new_adr.js — 新しいADRを作成するためのスクリプト
scripts/set_adr_status.js — ADRステータスを更新するためのスクリプト
scripts/bootstrap_adr.js — 新しいリポジトリにADRを導入するためのスクリプト

ADR スキル（アーキテクチャ決定記録）