x-qdev

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 文档后再重查；修不了（比如需求本身有歧义）就停下来问用户。全部通过才交付。