Claude Media
Claudeのarchitectureスキル(ADR)で技術選定の決定記録を書く
Claude CodeCoworkClaude連携チュートリアル

Claudeのarchitectureスキル(ADR)で技術選定の決定記録を書く

engineeringプラグインのarchitectureスキルは、技術選定をADR形式で書き出します。導入手順、ADRの各欄、モードの使い分け、チームの規約に載せる方法を説明します。

読了目安 約13分

engineeringプラグインのarchitectureスキルは、技術選定や設計判断をアーキテクチャ決定記録(ADR、Architecture Decision Record)の形で書き出すスキルです。「KafkaとSQSのどちらを使うか」のような問いを渡すと、背景・選択肢・トレードオフ・帰結を固定の欄に並べて返します。

提供元はAnthropicのknowledge-work-pluginsリポジトリです。engineeringプラグインはCowork向けに設計されていますが、Claude Codeでも動きます。この記事では、入れ方、ADRの各欄が何を求めるか、3つのモードの使い分け、チームの規約に載せる方法を順に説明します。

architectureスキルが書き出すもの

SKILL.mdの説明文は、このスキルを「ADRの作成または評価」と位置づけています。使う場面として挙がっているのは次の4つです。

  • 技術を選ぶとき(例: KafkaとSQS)
  • トレードオフと帰結つきで設計判断を残すとき
  • 設計提案をレビューするとき
  • 要件と制約から新しいコンポーネントを設計するとき

呼び出しは /architecture に引数を続ける形です。引数のヒントは <decision or system to design> で、決めたいことか、設計したい系を文章で渡します。プラグインのコンポーネントは名前空間つきで呼ばれるので、Claude Codeの対話では /engineering:architecture と打つのが確実です。

engineeringプラグインのREADMEでは、/architecture はコマンドとして一覧されています。リポジトリ上の実体は skills/architecture/SKILL.md で、Claudeが話題に応じて自動で使う場合もあります。

engineeringプラグインを入れる

導入は2コマンドです。マーケットプレイスを追加してから、プラグインを入れます。

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install engineering@knowledge-work-plugins

Claude Codeの対話の中なら、/plugin marketplace add で同じマーケットプレイスを追加できます。/plugin install はすぐには入れず、/plugin パネルの詳細画面を開いて、範囲(スコープ)を選ばせます。

プロジェクトのスコープで入れると、有効化の記述が .claude/settings.json に入ります。コミットすれば共同作業者の設定でも有効になりますが、各自のマシンへのダウンロードは別です。メンバーごとに claude plugin install engineering@knowledge-work-plugins --scope project を1回実行します。

入れ終えたら、次の形で試せます。

/engineering:architecture イベント基盤にKafkaとSQSのどちらを使うか。
チームは4人、AWS上で運用、ピークは1万rps、2週間で出したい

SKILL.mdの「Tips」は、制約を先に書くことを勧めています。「2週間で出す」「1万rpsを捌く」のような条件が、結論を左右するためです。

ADRの欄は何を求めるか

出力フォーマットは固定で、次の順に並びます。

欄書く内容
タイトル書く内容ADR-[番号]: [題名]
Status書く内容Proposed / Accepted / Deprecated / Supersededのどれか
Date書く内容決定日
Deciders書く内容承認が要る人
Context書く内容状況と、働いている力
Decision書く内容提案する変更
Options Considered書く内容選択肢ごとの評価表と、Pros / Cons
Trade-off Analysis書く内容選択肢間の主なトレードオフと、その理由
Consequences書く内容楽になること、難しくなること、見直すこと
Action Items書く内容実装手順とフォローアップ(チェックボックス)

選択肢の評価表には、Complexity、Cost、Scalability、Team familiarityの4行があります。ComplexityはLow / Med / Highで答える欄です。Costなど残りの3行は評価の文章で埋めます。

注目したいのはConsequencesです。「楽になること」「難しくなること」「見直すこと」の3つに分けて書く形になっています。決定の利点だけでなく、引き受ける不利益と将来の見直し点まで、決定時に記録に残る構造です。

次は、フォーマットに沿った書き出しの例です。これは欄の使い方を示す例で、実際の出力ではありません。

# ADR-0007: イベント基盤にSQSを採用する
 
**Status:** Proposed
**Date:** 2026-10-27
**Deciders:** バックエンドリーダー、SRE
 
## Context
ピーク1万rps、運用は4人、リリースまで2週間。すでにAWS上で運用している。
 
## Decision
イベント基盤はSQSで始める。
 
## Consequences
- 楽になること: 運用するサーバーがなく、初期構築が短い
- 難しくなること: 複数の購読者へ同じイベントを配る設計
- 見直すこと: 購読者が増えた時点でKafkaを再評価する

Optionsの評価表やPros/Consは省いています。実際に使うときは、フォーマット全体が埋まった形で返ってきます。

3つのモードを使い分ける

SKILL.mdはモードを3つ挙げています。

モード

architectureスキルの3モード

  • ADRを作る

    「イベント基盤にKafkaとSQSのどちらを使うか」のように、選択肢のある決定を渡します。上のフォーマットで返ります。

  • 設計を評価する

    「このマイクロサービス案をレビューして」のように、既存の提案を渡します。提案の側が決まっているときの使い方です。

  • システムを設計する

    「アプリの通知システムを設計して」のように、要件から組み立てさせます。

3つ目のモードでは、system-designスキルの枠組みが使われます。SKILL.mdは詳細をsystem-designスキルに任せています。system-designは、要件の整理、高水準設計、深掘り、スケールと信頼性、トレードオフ分析の5段で進める作りです。出力は、図と明示された前提とトレードオフ分析を持つ設計文書で、「システムが育ったときに見直す点」を必ず挙げる指示があります。

