# Devflow Fix

> Devflow Fix

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

---


# DevFlow 缺陷修复

## 总览

修缺陷最大的失败模式不是修不好，而是**修了症状**：没复现就开改、把"不再报错"当"修好了"、顺手把周围看不顺眼的代码一起动了。纪律一句话：

> **先复现，再归因，后修复；没有失败的测试就没有修复。**

产出按问题严重度伸缩：简单缺陷把三段记录（复现/根因/修复边界）写进组件根下 `features/DTS<id>-<slug>/fix.md`（或团队覆盖路径）即可；根因涉及设计缺陷或行为变更时，回到完整的 spec/design 流程。

## 工作流

### 1. 复现

- 用最小步骤稳定复现，记录：触发输入、环境（版本/平台/配置）、预期 vs 实际、证据（日志/core/trace）。
- **复现不了就不要修。** flaky 的问题先想办法提高复现率（压力、注入延迟、缩小区间），仍不可复现 → 记录已排除的假设，交回报告人补信息，不上"盲修补丁"。

### 2. 根因分析

- 从现象向后追因果链，每一步要有证据（日志、代码路径、git 历史、二分），直到回答「**为什么会发生**」而不是「在哪发生」。连续追问"为什么"直到再往下是设计决策或外部事实为止。
- 区分三层并全部写下来：**直接原因**（哪行代码错了）、**根本原因**（为什么会写错/漏掉——契约不清？边界没定义？测试缺口？）、**波及范围**（同样的模式还出现在哪里）。
- 被排除的假设记录排除证据——这是防止下一个人重走弯路的最廉价文档。
- 改一行试试看 → 不行再改一行——这是猜，不是归因。两次"试试看"不中就必须停下来回到证据。

### 3. 界定修复边界

明确写下：**最小安全修复范围**（哪些文件/函数）、**显式不修什么**（周边坏味道、同类风险点登记不动手）、**回退策略**。然后分流：

| 根因性质 | 路径 |
|---|---|
| 实现错误（逻辑/边界/资源），契约本身正确 | 直接进入步骤 4 |
| 行为/契约需要变更（错误码、接口语义、阈值） | 这是变更不是修复 → 走 `devflow-specify`（modify 条目 + 基线） |
| 设计缺陷（边界划错、并发模型错） | 回 `devflow-design` 修订后再实现 |
| 波及范围里发现同类隐患 | 登记为独立工作项，不在本次顺手修 |

### 4. TDD 修复

- **先写复现缺陷的失败测试**（RED）：把复现步骤翻译成自动化用例，确认它因为这个缺陷而失败。这个测试就是回归屏障。
- 最小修复让它转绿（GREEN）；完整套件确认无回归；必要的清理留在 REFACTOR（纪律同 `devflow-tdd`）。
- 根因是"测试缺口放过了它" → 补的不只是这一个用例：检查同一缺口下还有哪些边界没有测试。

### 5. 收尾

fix.md 补全四问：根因是什么、为什么测试没拦住、修复改了什么、同类风险登记在哪。代码与测试按 `devflow-review` 的 code/test rubric 评审；评审闭环后经 `devflow-ship` 做 DoD 核验与关闭（DoD 对缺陷工作项的裁剪规则见其 definition-of-done）。

## 风险信号

- 没有复现记录就出现了修复 diff
- 根因写的是「空指针访问」这种"在哪发生"（直接原因），没有"为什么会发生"
- 修复 diff 里混着重命名、格式化、顺手清理
- 修复后没有新增任何测试（"改完手动验了"）
- 同一个函数第二次因同类原因被修（第一次的根因分析是假的）
- 用重试/延时/放宽阈值让问题"不再出现"而不解释机理

## 自检清单

- [ ] 复现步骤与环境已记录，证据可回看
- [ ] 因果链每步有证据；直接原因/根本原因/波及范围三层齐全
- [ ] 修复边界显式：改什么、不改什么、怎么回退
- [ ] 存在先失败后通过的复现测试；完整套件无回归
- [ ] 行为/契约变更走了 specify，没有伪装成"修复"
- [ ] 同类风险已登记；"为什么测试没拦住"已回答

## 支撑参考

| 文件 | 用途 |
|---|---|
| `references/fix-template.md` | fix.md 模板（复现/根因/修复边界三段） |