# Test Fix

> 修正测试用例错误，记录陷阱到 TEST_SPEC，并判断是否为 skill 级系统性问题——若是则定位并更新对应 skill

- Skill: `tlzmw001/test-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tlzmw001/test-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tlzmw001/test-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tlzmw001 (https://skillmd.com/u/tlzmw001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tlzmw001/test-fix

---


# 测试用例修正

修正用例 `$case_id`，错误描述：`$error_description`。如果提供 `$suite_file`，优先只在该 suite 中定位；如果未提供且同一 case_id 匹配多处，停止并要求用户指定 suite。

## 前置：读取项目配置

读 `aitest_config/aitest.yaml`，获取 `workspace.paths.*`、target/module registry 和 codegen 配置。

## 执行流程

### 第一步：定位用例

1. 从 `$case_id` 中提取模块缩写（如 TC-ROUTE-013 → ROUTE）
2. 查 `{paths.test_spec}` 的模块缩写对照表，确定模块名
3. 在以下位置搜索该用例：
   - `$suite_file` 指定的 suite 及其 `case_files`
   - 已知 suite 目录或 `suite.yaml` 声明的 `case_files`
   - `test_workspace/suites/` 中绑定该 module 的 suite
4. 如果同一 `$case_id` 匹配多个 suite，停止并要求用户指定 `$suite_file`
5. 读取该用例的完整内容和上下文（前后用例、关联的知识库文档）

### 第二步：分析错误

1. 读取用例关联的知识库文档（L1/L2）
2. 如果错误涉及代码行为，读取相关源代码确认实际行为
3. 判断错误类型：
   - **预期结果错误** — 预期值与实际行为不符
   - **前置条件不可行** — 无法按描述构造测试环境
   - **输入不完整** — 请求体缺字段或格式错误
   - **测试步骤遗漏** — 关键操作未写出
   - **逻辑错误** — 用例设计本身有问题（如验证了不可能的场景）
4. 向用户确认修正方案（如果错误原因不明确）

### 第三步：修正用例

1. 在用例文件中修正该用例
2. 修正后的用例必须满足 TEST_SPEC 质量红线（Q1-Q10）
3. 如果修正影响了覆盖变更清单，同步更新

### 第四步：记录陷阱

在 `{paths.test_spec}` 的"已知陷阱"章节追加一条记录：

```markdown
### 陷阱-{序号}：{一句话描述错误模式}
- **错误写法**：原来怎么写的（具体到可对照）
- **正确做法**：应该怎么写
- **原因**：为什么原来的写法是错的
- **适用范围**：哪类用例需要注意这个问题
```

陷阱序号从已有最大序号 +1 开始。

### 第五步：Skill 级根因分析

修完用例后，判断这个错误是**用例本身的问题**还是**skill 指令导致的系统性问题**：

1. **用例本身的问题**（到此为止，不需要额外动作）：
   - 个别用例的数据写错、步骤遗漏
   - 对业务规则的理解偏差（已通过陷阱记录）

2. **Skill 级系统性问题**（需要更新 skill）：
   - 同类错误在多条用例中重复出现（说明 skill 指令有盲区）
   - 错误源于 skill 的步骤设计缺陷（如缺少某个检查环节、断言策略指导不足）
   - 错误源于 skill 读取的输入不完整（如该读 proto 但 skill 没要求读）

   **定位并更新对应 skill**：
   - 根据错误类型判断属于哪个 skill 的职责范围（test-design / knowledge-build / doc-review）
   - 读取该 skill 的 SKILL.md，定位到导致问题的步骤
   - 添加或修正指令，使同类错误不再发生
   - 如果问题涉及共享引用（断言策略、用例格式、mismatch 格式、L1/L2 模板），更新 `{paths.refs_dir}/` 下对应文件
   - 在完成输出中注明更新了哪个 skill 及具体改动

### 第六步：完成输出

向用户输出：

```markdown
## 用例修正摘要

修正用例：$case_id
错误类型：（预期结果错误 / 前置条件不可行 / ...）
修正内容：（改了什么）
新增陷阱：陷阱-{序号}（一句话描述）
Skill 更新：（无 / 更新了 {skill名} — 具体改动描述）
Refs 更新：（无 / 更新了 {refs文件名} — 具体改动描述）
```

## 约束

- 只修正用户指定的用例，不扩大修改范围
- 修正预期结果时，必须有依据（知识库规则或代码行为），不能猜测
- 陷阱记录必须抽象到可复用的模式，不能只描述单个用例的具体问题
- 如果错误是知识库本身的问题（规则描述不准确），在陷阱中标注，但不修改知识库（知识库修改需用户单独确认）