aif-qa

QA — 実装テスト

変更の概要を生成し、テスト計画を作成して、機能またはタスクの実装に関するテストシナリオを説明します。

モード

このスキルは、次の3つのモードを順番に実行します。

引数	モード	実行内容
change-summary	変更の概要	変更内容を分析し、リスクを評価して、概要を作成します
test-plan	テスト計画	変更の概要に基づいて、構造化されたテスト計画を作成します
test-cases	テストケース	計画に基づいて、具体的なテストシナリオを説明します
--all	全工程	各段階で確認を求めず、3つのモードすべてを順番に実行します

---

ワークフロー

ステップ 0：設定の読み込み

最初に： .ai-factory/config.yaml が存在する場合は読み込み、以下を解決します。

• パス： paths.description、paths.architecture、paths.qa（デフォルト：.ai-factory/qa）
• 言語：
  • language.ui は、AskUserQuestion のプロンプト、進捗メッセージ、最終概要、次のステップの案内に使用します
  • language.artifacts は、生成される QA 成果物に使用します
  • language.technical_terms は、成果物の作成時に、人が読みやすい技術用語の表記スタイルに使用します
  • language.artifacts がない場合は、language.ui を使用します
  • 両方ない場合は、en を使用します
• Git： ブランチ比較には git.enabled と git.base_branch を使用します

config.yaml が存在しない場合は、以下のデフォルト値を使用します。

• DESCRIPTION.md：.ai-factory/DESCRIPTION.md
• ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
• QA 成果物：.ai-factory/qa/
• ui_language：en
• artifact_language：en
• technical_terms_policy：keep
• Git の有効化：true
• Git のベースブランチ：main

以下を保存します。

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"
• git_enabled = git.enabled（設定されている場合）、それ以外は true
• base_branch = git.base_branch || "main"

すべての AskUserQuestion のプロンプト、ユーザーに表示する説明、各ステージの完了メッセージ、次のステップの案内は、必ず ui_language で記述してください。

生成されるすべての成果物（change-summary.md、test-plan.md、test-cases.md）は、必ず artifact_language で記述してください。

