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 は使用しない。

🔗 構造接続ルール

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

📂 推奨構成

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

原則：

1 screen = 1 file

⚙ CLI

mobilespec check
mobilespec update

check（CI / read-only）

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

pnpm run sdd:check

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

update（local / write）

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

pnpm run sdd:update

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

🧠 SDD のゴール

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

🔥 mobilespec の役割

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

📚 詳細ドキュメント構成

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/ 以下へ。