# 設計根拠（Rationale）の書き方ガイド

宇宙開発や高度なシステム開発において、最も避けなければならないのは**「なぜか動いた」「なんとなく選んだ」**という状態です。あらゆる設計判断（技術選定、パラメータ値、アーキテクチャ）に対して、「確かな理由＝根拠」を言語化して残すことは、システムの信頼性を担保するための必須スキルです。

---

## 1. 「必要十分」な設計根拠ドキュメントを構成するスタンス

設計ドキュメントは、「思いついたもの」を適当に書くだけでは、プロジェクト全体の整合性や技術的な信頼性を保証できません。
開発プロジェクト全体に対して**「必要十分（Necessary and Sufficient）」**な設計根拠が揃っているか、以下の3つのスタンスに沿って設計領域を特定・検証します。

### ① 要求からの逆算 (Mission-Requirement Mapping)
最上位の「ミッション定義（要求）」を達成するために必要な**すべての重要技術要素（ピラー）**を抽出し、それぞれの設計判断を抜け漏れなく網羅します。これが「十分性」を担保します。

### ② インターフェース境界の特定 (Interface Boundaries)
異なるコンポーネントが結合する部分（マイコン ↔ PC、ハードウェア ↔ ソフトウェア、シミュレータ ↔ 実機など）は最もバグが発生しやすく、技術的トレードオフが競合するポイントです。これらの境界領域の設計根拠を優先的に記述します。

### ③ 高リスク・不確実性の高い意思決定 (High-Risk Trade-offs)
複数の有効なアプローチ（解空間）が存在し、選定ミスが「モータの異常発熱」「通信ハングアップ」「描画フリーズ」といった重大な障害に直結する箇所の根拠を深く掘り下げます。

---

### 本プロジェクトにおける「必要十分」の検証マトリクス

本ゼミで開発する模擬衛星システムにおいては、最上位要求（シラバス記載）に基づき、以下の設計根拠ドキュメント群が定義され、相互に補完し合っています。

| 最上位要求（ミッション） | 該当サブシステム | 必須となる設計根拠ドキュメント（ピラー） | 主なトレードオフ / 決定根拠 |
| :--- | :--- | :--- | :--- |
| **太陽方向の推定＆姿勢制御** | 姿勢推定・制御系 | [attitude_control](../../software/design/satellite/attitude_control) | ・フォトダイオード差分ベクトル vs 光学センサ<br/>·ホイール飽和対策（UNLOAD）と揺り返し防止（LOTATE） |
| **対象物体のカメラ撮影** | 撮像・画像取得系 | [camera_acquisition](../../software/design/satellite/camera_acquisition) | ・OV7675 レジスタ制御と高速データ転送（DMA）<br/>·Watchdog回避のための32B非ブロッキング分割処理 |
| **地上局へのデータ伝送** | 通信・データ系 | [telemetry_command](../../software/design/system/telemetry_command) | ・P2P、REST、Pub/Sub (MQTT) の比較<br/>·画像送信中のテレメトリ停止（バッファ枯渇回避） |
| **地上でのリアルタイム表示** | 地上局データ処理・表示系 | [data_schema_persistence](../../software/design/system/data_schema_persistence)<br/>[charts](../../software/design/ground/charts) | ・JSON スキーマによる一元管理（SSoT）の整合性<br/>·時系列DBの選定、uPlot vs Recharts（SVG vs Canvas） |
| **結合開発・検証** | シミュレータ系 / システム統合系 | [sils](../../software/design/simulator/sils)<br/>[sils_integration](../../software/design/system/sils_integration) | ・実機レス検証のためのSILS設計、PlantとControllerの分離<br/>·フライトコードとのロジック同期、MQTTを介した透過的接続 |

---

## 2. 設計根拠を記述する5つのステップ

全体マップ（検証マトリクス）によって各ドキュメントの境界条件が決まったら、個々の設計根拠を以下の5つのステップに沿って記述します。

```mermaid
flowchart TD
    S1[ステップ1: 境界条件の明確化\nスコープを絞る] --> S2[ステップ2: 一般論・基本原理の提示\n解空間の起源を示す]
    S2 --> S3[ステップ3: 候補の列挙とトレードオフ分析\n比較マトリクスを作る]
    S3 --> S4[ステップ4: 意思決定と選定理由の記述\n制約に紐づく根拠]
    S4 --> S5[ステップ5: 合理的なブラックボックス化\n深追いの限界を定める]
```

### ステップ1：境界条件の明確化（スコープを絞る）
はじめに、その設計文書が「何を対象とし、何を対象としないか」の境界（スコープ）を明記します。すべての設計を一箇所にまとめようとすると、記述が浅くなり、本質的な議論が埋もれてしまいます。
*   **良い例**: `本資料は、姿勢制御回路のモータドライバIC選定根拠に限定し、マイコン側ソフトウェアは対象外とします。`
*   **悪い例**: `本資料は、姿勢制御システムの設計について書きます。`

### ステップ2：一般論・基本原理から出発する（解空間の探索）
答え（選定技術）をいきなり提示するのではなく、**「一般的にこの種のシステムでは、どのようなアプローチが使われているか」**というソフトウェア工学や宇宙工学の一般論（基本概念）を提示します。
これにより、自分たちの選択肢（解空間）がどのような技術史や先行事例から導出されたものなのかを整理します。
*   **アプローチ**:
    *   **既存規格への参照**: 「CCSDSやROS、SCADAなど、類似の監視通信分野では一般的にAかBという方式が主流である」
    *   **基本動作パターンの分類**: 「データを転送する通信方式には、一般論として①点対点直結、②ポーリング、③非同期Pub/Sub、の3パターンが存在する」

