---
name: qa-ai-context-engineering
description: >-
  将前面所有分析步骤（需求解构、场景树、边界清单、风险评估等）打包成一个结构化的AI上下文包，确保AI在生成测试用例时拥有完整的业务上下文、功能上下文和技术上下文。当已经完成了需求分析、场景构建和深度设计，即将进入提示词生成阶段时，必须经过此步骤。上下文包的完整度直接决定了AI生成用例的质量——输入垃圾，输出也是垃圾。当上游分析缺失时，本技能会读取用户上传的需求文件或fetch用户提供的URL以补充上下文，并对原始描述做结构化解析后并入上下文包，但不会替代上游分析步骤——缺失项仍需标注并建议回退补充。
  触发场景：上下文工程、构建上下文、上下文包、测试上下文、结构化上下文、上下文不够、已完成需求解构和场景构建需要打包上下文时。 Use when the user asks about: building a structured context package so an LLM has full business, functional, and technical context before generating test cases.
license: MIT
allowed-tools: Read Grep Glob WebFetch
metadata:
  display-name: "Ai Context Engineering"
  version: "1.8.0"
  when-to-use: "用户说\"上下文工程\"、\"构建上下文\"、\"上下文包\"、\"测试上下文\"、\"结构化上下文\"、\"上下文不够\"、已完成需求解构和场景构建需要打包上下文时"
  related-skills: "{\"upstream\":[\"qa-req-deconstruction\",\"qa-scenario-tree\",\"qa-boundary-deep-dive\",\"qa-combination-strategy\",\"qa-state-transition\"],\"downstream\":[\"qa-ai-prompt-strategy\"]}"
  references: "[\"references/window-adaptation.md\",\"assets/context-package.md\"]"
  input-format: "{\"required\":[{\"name\":\"需求解构表\",\"type\":\"object\",\"description\":\"来自qa-req-deconstruction的需求解构结果\"},{\"name\":\"场景树\",\"type\":\"object\",\"description\":\"来自qa-scenario-tree的场景树结构\"}],\"optional\":[{\"name\":\"边界清单\",\"type\":\"object\",\"description\":\"来自qa-boundary-deep-dive的边界分析结果\"},{\"name\":\"组合矩阵\",\"type\":\"object\",\"description\":\"来自qa-combination-strategy的组合覆盖矩阵\"},{\"name\":\"状态转换图\",\"type\":\"object\",\"description\":\"来自qa-state-transition的状态转换分析\"},{\"name\":\"风险评估\",\"type\":\"object\",\"description\":\"来自qa-risk-intuition的风险评估结果\"}]}"
  output-format: "{\"traceability\":[\"本技能只打包上下文、不产出新 ID；沿用上游需求ID：REQ-{需求模块缩写}-{序号}、场景ID：SC-{场景模块缩写}-{序号}、边界ID：BD-{模块缩写}-{序号}、风险ID：RISK-{模块缩写}-{风险类型}-{三位序号}、规则ID：RULE-{CAL|VAL|PERM|FLOW}-{序号}\"],\"structure\":[{\"context_package\":\"AI上下文包：四层金字塔（第1层业务目标与用户角色 / 第2层功能描述与约束条件 / 第3层技术细节与历史缺陷（按需）/ 第4层输出格式与质量要求）\"},\"来源标注：每条信息必须标 [用户提供] / [推断] / [假设]；[假设] 项下游必须显式暴露或回上游确认\",\"第1层与第4层必填且永不裁剪；第3层按需，超窗时首个被裁\",\"第4层的 9 列输出格式引用 qa-test-case-design 的真源，本技能不自行定义或改动\",\"缺失的上游必须显式声明并给出回退建议，不得静默假设\",\"本技能不产出 9 列用例表 —— 只打包上下文，用例由下游 qa-ai-prompt-strategy 驱动生成\",\"覆盖率：标注口径（基于已有上游产出），禁止\\\"全覆盖/100%\\\"绝对化表述\"]}"
  error-recovery-guidance: "{\"on_failure\":\"上下文包不完整时回退到上游分析步骤补充\",\"retry_behavior\":\"补充缺失的上游输入后重新打包上下文\"}"
  categories: "[\"Development\",\"Testing\",\"AI\"]"
  depth-requirement: "{\"reference_value\":\"按上游分析的丰富度决定包深度；四层全建为「完整测试」，可只建第1/2/4层为「日常/紧急测试」\",\"minimum\":\"至少包含需求解构表、场景树、边界清单 3 个核心上游输入；缺失项必须显式声明\"}"
---

> ⚠️ 本技能单独使用效果有限，建议配合完整技能集（12 步工作流）使用。安装：npx skills add Kokxi/qa-test-skills

# AI 上下文工程

## 核心原则

你是一位资深测试架构师，擅长为 AI 构建高质量的测试上下文。

**不是给更多信息，而是给对的信息结构。**

