Communityコーディング&開発github.com

システム設計

制約条件(サービス境界、同期/イベント駆動通信、一貫性、障害動作、キャパシティ)から分散システムを設計・評価し、各選択がもたらすトレードオフを明示します。サービス分割・統合、呼び出し方式の選択、データ配置の決定、アーキテクチャ提案のレビュー、システム設計問題への回答に使用します。

システム設計 とは?

このスキルは、分散システムの設計または評価を構造化された体系的なプロセスで支援することを目的としています。設計の失敗パターンとして、制約条件を定義せずにコンポーネントに飛びつくことを挙げ、最初に制約条件を明確にすることを強く推奨します。これにより、設計が推測ではなく根拠に基づいたものになります。このスキルは、Claude Code、Cursor、CodexなどのAIエージェントと連携することを想定しており、開発者がサービス境界の決定、同期的通信とイベント駆動通信の選択、一貫性と可用性のトレードオフ評価、障害時動作の定義、キャパシティ計画を立てる際に役立ちます。プロセスは6つのステップで構成されます:(1)制約条件(負荷、データ、一貫性、可用性、レイテンシ、所有権)の文書化、(2)サービス境界の決定(変更単位とデータ所有権に基づく)、(3)同期/イベント駆動の選択、(4)すべてのリモート呼び出しに対する障害前提の設計(タイムアウト、リトライ、冪等性、劣化動作)、(5)トランザクション内での不変条件の保護と補償アクションによる結果的一貫性の許容、(6)決定事項とトレードオフの文書化。各ステップには明確なトレードオフが記載されており、設計判断を体系的に行えます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-system-design

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

システム設計 は何をしますか?

失敗パターンはコンポーネントに飛びつくことです。制約条件を名前付ける前にサービスを名前付ける設計は、枠で囲まれた推測に過ぎず、何を達成すべきかが明示されていないため評価できません。

1. 制約条件をコンポーネントより先に

まずこれらを書き留めます。それぞれが設計案を除外します:

  • 負荷 — ピーク時の1秒あたりのリクエスト数、および読み取りと書き込みの比率。読み取りと書き込みはまったく異なる手段でスケールするため、この比率が絶対数よりも多くを決定します。
  • データ — 総量、増加率、および単一アイテムのサイズ。
  • 一貫性 — 即座に正しくあるべきものと、古くても許容されるもの。ほぼ決して「すべて」ではありません。厳密でなければならない小さな部分を特定することが、残りを安価にするのです。
  • 可用性 — このコンポーネントの停止中にビジネスに何が起こるか、および許容可能な低下動作は何か。
  • レイテンシ — ユーザー向けパスの予算。平均ではなくパーセンタイルで指定します。
  • 所有権 — 各パーツをデプロイし、オンコール対応するチーム。チームをまたがる境界は、すべての変更に調整コストをもたらします。

大まかに見積もり、そのように明記します。アーキテクチャを選択するには桁数で十分であり、持っていない精度に費やす価値はありません。

2. 境界

名詞ではなく、何が一緒に変更されるか、誰がデータを所有するかで分割します。別のサービスと同時にデプロイしなければデプロイできないサービスは、ネットワーク呼び出しが追加された、2つのリポジトリにある1つのサービスです。

各データには、それを書き込む唯一の所有者が1つ存在します。他のすべては、所有者のインターフェースを通じて、または所有者が公開するコピーを通じて読み取ります。2つのサービスが同じテーブルに書き込むことは、分散モノリスです。独立したデプロイ、共有された障害、そして不変条件を強制する明確な場所がありません。

実際の力関係が分割を必要とするまで、より少数でより大きなサービスを優先します — 独立したスケーリング、別々の所有権、真に異なる可用性要件。分割は安価に実行でき、元に戻すには高価であり、すべての境界は関数呼び出しを、失敗し、リトライし、2回到着する可能性のあるネットワーク呼び出しに変換します。

3. 同期かイベント駆動か

呼び出し元が答えなしでは続行できず、ユーザーが待機している場合は同期的に呼び出します。すべての同期的依存関係は、そのダウンタイムをあなたのものに、そのレイテンシをあなたの予算に追加するため、それらを数えます:5つのサービスに同期的に触れるリクエストは、そのうちのどれよりも可用性が低くなります。

システムの他の部分が何かが起こったことを知る必要があるが、呼び出し元がその応答を必要としない場合は、イベントを公開します。これにより可用性が切り離されます — コンシューマーがダウンしていても書き込みは失敗しません。

コストについて正直になりましょう。イベントは、結果的な一貫性、順序外および重複配信、そして単一のスタックトレースには現れなくなるデバッグパスをもたらします。モダンに聞こえるからではなく、切り離しが必要な場合にそのトレードオフを受け入れます。

書き込みがローカル状態を更新しかつ他の誰かに伝える必要がある場合、この2つが乖離してはいけません。イベントを状態変更と同じトランザクションに書き込み、そこから公開します。行を書き込んでからブローカーを呼び出すのではなく — これら2つの呼び出しの間のギャップに、失われたメッセージが存在します。

4. すべてのリモート呼び出しは失敗すると仮定する

それぞれについて、事前に決定します:

  • タイムアウト — 明示的なもので、呼び出し元自身の予算よりも短くします。タイムアウトのない呼び出しは、スレッドが積み重なるにつれて、遅い依存関係を障害に変えます。
  • リトライ — 一時的な障害にのみ、バックオフとジッターを伴い、かつ操作が冪等である場合にのみ行います。非冪等な書き込みをリトライすると、それが複製されます。すべてのクライアントからの同期されたリトライは、小さな問題を殺到に変えます。
  • 冪等性 — 呼び出し元が提供するキーで、タイムアウト後のリトライが認識されるようにします。呼び出し元は、失われたリクエストと失われた応答を区別できないため、リトライします。
  • 劣化動作 — これがダウンしたままのときにユーザーが目にするもの。キャッシュされた結果または部分的な結果を提供することは、通常エラーページよりも優れており、設計時にそれを決定することが、それを可能にします。

5. 一貫性

決して壊れてはならない不変条件を特定します — お金の保存、在庫の過剰販売なし、二重請求なし — それを単一のサービス内の単一のトランザクション内に保持します。この制約は、他の何よりも、境界を決定する必要があります。

その不変条件の外側にあるものはすべて、結果的に一貫性があればよいです。ワークフローが複数のサービスにまたがる場合、各ステップに対して補償アクションを伴うローカルトランザクションのシーケンスとしてモデル化し、中間状態が見えることを受け入れます。

サービス間の分散トランザクションは最後の手段です。補償アクション設計は考えるのが難しく、運用するのははるかに簡単です。

6. 文書化する

制約条件    <負荷、データ、一貫性、可用性、レイテンシ、所有権>
設計        <コンポーネントと各々が所有するもの>
フロー      <重要ないくつかのパスを順に>
障害        <各依存関係がダウンしたときに何が起こり、ユーザーが何を見るか>
トレードオフ <この設計が困難にするもの、および10倍になったときに最初に変更するもの>
棄却案      <代替案とその理由>

障害と棄却案の行が、設計を図面から区別するものです。ハッピーパスのみを説明する提案は評価されていません。

してはいけないこと

  • 測定または見積もりしていない負荷に対して、キュー、キャッシュ、またはシャードを追加しないでください。
  • 1倍のときに100倍向けに設計しないでください。既知の次のステップが可能になるように設計し、それを超えたときに最初に壊れるものを明示してください。
  • 単一の選択肢を不可避として提示しないでください。棄却したものを名前付けてください。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

関連スキル