ソフトウェアエンジニアリング & システム設計標準
ソフトウェアエンジニアリングの卓越性、システムアーキテクチャ、低レベル設計、分散システムのための、厳格かつ実戦で鍛えられた運用ガイドです。
1. 中核となる動作原則
- 原則よりもトレードオフ: 普遍的な「ベストプラクティス」は存在せず、トレードオフのみです。あらゆるアーキテクチャ上の選択は、特定のコスト（レイテンシ、一貫性、運用複雑性、または認知オーバーヘッド）を支払うことで、一連の利益を得ます。常に何を犠牲にしているかを明示してください。
- 可逆性を優先: 一方通行の決定（不可逆）よりも、両方向の決定（可逆）を優先します。特定のベンダー、フレームワーク、または分散トポロジーへの早期の結合を避けてください。
- アーキテクチャの空理空論を排す: すべての抽象化、インターフェース、レイヤーは、推測による将来の要件ではなく、具体的な既存要件に対してその重みを正当化できなければなりません（YAGNI）。
- 証拠に基づく設計: 決定を前提ではなく、具体的なプロファイル、測定値、クエリプラン（
EXPLAIN ANALYZE）、およびキャパシティ限界に基づいて行います。 - フェイルファスト & 明示的な境界: サブシステム、ドメイン、またはネットワークホップ間の境界には、明示的で強く型付けされた契約、バリデーション、タイムアウト、サーキットブレーカー、および冪等性保証が必須です。
2. 高レベル設計 (HLD) & アーキテクチャワークフロー
システムの設計、アーキテクチャの評価、または主要サブシステムのリファクタリングを依頼された場合は、この6ステップのフレームワークを実行してください：
flowchart TD
Step1["1. 要件とスコープの明確化<br>(機能、非機能、レイテンシ、可用性、一貫性)"]
Step2["2. キャパシティとスケールの見積もり<br>(DAU、QPS、スループット、ネットワーク帯域幅、ストレージ、キャッシュRAM)"]
Step3["3. 高レベルアーキテクチャ (C4 L1/L2)<br>(サービス境界、ストレージ選択、イングレス、キャッシング)"]
Step4["4. データモデルとインターフェース契約<br>(エンティティ、スキーマ、主キー、インデックス、REST/gRPC API)"]
Step5["5. 深掘りとボトルネックの特定<br>(レプリケーション、シャーディング、並行性、キャッシングの病理、ホットスポット)"]
Step6["6. レジリエンス & SRE戦略<br>(SLO、サーキットブレーカー、ジッター付きリトライ、冪等性、DLQ)"]
Step1 --> Step2 --> Step3 --> Step4 --> Step5 --> Step6
詳細HLDリファレンス
分散システムの定理（CAP、PACELC）、一貫性階層、コンセンサス（Raft/Paxos）、シャーディング、レプリケーション、Sagaパターン、トランザクショナルアウトボックスパターンについては、以下を参照してください： 👉 高レベルシステム設計 & 分散システムリファレンス
3. 低レベル設計 (LLD) & クリーンコード標準
コードを記述、レビュー、またはリファクタリングする際は、以下の標準に従ってください：
3.1 SOLIDのルール
- SRP（単一責任）: モジュールは単一のアクター/ステークホルダーのみに応答します。永続化、HTTPシリアライゼーション、ビジネスロジックを別々の関心事に抽出してください。
- OCP（オープン/クローズ）: 広範な
switch/if-else型ディスパッチ文よりも、ポリモーフィズム、Strategy、またはVisitorパターンを優先します。 - LSP（リスコフ置換）: サブタイプは親のすべての振る舞い不変条件を満たさなければなりません。
NotImplementedExceptionをスローするようオーバーライドすることはLSP違反です。 - ISP（インターフェース分離）: 広範な「神インターフェース」よりも、小さくクライアント固有のロールインターフェースを優先します。
- DIP（依存性逆転）: コアビジネスルールは抽象化（ポート）にのみ依存し、外部のデータベースライブラリ、UIフレームワーク、ネットワークドライバに直接依存してはなりません。
3.2 モジュールのカプセル化（Parnas & Connascence）
- モジュールの秘密: モジュールはその主要な秘密（内部アルゴリズム/データ構造）と副次的な秘密（外部環境/ファイル形式）を完全に隠蔽しなければなりません。
- Connascence: 動的な結合（実行順序、タイミング、値制約）を最小限に抑え、静的な名前/型の一致への結合度を低減します。
詳細LLDリファレンス
GoFデザインパターンフィールドガイド、ドメイン駆動設計（DDD）の戦術的ビルディングブロック（エンティティ、値オブジェクト、集約、ドメインイベント）、およびリファクタリング手法については、以下を参照してください： 👉 低レベル設計 & クリーンコードリファレンス
4. API & データ永続化標準
- RESTful API:
- HTTPメソッドのセマンティクスに厳密に従う（
GETは安全かつ冪等、PUT/DELETEは冪等、POSTは作成）。 - 構造化エラーレスポンスには RFC 7807 (Problem Details) を使用する。
- 大量コレクションには、オフセット/リミットページネーションではなく Keyset/Cursorページネーション を使用する。
- HTTPメソッドのセマンティクスに厳密に従う（
- データベースインデックス (E-R-Sルール):
- 複合インデックスのカラム順序: [等価条件カラム] → [範囲条件カラム] → [ソートカラム]。
- カバリングインデックス（インデックスオンリースキャン）と部分インデックスを使用して、ホットクエリのディスクページルックアップを排除する。
- クエリは常に
EXPLAIN QUERY PLANまたはEXPLAIN ANALYZEで検証する。
- 非同期メッセージング & イベント:
- 最低1回のブローカ配信とコンシューマの冪等性（ストレージ内で重複排除される一意のメッセージID）を組み合わせて、実質一度の処理を保証する。
- 処理不能なポイズンピルはデッドレターキュー（DLQ）にルーティングし、パーティションの停止を防ぐ。
詳細API & データリファレンス
5. パフォーマンス、キャパシティ & 信頼性エンジニアリング
- 簡易見積もり:
- $1 ext{ 日} approx 10^5 ext{ 秒}$ ($86,400 ext{ 秒}$)。$1 ext{M リクエスト/日} approx 12 ext{ RPS}$。
- ピークQPS = 平均QPS $ imes$ $3$。
- キャッシュRAM = $20% imes ( ext{1日の読み取り量} imes ext{アイテムサイズ})$（パレート80/20ルール）。
- リトルの法則: $L = elda W$（インフライト並行性 = 到着率 $ imes$ レイテンシ）。
- キャッシングの規律:
- 通常の運用時間中に期限切れとなる、測定されていない任意のインメモリTTLを決して設定しない。
- データバージョン/フィンガープリントまたはセッションタイムスタンプに基づいて無効化する。
- キャッシュスタンピード（ミューテックス/分散ロックの使用）、キャッシュペネトレーション（ブルームフィルタ）、キャッシュアバランシェ（TTLジッター）から防御する。
- サイト信頼性エンジニアリング (SRE):
- 明示的なSLOとレイテンシ予算（$p50$、$p95$、$p99$）を適用する。
- サーキットブレーカー、バルクヘッド、フルジッター付き指数バックオフを実装する。
詳細信頼性 & パフォーマンスリファレンス
👉 信頼性、パフォーマンス & キャパシティエンジニアリングリファレンス
6. アーキテクチャ決定記録 (ADR)
重要な技術的選択は、標準のADR形式を使用して文書化します：
- コンテキスト & ドライバー: 問題、運用上の制約、レイテンシ/スケール目標。
- 検討したオプション: 構造的な代替案とそのトレードオフ。
- 決定 & 結果: 決定ドライバーに結び付ける具体的な正当性。
- 結果: 明示的な肯定的利益と、受け入れた否定的コストの両方。