specsfy-06-tdd-bdd

仕様の BDD に基づく TDD の実行

必須の準備

このスキルを実行する前に、プロジェクトのルートで $specsfy-setup を必ず読み込んでください。自動ハンドオフの場合は、このステップの前に再度読み込んでください。会話で確認済みのルートを再利用し、セットアップで未解決事項が示された場合は続行しないでください。

対話モード

対話モード：perguntas。 質問を作成する前に、.specsfy/Spec.md の 番号付き質問の規約を読み、適用してください。

BDD を参考資料として読み、仕様で定義された振る舞いを、実行可能な TDD テストと追跡可能なエビデンスに変換してください。Gherkin は、ユーザーとエージェントがコンテキスト、アクション、結果を理解するのに役立ちますが、それ自体はテストスイートではありません。

データベースの必須保護

フォーカステスト、テストスイート、回帰テストを実行する前に、コマンドと環境を確認してください。

node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \
  --project <raiz> --command "<comando-de-teste>"

Laravel では、.env.testing、APP_ENV=testing、および .env に記録された開発用データベースとは明確に異なるデータベースが設定されていることを確認する必要があります。結果が PENDING の間は、テストを一切実行しないでください。テスト環境を修正して確認を繰り返し、SAFE になった場合にのみ続行してください。

IGNORED は、コマンドを必ず破棄する状態として扱ってください。migrate:fresh、migrate:refresh、migrate:reset、migrate:rollback、db:wipe、schema:drop、prisma migrate reset、DROP DATABASE、DROP SCHEMA、DROP TABLE、TRUNCATE、またはこれらに相当するコマンドを実行したり、--force を付けて変更したり、実行許可を求めたりしないでください。RefreshDatabase も DatabaseMigrations も使用しないでください。Laravel では、DatabaseTransactions と、そのケースで使用するレコードのみを作成するファクトリーを優先してください。

会話のオーケストレーション

このステップの完了時、または別のステップの作業を検出した場合は、保留事項を検出しました：<説明> — アクション：このステップで解決します と告知し、その作業がこのステップの範囲に属する場合は解決してください。責任を移す場合は、自動トランジション：$specsfy-06-tdd-bdd → $<遷移先> — 理由：<理由> — 期待される結果：<結果> と告知し、確認を求めたりコマンドを繰り返したりせず、遷移先のスキルを直ちに読み込んでください。同じ会話を続けてください。このステップに必要な修正を行った後は、自動再開：$<遷移先> → $specsfy-06-tdd-bdd — 保留事項を解決しました：<結果> と告知し、直ちに再開してください。ハンドオフ後は、循環を避けるために状態を再評価してください。ハンドオフの確認を求めないでください。ただし、慎重な操作には引き続き個別の許可が必要です。

モードの選択

• prepare：実装前に、次のテスト／シナリオを作成し、プロダクションコードを書かずに RED を確認します。
• cycle：明示的に選択した一連の機能について、RED → GREEN → REFACTOR を実行します。
• verify：テストスイートを実行し、新しい振る舞いを作成せずにトレーサビリティを監査します。

ユーザーがモードを指定していない場合、セクション 14 がまだ実行中でなければ prepare を、アクティブなタスクがある場合は cycle を使用してください。

準備

1. specs/<estado>/<NNNN>-<slug>/spec.md、テスト、プロジェクトの設定を読みます。
2. Formato: Specsfy/2.0 と Definition Gate: Passed を必須とします。prepare モードでは Status: Defined と Plan Gate: Pending を使用します。cycle および verify モードでは、 Status: Planned または Implementing を使用します。
3. 小さな垂直スライスを選択します。1 つの Gherkin AC と、それに対応する FR/NFR です。
4. テストを書く前に、スタックに基づいてテストランナーを決定します。
   • PHP プロジェクト（composer.json または artisan があるもの）。PHP + Node の場合も含みます。Pest を使用します。
   • PHP を使用しない Node プロジェクトでは、インストールまたは設定を行う前に、採用するランナーをユーザーに確認します。デフォルトでは Vitest を推奨します。
   • その他のスタックでは、既存のテストランナーを維持します。再現可能な判断がない場合は、ユーザーに確認します。
5. check_database_safety.mjs で環境とコマンドを確認します。状態が SAFE でない場合は、テストを一切実行せず、ステップを保留のままにします。
6. Node では、package.json に test:tdd スクリプトが公開されている場合、判断が具体化されたものと見なします。黙って依存関係を選択またはインストールしないでください。
7. references/test-levels.md を読み、振る舞いを証明できる最も低いレベルを選択します。

BDD を使用して TDD を記述する

• spec.md の AC にある Gherkin ブロックを、意味を変えずに参照契約として使用します。
• .feature ファイルや step definition を作成、コピー、実行しないでください。Given/When/Then の用語は spec.md 内だけに残します。
• PHP では、振る舞いを証明できる最も低いレベルで、Pest を使って tests/Feature/ または tests/Unit/ に TDD テストを記述します。各実行可能ケースの定義のすぐそばに、次のマーカーを付けます。

// SPECSFY: US-001 FR-001 AC-001

