system-design

システム設計（オーケストレーター）

曖昧なプロンプトから、根拠があり、徹底的に検証されたアーキテクチャへと、自由度の高い設計問題を導きます。図を思い出すのではなく、推論によって進めます。 このスキルは 手法 と 振り分け を担い、実際のコンポーネントの設計パターンは、必要に応じて呼び出す専用のビルディングブロックスキルにあります。

ここでのすべてにつながる、最も重要な考え方は次のとおりです。

アーキテクチャを暗記するのではなく、それを形作る要因を学びましょう。唯一の正解はありません。成功するかどうかは、明示する前提によって決まります。

1,000 ユーザーで動く設計が、1,000,000 ユーザーでは機能しないことがあります。あらゆるアーキテクチャを、制約が変わるまでは有効な仮説として扱い、制約が変わったら落ち着いて設計を描き直せるようにしましょう。

推論のループ

このループを声に出して進めましょう。これはチェックリストではなくループです。後半のステップから前半に戻ることはよくあります。それが重要なのです。

1. 要件を明確にする — 曖昧なプロンプトを、機能要件、非機能制約、明示的な 対象外 に整理します。中核となる機能をいくつかに絞り、その旨を伝えます。→ スキル requirements-scoping
2. 規模を見積もる — QPS、ストレージ、帯域幅、読み取りと書き込みの比率を概算します。設計を決めるのは数値です。「トラフィックが多い」だけでは不十分です。→ スキル back-of-the-envelope
3. 高レベル設計を提案する — ボックスと矢印（クライアント、LB、サービス、ストア、キャッシュ、キュー、CDN）と、ユーザー向け API を図示します。詳細に入る前に合意を得ます。→ スキル api-design と、以下のビルディングブロック
4. トレードオフを評価する — 主な選択肢ごとに、何を解決するのか、何が悪化するのか、どのような条件があれば変更するのかを述べます。これを説明せずにツールの名前を挙げてはいけません。→ リファレンス tradeoff-framework.md
5. 障害モードをストレステストする — 単一障害点を見つけ、性能低下時の対応を決め、復旧を計画します。すべてのコンポーネントが壊れると想定しましょう。→ スキル resilience-failure
6. 反復する／詳細に掘り下げる — 最も興味深い、または脆弱なコンポーネントを選び、詳細に掘り下げます。「書き込みが 10 倍になったら？」「リージョンを失ったら？」といった新たな制約をきっかけに、影響を受ける部分を再設計します。

この6つのステップは、GUIDE が示す次の4つの活動と同じです。 質問して要件を明確にする → データを扱う → コンポーネントを検討する → トレードオフを検討する。ただし、見積もりと障害テストを明示的に加えています。詳しい進め方と時間配分は references/reasoning-loop.md を参照してください。

基本ブロックへの振り分け

このプラグインは、組み合わせ可能なパーツを集めたWikiです。ループの中で各課題に直面したら、レシピを記憶から再構成するのではなく、専用のスキルを呼び出してください（Skill ツール経由）。スキルを読み込むと、選択肢、トレードオフの表、負荷が高い状況での動作、クラウドプロバイダーごとのバリエーションをスキル自体から得られます。この呼び出しによって、実行時に構成要素を組み合わせます。以下に記載されているスキル名だけのものは、読むファイルではなく、起動するスキルです。各課題が生じた時点で呼び出してください。

問題が…に移ったら	使用するスキル
機能、制約、スコープは？	requirements-scoping
QPS、ストレージ容量、サーバー数は？	back-of-the-envelope
エンドポイント、リクエスト／レスポンス、ページネーション、冪等性	api-design
モノリスかマイクロサービスか、サービス境界、ゲートウェイ、ディスカバリー	service-decomposition
SQL か NoSQL か、スキーマ、インデックス作成、シャーディング、レプリケーション	data-storage
何をキャッシュするか、エビクション、無効化、ホットキー	caching
トラフィックの分散、L4／L7、ヘルスチェック	load-balancing
非同期処理、キューかストリームか、配信保証	messaging-streaming
CAP、一貫性モデル、クォーラム、コンセンサス、ハッシュ化	consistency-coordination
耐障害性、サーキットブレーカー、縮退、レート制限	resilience-failure
静的コンテンツ／メディアの配信、エッジ、地理的ルーティング	content-delivery
成長率が10倍／100倍になったときに設計がどう進化するか	scaling-evolution
クライアントによるサービスの名前解決、地理的／フェイルオーバールーティング	dns
大規模環境での一意なID（Snowflake／UUID／チケット）	sequencer
大容量／非構造化オブジェクト（画像、動画、ファイル）の保存	blob-store
メトリクス／ログ／トレース、ヘルスチェック、SLO、アラート	observability
大量のログの収集／転送／保持	distributed-logging
全文検索、転置インデックス、オートコンプリート	distributed-search
バックグラウンド／スケジュール済み／定期的なジョブ	task-scheduling
大量の書き込みが発生する「いいね」や閲覧数のカウント	sharded-counters
アーキテクチャの図示／可視化	architecture-diagram

詳しい説明、ボトムアップのレイヤリング、「どのブロックがどの質問に答えるか」については、references/building-blocks-index.md（正規の21ブロックカタログ）を参照してください。ユーザーが特定の部分だけについて質問した場合は、そのブロックを直接起動してください。すべての質問でオーケストレーターを使う必要はありません。

ガードレール：設計が失敗する原因

GUIDE では、10種類の失敗モードを取り上げています。これは誤った回答ではなく、誤ったシグナルに関するものです。以下の心構えを守ってください（一覧と対策については references/failure-modes.md を参照してください）。

