X Qdev

---
name: x-qdev
description: |
  用户提出小任务或明确任务时使用。例如"加个搜索框""修一下导出的 bug""给登录加个记住我""把这个按钮改成红色并加个二次确认"。任务是具体、范围明确、能在短时间完成的单一改动。先查找对应的 spec 文档，然后在一份 task 文档里依次完成：功能性需求描述、失败测试用例、技术实现、验证结果。不适用于需要重新讨论需求或跨多模块的大需求。
---

# x-qdev

小任务的快速开发流程。把"需求 → 测试 → 实现 → 验证"四步组合进**一份 task 文档**，一次性闭环。

## 核心原则

1. **一份文档。** 需求、测试、实现、验证结果都在同一个 md 文件里，不拆多个文件。
2. **先测试后实现。** 测试用例先写（此刻是失败的），实现让测试变绿。顺序不能反。
3. **需求段用功能性语言。** ①需求章节是用户能看懂的（继承 x-spec 原则：不写技术词汇）；②③④章节是开发者能执行的技术内容。
4. **验证结果只填真实输出。** 不写"应该会通过"，粘贴实际运行的输出。
5. **自检即 gate。** 交付前对 task 文档自身做一致性对账（见第 4 步），不依赖其他 skill 做验证。

## 工作流

### 第 1 步：找 spec 文档

按优先级查找：

1. 扫 `docs/spec/*/spec.md`，找当前任务相关的 spec（按 spec 标题和 feat 内容判断相关性）。
2. **找到** → task 文档建在 `docs/spec/<spec-name>/tasks/task-<task-name>.md`，并在文档头部标注对应的 feat（如 `feat: feat02`；实现多个 feat 就写 `feat: feat02, feat03`）。
3. **找不到** → 告诉用户："没找到对应的 spec 文档。建议先用 x-spec 整理需求；如果任务确实简单不需要 spec，我直接建独立 task 文档。"用户确认简单后，建在 `docs/task/task-<task-name>.md`。

任务超出小任务范围时（跨多模块、需要重新讨论需求、涉及数据迁移或鉴权等高风险），停下来提示："这个任务超出 x-qdev 范围，建议走 x-spec + x-req 完整流程。"不要硬干。

### 第 2 步：写 task 文档（①②两段）

先填 **①需求** 和 **②测试用例** 两段（此刻测试还没写实现，应当是失败的）：

**①需求**（功能性语言，用户视角）：
- 功能方向：这个任务要实现什么，1-3 句。
- 功能边界：做什么、不做什么，明确排除项。
- 不能破坏的不变量：既有功能中必须持续成立的规则（如"已有用户仍能正常登录"）。

**②测试用例**（技术语言）：
- 从①的每个功能点和不变量推导测试：unit（逻辑单元）+ smoke（最小真实调用链）+ e2e（按需，用户链路风险高时才写）。
- 必须覆盖边界：空输入、极值、错误输入。
- 每个测试标注对应的需求点或不变量。

### 第 3 步：执行 TDD 循环

按 ②→③ 的顺序实际动手：

1. **写测试代码，跑一遍，确认失败**（红）。失败原因应该是"功能还没实现"，而不是测试本身写错。
2. **写实现代码**（填③的实现步骤和涉及文件），跑测试（绿）。
3. **失败时**：改实现再跑；发现测试写错就改测试并在文档里记录修正原因。这个循环的每次返工不需要逐条记录，但重大方向调整要记进③。
4. **全绿后**，把真实测试输出粘进 **④验证结果**，并跑一遍既有测试确认不变量没被破坏（结果也粘进④）。

### 第 4 步：文档自检并交付

交付前对自己刚产出的 task 文档做一次完整对账。**自检只用 task 文档本身（有 spec 时加上头部指针指向的 spec）作为核对材料，不调用 x-spec / x-req / x-verify 等任何其他 skill，也不改判它们的产物。** 按顺序检查，先结构后内容：

