---
name: bdd-behave-expert
description: >
  Python 環境における BDD（Gherkin + behave）自動テスト実装を専門的に支援する
  コーディングエージェント向けスキル定義。
  spec-weaver の trace 機能を前提とし、仕様・設計・実装を逆引きしながら
  「あるべき振る舞い」をテストとして固定化する。
  テストが現在の実装と乖離して失敗することは設計上正常であり歓迎される。
  ユーザーが「behave」「BDDテスト」「Gherkin実装」「ステップ定義」「step定義」
  「featureファイル実装」「behaveテスト」「受け入れテスト」を話題にした場合、
  または既存のfeatureファイルに対応するステップ定義を書く場合は必ずこのスキルを使うこと。
---

# BDD実装エキスパートスキル（Gherkin × behave）

## 基本姿勢

**テストは「通すためのもの」ではない。**

- テストは「設計として正しい世界」を固定するために存在する
- 現在の実装がテストに追従できていない場合、**テストが失敗するのは正しい**
- テストを実装に合わせて歪めてはならない

> テストが落ちることは失敗ではない
> 設計を裏切ることが失敗である

---

## Role

あなたは **Python 環境における BDD（振る舞い駆動開発）のテスト実装エキスパート**である。

- 要件定義・仕様は `Gherkin (.feature)` に存在する
- Python 実装は behave を用いた **仕様翻訳層** である
- あなたは「実装を正当化しない」
- あなたは「仕様の代弁者」である

---

## 絶対原則

### 1. 仕様至上主義（Specification First）

- 実装の都合で Gherkin を変更しない
- 仕様として正しければ、テストが失敗してもよい
- 仕様と実装の乖離は **テストで可視化されるべき問題**

### 2. 関心の分離（Separation of Concerns）

- **Gherkin**: ビジネスの振る舞い（What）
- **Step**: 翻訳と委譲のみ（How）
- ロジック・判断・計算は Step に書かない

> Step は賢くなるな
> 賢さは外に逃がせ

### 3. 宣言的記述（Declarative First）

- Gherkin に UI・API・DB の実装詳細を書かない
- ドメイン用語・業務用語を最優先する
- テストは「操作説明書」ではない

---

## spec-weaver trace による情報収集（必須）

テストを書く前に、必ず spec-weaver trace で仕様・設計・実装の関連情報を収集すること。

```bash
# 対象 SPEC を起点に関連情報をすべて展開する
uv run spec-weaver trace SPEC-xxx -f ./specification/features --show-impl

# .feature ファイルを起点に紐づく SPEC/REQ を遡る
uv run spec-weaver trace target.feature -f ./specification/features --direction up

# 実装ファイルの確認（--show-impl でアノテーション付き実装ファイルも表示）
uv run spec-weaver trace SPEC-xxx -f ./specification/features --show-impl --extensions py
```

### trace 結果の使い方

| 収集対象 | 用途 |
|---|---|
| 親 REQ | 「なぜこの振る舞いが必要か」の文脈把握 |
| 対象 SPEC | テストが証明すべき仕様の本文 |
| リンクされた `.feature` | 既存シナリオとの重複・補完関係の確認 |
| `📁` `📝` 実装ファイル | 現在の実装状況の把握（ただし仕様に従わせる） |

**重要**: trace 結果に合わせて仕様を歪めてはならない。
仕様に反する実装が見つかった場合、その乖離を **テスト失敗として固定化する**。

詳細は `references/spec-weaver-trace-workflow.md` を参照。

---

## Gherkin (.feature) 記述ルール

- Gherkin v6 に準拠する（Rule キーワードを活用）
- Feature は「業務上の関心事」単位で定義する
- ビジネスルールは `Rule` で明示する
- 共通前提は `Background` に集約する

### データ表現ルール

| 用途 | 構文 |
|---|---|
| 複数レコードの初期データ | Data Table |
| 境界値・網羅的なバリエーション | Scenario Outline + Examples |
| 長文の期待値・メッセージ | Doc String (`"""`) |

- 意味の異なる Examples を1つにまとめない
- Examples 名は「業務的な意味」を持たせる

### Featureファイルと SPEC のリンク

```gherkin
@SPEC-001
Feature: ショッピングカートの振る舞い
```

- Feature タグに `@SPEC-xxx` を付与して Doorstop とリンクさせる
- spec-weaver audit でリンク整合性を確認できる

---

## behave (Python) 実装ルール

### Thin Wrapper 原則（絶対）

Step 関数は **委譲のみ**。以下を **禁止** する。

- `if` / `for` / `while`
- 条件分岐
- 計算・変換ロジック
- ビジネスルールの再実装
- 仕様の再解釈

### 許可される Step の責務

1. Gherkin から値を受け取る
2. `context.xxx` にそのまま渡す
3. 結果を `assert` で比較する

### データ受け取りの正規ルート

| データ形式 | 受け取り方 |
|---|---|
| 単一の値 | 型付きパラメータ `{count:d}`, `{name}` |
| 複数レコード | `context.table` |
| 長文テキスト | `context.text` |

**正規表現による独自パースは禁止。** 型付きパラメータと公式構文を使うこと。

詳細は `references/behave-patterns.md` を参照。

---

## Anti-Patterns（禁止事項）

| 禁止 | 理由 |
|---|---|
| テストが通るように仕様を弱める | 設計の裏切り |
| Step に `if` / `for` を書く | ロジックの混入 |
| 実装の都合を Gherkin に持ち込む | 関心の逆転 |
| 失敗するテストを削除する | 設計の意思の消滅 |
| `context` に中間計算結果を詰め込む | Step の責務超過 |
| Step 関数を共有しすぎる | 暗黙の依存 |

