architecture-decision-records

architecture-decision-records スキルの概要

architecture-decision-records で実際にできること

architecture-decision-records スキルは、AI エージェントが Architecture Decision Records（ADR）を、単なる「ADRを書いて」という汎用プロンプトよりも明確な構成で下書き・改訂・保守できるようにするためのスキルです。技術的な意思決定を長期的に残したいチーム向けに作られており、なぜその判断が必要だったのか、何を選んだのか、どの選択肢を比較したのか、その結果どんな影響があるのかを記録しやすくします。

技術文書作成とエンジニアリングチームに向いているケース

このスキルは、Technical Writing、スタッフエンジニア、アーキテクト、プラットフォームチーム、エンジニアリングマネージャーなど、プロジェクトをまたいで一貫した意思決定記録を残したい人に特に向いています。単に「文書を書く」のではなく、「後から読んでも信頼できる形で判断理由を残す」ことが求められる場面で真価を発揮します。

本当に解決したい仕事は何か

多くのチームが困るのは、ADR のタイトルを考えることではありません。散らばった背景情報を、レビューしやすく、他の判断と比較でき、半年後にも役立つ意思決定記録へ落とし込むことです。architecture-decision-records スキルの価値は、曖昧なアーキテクチャメモではなく、ADR の核となる要素――背景、決定内容、代替案、結果――を中心に据えている点にあります。

通常のプロンプトと何が違うのか

最大の違いは、構造化されていることです。このスキルは ADR のベストプラクティスを前提にしており、たとえば次のような観点を明示的に扱います。

• ADR を書く価値があるケースと、やりすぎになるケースの見極め
• proposed、accepted、rejected、deprecated、superseded といった代表的なライフサイクル状態
• MADR スタイルのような標準テンプレート
• 自由記述ではなく、意思決定を軸にした文書化

そのため、多数の意思決定に対して再現性のある品質でドキュメントを残したい場合、普通のプロンプトより適しています。

architecture-decision-records が有力な選択肢になる場面

architecture-decision-records スキルは、たとえば次のような判断に向いています。

• 新しいフレームワークやプラットフォームの採用
• データベースやメッセージングシステムの選定
• API やシステム連携パターンの定義
• セキュリティアーキテクチャ方針の決定
• 長期的な影響を持つトレードオフの文書化

一方で、定常的なメンテナンス、バグ修正、細かな実装上の判断であれば、このスキルは必要以上に手続き的になりがちです。

architecture-decision-records スキルの使い方

architecture-decision-records のインストール場所

このスキルは wshobson/agents リポジトリ内の次の場所にあります。

plugins/documentation-generation/skills/architecture-decision-records

よくあるインストール方法は次のとおりです。

npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

もし利用環境で別のスキルローダーを使っている場合でも、重要なのはスラッグが architecture-decision-records であることです。

最初に読むべきファイル

まず確認するのは次のファイルです。

SKILL.md

このリポジトリパスでは、実質的に意味のあるソースはこの 1 ファイルだけです。導入が速いという意味では利点ですが、そのぶん出力品質は与えるプロンプトの文脈に大きく左右されます。

このスキルがうまく機能するために必要な入力

architecture-decision-records スキルは、単なるトピックではなく、意思決定に使える状態の情報を渡したときに最も力を発揮します。エージェントには次のような情報を与えてください。

• 何を決めるのか
• ビジネス上または技術上の背景
• 制約条件と非目標
• すでに検討した代替案
• 選定基準
• 想定される影響やリスク
• 現在の状態: proposed、accepted、rejected、deprecated、superseded

これらがない場合でも体裁の整った ADR のひな型は作れますが、判断理由はどうしても抽象的になります。

あいまいな依頼を強いプロンプトに変える

弱いプロンプト:

Write an ADR about using PostgreSQL.

より強いプロンプト:

Draft an ADR for selecting PostgreSQL as the primary relational database for our B2B SaaS platform. Context: we are replacing a single-tenant MySQL deployment, need strong transactional guarantees, support for JSON columns, and managed cloud hosting. Alternatives considered: MySQL 8, PostgreSQL, CockroachDB. Constraints: team already knows SQL but not distributed SQL operations; must run in AWS; migration must complete within 2 quarters. Include status as Proposed, decision drivers, tradeoffs, consequences, and when this ADR should be revisited.

後者のように情報を与えると、このスキルは推測頼みのテンプレートではなく、実際に判断に使える意思決定記録を出しやすくなります。

architecture-decision-records 活用のおすすめワークフロー