1. **结构**：四段齐全且顺序为 ①需求 → ②测试用例 → ③技术实现 → ④验证结果；头部 `spec:`、`feat:`、`创建:` 三行完整（无 spec 的独立任务按第 1 步约定处理）。
2. **回指有效**：头部 `feat:` 标注的每个 feat 号都真实存在于 spec；②里每条测试标注的需求点/不变量编号都能在①里找到定义。悬空标注在这一步修正。
3. **覆盖闭合**：①的每个功能点、每个"不能破坏的不变量"都至少被②一条测试回指；②不存在标注不到①任何条目的测试。
4. **结论一致**：④的测试输出真实存在（不是"应该会通过"之类的占位）、通过的测试数量与②列出的数量对得上；不变量回归有真实结果；结论四个勾选与④的实际内容一致——有测试没过就不许勾"所有测试真实跑过且通过"。
5. **边界核对**：③涉及文件列表与实际改动一致，没有超出①"功能边界"声明范围的"顺便"改动。

发现问题直接修自己的 task 文档后再重查；修不了（比如需求本身有歧义）就停下来问用户。全部通过才交付。

交付回执格式：

```
✅ x-qdev 完成 · <task-name> · 测试 N/N 通过 · 不变量回归通过 · 改动文件 M 个
```

## task 文档模板

完整读取 `templates/task.md` 后填充，删除占位符和空示例。四段结构固定，顺序不能换：

```markdown
# <task 标题，功能性描述>

> spec: docs/spec/<spec-name>/spec.md（无 spec 写"无，独立任务"）
> feat: feat02（对应 spec 的 feat；无 spec 删本行）
> 创建: YYYY-MM-DD

## ① 需求

### 功能方向
<这个任务要实现什么功能，用户视角，1-3 句>

### 功能边界
- 做：<具体功能点>
- 不做：<明确排除的>

### 不能破坏的不变量
- <不变量，如"已有用户仍能正常登录">

## ② 测试用例（先写，此刻失败）

### unit
<名称 + 对应需求点 + 测试代码/命令>

### smoke
<最小真实调用链测试>

### e2e（按需）
<用户链路测试，含边界；不需要时写"不需要，依据：<原因>"并删除小节>

## ③ 技术实现

### 实现步骤
1. <改哪个文件，做什么>

### 涉及文件
- <path>: <改动说明>

## ④ 验证结果

### 测试输出
<真实运行输出粘贴>

### 不变量回归
<既有测试运行结果>

### 结论
- [x] 所有需求点被测试覆盖
- [x] 所有测试真实跑过且通过
- [x] 实现在边界内
- [x] 不变量未破坏
```

## 完整示例

一个"给待办列表加搜索框"的小任务，task 文档目标形态（节选）：

```markdown
# 给待办列表加按标题搜索

> spec: docs/spec/todo-app/spec.md
> feat: feat03
> 创建: 2026-08-14

## ① 需求

### 功能方向
用户可以在待办列表页通过关键词搜索待办事项，只显示标题包含关键词的条目。

### 功能边界
- 做：标题包含关键词的过滤显示、清空关键词恢复全部显示
- 不做：按内容/标签搜索、模糊拼音匹配、搜索历史

### 不能破坏的不变量
- 不搜索时列表显示与之前完全一致（排序、分组不变）
- 新增、完成、删除待办的功能不受影响

## ② 测试用例（先写，此刻失败）

### unit
- filter_by_keyword：关键词"会议"只保留标题含"会议"的条目 → 功能方向
- empty_result：关键词无匹配时列表为空并显示"无匹配待办" → 边界
- boundary_blank：关键词为纯空格时视为清空，显示全部 → 边界

### smoke
- 打开列表页 → 输入"会议" → 只显示含"会议"的条目 → 清空 → 恢复全部

### e2e
不需要，依据：纯前端过滤，无跨进程用户链路风险

## ③ 技术实现

### 实现步骤
1. `src/components/TodoList.tsx`：加搜索输入框，受控组件绑定 state
2. `src/components/TodoList.tsx`：列表渲染前按 `title.includes(keyword.trim())` 过滤
3. `src/components/TodoList.tsx`：空结果时渲染"无匹配待办"提示

### 涉及文件
- src/components/TodoList.tsx: 搜索框 + 过滤逻辑 + 空态提示

## ④ 验证结果

### 测试输出
（真实输出粘贴处）

### 不变量回归
（既有测试运行结果粘贴处）

### 结论
- [x] 所有需求点被测试覆盖
- [x] 所有测试真实跑过且通过
- [x] 实现在边界内
- [x] 不变量未破坏
```

注意：①是用户能看懂的功能性描述（没有组件名、没有 state），②③④是开发者能直接执行的技术内容。