ブループリントの例

{
  "intent": "夜と昼のラウンドを、全員に見えるタイマーでゲーム自身が進行し、誰もGM役で抜けなくて済むようにする。",
  "why": "いまは誰か1人がゲームから抜けて、役職を配り、夜に起こし、票を数えています。その人は一度も遊べません。このアウトカムのすべては、その役目を交代制にするのではなく消すために存在します。",
  "success": [
    {
      "statement": "最初の夜から決着まで、人間の進行役なしに1ゲームを完走できる",
      "verifiable": true
    },
    {
      "statement": "フェーズの変化が2秒以内に全プレイヤーの画面へ届く",
      "verifiable": true,
      "changeType": "modified"
    },
    {
      "statement": "フェーズが閉じる前に送られた行動は必ず集計される",
      "verifiable": true
    }
  ],
  "stakes": {
    "nonNegotiable": [
      "プレイヤーが他人の役職を受け取ることはない",
      "時計はサーバーが持ち、クライアントは表示するだけ"
    ],
    "acceptableTradeoffs": [
      "フェーズが閉じる時点でオフラインのプレイヤーは、そのフェーズの行動を失う",
      "ラウンド履歴はそのゲーム内のみで保持し、保管はしない"
    ]
  },
  "constraints": [
    {
      "rule": "片手で操作できるモバイルブラウザで動くこと",
      "hard": true
    },
    {
      "rule": "アカウントなし。席は参加リンクの使い捨てトークン",
      "hard": true
    }
  ],
  "escalate": [
    {
      "when": "同じゲームで、2人が別のフェーズを見ていると報告された",
      "action": "ラウンドを凍結してオーナーに上げる — 時計が割れると以降の投票がすべて静かに無効になる"
    },
    {
      "when": "その役職を持たないプレイヤーへの応答に、役職が含まれていた",
      "action": "ゲームを停止して配り直す — 勝てないゲームになっており、誰もそれに気づけない"
    }
  ]
}

sequenceDiagram
  autonumber
  actor P as プレイヤー
  participant R as ラウンドサービス
  participant D as Postgres
  participant C as フェーズタイマー
  actor O as 他のプレイヤー
  P->>R: 夜の行動を送信
  alt フェーズが開いている間
    R->>R: 役職がその行動を許すか検証
    R->>D: 行動を保存（フェーズ番号つき）
    R-->>P: 受理
  else 締め切り後
    R-->>P: 拒否。すでに解決済みのフェーズ
  end
  C->>R: 夜のタイマー満了
  R->>D: フェーズを閉じる
  R->>R: この夜の行動をまとめて解決
  R->>O: 結果を全員へ配信
  R->>P: 結果を全員へ配信
  P-->>P: 夜明けの結果を見る

stateDiagram-v2
  [*] --> Lobby
  Lobby --> Dealing: 全席が埋まる
  Dealing --> Night: 役職を配り終える
  Night --> Dawn: 夜のタイマー満了
  Dawn --> Day: 夜の行動を解決
  Day --> Voting: 議論のタイマー満了
  Voting --> Tally: 開票
  Tally --> Day: 同数
  Tally --> Resolution: 追放が確定
  Resolution --> Night: 決着せず
  Resolution --> MafiaWin: 人狼の勝ち
  Resolution --> TownWin: 村人の勝ち
  MafiaWin --> [*]
  TownWin --> [*]

Table games {
  id uuid [pk]
  join_code varchar [not null, unique]
  phase varchar [not null]
  phase_number int [not null, default: 0]
  phase_ends_at timestamptz
  note: '唯一の時計がこの phase_ends_at。フェーズの終了をクライアントが判断することはない。'
}

Table seats {
  id uuid [pk]
  game_id uuid [not null, ref: > games.id]
  display_name varchar [not null]
  seat_token varchar [not null, unique]
  alive boolean [not null, default: true]

  indexes {
    (game_id, display_name) [unique, name: 'one_seat_per_name_per_game']
  }
  note: '席の証明に使うのは seat_token。名前は公開だが、トークンは公開しない。'
}