• Node では、ユーザーの回答後に、選択したランナーで TDD テストを記述し、SPECSFY: US-001 FR-001 AC-001 を使用します。
• feature 全体と各 US、FR、NFR について、少なくとも 3 つの異なる TDD ケースを具体化します。正常系、重要なルール／バリエーション、重要な失敗または境界です。ファイル内に複数のテストが含まれていても、ファイルで共有される SPECSFY: マーカーは 1 ケースとして数えます。
• 各 AC を少なくとも 1 つの TDD ケースでカバーし、同等のケースを増やさないでください。
• BDD に記述された境界に応じて、ユニット、統合、コントラクト、ブラウザーのいずれかを選択します。BDD とラベル付けするためだけに、2 つ目のスイートを作成しないでください。
• シナリオが証明しようとしている境界そのものを取り除くために、モックを使用しないでください。

必須のサイクル

RED

1. 参照 BDD を読み、AC とその要件を証明する最小の TDD テストを記述します。
2. TDD テストを実行します。Gherkin は実行しないでください。
3. 振る舞いの欠落または誤りによる失敗を確認します。
4. 構文、fixture、インポート、または環境が原因で失敗した場合は、テストを修正して再実行します。
5. 変更前にテストが通る場合、そのテストでは gap を示せていません。テストを改善するか、機能がすでに存在することを証明します。

prepare モードでは、有効な RED の後で停止し、証拠を記録して、対応する [TEST] タスクの チェックリストを完了します。Plan Gate は変更せず、$specsfy-05-tasks に通知して自動的に戻ります。このステップでは、spec を Planned に昇格させる前に、すべての先行タスクが検証されます。 Evidência RED-GREEN-REFACTOR テーブルの対応する行に、観測した RED を記録します。

GREEN

cycle モードでは、シナリオを満たす最小限の本番コードを記述します。最初に対象テストを実行し、その後、関連するスイートを実行します。一般化を必要とする例が出るまでは、一般化しないでください。 同じ証拠行を更新し、観測した GREEN を記録します。

REFACTOR

すべてのテストが成功したら、振る舞いを変えずに重複を取り除き、名前や構造を改善します。関連するスイートを再実行します。 セクション 11 に回帰テストのコマンドを記録し、セクション 12 のマトリクスに証拠を記録します。

トレーサビリティを監査する

次を実行します。

node .agents/skills/specsfy-06-tdd-bdd/scripts/check_traceability.mjs specs/<estado>/<NNNN>-<slug>/spec.md .

各 feature、US、FR、NFR について、TDD ケースが3件未満の場合、および各 AC について、ケースが1件もない場合はギャップとして扱います。手動またはオブザーバビリティによって検証する NFR については、証拠を記載したうえで、自動化可能な3件のケースを省略しないでください。必要に応じて、該当する ID を削除せずに --kinds を調整します。 Evidence Contract: 1 の仕様では、--full-chain を追加して US/FR/NFR/AC → テスト → タスク → 証拠 を必須にします。 実行中は Delivery Gate: In Progress を維持し、セクション13の Gate do Ato III — Entrega を更新します。必須のギャップがなく、すべてのタスクが完了し、Definition of Done が立証された場合に限り、Passed を使用してください。

プレッシャー下での規律

誘惑	ルール
「小さな変更です。」	小さな変更には小さなテストを適用します。規模を理由に RED を省略してはいけません。
「コードはもうできています。」	特性テストを書きます。RED を作り出すために本番コードを変更してはいけません。新しい動作の場合は、まだ満たされていないケースを選びます。
「期限に間に合わせるには RED を省略できます。」	失敗を確認していなければ、そのテストが要件を保護する証拠はありません。
「リーダーが許可しました。」	権限によってスコープは変更できますが、証拠がない状態を TDD に変えることはできません。
「後からテストするのも同じです。」	テストファーストは契約を導き、実装前に感度を証明します。

テストタスクでは、各ステップの進行に応じて PREP、EXECUTE、VERIFY、VISUAL、 EVIDENCE、IMPROVE を更新します。VISUAL 項目は、テストがインターフェースに触れるかどうかの確認にも必須です。触れない場合は、Não aplicável とその理由を記録します。ファイル、マーカー、有効な RED、コマンド／証拠、プロセスのレビューが揃うまで、親タスクを完了としてはいけません。 同じスライスの BDD で示された先行 TDD が完了し、仕様に RED が記録されるまで、本番コードを書いてはいけません。

QA を監査する

リポジトリに属するランナーを実行した後、セクション12の証拠列に Passed または失敗を記録し、次を監査します。

node .agents/skills/specsfy-06-tdd-bdd/scripts/verify_acceptance.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md .

監査ツールは Markdown から抽出したコマンドを実行しません。手動の AC には、手法、担当者、証拠が必要です。結果がない AC がある場合、Delivery Gate: Passed にしてはいけません。 ランナーのアテステーションがある場合は、--attestation PATH を指定して再実行します。監査ツールは、承認済みの acceptance:<slug> チェックが正確に存在すること、有効な detail JSON、すべての AC のカバレッジを必須とします。Passed というテキストだけでは、その証明の代わりになりません。

証拠を報告する

スライス、カバーする ID、テストファイル、RED コマンド、失敗の原因、該当する場合は GREEN コマンド、回帰テストスイート、トレーサビリティのギャップを報告します。

必要に応じて専門家を参照する

ランナー、境界、テストオラクルが特定のテクノロジーに依存する場合は、references/specialists.md を読んでください。専門家の知見は補助として利用します。このスキルでは RED/GREEN とトレーサビリティを維持します。