> **本技能最大的失败模式是"不标来源"**。下游 AI 无法区分"需求文档要求的"和"你编的"，
> 于是把假设当事实写进用例——这类缺陷到最后都查不出是谁引入的。
> **每条信息都要标 `[用户提供]` / `[推断]` / `[假设]`。**

## 1. 上下文金字塔（必须按此顺序构建）

### 第 1 层 业务目标与用户角色（必填，永不裁剪）
```text
【业务背景】业务目标 / 目标用户 / 核心价值
【用户角色】角色A - 核心诉求；角色B - 核心诉求
```
> 业务目标丢了，AI 不知道测什么。**这一层是包的骨架，不可裁剪。**

### 第 2 层 功能描述与约束条件（必填）
```text
【功能边界】功能名称 / 核心流程 / 输入 / 输出
【非功能需求】性能 / 安全 / 兼容性
```
> 业务规则直接引用 `qa-req-deconstruction` 的 `RULE-` 清单，不重写。

### 第 3 层 技术细节与历史缺陷（按需，超窗首个被裁）
```text
【技术架构】技术栈 / 关键接口 / 数据流向 / 依赖服务
【历史缺陷模式】同类型功能曾出现过的 Bug + 规避方法
```

### 第 4 层 输出格式与质量要求（必填，永不裁剪）
```text
【输出要求】9 列标准用例表（真源：qa-test-case-design/references/output-template-full.md）
           编号 TC_{模块缩写}_{功能缩写}_{三位序号}
           级别占比 P0≤20% / P1≤40% / P2≤30% / P3≤10%
           覆盖率必须标注口径
```

## 2. 上下文类型速查

| 场景类型 | 建哪几层 | 关键侧重 |
|---------|---------|---------|
| **日常测试** | 1 + 2 + 4 | 功能边界 + 输出格式 |
| **紧急测试** | 1 + 4 | 业务目标 + 输出格式，依赖假设快速产出 |
| **完整测试** | 全部 4 层 | 全量信息 + 历史缺陷 + 技术细节 |
| **复测回归** | 1 + 3 + 4 | 历史缺陷模式 + 输出格式 |

## 3. 工作流程

1. **识别输入类型**：直接描述 → 提取关键信息；上传文件 → 读取解析；URL → 获取分析
2. **核对上游齐备度**：逐项列出已收到的上游产出，**缺失项显式声明并给出回退建议**
3. **按金字塔构建**：四层组织，逐条标来源
4. **声明缺失**：上游没有的不要静默假设，标出来并建议回退到对应技能

## 4. 加载时机

| 什么时候读 | 读哪个 |
|-----------|--------|
| 写上下文包 | [`assets/context-package.md`](assets/context-package.md)（四层模板 + 来源标注表 + 填写要求 + 自检） |
| 目标模型窗口不够、或要看完整包示例 | [`references/window-adaptation.md`](references/window-adaptation.md)（窗口适配 + 超窗降级 + 完整示例） |

> 窗口数据是**快照值，会过时**。用之前核实当前值；不确定目标模型时按 8K-32K 规划——
> 按最小窗口设计的包在任何更大窗口里都不会被截断，反之不成立。

## 5. 产出

四层结构骨架 + 来源标注汇总（示例见 `assets/context-package.md`）：

```text
📦 AI上下文包（目标模型：X，窗口 YK，预估 ZK token）
├─ 上游齐备度：需求解构 ✓ / 场景树 ✓ / 边界清单 ✓ / 组合矩阵 ○ …
│                缺失：X → 建议先补 qa-xxx
├─ 第1层 业务目标与用户角色        [必填]
├─ 第2层 功能描述与约束条件        [必填]
├─ 第3层 技术细节与历史缺陷        [按需]
├─ 第4层 输出格式与质量要求        [必填]
└─ 来源标注汇总：[用户提供] n 条 / [推断] n 条 / [假设] n 条
```

**本技能不产出 9 列用例表**——只打包上下文，用例由下游 `qa-ai-prompt-strategy` 驱动生成。

## 6. 四个常见翻车点

1. **信息过载**：给太多细节导致 AI 迷失重心 → 用结构化格式组织，按金字塔分层
2. **假设未标注**：AI 不知道哪些是你编的 → 明确标 `[假设]`，并要求下游暴露
3. **缺少负面案例**：AI 不知道什么是"不好的" → 给出反例
4. **输出格式模糊**：AI 不知道你要什么格式 → 明确指定 9 列并引用真源

## 7. 交付前自检

- [ ] 四层齐备（第 3 层可按需，缺失需说明）
- [ ] **每条信息都标了来源**，无未标注内容
- [ ] `[假设]` 项已列出，且要求下游显式暴露或回上游确认
- [ ] 上游缺失项已显式声明 + 给出回退建议
- [ ] 业务规则引用 `RULE-` ID，未另起一套编号
- [ ] 第 4 层引用 `qa-test-case-design` 真源，未自行改动列
- [ ] 标注了目标模型与窗口；包大小估算 < 窗口 80%
- [ ] 已知历史缺陷模式已带入（有的话）