Table role_assignments {
  seat_id uuid [pk, ref: > seats.id]
  role varchar [not null]
  note: '読み出すのはサーバーのみ。所有する席にしか返さない。'
}

Table night_actions {
  id uuid [pk]
  game_id uuid [not null, ref: > games.id]
  phase_number int [not null]
  actor_seat_id uuid [not null, ref: > seats.id]
  target_seat_id uuid [ref: > seats.id]

  indexes {
    (game_id, phase_number, actor_seat_id) [unique, name: 'one_action_per_seat_per_phase']
  }
  note: '送信時のフェーズ番号を刻む。遅れて届いた行動は次の夜に適用されず、拒否される。'
}

Table votes {
  game_id uuid [not null, ref: > games.id]
  phase_number int [not null]
  voter_seat_id uuid [not null, ref: > seats.id]
  target_seat_id uuid [not null, ref: > seats.id]

  indexes {
    (game_id, phase_number, voter_seat_id) [unique, name: 'one_vote_per_seat_per_phase']
  }
}

# ──── Core Tier ────

core: {
  round: {
    Round: {
      shape: class
      \# Aggregate Root
      gameId: uuid
      phase: Phase
      phaseNumber: int {constraint: monotonic}
      phaseEndsAt: timestamptz

      open()
      close()
      resolve()
    }

    # @change: added
    NightAction: {
      shape: class
      actorSeatId: uuid {constraint: unique with phaseNumber}
      targetSeatId: uuid
      phaseNumber: int
    }

    Vote: {
      shape: class
      voterSeatId: uuid {constraint: unique with phaseNumber}
      targetSeatId: uuid
      phaseNumber: int
    }

    Round -> NightAction: 保持する
    Round -> Vote: 保持する
  }

  roster: {
    Game: {
      shape: class
      \# Aggregate Root
      id: uuid
      joinCode: string {constraint: unique}
    }

    Seat: {
      shape: class
      id: uuid
      displayName: string
      seatToken: string {constraint: secret}
      alive: boolean
    }

    RoleAssignment: {
      shape: class
      seatId: uuid
      role: Role {constraint: server-only}
    }

    Game -> Seat: 保持する
    Game -> RoleAssignment: 配る
  }
}

# ──── Supporting Tier ────

supporting: {
  presence: {
    Connection: {
      shape: class
      seatId: uuid
      lastSeenAt: timestamptz
    }
  }
}

# ──── Generic Tier ────

generic: {
  delivery: {
    # @change: modified
    PhaseBroadcast: {
      shape: class
      phase: Phase
      sentAt: timestamptz
    }
  }
}

# ──── Cross-Context Relationships ────

core.roster.Seat -> core.round.NightAction: 対象にする
core.round.Round -> core.roster.Game: 進める
supporting.presence.Connection -> core.roster.Seat: 着席する
core.round.Round -> generic.delivery.PhaseBroadcast: 配信する

specification {
  element actor
  element system
  element container
  element database
}

model {
  player = actor "プレイヤー"
  mafia = system "人狼ゲーム" {
    web = container "ゲーム画面" "Next.js、モバイルブラウザで動作"
    round = container "ラウンドサービス" "フェーズの時計を持ち、行動を解決する"
    timer = container "フェーズタイマー" "各フェーズを時間どおりに閉じる"
    db = database "Postgres" "ゲーム、席、役職、行動、投票"
  }
  player -> mafia.web "遊ぶ"
  mafia.web -> mafia.round "行動と投票を送る"
  mafia.round -> mafia.db "フェーズ番号つきで保存"
  mafia.timer -> mafia.round "フェーズを終了"
  mafia.round -> mafia.web "フェーズの変化を配信（役職は含まない）"
}

views {
  view rounds { include * }
}