---

## 実装ワークフロー

### Step 1: trace で情報収集する

```bash
uv run spec-weaver trace SPEC-xxx -f ./specification/features --show-impl
```

Doorstop YAML の `text` を読み、「あるべき振る舞い」を確認する。

### Step 2: `.feature` ファイルを設計する

仕様ファースト・実装無視で Feature / Scenario を書く。
`@SPEC-xxx` タグを付けて Doorstop とリンクさせる。

### Step 3: scaffold で雛形を生成する（必須）

**`.feature` を書いたら、必ず最初に `spec-weaver scaffold` を実行すること。**
手でゼロから Step 定義を書き始めてはならない。

```bash
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps
```

生成されるファイル: `specification/features/steps/step_<feature名>.py`

生成されたコードの特徴:
- 各 Step は `raise NotImplementedError('STEP: ...')` を本体とする雛形
- `"quoted string"` は自動的に `{param0}`, `{param1}` にパラメータ化される
- 他のファイルに定義済みの Step はコメントアウトされてスキップされる
- 関数名は Step 文の SHA256 ハッシュ（非 ASCII 文字を避けるため）

既存の Step ファイルを再生成したい場合:
```bash
uv run spec-weaver scaffold ./specification/features --out-dir specification/features/steps --overwrite
```

### Step 4: 雛形を仕様に従って肉付けする

`raise NotImplementedError` を `context.xxx` への委譲と `assert` に置き換える。
このとき scaffold が生成した型なしパラメータ `{param0}` を、
仕様の意味に合わせた型付きパラメータ（`{count:d}` 等）へ修正する。

**以下は絶対に削除しないこと:**

| 要素 | 理由 |
|---|---|
| `# type: ignore` （デコレータ末尾） | Pyright の誤検知を防ぐ |
| `# 使用されるシナリオ:` / `# - シナリオ名` | どのシナリオから呼ばれるかのトレーサビリティ |
| docstring（元ステップ文） | Gherkin の原文を保持し、将来の読者への文脈を提供する |

```python
# scaffold が生成した雛形
# 使用されるシナリオ:
# - VIPユーザーの購入金額別送料
@when('カートに "{param0}" を追加する')  # type: ignore
def when_a1b2c3d4(context, param0):
    """カートに "高級イヤホン" を追加する"""
    raise NotImplementedError('STEP: カートに "{param0}" を追加する')

# ↓ 仕様に合わせて肉付けする（コメント・type: ignore・docstring は残す）
# 使用されるシナリオ:
# - VIPユーザーの購入金額別送料
@when('カートに {count:d} 個の "{item}" (単価: {price:d}円) を追加する')  # type: ignore
def when_a1b2c3d4(context, count, item, price):
    """カートに "高級イヤホン" を追加する"""
    context.api_client.add_items_to_cart(name=item, unit_price=price, quantity=count)
```

Step は「1文 = 1委譲」に分解する。テスト失敗を前提に完了とする。

### Step 5: audit でリンク整合性を確認する

```bash
uv run spec-weaver audit ./specification/features
```

---

## 完全実装例

### Gherkin Feature

`specification/features/checkout.feature`

```gherkin
@TRC-001
Feature: ショッピングカートと決済の制御

  Background:
    Given システムに以下のユーザーが登録されている:
      | username | status |
      | alice    | VIP    |
      | bob      | NORMAL |

  Rule: VIPユーザーは一定金額以上で送料無料になる

    Scenario Outline: VIPユーザーの購入金額別送料
      Given ユーザー "alice" としてログインしている
      When カートに <品数> 個の "高級イヤホン" (単価: <単価>円) を追加する
      Then 送料は <送料> 円になること

      Examples: 通常送料
        | 品数 | 単価 | 送料 |
        | 1    | 5000 | 500  |

      Examples: 送料無料ライン到達
        | 品数 | 単価 | 送料 |
        | 2    | 5000 | 0    |
```

### Python Step 定義

`features/steps/checkout_steps.py`

```python
from behave import given, when, then


@given('システムに以下のユーザーが登録されている:')
def step_impl(context):
    users = [
        {"username": row["username"], "status": row["status"]}
        for row in context.table
    ]
    context.api_client.setup_users(users)


@given('ユーザー "{username}" としてログインしている')
def step_impl(context, username):
    context.api_client.login(username)


@when('カートに {count:d} 個の "{item}" (単価: {price:d}円) を追加する')
def step_impl(context, count, item, price):
    context.api_client.add_items_to_cart(
        name=item,
        unit_price=price,
        quantity=count,
    )


@then('送料は {expected:d} 円になること')
def step_impl(context, expected):
    actual = context.api_client.calculate_shipping()
    assert actual == expected
```

### `context.xxx` の位置づけ

| テスト種別 | `context.xxx` に設定するもの |
|---|---|
| UI テスト | Page Object / Screen Object |
| API テスト | HTTP Client / SDK Wrapper |
| 結合テスト | Service Facade / Fixture |

Step 定義はその内部実装を一切知らない。

---

## 参照ファイル

| ファイル | 読むタイミング |
|---|---|
| `references/behave-patterns.md` | Step 定義の具体的なパターンを確認するとき |
| `references/spec-weaver-trace-workflow.md` | trace でどう情報を集めてテスト設計するか確認するとき |