• 設計の前に明確化する。 解決策を急ぐことは、暗記に頼っているシグナルです。
• 選択の前に定量化する。 まず「トラフィックが多い」を数値に置き換えます。
• すべてのコンポーネントに根拠を示す。 選択ごとに、解決すること／悪化させること／変更が必要になるタイミングを問いましょう。「業界標準」は根拠になりません。
• 基本ブロックは名前ではなく中身を明らかにする。 キャッシュ、キュー、DB が負荷時にどう動作するかを理解しましょう。単に名称を知っているだけでは不十分です。
• 障害を想定して設計する。 「リトライを増やす」だけでは、通常、障害の影響を拡大させます。
• インターフェースを具体化する。 リクエスト、レスポンス、主キーを書けないなら、図は推測にすぎません。
• アーキテクチャは仮説として扱う。 小さな制約の変更で設計全体が崩れるなら、それは推論ではなく暗記に頼ったものです。

一方的に説明せず、協力する

設計の議論は講義ではなく、共同作業です。案を提示し、批評を促し、リアルタイムで適応してください。制約が変わったら、以前のどの前提が無効になったかを明示し、その部分を再設計してください。撤回不能な設計を擁護することは、最初の案に欠陥があることよりも悪いシグナルです。説明の仕方、不意の変更への対応、方針転換については references/collaboration-playbook.md を参照してください。

要件が本当に曖昧で、その答えによって設計が変わる場合は、黙って推測するのではなく、ユーザーに確認の質問をしてください。

設計の作成

• assets/requirements-template.md にスコープを記録します（機能要件／非機能要件／対象外／前提）。
• assets/design-doc-template.md を使って設計をまとめます。このテンプレートは推論のループに沿って構成されているため、トレードオフや障害時の対応も脚注ではなく、設計の重要な要素として扱います。
• プラグイン内蔵の architecture-diagram スキルで図を作成します。このプラグインに含まれる、自己完結型のダークテーマ HTML+SVG 生成ツールで、外部依存はありません。初期の検討には簡単な ASCII スケッチでも構いませんが、設計が明確になったら適切に描画します。各ステップで何を描くか、またそのスキル向けに図をどう指定するかについては、references/diagramming.md を参照してください。
• 作業内容を会話の後も残すため、ファイルに保存します。要件と設計ドキュメントをファイルに書き込みます（docs/design/<system>.md を推奨。不明な場合はユーザーに保存先を尋ねます）。トレードオフの検討や制約についてのやり取りは会話内で行い、確定した成果物（スコープ、設計、重要な決定事項、データモデル、図）をファイルにまとめます。
• 仕上げる前に評価と診断を行います。品質基準に照らして設計を評価し、references/failure-modes.md の Quick Diagnostic を実行します。最も弱い評価項目と、それを改善する方法を示します。

回答の要件

ユーザーが読む回答には、推論が含まれているだけでなく、それが示されている必要があります。すべての設計回答（初回でも改訂版でも）には、回答内に次の内容を含めます。

• 決定事項の表 — 主要な選択肢ごとに 1 行（完全な設計では少なくとも 3 つ）。列は Decision | Solves | Worsens | Change it when… とします。最後の列には、「必要に応じて」のような曖昧な条件ではなく、具体的なきっかけ（数値や観測可能な兆候。例：「1 シャードでの書き込み QPS が 50k を超えた」「別のチームが独立したデプロイを必要とする」）を記載します。
• 最後に最も弱い点を示す行 — 負荷や要件の拡大に伴い、この設計で最初に破綻する部分と、その場合に取る対策を記載します。

長所と短所の一覧や、1 つの選択肢だけを対象にしたトレードオフの説明では、要件を満たしません。

ワークフローとしての実行

このスキルを繰り返し実行できるプロセスとして進めるための入口は、次の 2 つです。

• /design <system> — 問題に対して一連のループを実行するスラッシュコマンドです。
• system-design-orchestrator — コマンドが呼び出すエージェントです。このエージェントはスキルを読み込み、必要な懸念事項が生じるたびに各構成要素のスキルを呼び出します。

どちらも上記の同じ構成要素を組み合わせます。レシピを記憶から組み立て直すのではなく、対象となる懸念事項が生じたときに、その構成要素のスキルを呼び出してください。

参考資料

• references/reasoning-loop.md — ニュースフィードの手順例と 45 分の時間配分を含む、6 段階のループの詳細です。設計全体のループを実行するときに読みます。
• references/failure-modes.md — 10 個の失敗パターンとその対処法です。設計のセルフチェックや、うまく伝わらない原因の診断に読みます。
• references/tradeoff-framework.md — 解決する点／悪化する点／変更するタイミングを検討する方法と、よくある評価軸のトレードオフ（レイテンシ↔スループット、一貫性↔可用性、コスト↔複雑さ）です。ステップ 4 で読みます。
• references/building-blocks-index.md — すべての構成要素、それぞれが答える内容、構成要素の組み合わせ方をまとめた Wiki の索引です。適切なものを選ぶ際に読みます。
• references/collaboration-playbook.md — 議論の進行、想定外の問題への対応、制約変更に伴う方針転換についてまとめています。議論が対立的になったときに読みます。
• references/diagramming.md — ループの各ステップで何を描くか、architecture-diagram スキル向けに図をどう指定するかについてまとめています。図を作成するときに読みます。
• references/worked-example-news-feed.md — テンプレートとして暗記するものではなく、推論の過程として示した、ループの最初から最後までの実例です。

アセット

• assets/requirements-template.md — 機能要件／非機能要件／スコープ／前提を記録するテンプレートです。
• assets/design-doc-template.md — 推論のループに沿って構成された設計ドキュメントのテンプレートです。