system-design

システム設計

アーキテクチャ上の意思決定を支援し、構造化された設計成果物を作成します。

使用する場面

• 新しいシステムや主要な機能をゼロから設計する場合
• アーキテクチャのアプローチ間のトレードオフを評価する場合
• アーキテクチャ決定記録（ADR）を作成する場合
• スケーラビリティ、信頼性、保守性の観点から既存のアーキテクチャをレビューする場合
• モノリスを分解する場合や移行を計画する場合

ワークフロー

ステップ 1：要件を明確にする

設計を始める前に、次の内容を確認します。

1. 機能要件 - システムは何を実行する必要がありますか？
2. 非機能要件 - パフォーマンス、可用性、セキュリティ、コストに関する制約
3. スコープの境界 - 明確に対象外とするものは何ですか？
4. 既存の制約 - 現在の技術スタック、チームのスキル、スケジュール

要件に不明確な点があれば、先にユーザーに確認してください。

ステップ 2：コンポーネントを特定する

システムをコンポーネントに分割します。

• データストア - どのようなデータが存在しますか？どのようにアクセスしますか？
• サービス／モジュール - 論理的な作業単位は何ですか？
• インターフェース - コンポーネント間はどのように通信しますか？（API、イベント、共有 DB、ファイル）
• 外部依存関係 - サードパーティサービス、API、インフラストラクチャ

ステップ 3：代替案を評価する

重要な意思決定ごとに、少なくとも 2 つの選択肢を記録します。

基準	選択肢 A	選択肢 B
複雑さ	...	...
スケーラビリティ	...	...
運用コスト	...	...
チームの習熟度	...	...

明確な理由を添えて、1 つの選択肢を推奨します。

ステップ 4：設計成果物を作成する

構造化された設計ドキュメントを出力します。

# Design: <Title>

## Context
[Problem statement and motivation]

## Requirements
- Functional: ...
- Non-functional: ...

## Architecture
[Component diagram or description]

## Key Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| ... | ... | ... |

## Data Model
[Schema or entity relationships]

## API Surface
[Key endpoints or interfaces]

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| ... | ... | ... |

## Open Questions
- ...

ステップ 5：レビューチェックリスト

最終化する前に、次の点を確認します。

• 各コンポーネントの責務が単一である
• モジュール間に循環依存がない
• 障害モードを特定し、対処している
• データ整合性モデル（強整合性か結果整合性か）が明示されている
• セキュリティ境界が定義されている
• 可観測性のポイント（ログ、メトリクス、トレース）が計画されている

原則

1. シンプルに始める - 要件で必要とされる場合にのみ複雑さを加えます
2. トレードオフを明示する - すべての選択にはコストが伴うため、記録します
3. 変更に備えて設計する - インターフェースは安定させ、実装は置き換え可能にします
4. 関心事を分離する - データ、ロジック、プレゼンテーションを密結合させません
5. 適切に失敗させる - 理想的なケースだけでなく、部分的な障害にも対応できるよう設計します