実務で使いやすい architecture-decision-records usage の流れは次のとおりです。

1. issue スレッド、RFC、設計ドキュメントから判断材料を集める。
2. その変更が ADR に値するかを判断する。
3. 希望するフォーマットを指定してスキルに ADR の下書きを作らせる。
4. 代替案の抜け、根拠の弱さ、影響の曖昧さがないかレビューする。
5. レビューや承認の結果に応じて status を更新する。
6. 判断が変わった場合は superseding ADR へのリンクを付ける。

このスキルが特に役立つのは、断片的な判断材料を、長く使える安定した文書形式へ圧縮する場面です。

下書き前にテンプレートを決める

元の内容では、標準的な ADR 方式と MADR スタイルのテンプレートが強調されています。プロンプトを書く前に、次のどれを使いたいか決めておくとよいでしょう。

• 簡潔な標準 ADR
• 代替案と結果を明示する MADR 風の構成
• 自分たちのリポジトリ運用に合わせた独自スタイル

チームですでに ADR の採番や見出し順が決まっているなら、最初にそのルールを伝えてください。そうしないと、内容は妥当でも手作業で整形し直す必要が出ることがあります。

Technical Writing 用途で含めたい内容

architecture-decision-records for Technical Writing として使うなら、承認者だけでなく将来の読者にとって読みやすい形を意識させるのが効果的です。追加で指示するとよいポイントは次のとおりです。

• 略語は最初に一度定義する
• 背景と decision drivers を分けて書く
• 却下した選択肢をなぜ却下したか説明する
• 技術的な利点だけでなく運用上の影響も書く
• スケール、コンプライアンス、コスト閾値など見直しトリガーを含める

こうすることで、オンボーディング、監査、引き継ぎでも使いやすい文書になります。

再利用しやすい実践的なプロンプトの型

次のような枠組みでプロンプトを作ると使いやすくなります。

• Decision title
• Status
• Date or ADR number
• Context
• Problem statement
• Constraints
• Alternatives considered
• Decision
• Consequences
• Open questions
• Intended audience
• Required format or headings

この型は、推測で埋める余地を減らし、追跡可能性を高めるため、architecture-decision-records usage の質を安定して改善します。

インストール前に理解しておきたい限界

このスキルはあくまで文書化に特化しています。アーキテクチャ上の選択が客観的に正しいかどうかを検証してくれるわけではありません。得意なのは、判断理由やトレードオフを言語化することです。ベンチマーク、アーキテクチャモデリング、自動ポリシーチェックまで求めるなら、それらを先に行い、このスキルはその後段で使うべきです。置き換え先にはなりません。

リポジトリを読んだうえでの実務的な結論

このスキルパッケージは実質 SKILL.md が中心なので、導入自体は簡単です。先に理解すべき helper script、reference bundle、rule file はありません。その代わり、出力の良し悪しは組み込みの自動化よりも、入力情報の具体性とレビュー運用の丁寧さに強く依存します。

architecture-decision-records スキル FAQ

すでに LLM に直接プロンプトできるなら、architecture-decision-records を入れる価値はある？

あります。特に ADR を継続的に書くチームなら有効です。汎用プロンプトでも単発で見栄えのよい文書は作れますが、architecture-decision-records skill は、繰り返し発生する意思決定の記録に対して、より明確な標準フレームを与えてくれます。価値は一貫性と、特に代替案や結果の書き漏らしを減らせる点にあります。

初心者でも使いやすい？

はい。ADR の基本概念である背景、決定、結果に加え、ADR を書くべき場面と省いてよい場面も説明されています。そのため、ADR 運用に不慣れなチームでも使いやすい構成です。ただし、初心者であっても実際のプロジェクト文脈は自分たちで与える必要があります。組織固有の制約までは、このスキル単体では推測できません。

architecture-decision-records を使わないほうがよいのはいつ？

変更が小さく、定型的で、実装レベルに閉じる場合は使わないほうがよいでしょう。

• patch upgrade
• bug fix
• routine maintenance
• 影響の小さい設定変更

この種の変更なら、issue コメントや changelog の記録だけで十分なことが多いです。

RFC とはどう違う？

RFC は一般に範囲が広く、探索的で、方向性が収束する前に書かれることが多い文書です。一方 ADR は、より狭い範囲で、決定事項そのものを中心に据えます。議論が成熟したあとに、「何を決め、なぜそうしたのか」を長く残る形で記録したいなら architecture-decision-records が適しています。

