aif-qa

QA — 实现测试

生成变更摘要、制定测试计划，并描述功能或任务实现的测试场景。

模式

此技能按顺序在三种模式下运行。

参数	模式	执行内容
change-summary	变更摘要	分析变更内容、评估风险并生成摘要
test-plan	测试计划	根据变更摘要创建结构化测试计划
test-cases	测试用例	根据测试计划描述具体测试场景
--all	完整流程	依次运行全部三种模式，阶段之间无需提示

---

工作流

步骤 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 = 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 之前，使用 ui_language 请用户提供以下任一变更上下文来源：粘贴的 diff、变更文件列表、简短的实现说明，或取消。

步骤 0.1：加载项目上下文

如果文件存在，读取解析后的描述路径，以了解：

• 技术栈（语言、框架、数据库、ORM）
• 项目架构和编码规范
• 非功能性需求

如果文件存在，读取解析后的架构路径，以了解：

• 选定的架构模式
• 文件夹结构规范
• 层／模块边界和依赖规则

生成摘要、测试计划和测试用例时使用这些上下文。

读取 .ai-factory/skill-context/aif-qa/SKILL.md——如果文件存在，则为必需操作。

此文件包含 /aif-evolve 根据补丁、代码库规范和技术栈分析积累的项目特定规则。这些规则针对当前项目量身定制。

如何应用技能上下文规则：

• 将其视为此技能通用说明的项目级覆盖规则
• 当技能上下文规则与此 SKILL.md 中的通用规则冲突时，以技能上下文规则为准
• 如果没有冲突，则同时应用两者：SKILL.md 中的通用规则 + 技能上下文中的项目规则

步骤 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

存储这两个值，以便在所有参考文件中使用：

• resolved_branch——正在分析的分支（用于定位／保存产物）

• artifact_dir——<resolved paths.qa>/<branch-slug>，其中 branch-slug 是根据 resolved_branch 确定性生成、安全适用于文件系统且具有抗冲突能力的 slug。分三步计算：

  1. 安全 slug。 获取 resolved_branch，将每个不属于 [A-Za-z0-9._-] 的字符替换为 -，将连续的 - 合并为单个 -，并去除首尾的 -。如果结果为空，则使用 branch。然后必须截断为前 40 个 ASCII 字符。由于规范化后的 safe_slug 字符集为 [A-Za-z0-9._-]，字节长度与字符长度相同。将其命名为 safe_slug。
  2. 哈希后缀。 运行 git hash-object --stdin <<< "<resolved_branch>"，并取输出的前 8 个十六进制字符。将其命名为 hash8。哈希根据未规范化的原始分支名称生成，因此规范化后得到相同 safe_slug 的分支在通常情况下仍会生成不同的派生 slug。
  3. 组合： branch-slug = "<safe_slug>-<hash8>"。

  哈希的作用： 可读 slug 会造成信息损失——feature/foo 和 feature-foo 会规范化为相同的 safe_slug，从而覆盖彼此的产物。添加原始完整名称的短哈希，可使派生 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

步骤 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）

依次运行所有三个模式。每个阶段成功完成后，自动进入下一阶段——不要显示阶段间的 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 标志遵守相同的边界。
• 写入策略：持久化写入仅限于上述三个归属工件；不得创建或修改其他文件。
• 配置策略：支持读取配置，但仅限只读。读取 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. 不得跳过阶段