system-design

システム設計

アーキテクチャは、雰囲気ではなく、不変条件、ワークロードの数値、障害モード、運用上の制約によって決まります。まず本番で成立する最もシンプルな候補を描き、重要な軸が異なり、根拠に耐えうる代替案だけを追加します。根拠の連鎖を示して一案を推奨し、別のコーディングエージェントセッションが続行できる設計成果物を残します。

このプロセスは、リポジトリでの作業でもグリーンフィールドでの作業でも同じです。面接で通用する推論は、本番環境での規律から自然に導かれます。

すべての推奨事項には、エンベロープの数値、正当性の不変条件、名前を付けた障害モード、またはHEURISTICS.mdの原則を必ず引用してください。

デフォルトでは例を読み込みません。初稿の推奨事項やインターフェースがまだ一般的なままである場合に限り、EXAMPLES.mdにある対応するBAD/GOODの対比を参照し、一般的な表現を、関連する数値、不変条件、責任範囲、または障害時の動作に置き換えてください。

プロセス

0. プロセスを実行する前に依頼の規模を見積もる

このプロセスのコストに見合うのは、決定を覆すのが難しい場合、数値が重要な判断材料になる場合、または構造の異なる複数の設計が実際に有力な候補として残る場合です。まずエンベロープを概算してください。HEURISTICS.mdにある過剰設計を避ける基準を下回る場合、または記録済みの決定によってすでに答えが一つに定まる場合は、どの基準または決定によって候補が絞られたかを述べ、アーティファクトを作成せず、段落で直接回答してください。見せかけの選択肢を対等なタブとして並べるのは、文書を作らないより悪い結果です。

プロセスを実行する場合は、まず本番で成立する最もシンプルな設計を描いてください。エンベロープと不変条件を踏まえても成立し、かつ重要な軸が異なる場合にのみ候補を追加します。たとえば、実測によるスケールの境界、または正当性、障害分離、コスト、運用性における支配的なリスクが異なる場合です。要件、基準、または名前を付けた障害によって除外された選択肢は、1行の却下理由として記録してください。対等な候補として図示、評価、監査してはいけません。候補は最大3つですが、目標は3つにすることではありません。

1. 配置を確認して再開する

既存の設計を列挙します。docs/design/*/design.json、またはGitリポジトリ外では./*/design.jsonを確認し、それぞれのslug、title、statusを読み取ってください。既存の設計が今回の依頼を対象としている場合は、それを読み込んで新たな調査を始める前にユーザーのフィードバックを反映してください。2つの設計が該当する可能性がある場合は、両方を示してどちらを対象にするか尋ねてください。

該当する設計がなければ、依頼の表現ではなくシステムまたはサブシステムを表すケバブケースのスラッグを作成します（add-a-commerce-layerではなくcommerce-layer）。次のいずれかを選択してください。

• リポジトリモード：現在のコードベースに関する依頼の場合。既存システムをアーキテクチャ0とします。
• グリーンフィールドモード：まだ実装が存在しない場合。

モード、理由、既存設計を再開したかどうか、対象ディレクトリを1行で示してください。

2. 現状の真実を確定する

リポジトリモードでは、まずトップレベルの各ディレクトリを、システムコード、開発が継続中のファーストパーティのベンダーコード、または依存関係・サンプル・ビルド出力に分類します。対象となるのは最初の2つだけです。ディレクトリのサイズは重要性を示すものではありません。通常、最大のツリーはシステムではありません。ほとんどの場合、git log --format=format: --name-only -200 | sed 's#/.*##' | sort | uniq -c | sort -rnで判断できます。依頼の位置づけと食い違う場合は、その食い違いも含めて、分類を1行で示してください。

対象パスに限定して、アーキテクチャのドキュメント、ADR、ドメイン用語、設定、最近の履歴におけるホットパスを読みます。それに加え、このシステムの形態で状態と副作用を担うものも確認します。ネットワークサービスならスキーマ、API、キュー、クライアント、デスクトップ、組み込みコードベースならエントリーポイントとライフサイクル、状態の所有者、書き込みとフラッシュの経路、永続化されたキーの名前空間、ディスク上の形式、エンティティの識別キー、プロセスまたはサンドボックスの境界です。以下のフローと不変条件が解明できたら、調査を終えます。コードとスキーマは、食い違う場合は説明文より優先されます。その食い違いをrequirements.conflictsに記録し、不変条件が変わる場合は、どちらかを黙って選ばずに確認します。

