Claudeのsystem-designスキルで要件から構成とトレードオフを詰める

engineeringプラグインのsystem-designスキルは、システムやサービスの設計を、要件・全体設計・深掘り・スケール・トレードオフの5段で進めるスキルです。「通知システムを設計して」のような依頼に対して、図と前提とトレードオフ分析を備えた設計文書を返す役割を持ちます。

提供元はAnthropicのknowledge-work-pluginsリポジトリです。SKILL.mdは40行ほどの短い文書で、書かれているのは枠組みと出力の方針です。短いぶん、結果を左右するのは依頼する側が渡す材料になります。この記事では、入れ方、5段それぞれで渡すと効く情報、チーム規模や期限といった制約の渡し方、返ってきた文書の読み方を順に説明します。

system-designスキルは何を引き受けるか

SKILL.mdの説明文は、このスキルを「システム、サービス、アーキテクチャの設計」と位置づけています。呼び出しの合図として挙がっている言い回しは、「design a system for」「how should we architect」「system design for」「what's the right architecture for」の4つです。APIの設計、データモデリング、サービス境界の相談でも使われます。

出力の方針は3点です。

• 構造化された設計文書にする(図はASCIIか、言葉による説明)
• 前提を明示する
• システムが育ったときに見直す点を必ず挙げる

3点目が、このスキルの性格をよく表しています。設計の案を出して終わりにせず、「今の規模ならこれでよいが、ここが変わったら見直す」という条件まで書かせる作りです。

入れ方と呼び出し方

engineeringプラグインは、マーケットプレイスの追加とプラグインの導入の2コマンドで入ります。

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

READMEによると、engineeringプラグインはCowork向けに設計されていて、Claude Codeでも動きます。system-designはコマンドではなくスキルとして一覧されており、「関連する場面でClaudeが自動で使う知識」という扱いです。

Claude Codeでは、プラグインのスキルは /プラグイン名:スキル名 の形で呼び出せます。このスキルなら /engineering:system-design です。

/engineering:system-design 社内向けの通知基盤を設計したい。
メール・Slack・アプリ内通知に対応し、1日あたり50万通を送る

自動で選ばれる場合は、依頼の文面がスキルの説明文と合致するかで決まります。説明文の合図は英語なので、日本語で頼んだときに毎回選ばれるとは限りません。確実に使いたい場面では、名前を付けて呼ぶほうが安定します。

5段の枠組みと、各段で渡す材料

SKILL.mdの枠組みは5段です。各段に挙がっている項目と、依頼側が先に用意すると結果が具体的になる情報を、表にまとめます。

1段目の「制約」が、5段目の判断軸と同じ顔ぶれ(チーム、時間、既存技術)で再登場している点に注目です。最初に制約を渡さないと、最後のトレードオフ分析は一般論で終わります。

制約の渡し方で出力が変わる

枠組みの1段目は、制約を「チーム規模・期限・既存技術」と明記しています。これを渡すかどうかで、依頼の質が変わります。

次の2つの依頼は、同じ通知基盤の設計を頼んだ例です。どちらも依頼文の例で、返ってくる設計の実例ではありません。

後者は、規模・チーム・期限・既存技術のどれもが、1段目の要件と5段目のトレードオフに直結します。「新しい基盤技術は避けたい」の一文があれば、キューやストレージの選択がチームの習熟度を基準に比較される材料になります。

毎回書く情報は設定ファイルに置く

engineeringプラグインのREADMEは、engineering/.claude/settings.local.json に個人とチームの情報を置く方法を示しています。例に挙がっているキーは name、title、team、company、techStack、defaultBranch、deployProcess です。

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

READMEには、未設定ならプラグインが対話で聞き返すとも書かれています。設計の依頼ごとに「AWSでPostgreSQL」と書くのが手間なら、techStack を先に置いておくと、既存技術の説明を省けます。

プロジェクトの前提はCLAUDE.mdに持たせる

設定ファイルのキーは固定です。「SLAは99.9%」「個人情報を含むデータは東京リージョンから出さない」のようなプロジェクト固有の前提には向きません。こうした前提は、CLAUDE.mdに書いておくと、設計の依頼のたびに読み込まれます。

## システム設計の前提
- 本番はAWS東京リージョン。個人情報を含むデータはリージョンの外に出さない
- 可用性の目標は99.9%。計画停止は深夜帯に限る
- 新規のマネージドサービスは、運用担当の4人が学習できる範囲に限る
- 設計案には、見直す条件(規模・コスト・体制の閾値)を必ず添える

