はじめに（Why）

数年運用している業務システムで、ずっとモヤっとしていた問題がありました。

機能は動いているが 仕様書がない
「これは仕様？それともたまたま？」がコードを読まないと分からない
特に 例外系・権限・二重処理 で、担当者ごとに解釈が違う

今回対象にしたのは「ポイント交換」機能です。

複数の交換先がある
最小/最大、換算率、権限など制約が多い
外部連携失敗時の扱いが重要

正直、毎回コードを追うのはしんどく、
「人間が読める仕様」に落としたいと思いました。

ただし、現実は既存システム。
新規開発のように Gherkin から書くのは無理です。

そこで試したのが、AIを使った逆Gherkin化でした。

Gherkin / BDD とは（最小限）

Gherkin：Given / When / Then で振る舞いを書くフォーマット
BDD：仕様とテストの認識を揃える考え方

今回は 「テスト自動化」ではなく「仕様の可視化」 が目的です。
いきなり Behave / Cucumber を回すことはしません。

なぜ「逆Gherkin化」なのか

新規開発なら、

仕様 → Gherkin → 実装

が理想です。

でも既存システムでは、

実装（＝事実） → 仕様

の方が現実的です。

正解は「動いているコード」
仕様書よりコードの方が新しい
暗黙知を炙り出したい

逆Gherkin化は、既存システムにBDDを途中導入する現実解だと感じました。

対象にしたシステム（抽象化）

バックエンド：Python系API
フロント：Web / アプリ相当（別リポジトリ）
機能：ポイント交換（複数の交換先）

この機能の特徴は、

残高チェック
最小 / 最大交換量
換算レート（デバイス差あり）
権限（購入・利用実績によって変化）
二重処理防止
外部連携失敗時のロールバック

仕様の塊みたいな機能でした。

実際にやった手順（How）

Step1：対象を絞る

最初から全部はやりません。

if / else が多い
ステータス分岐がある
例外が多い

この条件に当てはまる 交換フロー1種類から始めました。

Step2：AIに「調査役」をやらせる

重要なのは プロンプト設計です。
「Gherkinにして」だけだと、ほぼ失敗します。

実務で使っている調査依頼プロンプト（汎用化）はこちらです。

あなたは既存システムの仕様調査担当です。
仕様書が存在しない「ポイント交換」機能について、コードから振る舞いを読み取り、
人間が理解できるようにGherkin（Given/When/Then）で列挙してください。

目的:
- 仕様の全体像と差分を把握する
- レビュー・合意可能な仕様書を作る

ルール:
- 技術用語（クラス名、DB、HTTPなど）は使わない
- ユーザー視点・業務視点で書く
- if/elseをそのまま列挙しない
- 正常系と代表的な異常系を含める
- 断定できない点は「要確認」と明示する

出力:
1) 発見した交換種類と制約
2) Gherkin（Feature / Scenario）
3) 要確認事項

ポイントは 「断定しない」「要確認を出させる」 です。

Before / After（ここが一番反応が良かった）

Before（擬似コード）

if not user.can_exchange:
    raise Forbidden

if amount < MIN_AMOUNT:
    raise ValidationError

if lock_exists(user_id):
    raise Conflict

deduct_points(user, amount)

try:
    external_grant(converted_amount)
except ExternalError:
    refund_points(user, amount)

After（Gherkin）

Feature: ポイントを外部サービスへ交換する

  Background:
    Given ログイン済みの会員である
    And ポイント交換が許可されている

  Scenario: 正常にポイントを交換できる
    Given 利用可能ポイントが1,000ptある
    When 500ptの交換を申請する
    Then 利用可能ポイントが500pt減る
    And 外部ポイントが付与される

  Scenario: 交換権限がない場合は交換できない
    Given ポイント交換が許可されていない
    When 交換を申請する
    Then 交換できない旨が表示される
    And ポイントは減らない

  Scenario: 外部付与に失敗した場合は元に戻る
    Given 交換申請が受け付けられている
    When 外部付与が失敗する
    Then ポイントは元に戻る
    And 利用者に失敗が分かる

コードでは「当たり前」だった分岐が、
仕様として初めて言語化されました。

やって分かった：AIは万能じゃない（Gotcha）

Gotcha1：内部仕様を仕様だと誤解する

TTL
リトライ回数
バッチタイミング

AIは全部 Then に書きたがります。

👉 Gherkinは「観測可能な結果」だけにする
👉 内部都合は「実装メモ」へ逃がす

Gotcha2：提供終了・移行中の機能が混ざる

画面では終了案内が出ているのに、
Scenario上は「普通に使える」扱いになっていました。

👉 @deprecated や @disabled のタグで整理
👉 「現行 / 過去 / 移行中」を明示

Gotcha3：用語が揺れる

「残高」「利用可能」「付与」「交換」などが混在。

👉 用語を Feature冒頭で固定
👉 Glossaryを別途作成

なぜ最初からテストにしなかったのか

最初からBDDテストにすると、

仕様が固まっていない
要確認が多い
テストが壊れやすい

今回はあえて 「仕様の可視化」だけ に集中しました。

テスト化は、
合意が取れた Feature から段階的にで十分でした。

導入して得られた効果

仕様確認が「コード読む」→「Scenario読む」に変わった
例外系の認識ズレが減った
レビュー観点が整理されたことで、1件あたりのレビュー往復回数が
- 逆Gherkin化前：平均3〜4往復
- 逆Gherkin化後：平均1〜2往復
  程度に減りました（体感ベース）。
新規メンバーのキャッチアップが楽になった

特に「これは仕様ですか？」という会話が
Gherkinを指差すだけで済むようになったのは大きかったです。

まとめ

逆Gherkin化は 既存システムにBDDを入れる現実解
AIは「仕様の叩き台作成」に非常に強い
ただし レビューと要確認整理は人間必須
全部やらず、重要フローだけで十分

もし既存コードの仕様化に悩んでいるなら、
テストを書く前に、逆Gherkin化を強くおすすめします。