確定済みのADRは制約です。ただし、ひな形にすぎないもの、後続のADRに置き換えられたもの、重複しているもの、このリポジトリの外を参照しているものは、制約ではなく参照できない証拠として扱います。読めなかったものを列挙してください。これらのADRはステップ8の監査で比較する基準モデルでもあるため、それぞれのステータスを記録してください。採択済みなのに気づかれないまま違反されている決定と、置き換えられたのに削除されていない決定とでは、指摘すべき内容が異なります。このテーマをすでに扱っているドキュメントを明記してください。そのドキュメントが依頼内容の一部をすでに決定している場合は、何が決まっているのかを述べ、未解決の部分に作業の焦点を当てます。ユーザー向けのフローを最初から最後まで追跡し、HTML-REPORT.mdのタイプを使用するすべてのコンポーネントを一覧にします。

どちらのモードでも、以下を定義します。

• 中核となるエンティティと、決して破ってはならない不変条件。
• システムインターフェースと、その整合性・冪等性に関する契約。
• 失敗時と復旧時のフローを含む、重要なエンドツーエンドのフロー。
• 信頼できる情報源となるストアと、そこから派生するビュー。

リポジトリやプロンプトから判断できない事項についてのみ、ユーザーに確認します。

3. 要件の未解決範囲を解消する

INTERVIEW.mdを使用して、未解決の範囲のみを確認します。番号付きの質問を、最大3ラウンド、それぞれ最大8問まで行い、各質問に推奨されるデフォルトを示します。質問に回答するユーザーがいない場合は、質問せずにデフォルトを採用します。機能範囲、対象外の範囲、数値で示す非機能目標、ワークロードの特性、チーム・コストの制約、最も重要な3つの特性を明示します。すべての仮定にラベルを付けてください。

4. エンベロープを計算し、検証する

このシステムの制約となる数値を計算します。リクエストを処理するシステムでは、平均およびピーク時の QPS、ストレージの増加量、帯域幅、キャッシュの容量、同時実行数、そしてドメインの負荷を左右する分布（バースト、偏り、ファンアウト、ホットキー、オブジェクトサイズ）が該当します。デバイス上の制約が支配的な場合は、その制約に結び付く単位で計算します。セッションあたりのバイト数とラウンドトリップ数、プロバイダーのクォータとそのコストに対するリクエスト量、OS が終了させる可能性のあるプロセスのメモリ上限、デバイス上のストレージ増加量、コールドスタートの予算、オフライン時の不整合期間などです。金銭が境界を越える場合は、設計で保護するイベントのユニットエコノミクスを計算します。該当しない標準的な指標は、理由を1行添えて n/a と記録してください。行を埋めるために数値を捏造してはいけません。導出過程を示し、シェルコマンドで計算を検証してください。

INTERVIEW.md にある物理法則／CAP の妥当性確認を実施します。ARCHETYPES.md のコンパクトなルーターで、保護対象の不変条件に基づいて選択し、選択したパックだけを読み込みます。デフォルトで全パックを読み込んではいけません。選択した各アーキタイプの Shape と、設定されている場合は Numbers anchor に照らしてエンベロープを検証します。Not when 条件に該当するアーキタイプは不適切なため、除外し、そう判断したことを明記してください。このシステムに不要な仕組みを持ち込んではいけません。候補を作成する前に矛盾を解決してください。

5. データモデルと一貫性モデルを定める

データモデルを誤ったままでは、トポロジーが正しくても適切な設計にはなりません。何かを図示する前に、各コアエンティティについて、メモリ上および永続化時の表現、識別方式、順序付けの権限を持つコンポーネント、フィールド種別ごとの競合解決方法、書き込みが永続化される時点、ガベージコレクションまたは圧縮の方針を明記してください。HEURISTICS.md の競合解決ルールを使います。ルールは高度さではなく、利用可能な調整手段に基づいて選びます。

候補ができる前に、これらを dataModel に記述してください。さらに、構造化ストアごとに直感的なデータベーススキーマを作成します。テーブルまたはコレクションの名前を付け、設計の説明に必要なフィールドだけを列挙し、主キー、パーティションキー、ソートキー、重複排除キーを明示して、重要なインデックス、リレーションシップ、信頼できる情報源としての位置付け、保持に関する注意事項を記載します。Ticket — id, eventId, seat, price, status, userId のような、人が読みやすいカード形式を使ってください。実行可能な DDL は作成しないでください。候補間でこれらのいずれかに相違がある場合、その相違自体を候補の軸として扱います。手順6を参照してください。

6. 候補を描く

本番運用に耐える最もシンプルなアーキテクチャを完全に描いてください。エンベロープと不変条件を満たし、重要な構造、データモデル、一貫性、コスト、運用性のいずれかの軸で異なる場合に限り、候補を追加してください。実際に残る有用な代替案は、測定された規模の境界、または支配的な正確性、障害分離、コスト、運用性のリスクに最適化されていることがよくあります。却下した選択肢はすべて、却下に至った要件、ゲート、または障害モードとともに、一行で示してください。欄を埋めるためだけに同等の候補をでっち上げてはならず、3つを超えてはなりません。

