| name | teams-docs-qa |
| description | Generate QA phase documents (test plan, non-functional requirement tests, Gherkin scenarios) in the teams/ directory. Phase 3 of the /start-teams-doc workflow. Requires Design phase approval. Use when creating test plans, test scenarios, Gherkin .feature files. |
Teams Docs — QA スキル
トリガー条件
/teams-docs-qa コマンドが呼ばれたとき/start-teams-doc の第3フェーズ（qa フェーズ）として呼ばれたとき- ユーザーが「テスト計画を作りたい」「Gherkin シナリオを作りたい」「.feature ファイルを作りたい」と言ったとき
入力パラメータ
/start-teams-doc から以下が引き渡される:
docs_root: ドキュメントルートパス（sdd-docs または .）team, project, feature, feature_id, goal, scope_in, scope_out- 任意:
constraints
実行前チェック
{docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml を読み込むdesign.status != approved の場合は停止して Design フェーズの承認を促すqa.status == changes_requested の場合は修正モードで実行qa.status == in_review の場合はドキュメント生成をスキップし、構造バリデーションのみ再実行して承認確認メッセージに直接進む
手順
1. ディレクトリ準備
{docs_root}/teams/{team}/{project}/{feature}/qa/
├── テスト計画書.md
├── 非機能要件のテスト.md
└── ユーザーストーリー/
└── {シナリオタイトル}.feature
2. テスト計画書.md 生成
- テンプレート: assets/テスト計画書-template.md
- discovery の全 US を洗い出してテストシナリオファイルとの対応表を作成
- テストピラミッド方針・環境・リリース判定基準を記入
- 未テストの US が 0件になるよう対応表を埋める
3. 非機能要件のテスト.md 生成
4. ユーザーストーリー/*.feature 生成
- テンプレート: assets/シナリオ-template.feature
- ファイル名:
{シナリオタイトル}.feature（日本語可）
- TC ID を
TC-{feature_id}-NNN 形式でファイル先頭に記入
# Related: US-{feature_id}-NNN を各ファイルに記入- 各 US に対して正常系・異常系を最低1件ずつ記述
Then には具体的な期待値を記載する（「〇〇が表示される」「ステータスが 200 になる」など）
5. Traceability Matrix 更新
テスト計画書.md 末尾の Matrix に US→TC の対応を記入する。
品質ゲート（承認前チェック）
references/quality-checklist.md の全項目を確認する。
未テスト US が残っている場合は承認不可。
バリデーションスクリプトを実行して自動チェックを行う:
python <this_skill_dir>/scripts/validate.py <feature_dir>
<this_skill_dir> は、この SKILL.md が配置されているディレクトリの実際のパスに解決すること。
エラーが出た場合は修正してから承認確認を行う。
承認確認メッセージ
品質ゲート通過後、承認確認メッセージを表示する前に _approval-status.yaml の qa.status を in_review に更新する。
これにより、ユーザーが承認確認中にセッションを中断しても、次回再開時にドキュメント生成をスキップできる。
✅ [qa] フェーズの品質ゲートを通過しました。
承認しますか？
1. Approve & Continue（_approval-status.yaml を更新して完了）
2. Request Changes（修正点を確認して停止）
3. Pause Review（レビューを中断して後で再開）
承認時: _approval-status.yaml の qa.status を approved、approved_at を本日付で更新する。
修正要求時: _approval-status.yaml の qa.status を changes_requested に更新し、ユーザーが指摘した修正点の一覧を表示して停止する。
レビュー中断時: status は in_review のまま維持。以下を表示して停止する:
⏸️ [qa] フェーズのレビューを中断しました。
`/start-teams-doc` で再開できます。
出力ファイル一覧
| ファイル | 必須 |
|---|
qa/テスト計画書.md | ✅ |
qa/非機能要件のテスト.md | ✅ |
qa/ユーザーストーリー/{タイトル}.feature | ✅（US 数分） |
ソースコード参照
サブモジュールモード（docs_root = sdd-docs）の場合、ワークスペースルートにメインリポジトリのソースコードが存在する。以下を積極的に参照してドキュメントの精度を高めること:
- 既存テストコードのパターン・テストフレームワーク設定 → テスト計画書に反映
- CI/CD パイプライン設定 → テスト実行環境・リリース判定基準に反映
- E2E テストの既存シナリオ → Gherkin シナリオの記述スタイルを統一
Troubleshooting
- .feature ファイルの構文エラー → Gherkin キーワード（
Feature:, Scenario:, Given, When, Then）のスペルと半角コロン・半角スペースを確認する。Scenario Outline: の場合は Examples: テーブルも必須。
- 未テスト US が検出される → 該当 US に対応する
.feature ファイルを qa/ユーザーストーリー/ に作成し、# Related: US-{feature_id}-NNN を記載する。
- Then 節が短すぎると警告される → 具体的な期待値を記載する。「表示される」→「検索結果一覧に商品名と価格が表示される」のように詳細化する。
参照