最後の行は、SKILL.mdが求める「システムが育ったときに見直す点」を、プロジェクトの決まりとして固定する書き方です。Claude Codeの全体像にあるとおり、CLAUDE.mdは毎セッションの前提を持たせる場所なので、設計の前提を置く先として相性がよい書き方です。

段ごとに区切って回す

5段を1回の依頼で全部頼むこともできますが、深掘りの段は項目が多く、1回の返答に詰め込むと各項目が薄くなります。Claude Codeの対話では、段ごとに区切る進め方が取れます。

区切るときは、前の段の結論を次の依頼文に残しておくと、会話が長くなっても前提がぶれません。要件の一覧をCLAUDE.mdやドキュメントのファイルに書き出させ、「このファイルを前提に2段目をやって」と頼む形が扱いやすくなります。

返ってきた設計文書の読み方

SKILL.mdの出力方針に沿うと、返ってくる文書には3つの要素が含まれます。それぞれ、読むときに見る点が違います。

• 図: ASCIIか言葉による説明で返る。正式な作図ツールの出力ではない
• 前提: 依頼側が渡さなかった条件を、スキルが置いた仮定。ここが現実と合っているかが最初の確認点
• 見直す点: 規模が伸びたときに変える箇所

前提は、読み飛ばさないほうがよい箇所です。たとえば「ピークは平常時の3倍」とスキルが置いていて、実際は10倍なら、その後の負荷の見積もりはすべてやり直しになります。依頼文に数字を入れておく理由は、この仮定の置き換えを減らすことにあります。

負荷の見積もりやコストは、渡された数字から計算された見積もりです。実環境の計測値ではありません。決める前に、既存の監視データや料金表の数字と突き合わせる工程が要ります。

図を作図ツールで描き直したいとき

SKILL.mdが指定する図はASCIIか言葉による説明です。Mermaidのような記法で受け取りたい場合は、依頼文でその形式を指定します。

さきほどの全体設計のコンポーネント図とデータフローを、
Mermaidのflowchartで書き直して

これはスキルの機能ではなく、会話の中での追加依頼です。Mermaidを会話内に表示する方法は、Mermaid Chartコネクタの記事で扱っています。

architectureスキルと組み合わせる

同じプラグインのarchitectureスキルは、技術選定をADR(アーキテクチャ決定記録)の形で書き出すスキルです。architectureスキルの記事によると、architectureの「システムを設計する」モードは、system-designの枠組みを使います。

2つの役割は、時間軸で分けると整理できます。

system-designの3段目や5段目で「Kafkaか、SQSか」のような分岐が出たら、その分岐だけをarchitectureに渡してADRにする流れが自然です。設計文書の全体をADRにするのではなく、後から理由を問われそうな判断だけを切り出すと、記録が肥大化しません。

設計が固まった後は、運用側のスキルにつながります。tech-debtスキルは技術的負債の棚卸しに、incident-responseスキルは障害対応の準備に使えます。リリース前の確認は、deploy-checklistが受け持ちます。

SKILL.mdに書かれていないこと

短いSKILL.mdには、運用で気になる点のいくつかが記載されていません。

• 設計文書の保存先とファイル名の決まり。保存場所はチーム側で決める
• 出力の見出しの固定形式。architectureスキルのADRにある固定の欄のような、決まった雛形はない
• コネクタとの連携。READMEのコネクタ表で、ナレッジベースとの連携が挙がっているのは「Architecture decisions」の行です。system-designに関する記載はSKILL.mdにありません
• 負荷の見積もりの根拠の示し方。数式や前提の明記の要求は「明示された前提」にとどまる

雛形が固定されていないため、毎回同じ構成の文書が欲しい場合は、依頼文かCLAUDE.mdで見出しを指定する必要があります。たとえば「要件、全体設計、データモデル、スケール、トレードオフ、見直す点の順で書く」と決めておくと、設計文書をチーム内でレビューするときに、比較しやすくなります。

まとめ

system-designスキルは、5段の枠組みと「前提を明示し、見直す点を挙げる」という出力方針だけを持つ、軽いスキルです。軽いぶん、制約を渡した分だけ設計の具体性が上がります。チーム規模・期限・既存技術は、毎回の依頼文に書くか、設定ファイルとCLAUDE.mdに持たせるかを先に決めておくと、依頼のたびの手間が減ります。構成を詰める作業にはsystem-design、選定理由を残す作業にはarchitectureと、2つを役割で分けて使うのが運用の基本線です。