リポジトリモードでは、それぞれがアーキテクチャ0の進化形であり、移行コストを最重要事項として扱います。候補はHTML-REPORT.mdの差異化ルールを満たす必要があります。難しさがコンポーネントのグラフではなくデータモデル（共同編集、コンセンサス、台帳、インデックスなど）にある場合は、トポロジーを固定し、データモデルの軸で候補を生成してください。

分散メカニズムを採用するには、数値、不変条件、または明示された障害モードによる根拠が必要です。各候補には、少なくとも1つの正直な弱点を記載し、ARCHETYPES.mdを通じて選択したパック内で、その候補が扱うすべてのアーキタイプのStaffゲートをクリアする必要があります。もっともらしい図だけでは答えられないのが、この質問です。

この設計でそのアーキタイプをどう実現するかに即して回答することで、ゲートをクリアしてください。担当するコンポーネント、守る数値、または受け入れる動作を示します。ゲートの文言を繰り返すだけでは回答になりません。実装していない設計の根拠としてゲートの文言を引用することは、このルールが防ごうとしている失敗です。異なる構造を採用したためアーキタイプのゲートが適用されない場合は、どの構造に置き換えたのか、またそのゲートが防いでいた障害を何がカバーするのかを述べてください。義務は履行するか、明示的に廃止するかのどちらかであり、放置してはなりません。候補が従来のベースラインから逸脱する場合は、そのベースラインを明示し、逸脱しても障害モードをどのようにカバーするのかを証明してください。

各候補についてフローを最優先したキャンバスを作成してください。canvas.primaryFlowを設定し、各コンポーネントにおおよその中心点となるpositionを設定してください。一般的な図形の中央に収まるよう、コンポーネント名は短くしてください。また、描画側で自動的に解決される項目も記載されているHTML-REPORT.mdのレイアウトルールに従ってください。

7. 判断し、深く掘り下げる

HEURISTICS.md を使い、ユーザーが重視する上位3つの特性を軸に、候補をすべて評価します。証拠をつないだ論拠とともに、1つを推奨します。評価値はその論拠に含めない場合があります。評価値は候補自身による自己評価だからです。論拠は、エンベロープ数、不変条件、または名前の付いた障害モードに基づきます。

正確性、コスト、運用性への圧力が最も大きい判断を2つか3つ解決します。各深掘りでは、圧力、判断、却下した選択肢、障害モード、証拠を記録します。リトライ、タイムアウト、冪等性、照合、フェイルオーバー、可観測性、ロールアウト、最初に壊れるもの、推奨を覆す測定値を明記します。

次の条件をすべて満たして初めて、設計は完成です。

• すべての重要なフローが、名前の付いた永続的または最終的な効果に到達する。
• すべての不変条件に、適用を担う権限主体が1つある。
• すべての依存関係に、期限、リトライの担当者、上限のあるバックログがある。
• すべての権威あるストアに、確認応答点、障害ドメイン、RPO、RTOがある。
• すべての派生ビューに、再構築元とカーソルが明記されている。
• すべての候補に、最初に発生する障害が明記されている。
• すべての推奨に、反証可能な証拠の連鎖がある。
• 未解決の不確実性はすべて、前提または測定値として記録されている。
• すべての成果物が、構造とレンダリングのチェックに合格する。

レンダリングする前に、次を確認します。

• すべての重要なフローが、永続的または最終的な効果に到達する。
• すべてのキュー／ログで、配信と冪等性のセマンティクスが明示されている。
• すべてのストアが、信頼できる唯一の情報源か派生データか明示されている。
• すべての依存関係のエッジに、期限、リトライの担当者、その背後にキューイングされ得る作業量の上限が明記されている。
• リトライによる増幅も含め、容量が最も低い時点における流入負荷を処理能力と対比して示している。
• すべての権威あるストアに、障害ドメイン、復旧経路、その経路が許容するデータ損失と停止時間が明記されている。
• すべての構造化ストアに、直感的なスキーマがあり、フィールド、キー、インデックス、リレーションシップが、明記されたアクセスパターンと不変条件を支えている。
• すべてのスキーマ変更とワイヤー契約の変更に、互換性の方向と、読み取り側と書き込み側をデプロイする順序が明記されている。
• 設計が、それ自体のクライアントに耐えられる。つまり、重複送信、再接続の集中、キャッシュのコールドスタート、そして障害ではなく処理速度が低下する依存関係に対応できる。
• バースト、偏り、ファンアウト、ホットキー、部分障害に対処している。
• 該当する場合、セキュリティ、プライバシー、不正利用、保持、削除に対処している。
• 重要な深掘りを、曖昧な次のステップに先送りしていない。
• すべての指摘が証拠を引用し、4つすべての負債テストに合格している。また、すべての blocking 指摘が、違反する不変条件または目標を ID で明記している。
• debt.checked に、調査したカテゴリがすべて列挙されている。また、実行時に確認できなかった項目も、記録から除外せずに記載されている。

