私たちが Salty Poker をこう作っている:spec-driven development

ほとんどのポーカー・プラットフォームは、ほとんどのポーカーのハンドがプレイされる方法と同じ作り方をされている — 速く、感覚で、進みながら考えながら。私たちはそうはしない。

初日から、私たちはこのプラットフォームを spec-driven development で作ると意図的に決めた。これは AI アシスト・エンジニアリングの界隈で本気で勢いを増している方法論であり、私たちが作っているすべてが乗っている土台だ。

Spec-driven development とは何を意味するのか

プロダクション・コードの 1 行が書かれる前に、まず仕様書が書かれた。100 ページを超える。システムのあらゆる領域を扱う 23 個のモジュール — インフラ、データベース・スキーマ、API コントラクト、サービス境界、コンプライアンス・コントロール、CI/CD パイプライン、運用 runbook。

この方法論は 3 つのレベルに分解される。Spec-first:どんなコードよりも先に徹底した仕様書が書かれ、それをもとに開発を進める。Spec-anchored:プロジェクトが成熟するにつれ、仕様書がコードベースと並行して生き続け、一緒に進化していく。Spec-as-source:人間が触るのは仕様書だけであり、コードは完全にそこから生成される。

名前をつけておく価値のある失敗パターンもある:spec-once — 仕様書がプロジェクトをキックオフして、ビルドが深まるにつれ静かに放棄されていくパターン。設計図が遺物に変わってしまう。

私たちはこれに明確に抗って設計されている。私たちの仕様書は生きた文書だ。決定が下されるたび、エッジケースが浮上するたび、アーキテクチャが進化するたびに更新される。セッションが終わるとき、仕様書は今まで作られたものを反映する。次のセッションが始まるとき、仕様書は前回のセッションが終わったまさにその地点から引き継ぐ。

なぜこれがポーカー・プラットフォームにとって重要なのか

ポーカー・プラットフォームは予測できる仕方で失敗する — そしてほとんどすべての失敗は同じ根本原因にたどり着く:初期段階で取られたショートカットが積み重なって、後に深刻な問題になる。

きちんとした複式簿記の ledger を持たずに作られたウォレット・システム。エッジケースに対してストレス・テストされていないゲーム・エンジン。初日から練り込まれたのではなく、あとから後付けで螺子留めされたコンプライアンス・レイヤー。50 人のプレイヤーでは問題なく動くが 500 人で崩壊するプラットフォーム。

Spec-driven development はそれを防ぐ規律だ。あらゆるサービス境界は、構築される前に定義される。あらゆるデータフローは、実装される前にドキュメント化される。あらゆるコンプライアンス要件は、たった 1 回のマイグレーションが実行される前にすでに仕様書に入っている。「それはあとで考えよう」という決定は存在しない — 「あとで」とは、プレイヤーが既にテーブルについている瞬間のことだからだ。

実行エンジンとしての Agentic AI

私たちはこのプラットフォームを作るために agentic AI を使っている — そしてこれと、多くの人が馴染んでいる AI ツールとの間には重要な区別がある。

Agentic AI はただ質問に答えたりコードを自動補完するだけではない。定義された境界の内側で、複数ステップのワークフローを自律的に実行する — コードを書き、テストを走らせ、失敗を捕まえ、直し、commit する — 人間がすべての動作を監督する必要はない。タスクを最初から最後までやり切り、人間のために予約された決定に達したときに制御を返す。

それを安全かつ予測可能にしているのが仕様書だ。エージェントは、定義されレビュー済みでバージョン管理された仕様書のもとで動作する。各セッションは、集中したモジュールのサブセットを読み込む — 一度に 2 つから 4 つ — エージェントが必要とする正確な文脈を与え、それ以外は与えない。各セッションには定義されたスコープがある。次のフェーズへの門は checkpoint で守られる。チェックリストが綺麗にならない限り、何も先に進まない。

エージェントは何を作るかを決めない。仕様書が決める。エージェントは実行する。

その結果

それにふさわしい厳格さで作られたプラットフォーム。あらゆるアーキテクチャ上の決定は文書化されている。あらゆるサービス境界は意図されたものだ。あらゆるコンプライアンス要件は、それが問題になる前に扱われている。

それが私たちが作っているものだ。そして、その上でプレイするとき、あなたは違いを感じるだろう。

私は spec-driven development について方法論として — 決定、ツール、セッションの構造、そしてポーカーを超えてそれが何を意味するのか — The Salty Korean に書いている。エンジニアリング側に興味があるなら、より深い話はそこにある。

この方法論についてさらに:Heeki Park による Using Spec-Driven Development with Claude Code。

Stay salty.