テンプレートで定義するのは構造であり、言語ではありません。templates/*.md の標準英語テンプレートを使用してください。artifact_language が en 以外の場合は、保存する前に artifact_language に翻訳してください。見出し、ラベル、チェックリスト項目、プレースホルダー、列挙型のラベル、リスクラベル、説明文はすべて artifact_language で記述する必要があります。

artifact_language が en 以外の場合、英語のテンプレートをそのまま使用しないでください。Markdown の構造、表の形、チェックボックスの構文、テストケース ID（TC-001）、コード識別子、パス、コマンド、ブランチ名、設定キー、API 名、パッケージ名、生のエラーメッセージはそのまま保持してください。

artifact_language = ru の場合、人が読む文章、見出し、リスク、優先度、推奨事項、テスト手順、期待される結果はロシア語で記述してください。コード識別子、ファイル名、ブランチ名、コマンド、設定キー、API 名、生のエラーテキストは変更しないでください。

成果物の作成時には、technical_terms_policy を適用してください。

• keep — プロジェクトの対象者にとって明確であれば、commit、branch、diff、endpoint、payload、rollback、regression、fixture などの一般的な技術用語はそのまま使用します
• translate — 自然な訳語がある場合は、人が読む技術用語を翻訳します
• mixed — 通常の文章に含まれる用語は翻訳し、コード、インフラストラクチャ、エコシステムに関する用語は変更せずに使用します

git_enabled = false の場合、または現在のディレクトリが git のワークツリーではない場合は、git diff/log コマンドを実行しないでください。代わりに手動の変更コンテキストモードを使用し、change-summary を実行する前に、変更内容を把握するための情報として、貼り付けた diff、変更ファイルの一覧、実装の簡単な説明のいずれかを提供するか、キャンセルするよう ui_language でユーザーに尋ねてください。

Step 0.1：プロジェクトのコンテキストを読み込む

ファイルが存在する場合は、解決済みの説明パスを読み込み、以下を把握します。

• 技術スタック（言語、フレームワーク、データベース、ORM）
• プロジェクトのアーキテクチャとコーディング規約
• 非機能要件

ファイルが存在する場合は、解決済みのアーキテクチャパスを読み込み、以下を把握します。

• 選択されたアーキテクチャパターン
• フォルダー構成の規約
• レイヤー／モジュールの境界と依存関係のルール

このコンテキストは、サマリー、テスト計画、テストケースの生成時に使用します。

.ai-factory/skill-context/aif-qa/SKILL.md を読み込みます — ファイルが存在する場合は必須です。

このファイルには、パッチ、コードベースの規約、技術スタックの分析から /aif-evolve が蓄積した、プロジェクト固有のルールが含まれています。これらのルールは、現在のプロジェクトに合わせたものです。

skill-context ルールの適用方法：

• このスキルの一般的な指示に対するプロジェクトレベルの上書きルールとして扱います
• skill-context のルールが、この SKILL.md に記載された一般的なルールと矛盾する場合は、skill-context のルールを優先します
• 矛盾がない場合は、SKILL.md の一般的なルールと skill-context のプロジェクトルールの両方を適用します

Step 0.2：引数を解析してブランチを解決する

他の作業を始める前に、$ARGUMENTS をすべて解析します。

1. --all フラグを検出する — 存在する場合は all_mode = true に設定し、引数からフラグを削除します
2. モードを検出する — change-summary、test-plan、test-cases に一致する最初の単語を検出し、引数から削除します
3. ブランチを検出する — 残りのテキスト（ある場合）を対象ブランチ名とします

作業ブランチを解決します：

If git_enabled = false or the repository is not a git work tree:
  If branch was provided in arguments → use it as the resolved branch label
  Otherwise → set resolved_branch = "manual"
  Use manual change context mode for analysis
If git_enabled = true and the repository is a git work tree:
  If branch was provided in arguments → use it as the resolved branch
  Otherwise → run: git branch --show-current

以下の2つの値を保存し、すべての参照ファイルで使用します。

• resolved_branch — 分析対象のブランチ（成果物の検索／保存に使用）

• artifact_dir — <resolved paths.qa>/<branch-slug>。branch-slug は、resolved_branch から決定論的に導出される、ファイルシステム上安全で衝突しにくいスラッグです。次の3つの手順で計算します。

  1. 安全なスラッグ。 resolved_branch の [A-Za-z0-9._-] に含まれない各文字を - に置き換え、連続する - を1つにまとめ、先頭と末尾の - を取り除きます。結果が空の場合は branch を使用します。その後、必ず先頭から40 ASCII 文字に切り詰めます。正規化後の safe_slug に使われる文字は [A-Za-z0-9._-] なので、バイト長と文字数は同じです。これを safe_slug とします。
  2. ハッシュ接尾辞。 git hash-object --stdin <<< "<resolved_branch>" を実行し、出力の先頭8桁の16進数を取得します。これを hash8 とします。ハッシュは正規化前の元のブランチ名から生成されるため、通常の使用では、同じ safe_slug に正規化されるブランチでも異なるスラッグが生成されます。
  3. 結合： branch-slug = "<safe_slug>-<hash8>"。

  ハッシュを付加する理由： 読みやすいスラッグだけでは情報が失われます。feature/foo と feature-foo は同じ safe_slug に正規化され、成果物を上書きしてしまいます。元の名前全体の短いハッシュを付加することで、導出されるスラッグの安定性と読みやすさを保ちつつ、実用上の衝突を防ぎます。

  例：

  • feature/foo → safe_slug=feature-foo、hash8=a72ccce7 → feature-foo-a72ccce7
  • feature-foo → safe_slug=feature-foo、hash8=6f80dfc6 → feature-foo-6f80dfc6
  • main → safe_slug=main、hash8=<computed> → main-<hash8>

• all_mode — ステージ間のプロンプトをスキップするかどうか

モードが指定されておらず、all_mode = false の場合は、ui_language でユーザーに尋ねます。

AskUserQuestion in `ui_language`.
Meaning: ask which QA mode to run.
Options meaning:
1. Change summary (`change-summary`) — analyze what changed, assess risks, produce a summary
2. Test plan (`test-plan`) — create a structured test plan based on the change summary
3. Test cases (`test-cases`) — describe concrete test scenarios based on the plan
4. Full pipeline (`--all`) — run all three modes in sequence

Step 1：選択したモードを実行する

このスキルは厳密に順番どおりに実行されます — 各ステージでは、前のステージの成果物を使用します。

change-summary → test-plan → test-cases

選択したモードの詳細な手順を読み込みます。

変更サマリー（change-summary）

references/CHANGE-SUMMARY.md を読み込みます。

テスト計画（test-plan）

references/TEST-PLAN.md を読み込みます。

テストケース（test-cases）

references/TEST-CASES.md を読み込みます。

フルパイプライン（--all）

3 つのモードをすべて順番に実行します。各ステージが正常に完了したら、ステージ間の AskUserQuestion は表示せず、自動的に次へ進みます。

1. Execute change-summary (references/CHANGE-SUMMARY.md) → save artifact
2. Execute test-plan      (references/TEST-PLAN.md)      → save artifact
3. Execute test-cases     (references/TEST-CASES.md)     → save artifact
4. Show context cleanup prompt (Step 6 of TEST-CASES.md)

いずれかのステージで失敗した場合（例：git エラー、差分が大きすぎてユーザーがキャンセルした場合）は、パイプラインを停止し、失敗したステージを報告します。

---

原則

必ず行うこと：

• テスト計画とテストケースを作成する前に、対象を理解します（変更内容／テスト計画／マージリクエスト／タスク／テキストによる説明を分析します）
• 変更内容の分析、テスト計画、テストケースに必要な範囲でのみ、リポジトリのコードを使用します
• どのテスターでもコードベースの知識なしに実行できるよう、手順を明確に記述します
• 「有効なデータを入力する」のような抽象的な表現ではなく、具体的なテストデータを指定します
• 優先順位を付けます。すべてが同じ重要度とは限りません
• 周辺システム、連携機能、依存関係も考慮します
• 否定的なシナリオやエッジケースを含めます。多くのバグはこれらで検出できます
• コードからビジネスロジックが明らかでない場合は、確認の質問をします

行ってはいけないこと：

• 手動 QA 計画を、自動テストの実装詳細に置き換えないでください
• コードを読まずにビジネスロジックを推測しないでください
• 否定的なシナリオを省略しないでください
• すべての項目についてテストケースを作成しないでください。リスクの高い領域に重点を置きます
• データのエッジケースを無視しないでください

手動 QA 計画を、自動テストの実装詳細に置き換えないでください。 既存の自動チェックに触れる場合は、補助的な検証としてのみ記載できます。主な出力は、引き続き手動 QA シナリオでなければなりません。

---

優先度の目安

優先度	使用する場面
高	コアビジネスロジック、ユーザーデータ、決済、セキュリティ、認可
中	補助機能、UI/UX、レポート、連携
低	外観上の変更、まれなシナリオ、あると便利な機能

成果物の所有範囲と設定ポリシー

• 主な所有範囲：<paths.qa>/<branch-slug>/ 配下の QA 成果物。具体的には change-summary.md、test-plan.md、test-cases.md です。--all フラグも同じ境界を遵守します。
• 書き込みポリシー：永続的な書き込みは、上記 3 つの所有対象成果物に限定されます。他のファイルは作成も変更もしません。
• 設定ポリシー：設定を参照しますが、読み取り専用です。paths.description、paths.architecture、paths.qa、language.ui、language.artifacts、language.technical_terms、git.enabled、git.base_branch を読み取ります。config.yaml への書き込みは行いません。

重要なルール

1. change-summary 成果物なしで test-plan を作成してはいけません
2. test-plan 成果物なしで test-cases を作成してはいけません
3. ステージを省略してはいけません