8. アーキテクチャの負債を監査する

リポジトリモードの場合に限り、またこの段階になって初めて実施します。指摘事項の影響度は、この実行で推奨する候補に照らして測定します。その候補は前のステップまで存在していませんでした。グリーンフィールドには比較対象となる実装済みのアーキテクチャがないため、このステップを完全に省略します。

AUDIT.md に従ってください。ステージの順序こそが重要であり、形式的な手順ではありません。まず構造上の事実（グラフ、エッジの契約、ADR のステータス、変更履歴）を収集してから、判断を下してください。前回の実行のリストをファインダーに見せず、候補の指摘事項はカテゴリごとに一つずつ生成してください。すべての候補を機械的なゲートに通し、残ったものをレッドチームに渡します。レッドチームに見せるのは主張だけで、その背後にある論拠は決して見せません。モデルはアーキテクチャ上の問題を検出するのは不得意ですが、反証するのは得意です。そのため、何かが問題を退けようとするまでは、どの指摘事項もレポートに掲載しません。

サブエージェントのプリミティブがある場合は、カテゴリごとに一つのファインダーを、観点ごとに一つの検証担当を実行してください。ない場合は、各境界で依頼内容を言い直し、前のステージの推論を破棄しながら、同じステージをインラインで実行してください。一度のパスで発見と判断を同時に行う方法だけは機能しません。

結果は design.json の debt に書き込み、何を確認したか、何を確認できなかったかも含めてください。指摘事項は risks と nextSteps の種になることはありますが、候補を生成することはなく、ADR になることもありません。

9. 書き込み、レンダリング、検証

design.json を書き込み、その隣に DESIGN.md を再生成します。ユーザー所有の ## Notes はそのまま保持してください。すべての ID とフロー参照を検証します。

その後、レンダリングして開いてください。レポートがディスク上に作成され、開かれるまでは実行は完了していません。レポートのない design.json と DESIGN.md は、完了した実行ではなく未完了の実行です。

<skill-dir> は、このファイルがインストールされている場所を問わず、このファイルを含むディレクトリです。スクリプトは自身を基準にテンプレートを解決するため、絶対パスを常に使用できます。

python3 <skill-dir>/scripts/render_report.py \
  --design docs/design/<slug>/design.json \
  --out "$TMPDIR/system-design-<slug>.html"

スクリプトはレポートの書き込み後に自動で開くため、忘れやすい別手順はありません。--no-open を渡すのは、スクリプト実行またはヘッドレス実行など、誰も見ていない場合に限ってください。

スキルディレクトリが不明な場合は、このステップを省略せずに探してください。ls ~/.claude/skills/system-design/scripts/render_report.py ~/.agents/skills/system-design/scripts/render_report.py 2>/dev/null で、スタンドアロンのインストール先をどちらも確認できます。プラグインのインストール先は ~/.claude/plugins/cache/ 以下です。assets/report-template.html をコンテキストに読み込んだり、手作業でレポートを再構築したりしないでください。HTML-REPORT.md を参照してください。レポートに含めるのは、レポート自体のタイトルと日付の表示のみです。プロトタイプやハーネスのラッパーは含めないでください。

次に、レンダリングが正常に完了したことを確認してください。レンダリングされたページには、テンプレートの System design report というプレースホルダーではなく、設計自体の title が表示されている必要があります。一致しない場合は、JSON が解析されていません。タイトルは実行時に設定されるため、静的ファイルの <title> タグには引き続きプレースホルダーが含まれます。そのため、埋め込みの application/json ブロックを grep するか、__DESIGN_JSON__ が残っていないことを確認してください。ブラウザツールがある場合は、すべてのアーキテクチャルートを読み込み、非表示の report-diagnostics 要素を確認してください。data-component-overlaps、data-route-collisions、data-text-overflows、data-fit-overflows、data-label-occlusions は、すべて 0 でなければなりません。ゼロ以外の値は design.json の不備です。名前を短くし、位置を移動してから、再レンダリングしてください。ブラウザツールがない場合は、レポートをレンダリングしたものの確認はしていないと述べ、確認できない操作まで確認したと主張しないでください。

反復は design.json を通じて行い、レンダリング済み HTML を手作業で編集してはいけません。

10. 決定を記録する

ユーザーが選択したら、status: decided に設定します。リポジトリモードでは、採用した候補、却下した候補、根拠、影響を記録する ADR を docs/adr/ に作成することを提案します。「Context」には手順 2 で挙げた担当ドキュメントの名前を記載し、置き換える ADR があれば superseded としてマークし、リポジトリ内でドキュメントを一覧表示している場所から DESIGN.md にリンクします。今後の実行ではこの ADR を読み、新たな根拠がない限り、決定を再検討しないでください。