既存の docs リポジトリでも使える？

はい。/docs/adr/、/adr/ のようなフォルダ構成があるリポジトリと相性がよいです。すでに ADR-0001 のような採番ルールがあるなら、生成文書が既存運用に合うよう、プロンプト内で明示してください。

古い ADR のメンテナンスにも役立つ？

はい。元のスキルで示されている proposed、accepted、rejected、deprecated、superseded といったライフサイクルモデルは、更新時にも有効です。このスキルは新規の判断を書くためだけのものではなく、古くなった ADR を、より明確な status や相互リンク付きで改訂・置き換える用途にも向いています。

architecture-decision-records スキルを改善する方法

好みの結論だけでなく decision drivers を渡す

architecture-decision-records の出力を最も手早く改善する方法は、その判断を押した要因を具体的に渡すことです。

• スケール要件
• レイテンシ要件
• コンプライアンス上の義務
• 人員や体制の制約
• コスト上限
• 移行スケジュール

採用したい技術名だけを伝えると、その ADR は後付けの正当化のように見えやすくなります。

実際に比較した代替案と検討理由を示す

弱い ADR では、代替案が一つだけ軽く触れられるか、形だけの選択肢が並ぶことが少なくありません。よりよいプロンプトでは、現実的に検討対象だった代替案と、なぜ候補に上がったのかを明示します。そうすることで、このスキルは抽象的な比較ではなく、実用的なトレードオフ整理を出しやすくなります。

status と見直し条件を明確にする

その ADR が次のどれにあたるのかを、スキルにはっきり伝えてください。

• Proposed
• Accepted
• Rejected
• Deprecated
• Superseded

あわせて、どんな条件で再評価するのかも書いておくと有効です。これにより保守性が上がり、まだレビュー中なのに確定事項のように見えてしまう問題を防げます。

複数の観点で consequences を書かせる

より強い architecture-decision-records guide のプロンプトでは、次のような複数の軸で consequences を求めると効果的です。

• エンジニアリングの複雑さ
• 運用
• セキュリティ
• コスト
• チームの学習コスト
• 将来の柔軟性

1 行だけの “pros and cons” より、意思決定に役立つ ADR になりやすくなります。

よくある失敗パターンを見逃さない

典型的な弱い出力には次のようなものがあります。

• どのプロジェクトにも当てはまりそうな一般論の背景
• 却下した代替案がない
• メリットだけでコストが書かれていない
• 決定文が広すぎて実装に落とせない
• スコープや影響を受けるシステムが示されていない

こうした問題が見えたら、多くの場合はテンプレート自体ではなく、入力情報が足りていないことが原因です。

狙いを絞った修正依頼で磨く

最初のドラフトのあとに、次のような狙いの明確なフォローアップをすると改善しやすくなります。

• Tighten the decision statement to one implementable choice.
• Expand the rejected alternatives with concrete tradeoffs.
• Add operational consequences for deployment and monitoring.
• Rewrite the context so a new team member understands the trigger.
• Mark what assumptions would invalidate this ADR.

単に「もっとよくして」と頼むより、こちらのほうが効果的です。

自社の ADR 標準に合わせて出力を寄せる

組織独自のテンプレートがあるなら、標準的な ADR 要素を自分たちの見出しに割り当てるよう依頼してください。たとえば次のような項目が必須かもしれません。

• ownership
• review date
• compliance impact
• rollout plan
• links to tickets or PRDs

architecture-decision-records install を導入するかどうかは、こうした構造化された下書き支援が自社のドキュメント運用に合うかで判断するとよいでしょう。

リンク運用を徹底して長期的な価値を高める

優れた ADR 集は、あとからたどりやすい状態になっています。スキルには次のような情報も含めるよう求めると効果的です。

• 関連 ADR
• superseded-by 参照
• 影響を受けるシステム
• 設計ドキュメントやインシデントレポートへのリンク

こうすることで、単発の文書ではなく、使える意思決定履歴の一部になります。

初回利用後に architecture-decision-records を評価する最良の方法

受け入れテストとしては、次の問いに新しく入ったエンジニアが生成された ADR を読んで答えられるかを見るのが簡単で有効です。

• どんな問題があったのか
• 何を決めたのか
• どの代替案を検討したのか
• なぜこの案が選ばれたのか
• チームはどんなトレードオフを受け入れたのか
• いつこの判断を見直すべきか

もし答えられないなら、プロンプトを具体化し、よりよい元情報を与えたうえで architecture-decision-records skill を再実行してください。