はじめに
シリーズ第4回。ハーネスの土台（第2〜3回）の上の話です。
この記事では、何を・どう作るかを決める仕様駆動開発（SDD）のパイプラインを扱います。
- いきなり実装させない「発見（Example Mapping）」
- 要件を機械検証可能にする EARS と Gherkin
- 各段階に置いた 人間ゲート とトレーサビリティ
📦 ソースコード：https://github.com/NeoSolleil/aim-trainer/tree/harness-only
（harness-onlyブランチ。mainは今後の機能開発で変わるため、記事と一致する状態を固定したブランチです）
↓mainブランチはこちらです
なぜ「仕様駆動」なのか
AIに「エイム練習アプリを作って」と丸投げすると、それらしいものは出ますが、仕様が曖昧なまま実装が暴走します。「命中率って何で割るの？」「クリック0回のときは？」——こうした論点が未定のまま、AIが勝手に決めて進んでしまう。
そこで、先に「何を作るか」を機械検証可能な形で固めてから実装するのが仕様駆動開発（SDD）です。本プロジェクトでは、これを5つの段階に分け、**各段階の終わりに人間のレビュー（ゲート）**を置きました。
発見 → 仕様化 → 設計 → 分解 → 実装
discover specify plan tasks implement
（各段階に人間ゲート：未承認なら次へ進めない）
下敷きにしたのは、BDD（振る舞い駆動開発）の3工程 「発見 → 定式化 → 自動化」 です。
段階0：discover（発見）— いきなり仕様を書かない
最初の工夫は、仕様を書く前に「発見」段階を独立で置いたことです。いきなり要件を書くと、考慮漏れに気づけません。まず多角的に論点を洗い出します。
手法は Example Mapping（Matt Wynne 考案）。1つの機能を4色のカードに分解します。
- 🟡 Story：その機能は誰の・何を・なぜ
- 🔵 Rule：守るべきルール（受け入れ基準）
- 🟢 Example：ルールの具体例（正常・異常・境界）
- 🔴 Question：未確定・疑問・抜け漏れ
そして スリーアミーゴス（プロダクト・QA・開発の3視点）で洗い出します。本プロジェクトでは、この3視点をそれぞれ独立したAIエージェントに割り当てました（詳細は第5回）。
重要なルール：🔴（疑問）が残っている間は、次の仕様化に進めない。疑問を人間が答えて潰し、承認して初めて前進します。「AIが勝手に決めない」を構造で担保しています。
たとえばエイム練習なら、こんな🔴が出ます。
- 命中率の分母は「総クリック数」か「出現した的の数」か
- クリック0／ヒット0のときの命中率（0÷0問題）
- 的の寿命、二重クリックや空クリックの扱い
これらを人間が決めてから、初めて仕様を書きます。
段階1：specify（仕様化）— EARS と Gherkin
発見の結果を、機械検証可能な2つの文書に清書します。発見カードが、そのまま仕様の素になります。
EARS：要件＝ルールの台帳
要件は EARS という決まった構文で書きます。曖昧さを排除するための型です。
-
WHEN <トリガー>, the <システム> SHALL <応答>（イベント駆動） -
IF <異常条件>, THEN the <システム> SHALL <応答>（異常系）
例：
R-1 WHEN プレイヤーが的の内側をクリックしたとき,
the system SHALL ヒットと反応時間を記録する。
R-2 IF プレイヤーが的の外側をクリックしたとき,
THEN the system SHALL ミスを記録する。
各要件に R-1, R-2 …とIDを振ります。これが後で「全要件にテストがあるか」を追う鍵になります。
Gherkin：具体例＝合格条件
要件（抽象ルール）に対し、Gherkin で具体例（テスト可能な合格条件）をぶら下げます。
@R-2
Scenario: 的の外側クリックはミス
Given セッションが進行中で、中央に的が1つある
When プレイヤーが座標(10,10)をクリックする
Then システムはミスを記録する
And 反応時間の平均は変化しない
「機能 ＞ 要件 ＞ シナリオ」の3段
ここは混乱しやすいので明文化しました。
機能（フォルダ） ＞ 要件（EARS, R-x） ＞ シナリオ（Gherkin, @R-x）
1機能に複数の要件、1要件に複数のシナリオ。紐付けはファイル分割ではなく**タグ（@R-1）**で行う。
「ヒットの記録」は機能ではなく、シューティングセッション機能の中の1要件——といった粒度感も、この段階で揃えます。
段階2〜4：plan / tasks / implement
-
plan（設計）：要件を DDD（ドメイン駆動設計）の語彙で設計し、API契約・テーブル定義・画面設計を
design.mdにまとめる。 - tasks（分解）：設計を、Clean Architecture の内側から外側へ・テストファーストの順に作業分解する。新しいシナリオは作らず、既存のシナリオを参照してグルーピングするだけ。
- implement（実装）：TDD で進める。Gherkin シナリオをテストコードに変換してまず失敗させ（red）、最小実装で通し（green）、整える（refactor）。テストのない実装を「完了」と認めない。
全体を貫く2つの仕掛け
-
Status ゲート：各成果物（discovery.md / requirements.md / design.md / tasks.md）の先頭に
Status: Draft | Approvedを持たせ、前段が Approved でなければ次に着手しない。人間の承認を段階ごとに挟みます。 - トレーサビリティ：要件ID（R-x）→ シナリオ（@R-x）→ テスト、と一本の線で追えるようにする。「どの要件が、どのテストで守られているか」が常に分かります。
まとめ
SDDは「先に何を作るか固める」開発です。発見（Example Mapping）で漏れを潰し、仕様化（EARS＋Gherkin）で機械検証可能にし、設計・分解・実装と、各段階を人間ゲートで承認しながら進めます。
最終回（第5回）は、この5段階を誰が・どう回すか——Claude Code のスキルとサブエージェントで役割分担し、品質を上げる仕掛けを紹介します。