つまり、決定そのものを記録したいときはADRのモード、決める前の設計を詰めたいときはsystem-designの枠組み、と分かれます。

過去のADRと課題管理につなぐ

architectureスキルは、コネクタが接続されていると動きが変わります。SKILL.mdの記述は次の2つです。

  • ナレッジベースがつながっていれば、過去のADRと設計文書を検索し、技術的な背景を探す
  • プロジェクト管理がつながっていれば、関連するエピックとチケットにリンクし、実装タスクを作る

プラグインのCONNECTORS.mdでは、ナレッジベースの同梱サーバーはNotion、プロジェクト管理はLinear、Asana、Atlassian(Jira・Confluence)です。ほかのサーバーでも、同じカテゴリなら代用できると書かれています。

ADRを重ねる運用では、過去の決定と矛盾しないかを確かめる作業が増えます。ナレッジベースをつなぐと、その確認をスキルに任せられます。つなぎ先がなくても、スキルは単体で動きます。READMEは「システムを説明するだけでよい」としています。

ADRの保存先と運用ルールをCLAUDE.mdに書く

SKILL.mdには、ADRをどのファイルに保存するかの指定がありません。書き出した文章をどこに置くかは、チーム側で決める必要があります。ここは、Claude Codeの側で規約を持たせると安定します。

プロジェクトのCLAUDE.mdに、次のような節を足します。保存先やファイル名の付け方は一例で、チームの慣行に合わせて変えます。

## 設計判断の記録
- 技術選定や設計方針を変えるときは /engineering:architecture でADRを作る
- ADRは docs/adr/ に、連番付きのMarkdownとして保存する
- 新しいADRのStatusは Proposed で出し、承認後に Accepted へ変える
- 既存ADRを覆すときは、旧ADRを Superseded にして新ADRから参照する

Statusの4値と、Supersededの意味は、フォーマットがそのまま持っています。置き換えた決定を消さずに、状態として残す使い方です。

ADRを書く運用で崩れやすいのは、決めた後に更新されない点です。Action Itemsはチェックボックスで返るので、実装が進んだ時点で [x] に変える運用にすると、記録が実態に追いつきます。

チームの前提を設定ファイルに持たせる

評価表のTeam familiarityやCostは、チームの技術スタックを知らないと的外れになります。engineeringプラグインのREADMEは、engineering/.claude/settings.local.json に個人とチームの情報を置く方法を示しています。例に挙がっているキーは name、title、team、company、techStack、defaultBranch、deployProcess です。

{
  "team": "Your Team",
  "techStack": ["Python", "TypeScript", "PostgreSQL", "AWS"],
  "defaultBranch": "main",
  "deployProcess": "canary"
}

未設定のままでも、プラグインは対話で聞き返します。ADRを繰り返し書くなら、techStack と deployProcess を先に置いておくと、毎回の説明が減ります。

設計評価モードに渡す材料

「設計を評価する」モードは、ADRを作るモードより渡す情報が多くなります。SKILL.mdの例は「このマイクロサービス案をレビューして」です。案の文章かリンクに加えて、次の3点を添えると、評価が具体的になります。

  • 案が解こうとしている問題
  • 守るべき非機能要件(レイテンシ、可用性、コスト)
  • すでに検討して外した選択肢と、その理由

3点目は、そのままADRのOptions Consideredに入る材料です。評価の結果を決定記録に昇格させるときは、同じ会話で「この内容をADRにして」と続けると、前のやり取りを引き継げます。

結果を鵜呑みにしない

スキルが返すのは、渡された情報に基づく分析です。評価表のTeam familiarity(チームの習熟度)は、チームの実情を知らされなければ埋めようがありません。SKILL.mdのTipsが、非機能要件(レイテンシ、コスト、チームの専門性、保守の負担)を含めるよう勧めているのは、このためです。

選択肢を自分で名前で挙げるのも、効きます。SKILL.mdは「本命が決まっていても、選択肢を明示すればバランスの取れた分析が返る」と説明しています。

返ってきた表のCostやScalabilityは、数値の根拠までは付きません。ピークのrpsや月額の試算は、自分の環境の数字と突き合わせてから、DeciderのレビューでADRをProposedからAcceptedに進めます。

周辺のスキルと合わせる

engineeringプラグインは、architecture以外にも複数のスキルを持っています。READMEが挙げるものは次のとおりです。

スキル役割
system-design役割システムとサービスの設計、API設計、データモデリング
tech-debt役割技術的負債の洗い出しと優先順位づけ
documentation役割README、APIドキュメント、ランブックの作成
incident-response役割障害対応、ポストモーテム

決定の記録が増えると、後から「この決定の前提は今も成り立つか」を見直すことになります。そこで見つかった負債を tech-debt で整理する、という流れがつながります。

コードの変更そのものを多角的に見る手順は、Claude Codeのcode-reviewプラグインの記事にまとめています。スキルの作り込み方を見たい場合は、mattpocock skillsの導入と使い分けが別の事例です。Coworkでプラグインを探す画面は、Coworkのディレクトリの記事で扱っています。

まとめ

architectureスキルの価値は、ADRの欄を毎回同じ形で埋めさせる点にあります。とくにConsequencesの3分割が、決定の不利益と見直し点を記録に残します。保存先と運用ルールはスキルの範囲外なので、CLAUDE.mdで決めておくと、ADRが溜まったときに探しやすくなります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →