adr-skill

adr-skill スキルの概要

adr-skill ができること

adr-skill は、Architecture Decision Records を単なる経緯メモではなく、実装に直結するドキュメントとして作成・保守するのに役立ちます。adr-skill の本当の強みは、アーキテクチャ上の判断を、コーディングエージェントが追加の確認をほとんどせず実行できる ADR に落とし込めることです。たとえば、明確な制約、明示された非ゴール、変更対象ファイルの特定、検証手順、具体的な影響まで整理できます。

adr-skill が特に向いている人

このスキルは、後続の実装作業を導く意思決定を文書化する engineering leads、staff engineers、platform teams、technical writers に特に向いています。とくに、あとから戻しにくい判断、複数の関係者に影響する判断、人間と AI エージェントの両方に理解してもらう必要がある判断で有効です。

adr-skill の主なユースケース

次のような場面では adr-skill を使う価値があります。

• 新しいアーキテクチャ判断を提案したい
• 実装開始前に判断内容を ADR として残したい
• 既存の ADR を更新したい、または supersede したい
• まだ ADR がないリポジトリで運用を立ち上げたい
• コードベース全体で ADR の構成を統一したい

adr-skill for Technical Writing という観点では、関係者に読みやすく、かつ実装担当者には十分具体的な意思決定文書を作れる点が最も相性のよい使いどころです。

adr-skill が際立つ理由

最大の差別化ポイントは、エージェント実行を前提にした設計です。adr-skill は、背景・判断・結果を書いて終わりではありません。影響を受けるパス、依存関係、従うべきパターン、避けるべきパターン、必要な設定変更、検証条件まで含んだ実装計画を求めます。単なる「ADR を書いて」という一般的なプロンプトより、実務でそのまま使える形に寄せやすいのが特徴です。

導入前に確認したいこと

adr-skill を導入したり運用の中心に据えたりする前に、まずチームが「ADR を実行の起点として使いたい」のかを確認してください。もし必要なのが軽い判断メモ程度なら、このスキルは必要以上に構造化されていると感じるかもしれません。一方で、引き継ぎに耐え、解釈のブレを減らせる ADR を求めるなら、その厳密さこそが価値になります。

adr-skill スキルの使い方

adr-skill のインストール前提

リポジトリ抜粋を見る限り、SKILL.md 内にはこのスキル専用の install コマンドは明示されていませんが、一般的なパターンは次のとおりです。

npx skills add vercel/ai --skill adr-skill

追加後は、アーキテクチャ上の判断をこれから行う、あるいは文書化しようとしているタイミングで、AI コーディング環境から利用します。

まず読むべきファイル

最短で効果的な adr-skill usage に入りたいなら、次の順で読むのがおすすめです。

1. SKILL.md
2. references/adr-conventions.md
3. references/review-checklist.md
4. references/template-variants.md
5. references/examples.md

そのうえで、以下も確認してください。

• scripts/bootstrap_adr.js
• scripts/new_adr.js
• scripts/set_adr_status.js

この順番には意味があります。conventions で ADR の置き場所を把握し、checklist で品質基準を確認し、template variants で構成を選び、examples で求められる具体度をつかむ流れです。

adr-skill に渡すべき入力

adr-skill が最も力を発揮するのは、次の情報を渡したときです。

• 下したい判断そのもの
• いまその判断が必要になったきっかけや問題
• リポジトリの文脈と既存アーキテクチャ
• レイテンシ、コスト、コンプライアンス、デプロイ方式、チーム体制などの制約
• 非ゴール
• 影響を受ける想定のファイル、モジュール、サービス、ワークフロー
• すでに検討した代替案

これらがなくても下書き自体は作れますが、その場合の adr-skill は、実行可能な ADR というより汎用的な ADR 文面になりがちです。

粗いアイデアを強いプロンプトに変える方法

弱いプロンプトの例:

• “Write an ADR for switching databases.”

adr-skill usage 向けに強くしたプロンプトの例:

• “Create an ADR proposing SQLite for local dev and CI while keeping PostgreSQL in production. Context: shared Postgres makes tests flaky and adds 3+ minutes to CI setup. Constraints: local setup must work offline, CI setup under 10 seconds, production schema remains Postgres-compatible. Non-goals: no production migration, no full ORM rewrite. Affected paths likely include src/db/, test setup, and CI config. Include implementation plan and verification steps.”

後者のプロンプトなら、adr-skill は、別のエンジニアやエージェントが実際に実装へ進めるレベルの判断文書を書けるだけの材料を得られます。

テンプレートは意図して選ぶ