{
  "openapi": "3.0.3",
  "info": {
    "title": "人狼 ラウンドAPI",
    "version": "0.1.0",
    "description": "1ラウンドを進めるために必要な最小の面。役職を返す経路は存在しない。"
  },
  "paths": {
    "/games/{id}/state": {
      "get": {
        "summary": "自分から見た現在の状態",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "フェーズ、残り時間、生存者、そして自分の役職のみ"
          }
        }
      }
    },
    "/games/{id}/actions": {
      "post": {
        "summary": "夜の行動を送る",
        "responses": {
          "202": {
            "description": "受理。フェーズ番号を刻んで保存"
          },
          "403": {
            "description": "この役職にその行動は許されていない"
          },
          "409": {
            "description": "そのフェーズはすでに解決済み"
          }
        }
      }
    },
    "/games/{id}/votes": {
      "post": {
        "summary": "投票する",
        "responses": {
          "202": {
            "description": "受理"
          },
          "409": {
            "description": "この席はこのフェーズですでに投票済み"
          }
        }
      }
    },
    "/games/{id}/events": {
      "get": {
        "summary": "フェーズ変化のストリーム",
        "responses": {
          "200": {
            "description": "サーバー送出のフェーズ変化。役職は含まない"
          }
        }
      }
    }
  }
}

{
  "schemaVersion": 1,
  "decisions": [
    {
      "category": "language",
      "choice": "TypeScript",
      "icon": "typescript",
      "rationale": "フェーズとロールの型をサーバーと画面で共有し、片側だけ古くなることを防ぐ。",
      "alternatives": [
        "Python",
        "Go"
      ]
    },
    {
      "category": "framework",
      "choice": "Next.js",
      "icon": "nextdotjs",
      "rationale": "参加画面とラウンド画面を同じ土台で出し、サーバー送出イベントもそのまま扱える。",
      "alternatives": [
        "Remix",
        "SvelteKit"
      ],
      "tradeoffs": "同時接続が数百を超えると、専用のソケット層が必要になる。"
    },
    {
      "category": "database",
      "choice": "PostgreSQL",
      "icon": "postgresql",
      "rationale": "1フェーズ1席1行動という制約が、アプリのコードではなく一意インデックスそのもの。",
      "alternatives": [
        "MySQL",
        "DynamoDB"
      ],
      "changeType": "modified"
    },
    {
      "category": "hosting",
      "choice": "Vercel",
      "icon": "vercel",
      "rationale": "デプロイ単位が小さく、参加リンクの配信が素直。",
      "alternatives": [
        "Fly.io",
        "Render"
      ]
    },
    {
      "category": "auth",
      "choice": "席トークン（アカウントなし）",
      "rationale": "名前は通話にいる全員に見えるため、席の証明には使えない。参加時に配る使い捨てトークンで代替する。",
      "alternatives": [
        "Auth0",
        "Clerk"
      ],
      "changeType": "added"
    },
    {
      "category": "monitoring",
      "choice": "構造化ログ + エラートラッキング",
      "rationale": "ワークスペースの既定を継承。このアウトカムのために選び直していない。"
    }
  ]
}

{
  "dimensions": [
    {
      "name": "役職の秘匿",
      "target": 100,
      "current": 100,
      "weight": 1,
      "description": "自分のセッションが他人の役職を受け取ることはない。交渉の余地がない。",
      "slaTarget": "漏洩 0件",
      "linkedRequirements": [
        "J2-S1",
        "J2-S2"
      ]
    },
    {
      "name": "フェーズの一致",
      "target": 95,
      "current": 74,
      "weight": 1,
      "description": "全プレイヤーが同じ瞬間に同じフェーズを見ていること。",
      "slaTarget": "ずれ 2秒以内",
      "changeType": "modified"
    },
    {
      "name": "行動の取りこぼしのなさ",
      "target": 99,
      "current": 91,
      "weight": 0.9,
      "description": "締め切り前に送られた行動が、必ず集計されること。",
      "slaTarget": "取りこぼし 0件"
    },
    {
      "name": "復帰の正しさ",
      "target": 80,
      "weight": 0.6,
      "description": "切断から戻ったプレイヤーが、正しいフェーズと自分の役職に戻ること。未計測 — 別アウトカム。",
      "changeType": "added"
    },
    {
      "name": "モバイルでの操作性",
      "target": 90,
      "current": 83,
      "weight": 0.8,
      "description": "ルームでチャットしながら片手で操作できること。",
      "slaTarget": "主要操作は1タップ"
    }
  ]
}