architecture-decision-records
作成者 affaan-marchitecture-decision-records は、Claude Code のセッション中に生まれるアーキテクチャ上の判断を、構造化された ADR として記録できるスキルです。意思決定のタイミングを捉え、背景、選択肢、判断理由を整理して残し、将来の保守担当者のために ADR の履歴を維持します。長く参照できる意思決定の記録が必要な Technical Writing やエンジニアリングチームに向いています。
このスキルの評価は 78/100 です。ADR としてアーキテクチャ判断を残したいユーザーにとって、エージェントで扱いやすい有力な掲載候補といえます。導入判断に必要な情報は十分ありますが、リポジトリにはワークフローが 1 つの `SKILL.md` にまとまっているだけで、補助スクリプトや参照資料は用意されていない点に注意が必要です。
- 意思決定の場面、トレードオフの検討、「なぜ X を選んだのか？」といった問いなど、このスキルを使うタイミングが明確に示されています。
- コンテキスト、決定内容、代替案を整理できる具体的な ADR テンプレートと構造化セクションがあり、エージェントの推測に頼る余地を減らせます。
- プレースホルダーのままの記述がなく、ガイダンス量も十分で、デモ用の雛形ではなく実運用を意識した内容になっています。
- 補助ファイル、スクリプト、参照資料がないため、利用時は markdown の説明だけを頼りに進める必要があります。
- install command やリポジトリ全体の案内がなく、初めて使うユーザーには導入手順がやや見えにくい可能性があります。
architecture-decision-records スキルの概要
architecture-decision-records スキルでできること
architecture-decision-records スキルは、コーディングセッション中に進行中のアーキテクチャ上の判断を、その場で軽量な ADR に落とし込むためのスキルです。後から汎用的な要約を作るのではなく、意思決定のポイントを見つけ、前提やトレードオフを記録し、リポジトリに残せる構造化された記録としてまとめることを目的にしています。
Technical Writing とエンジニアリングチームに向くケース
AI 支援開発を進めるチーム、判断の履歴を長く残したいテックリード、そしてシステムドキュメントの一次情報を必要とする Technical Writing のワークフローに特に向いています。実際に解決するのは「markdown を書くこと」ではありません。チームがなぜその方針を選んだのかという理由を、チャット、コミット、記憶の中に埋もれる前に残しておくことです。
通常のプロンプトと何が違うのか
通常のプロンプトでも、ADR テンプレートを一度出力することはできます。ですが architecture-decision-records スキルが真価を発揮するのは、複数のセッションにまたがって意思決定が繰り返し発生する場面です。たとえばフレームワーク選定、API パターン、データストア、デプロイ設計、廃止判断などです。違いは、起動条件の考え方と、Michael Nygard の軽量スタイルに基づく一貫した ADR 構造にあります。
導入前に知っておきたい注意点
このスキルは意図的に用途を絞っています。単体でアーキテクチャレビュー、ガバナンス、リポジトリ固有の標準を置き換えるものではありません。さらに、提供物は補助スクリプトや検証ツールなしの単一 SKILL.md であるように見えるため、出力品質はプロンプトの質とリポジトリ側の運用ルールに強く左右されます。
architecture-decision-records スキルの使い方
インストール時の前提と最初に読むべき場所
architecture-decision-records の導入では、まず親となる skill collection を Claude Code の skills ワークフローに追加し、そのうえで skills/architecture-decision-records/SKILL.md を最初に確認してください。見える範囲では companion の rules/、resources/、自動化ファイルはないため、実用的なガイダンスのほぼすべてがその 1 ファイルに入っています。読む順番は When to Activate、ADR Format、最後に markdown fence 内の例、という流れがおすすめです。
うまく機能させるために必要な入力
architecture-decision-records スキルは、次の情報があると精度が上がります。
- 何を意思決定しようとしているのか
- 真剣に比較した代替案は何か
- コスト、性能、チームの習熟度、納期、コンプライアンス、移行リスクなどの制約
- 誰が決めたのか、現在の状態は何か（
proposed、accepted、deprecated、superseded） - ADR の保存先、命名規則、採番ルール
弱い入力: “Write an ADR for using Postgres.”
強い入力: “Create ADR-0012 for choosing Postgres over DynamoDB for transactional order processing. Context: multi-row consistency, existing SQL skills, moderate scale, AWS deployment, 3-month delivery window. Status accepted. Deciders: platform lead, backend lead.”
曖昧な依頼を、実用的な invocation prompt に変える
architecture-decision-records スキルを実務で活かすなら、「抽出」と「整形」を両方依頼するのが効果的です。プロンプトの型としては、次のような形が使いやすいです。
“Use the architecture-decision-records skill. From this discussion, identify whether an ADR should be created. If yes, draft it in Michael Nygard style with Context, Decision, and Alternatives Considered, and note any missing facts you need before finalizing.”
この言い回しが重要なのは、スキルが最も役立つのは判断がまだ固まりきっていない段階だからです。意思決定ポイントを検出し、ADR の草案を作りつつ、根拠を勝手に作り込むのではなく不足情報を表に出せるようになります。
実際のリポジトリでのおすすめ運用フロー
- 計画中または実装中に、意味のある意思決定を検知する。
- エージェントに architecture-decision-records スキルの使用を指示し、ADR の草案を作らせる。
- 事実関係、とくに却下した代替案や制約条件をレビューする。
docs/adr/やadr/のような固定フォルダに保存する。- PR、アーキテクチャ文書、オンボーディング資料からその ADR を参照する。
Technical Writing では、ADR に短い “impact” メモを添えると有効です。API、インフラ、将来の移行について、読者が今後何を前提にすべきかを一言で示します。そうすることで、エンジニア同士の会話履歴を超えて再利用しやすい ADR になります。
architecture-decision-records スキル FAQ
すでに ADR をプロンプトで書けるなら、architecture-decision-records を入れる価値はある？
あります。特に課題が markdown の整形ではなく、一貫性と記録のタイミングにあるなら有効です。architecture-decision-records スキルは、「数週間後ではなく、決まったその時点で記録する」という明確なトリガーをエージェントに与えます。単発で ADR テンプレートがほしいだけなら、通常のプロンプトでも十分な場合があります。
初心者にも向いている？
はい。ただし注意点が 1 つあります。初心者でも有用な ADR 草案は作れますが、どの制約が重要なのか、どの代替案が本当に比較対象だったのかを見極めきれないことがあります。このスキルは思考の整理には役立ちますが、受け入れ前に技術的なトレードオフをレビュー担当者が確認すべきです。
どんな場面では使わないほうがいい？
些細な実装詳細、一時的な実験、長期的なアーキテクチャ影響を持たない判断には使わないほうがよいです。記録しすぎると ADR がノイズ化します。architecture-decision-records を使うべきなのは、将来のメンテナーが「なぜこのスタック、このパターン、この境界、この連携なのか」と疑問に思うような選択です。
Technical Writing の仕事にはどうはまる？
architecture-decision-records スキルは、理由や背景を発生源に近い場所で記録できるため、Technical Writing と相性が良いです。ライターは承認済み ADR をもとに、システム概要、移行ノート、FAQ、オンボーディング資料を作れます。散在したチャットや PR コメントを後からつなぎ合わせて判断理由を再構成する必要が減ります。
architecture-decision-records スキルを改善する方法
テーマだけでなく、良い一次情報を渡す
品質を最も左右するのは具体性です。制約、却下した選択肢、そして実際にその判断を強いた要因を含めてください。“We picked Redis for caching” では弱すぎます。“We picked Redis over in-process caching because we need shared invalidation across workers and predictable behavior in horizontal scaling” のほうがはるかに有効です。architecture-decision-records スキルが残せるのは、入力として与えられた理由だけです。
よくある失敗パターンを防ぐ
ありがちな問題は、文脈が曖昧、代替案が形だけ、結論だけが妙に自信満々、というパターンです。草案を読んで「最初から自明だった」ように見えるなら、トレードオフをもっと広げるようエージェントに求めてください。代替案が浅いなら、本当に比較した上位 2〜3 案を明示します。まだ判断が暫定なら、無理に accepted にせず proposed のままにしておくべきです。
ADR 出力を自分のリポジトリ標準に合わせる
upstream のスキルは軽量な ADR 構造を採用していますが、チームによっては consequences、links、owners、review date などの追加項目が必要です。architecture-decision-records の使い方を改善するには、どの見出しがリポジトリで必須か、ファイルをどこに置くかをエージェントに明示してください。そうしないと、内容はよくても整形だけ後でやり直す草案になりがちです。
architecture-decision-records の初稿を出したあとに改善を重ねる
最初の出力は完成版ではなく、意思決定のチェックポイントとして扱ってください。たとえば次のような追質問が有効です。
- “What assumptions in this ADR are unstated?”
- “Which alternative deserves a fairer treatment?”
- “What future reversal signals should we document?”
- “What code areas or docs should link to this ADR?”
こうした追質問によって、architecture-decision-records スキルは単なるテンプレート穴埋め以上の価値を持ちます。特に、数か月後にも読み返される ADR にしたい場合に効果的です。