判断内容がほぼ固まっていて、「なぜそうするのか」「何が変わるのか」「どう実装するのか」を整理して残すのが主目的なら、simple template が向いています。

一方で、現実的な競合案が複数あり、判断要因も多く、関係者にトレードオフをレビューしてもらう必要があるなら、MADR-style template のほうが適しています。スキルには次の両方のパターンが含まれています。

• assets/templates/adr-simple.md
• assets/templates/adr-madr.md

実務での典型的な adr-skill ワークフロー

実際の運用では、次の流れが現実的です。

1. その変更が ADR に値するかをスキルに確認する
2. 背景、制約、非ゴールについて質問してもらう
3. 適切なテンプレートで ADR の下書きを作る
4. references/review-checklist.md で妥当性を確認する
5. リポジトリ固有のパス、命名、慣習に合わせて調整する
6. 選んだ ADR ディレクトリにファイルを作成または更新する
7. 必要に応じて、後から lifecycle status を変更する

ここで adr-skill guide としての価値が出ます。初稿を書くところだけでなく、ADR のライフサイクル全体を支えられる点が強みです。

ADR がないリポジトリで adr-skill を立ち上げる方法

まだ ADR の構造がないリポジトリでは、同梱されている次のスクリプトが便利です。

• scripts/bootstrap_adr.js

このスクリプトで、ADR ディレクトリの作成、index/README の生成、最初の “Adopt architecture decision records” ドキュメントの追加まで行えます。フォルダ構成を手作業で決めるより実用的なのは、ディレクトリ検出や命名戦略といった慣習上の選択が、すでにリポジトリ側にコード化されているためです。

新しい ADR を速く作る方法

繰り返し使える作成フローがほしいなら、scripts/new_adr.js を確認してください。次のような実務的オプションに対応しています。

• repo root
• ADR directory override
• title
• status
• template choice: simple or madr
• filename strategy
• deciders, consulted, and informed fields
• index updates

そのため、adr-skill install は、一回限りの文章生成よりも、チームで再現性ある運用をしたい場合により価値が高くなります。

ステータス変更の扱い

同梱の scripts/set_adr_status.js は、ADR の status をその場で更新します。これは、ADR を固定の markdown ファイルではなく、proposed、accepted、rejected、deprecated、superseded といった状態を持つ生きた文書として扱うチームにとって重要です。

出力品質に効くリポジトリ慣習

このスキルは ADR 品質について明確な方針を持っています。

• 制約は測定可能であるべき
• 非ゴールは明示されるべき
• consequences は後続タスクにつながるべき
• implementation plans では実際のパス名を挙げるべき
• verification では判断が正しく実装されたことの確認方法を示すべき

このあたりがプロンプトから抜けると、文章自体がきれいでも、出力の実用性は大きく落ちます。

揃えるべきディレクトリ・命名ルール

references/adr-conventions.md によれば、このスキルはまず既存リポジトリの慣習を優先し、それがない場合に docs/decisions/ や adr/ のような配置を提案します。ファイル名も、リポジトリに別ルールがない限り、YYYY-MM-DD-title-with-dashes.md のような予測しやすい形式を推奨します。

つまり、既存プロジェクトのパターンを無視して、adr-skill のデフォルトだけを機械的に押し付けるべきではありません。

adr-skill スキル FAQ

adr-skill は普通のプロンプトより優れている？

はい。目的が、長く使える実装志向の ADR を作ることなら、adr-skill のほうが有利です。一般的なプロンプトでも読みやすい文書は作れますが、adr-skill は、判断のきっかけ、測定可能な制約、非ゴール、実装計画、レビュー基準まで構造化して扱います。多くの場合、そのぶん場当たり的なプロンプトより曖昧さを減らせます。

adr-skill は初心者にも向いている？

はい。ただし注意点が 1 つあります。adr-skill は初心者がよりよい ADR を書く助けにはなりますが、不足しているアーキテクチャ文脈を勝手に補ってはくれません。ADR 自体に不慣れでも、examples や template variants があるので学習コストは下げやすいです。一方で、文書化対象のシステムそのものに詳しくないなら、まず必要な情報を集める工程が必要になります。

adr-skill が向かないケースは？

次のような場合は adr-skill を使わないほうがよいこともあります。

• 変更が小さく、すぐ戻せる
• 短い設計メモだけで足りる
• チームが ADR を継続的に保守しない
• 誰もその文書を実装の指針として使わない

このようなケースでは、求められる判断の重さに対して構造が重たく感じられるはずです。

adr-skill は更新や superseded ADR にも対応できる？

はい。adr-skill は新規 ADR 作成専用ではありません。判断の更新、accept、reject、deprecate、supersede に対応しており、アーキテクチャが固定ではなく変化していくリポジトリでは重要な特性です。