### ステップ3：候補の列挙とトレードオフの明文化
ステップ2で整理した一般論に基づき、今回検討した具体的な候補を複数（2〜3個）挙げます。それぞれの候補に対して、利点（Pros）と欠点（Cons）を**「比較マトリクス（表）」**を用いてフラットに比較します。
*   **評価軸の設計**: 比較する評価項目（メモリ消費、開発工数、リアルタイム性、耐障害性など）は、今回のミッション要求から逆算して設計します。

### ステップ4：意思決定と選定根拠の記述
比較マトリクスを踏まえ、なぜ特定の候補を採用したのかという「最後の意思決定の理由（根拠）」を書きます。
根拠は常に**「ミッション要求」および「ハードウェア制約」と論理的に結びついている**必要があります。
*   **根拠の組み立て**:
    *   「〇〇という制約（例：Pico Wのメモリバッファ）があるため、軽量な〇〇でなければハングアップする」
    *   「〇〇というミッション要求（例：実機レスでの地上局検証）を達成するため、疎結合な〇〇が不可欠である」

### ステップ5：合理的なブラックボックス化の明記
すべての仕組みをゼロから自作し、完璧に理解することは現実的ではありません。開発時間を有効に使うために、**「どの領域を信頼できるブラックボックスとして扱い、深追いしないか」**を決め、その判断自体に根拠を与えます。
*   **記述例**:
    *   `時系列データの保存ロジックは、自作せずに既製のオープンソースDB（InfluxDB）を利用します。これは、データ損失のリスクを消滅させつつ、衛星制御のメインアルゴリズムに開発資源を集中させるための合理的な割り切りです。`

## 3. 設計根拠の質を高める4つの技術スタンス

設計根拠ドキュメントを記述する際、単に「手順（5ステップ）」を満たすだけでなく、エンジニアとして以下の4つの「姿勢（スタンス）」を持つことで、文書の説得力と技術的整合性が飛躍的に向上します。

### ① 防御的設計・最悪ケースの想定 (Defensive Design)
*   **スタンス**: 「どうすれば正常に動くか」ではなく、**「どういう最悪の失敗（フリーズ、暴走、データ喪失）があり得るか」**を起点に設計を考えます。
*   **記述への反映**: 採用技術やパラメータの選定理由に、「〇〇というバグやハードウェア破損のリスクを回避するために、この制約（または分割送信等）が必要である」という防御的な意図を明記します。

### ② 検証可能性（Testability）の確保
*   **スタンス**: 「机上で正しい設計」よりも、**「素早くテストして確認できる設計」**を優先します。テストできない設計は、結合フェーズや実際の運用時に必ず破綻します。
*   **記述への反映**: 開発初期からシミュレータ（SILS）と地上局を透過的に繋げられるような「疎結合インターフェース」の選定根拠を明示し、いかにして実機なしで検証サイクルを高速化させるかを記述します。

### ③ 巨人の肩の上に立つ（合理的ブラックボックス）
*   **スタンス**: すべてをゼロから自作することは美徳ではありません。確立されたオープンソースツール（InfluxDB、Mosquitto、uPlotなど）を**「信頼可能なブラックボックスとして活用する」**ことで、限られたリソースをコアミッション（姿勢制御等）に集中させます。
*   **記述への反映**: なぜ自作を避けて既製品を使うのか、そのブラックボックス化によって節約されたリソースがどのコア開発（例：フライトソフトウェアのメインアルゴリズム）に充てられるのかを論理的に正当化します。

### ④ 要求と制約のバランス（YAGNI原則と簡素化）
*   **スタンス**: 「将来必要になるかもしれない」という予測に基づいた過剰設計（Over-engineering）を排除し、**「現在の制約下で最もシンプルで維持しやすい構成」**を選択します。
*   **記述への反映**: マイコン側の lwIP MQTT のような複雑な実装を避け、TCP-MQTTブリッジ（`bridge.py`）を挟むことでマイコンのプログラムを単純に保つといった、実用的な妥協と簡素化の意思決定を「合理的決断」として記述します。

---

## 4. 根拠を書くときのチェックリスト

自分の書いた設計ドキュメントを見直し、以下の項目が満たされているか確認しましょう。

*   `[ ]` 答え（採用技術）ありきのドキュメントになっておらず、不採用となった候補の欠点も客観的に書かれているか？
*   `[ ]` 一般的な類似システム（ROSや工業用IoT、他衛星プロジェクトなど）の「型」や「原理」に言及しているか？
*   `[ ]` 比較表の項目は、感覚的な「使いやすそう」ではなく、定量的・客観的な指標（メモリ負荷、通信オーバーヘッド、開発コスト等）になっているか？
*   `[ ]` 何をブラックボックスとして割り切った（自作を避けた）のかが明記されているか？
*   `[ ]` 読んだ第三者（他のゼミ生や講師）が、「この制約下なら、確かにこの選定が最も合理的だ」と納得できるか？
*   `[ ]` 「最悪ケースの回避（防御的設計）」や「検証しやすさ（SILS等による検証性）」が意思決定の軸として語られているか？