adr-skill

ADR スキル

哲学

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

そのため、次の点に留意します。

• 制約は曖昧な感覚ではなく、明確かつ測定可能なものにします
• 決定は実行できるほど具体的にします（「データベースを使う」ではなく、「pgvector を使う PostgreSQL 16 を使う」）
• 決定の結果は、具体的な後続タスクに結び付けます
• スコープの拡大を防ぐため、対象外の事項を明記します
• ADR は自己完結させ、特定の人だけが知っている情報があることを前提にしません
• ADR には実装計画を含める必要があります — 変更するファイル、従うパターン、作成するテスト、決定が正しく実装されたことを検証する方法を記載します

ADR を作成するタイミング

次のような決定については、ADR を作成します。

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

次の場合は ADR を作成しないでください。

• 確立されたパターンの範囲内での通常の実装上の選択
• バグ修正や誤字の修正
• 既存の ADR にすでに記録されている決定（代わりに既存の ADR を更新します）
• リンターやフォーマッターですでに規定されているスタイル上の好み

迷った場合は、このコードベースで作業する将来のエージェントが、その選択をした「理由」を知ることで役立つなら、ADR を作成します。

ADR を積極的に作成するきっかけ（エージェント向け）

リポジトリでコーディングするエージェントが次の状況に遭遇した場合は、作業を中断し、先に ADR の作成を提案してください。

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

提案方法： 直面している決定と、それが重要な理由を人間に伝え、ADR として記録するかどうかを尋ねます。承認された場合は、4 フェーズのワークフローをすべて実行します。承認されなかった場合は、決定をコードコメントに記録して作業を続けます。

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

すべての ADR は 4 つのフェーズを経ます。フェーズを省略しないでください。

フェーズ 0：コードベースを調査する

質問する前に、リポジトリから情報を集めます。

1. 既存の ADR を探します。 docs/decisions/、adr/、docs/adr/、decisions/ に既存の記録がないか確認し、内容を読みます。次の点を記録します。

   • 既存の慣例（ディレクトリ、命名規則、テンプレートのスタイル）
   • 現在の決定に関連する、または制約となる決定
   • この新しい決定によって置き換えられる可能性がある ADR

2. 技術スタックを確認します。 package.json、go.mod、requirements.txt、Cargo.toml などに相当するファイルを読みます。関連する依存関係とバージョンを記録します。

3. 関連するコードパターンを探します。 決定が特定の領域（例：「認証をどのように処理するか」）に関わる場合は、既存の実装を調べます。決定の影響を受ける具体的なファイル、ディレクトリ、パターンを特定します。

4. コード内の ADR 参照を確認します。 コメントやドキュメントにある ADR-NNNN への参照を探します（後述の「コード ↔ ADR のリンク」を参照）。これにより、既存の決定がコードベースのどの部分を規定しているかが分かります。

5. 調査結果を記録します。 この情報をフェーズ 1 に引き継します。質問をより的確にし、ADR が既存の決定と矛盾するのを防ぐのに役立ちます。

フェーズ 1：意図を把握する（ソクラテス式）

人間に質問して、意思決定の範囲を理解します。質問は一度に1つずつ行い、前の回答を踏まえて質問します。質問をまとめて列挙しないでください。

基本的な質問（おおむね以下の順に質問します。すでに文脈やフェーズ 0 で明らかな項目は省略します）：

1. 何を決めようとしていますか？ — 短く具体的なタイトルを考えてもらいます。動詞句（「X を選ぶ」「Y を採用する」「Z を W に置き換える」など）にするよう促します。
2. なぜ今ですか？ — 何が壊れたのか、何が変化しているのか、何もしなければ何が壊れるのかを尋ねます。これがきっかけです。
3. どのような制約がありますか？ — 技術スタック、スケジュール、予算、チームの規模、既存のコード、コンプライアンスなどについて、具体的に尋ねます。フェーズ 0 で見つけた内容を参照します（「すでに X を使用しているようですが、これが制約になりますか？」など）。
4. 成功とはどのような状態ですか？ — 測定可能な成果を尋ねます。「動作する」だけでなく、具体的な内容（レイテンシ、スループット、開発者体験、メンテナンスの負担など）を掘り下げます。
5. どのような選択肢を検討しましたか？ — 少なくとも2つの選択肢を挙げてもらいます。それぞれについて、主なトレードオフを尋ねます。選択肢が1つしかない場合は、ほかの選択肢を退けた理由を言語化できるよう支援します。
6. 現時点ではどの選択肢に傾いていますか？ — 現時点での直感を早めに把握します。表明されていない優先事項が明らかになることがよくあります。
7. 誰に知らせる、または承認を得る必要がありますか？ — 意思決定者、意見を求める専門家、情報共有が必要な関係者を確認します。
8. これを実装するために、エージェントには何が必要ですか？ — 影響を受けるファイルやディレクトリ、従うべき既存のパターン、避けるべきこと、動作を確認できるテストを尋ねます。これは実装計画に直接反映されます。