adr-skill は technical writers にも有効？ それともエンジニア向けだけ？

両方に有効です。Technical Writing の用途では、adr-skill は「何が変わるのか」「なぜ今なのか」「何をスコープ外とするのか」「実装をどう検証するのか」に必ず答えるよう促してくれます。そのため、エンジニアリングチームや将来の保守担当者にとって、より使える文書になります。

同梱スクリプトは必須？

いいえ。adr-skill は、下書き作成やレビュー補助のためだけに使うこともできます。スクリプトが効いてくるのは、リポジトリ全体で作成方法、初期セットアップ、status 更新を標準化したいときです。

adr-skill スキルを改善する方法

adr-skill にはトピックだけでなく判断の引き金を渡す

adr-skill の出力を最も改善しやすいのは、「なぜ今この ADR が必要なのか」をはっきり伝えることです。たとえば “Need an ADR for caching” では弱すぎます。対して “Current API p95 is 900ms, traffic doubled, and we need sub-200ms reads for product search” のように書けば、文書全体の軸が定まります。引き金の情報は ADR 全体の形を決めます。

具体的な制約と閾値を明示する

adr-skill は、測定可能な判断を前提に設計されています。可能な限り、数字や上限を入れてください。

• latency targets
• cost ceilings
• compatibility requirements
• rollout windows
• compliance constraints
• operational ownership boundaries

これによって、抽象的なアーキテクチャ説明から、意思決定として機能する文書へと一段引き上げられます。

早い段階で非ゴールを入れる

多くの ADR が失敗するのは、含意が広がりすぎるからです。何を明確にスコープ外とするのかを adr-skill に伝えてください。

• no migration of production data
• no API version change
• no vendor lock-in decision in this ADR
• no UI redesign

非ゴールが明確だと、スコープの膨張を抑えられ、implementation plan も現実的になります。

実在するパスやパターンを示す

使える implementation plan がほしいなら、リポジトリ内の実際のファイル、モジュール、類似コードを具体的に示してください。たとえば次のような形です。

• “Follow the pattern in src/payments/stripe.ts.”
• “Avoid adding logic to pages/api/*; use route handlers under app/api/.”
• “Config lives in infra/terraform/ and .github/workflows/.”

これは adr-skill skill の出力品質を上げるうえで、特に効きやすいポイントのひとつです。

初稿のあとにレビュー checklist を使う

最初の出力で止めないでください。ADR を references/review-checklist.md と照らし合わせ、特に次を確認します。

• newcomer が trigger を理解できるか
• constraints は実行に移せるレベルで具体的か
• affected paths が明記されているか
• follow-up tasks と verification steps が明示されているか
• consequence が判断内容の言い換えで終わっていないか

この checklist に、スキルの実務的な価値がかなり詰まっています。

判断の形に合ったテンプレートを選ぶ

よくある失敗は、単純な選択に options-heavy な MADR 構成を使ってしまうこと、あるいは関係者にトレードオフ記録が必要なのに simple template を選んでしまうことです。判断の複雑さにテンプレートを合わせると、ADR の読みやすさを保てます。

プレースホルダー止まりの文章を残さない

リポジトリ内の examples からも、placeholder text をそのまま実運用の ADR に残すべきではないことが明確に示されています。初稿に “use best practices” や “update relevant files” のような曖昧表現があるなら、次のような運用レベルの詳細に書き換えてください。

• specific dependency versions
• named configs
• migration order
• rollout or rollback checks
• exact test classes or suites

判断そのものだけでなく consequences を磨く

Decision セクションは練るのに、Consequences を放置する人は少なくありません。これは大きな損です。強い consequences とは、将来の実装担当者に対して、何が簡単になり、何が難しくなり、何のリスクやコストが増え、次に何が必須になるかを伝えるものです。ここが弱いと、ADR は実行の指針として機能しません。

チーム導入向けに adr-skill を改善する

adr-skill をチーム全体に広げたいなら、少なくとも次の 3 点は標準化しておくと効果的です。

• ADR directory convention をひとつに決める
• decision type ごとの default template choice を決める
• status vocabulary をひとつに揃える

これで運用の摩擦が減り、同梱スクリプトもリポジトリ横断で使いやすくなります。

公開前の最終チェック

adr-skill で作成した ADR を accept する前に、最後にひとつ厳しい問いを投げてください。「隠れた属人的知識がなくても、この変更をコーディングエージェントが実装できるか？」です。答えが no なら、yes になるまで、背景、パス、パターン、制約、verification steps を補ってください。