# mobilespec

## Structure-Driven Development (SDD) 仕様エンジン

mobilespec は  
**Structure-Driven Development（構造駆動開発）** を実践するための  
構造検証・可視化・契約整合エンジンです。

---

## 🎯 SDD とは

SDD は、

- API 構造（OpenAPI）
- 画面遷移構造（L2）
- UI 構成構造（L3）
- 状態・データ契約構造（L4）

を **唯一の正（SSOT）** とし、

実装コードを生成物として扱う開発手法です。

---

## 🧠 基本原則

1. 構造が正、実装は生成物
2. OpenAPI は API 契約の唯一の正
3. L2 / L3 / L4 は UI 契約の唯一の正
4. URL / HTTP メソッド直書き禁止
5. L4 は operationId のみ参照
6. selectRoot は必須（OpenAPI で証明可能であること）
7. 契約違反は CI が検知する（AIは検知しない）

---

## 🔎 診断ポリシー（固定）

mobilespec は **2段階のみ** を採用する。

| level | 意味                   |
| ----- | ---------------------- |
| error | 実装不能（CI fail）    |
| info  | 状態可視化（常時表示） |

warning は使用しない。

---

## 🔗 構造接続ルール

```txt
L3.action
↓
L2.transition.id
↓
L4.events key
↓
L4.data (query/mutation key)
↓
OpenAPI.operationId
```

この縦接続が成立している状態を  
**Structural Integrity（構造整合）** と呼ぶ。

---

## 📐 検証内容

### L2

- screen 重複
- 遷移ターゲット不正
- entry から到達不能 screen → ❌ error
- 未使用 transition → ℹ️ info

### L3

- action → L2 transition 不一致 → ❌ error

### L4

- screenKey 不一致 → ❌ error
- event ↔ L2 transition 不一致 → ❌ error
- query / mutation 未定義参照 → ❌ error

### OpenAPI

- operationId 未定義 → ❌ error
- 重複 → ❌ error
- L4 が存在しない operationId 参照 → ❌ error
- 未使用 operationId → ℹ️ info（構造進捗表示）

### i18n

- key 不存在 → ❌ error
- 未翻訳（ja以外） → ℹ️ info

---

## 📂 推奨構成

```txt
specs/
  L2.screenflows/
  L3.ui/
  L4.state/
  i18n/
```

原則：

> 1 screen = 1 file

---

## ⚙ CLI

```bash
mobilespec check
mobilespec update
```

### check（CI / read-only）

CI では **check のみ**を実行する（ファイルを生成・更新しない）：

```bash
pnpm run sdd:check
```

error が1件でもあれば exit 1。

### update（local / write）

ローカル開発では、仕様変更後に **生成物（i18n / mermaid）を更新してから検証**したい場合がある。

```bash
pnpm run sdd:update
```

`update` は i18n / mermaid を更新し、その後に `check` を実行する（副作用あり）。

---

## 🧠 SDD のゴール

- 実装は破棄可能
- フレームワーク変更可能
- AI は構造のみ読めば生成可能
- 契約違反は自動検知
- トークン消費最小

---

## 🔥 mobilespec の役割

> 構造を正とするための検証エンジン

---

## 📚 詳細ドキュメント構成

```txt
docs/
  adr/
  01_principles.md
  02_structure_model.md
  03_validation_model.md
  04_ci_policy.md
  05_lifecycle.md
  06_ai_collaboration.md
  07_configuration.md
```

README は「入口」。

詳細は docs/ 以下へ。