状況に応じた追加質問：回答を踏まえ、意思決定が曖昧な箇所をさらに掘り下げます。よくある追加質問は次のとおりです。

• 「この判断を誤った場合、最悪の結果は何ですか？」
• 「6か月後にこの判断を見直すとしたら、どのようなことがきっかけになりますか？」
• 「明確に『行わない』と決めていることはありますか？」
• 「コードベース内の既存の先例やパターンのうち、これに関連するものはありますか？」
• 「既存の ADR やパターンを見つけました。この新しい判断は、それに影響しますか？」

終了のタイミング：作り話をせずに、実装計画を含む ADR のすべてのセクションを埋められるだけの情報がそろったら終了です。どのセクションについても推測が必要な場合は、追加の質問をしてください。

意図の要約による確認：フェーズ 2 に進む前に、把握した内容を構造化して提示し、人間に確認または訂正を依頼します。

ADR に記載する内容をまとめました：

• タイトル：{title}
• きっかけ：{why now}
• 制約：{list}
• 選択肢：{option 1} と {option 2} [と ...]
• 現時点での傾き：{which option and why}
• 対象外：{what's explicitly out of scope}
• 関連する ADR／コード：{what exists that this interacts with}
• 影響を受けるファイル／領域：{where in the codebase this lands}
• 検証方法：{how we'll know it's implemented correctly}

意図を正しく反映できていますか？追加または訂正したいことはありますか？

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

フェーズ 2：ADR の草案作成

1. ADR ディレクトリを選択します。

   • 既存のディレクトリがある場合（フェーズ 0 で確認済み）は、それを使用します。
   • ない場合は、docs/decisions/（MADR のデフォルト）または adr/（シンプルなリポジトリ向け）を作成します。

2. ファイル名のルールを選択します。

   • 既存の ADR で数値のプレフィックス（0001-...）を使用している場合は、そのルールを継続します。
   • それ以外の場合は、スラッグのみのファイル名（choose-database.md）を使用します。

3. テンプレートを選択します。

   • 単純な意思決定（明確な最有力案が 1 つあり、トレードオフが最小限）の場合は、assets/templates/adr-simple.md を使用します。
   • 構造化された長所・短所・判断基準とともに複数の選択肢を記録する必要がある場合は、assets/templates/adr-madr.md を使用します。
   • ガイダンスについては、references/template-variants.md を参照してください。

4. 確認済みの意図の概要に基づいて、すべてのセクションを埋めます。 プレースホルダーのテキストを残さないでください。各セクションには実際の内容を記載するか、（任意のセクションに限り）削除してください。

5. 実装計画を記述します。 これはエージェント優先の ADR で最も重要なセクションです。次のエージェントが具体的に何をすべきかを示します。構成についてはテンプレートを参照してください。

6. 検証基準をチェックボックス形式で記述します。 各項目をエージェントがプログラムで、または手動で確認できる程度に具体的にしてください。

7. ファイルを生成します。

   • 推奨：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-NNNN の参照を見つけたとき

ADR の参照方法

1. ADR ディレクトリを探します。 docs/decisions/、adr/、docs/adr/、decisions/を確認します。インデックスファイル（README.mdまたはindex.md）も確認します。

2. タイトルとステータスを確認します。 インデックスを読むか、ファイル名の一覧を確認します。acceptedのADRに注目します。これらは有効な決定です。

3. 関連するADRを最後まで読みます。 タイトルだけでなく、コンテキスト、決定、結果、対象外の事項、そして実装計画を読みます。実装計画には、従うべきパターンと、この決定が適用されるファイルが記載されています。

4. 決定を尊重します。 承認済みのADRに「PostgreSQLを使用する」と記載されている場合、新しいADRを作成して既存のADRに取って代わるものとしない限り、MongoDBへの切り替えを提案しないでください。コードの動作とADRの内容に矛盾がある場合は、人間に報告してください。

5. 実装計画に従います。 ADRが適用される領域のコードを実装するときは、実装計画に指定されたパターンに従います。計画に「新しいクエリはすべてsrc/db/のデータアクセスレイヤー経由にする」と記載されている場合は、そのとおりにしてください。

6. 作業内でADRを参照します。 コードコメントとPRの説明にADR-NNNNを記載します（以下の「コード ↔ ADR のリンク」を参照）。

コード ↔ ADR のリンク

ADRと、その適用対象となるコードは双方向にリンクしてください。

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

実装計画のセクションでは、具体的なファイル、ディレクトリ、パターンを指定します。

## Implementation Plan
- **Affected paths**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Pattern**: all database queries go through `src/db/client.ts`

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

ADRに基づいてコードを実装するときは、そのADRを参照するコメントを追加します。

// ADR-0004: Using better-sqlite3 for test database
// See: docs/decisions/0004-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

コメントは簡潔にしてください。すべての行ではなく、エントリーポイントに1つだけ記載します。目的は見つけやすくすることです。将来のエージェントがこのコードを読んだときに、判断の理由をたどれるようにします。

重要な理由

• src/db/で作業するエージェントは、その領域に適用されるADRを見つけられます
• ADRを読むエージェントは、その決定を実装しているコードを見つけられます
• ADRが置き換えられたとき、コード内の参照を使えば、更新が必要な箇所をすべて簡単に特定できます

その他の操作

既存のADRを更新する

1. 意図を特定します。

   • 承認／却下：ステータスを変更し、最終的なコンテキストを追加します。
   • 非推奨にする：ステータスをdeprecatedに変更し、置き換え方法を説明します。
   • 置き換える：新しいADRを作成し、双方向にリンクします（古いADR → 新しいADR、新しいADR → 古いADR）。
   • 知見を追加する：日付を付けて## More Informationに追記します。過去の記録を書き換えないでください。

2. ステータスを変更する際は、scripts/set_adr_status.jsを使用します（YAMLのフロントマター、箇条書きのステータス、セクションのステータスに対応しています）。

承認後のライフサイクル

ADRの承認後：

1. 実装タスクを作成します。 実装計画の各項目と、結果に記載された各フォローアップを、追跡可能なタスク（issue、チケット、またはTODO）にします。
2. PRでADRを参照します。 PRの説明にADRへのリンクを記載します：「ADR-0004を実装」。
3. コード内に参照を追加します。 実装上の重要な箇所にADR-NNNNコメントを追加します。
4. 検証基準を確認します。 実装が完了したら、検証用チェックボックスを順に確認します。結果を## More Informationに記載してADRを更新します。
5. 条件に該当したら見直します。 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/
    0001-use-postgres.md
  frontend/
    0001-use-react.md
  infrastructure/
    0001-use-terraform.md

番号は各カテゴリ内で付けます。早い段階で分類方法（レイヤー別、ドメイン別、チーム別）を決め、インデックスに記載してください。

リソース

scripts/

• scripts/new_adr.js — リポジトリの規約に従い、テンプレートから新しい ADR ファイルを作成します。
• scripts/set_adr_status.js — ADR のステータスをインプレースで更新します（YAML フロントマターまたはインライン）。機械可読な出力には --json を使用します。
• scripts/bootstrap_adr.js — ADR ディレクトリ、README.md、および最初の「ADR の採用」決定を作成します。

references/

• references/review-checklist.md — フェーズ 3 のレビュー用エージェント対応チェックリストです。
• references/adr-conventions.md — ディレクトリ、ファイル名、ステータス、ライフサイクルの規約です。
• references/template-variants.md — シンプルなテンプレートと MADR スタイルのテンプレートの使い分けについて説明します。
• references/examples.md — 実装計画を含む、短い ADR と長い ADR の記入例です。

assets/

• assets/templates/adr-simple.md — 直接的な決定に適した簡潔なテンプレートです。
• assets/templates/adr-madr.md — 複数の選択肢と構造化されたトレードオフを含む決定向けの MADR 4.0 テンプレートです。
• assets/templates/adr-readme.md — scripts/bootstrap_adr.js で使用されるデフォルトの ADR インデックス用ひな形です。

スクリプトの使用方法

対象リポジトリのルートから実行します。

# Simple ADR
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed

# MADR-style with options
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed

# With index update
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index

# Bootstrap a new repo
node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions

注意：

• スクリプトは ADR ディレクトリとファイル名の方式を自動検出します。
• 上書きするには --dir と --strategy を使用します。
• 機械可読な出力を生成するには --json を使用します。