用途
workflow-bugfix 是一个面向缺陷修复的编排式工作流技能。它用于处理 bug、错误、崩溃、回归或陈旧/不正确输出等场景,尤其是原因未知或波及范围较广的问题。该技能明确区分了几类任务:改变预期行为的请求属于功能开发(workflow-feature),保持行为不变的重构属于重构(workflow-refactor),而本技能只处理缺陷修复。若某缺陷只有一个模块内已知的一行原因,路径会相应简化。
核心规则
工作流要求首先完成规模、类型与风险三项分诊,由分诊决定运行哪些推荐技能、深入到什么程度。在任何修复之前,必须从最终现象逆向追溯到根因;在编写任何回归测试之前,必须判定这是代码 bug 还是规格 bug;并且必须证明回归测试确实能捕获该缺陷——即在修复回退时测试失败(RED),恢复修复时测试通过(GREEN),并在同一次验证中完成。修复必须落在拥有被违反不变量的那一层;改动审查需收敛;当规范或契约行为发生变化时需同步规格。禁止把错误行为编码进规格或测试,也禁止为了让测试通过而削弱测试。
阶段与待办
工作流在执行前先建立待办:按选定模式的每个阶段各建一个待办,并按顺序列出该阶段的每一次出现(含条件性或可选项),保留出现 ID、角色和屏障组。随后将第一个待办标记为进行中,每个步骤行需以运行或跳过的证据关闭,只有当一个阶段所有行都关闭且相关退出条件满足时,该阶段待办才算完成。默认模式的阶段包括:发现(退出条件为根因已追溯)、规格、计划、构建(退出条件为规格已同步)、审查(退出条件为审查已收敛)、验证(退出条件为测试通过)、收尾(退出条件为运行已关闭)。
分诊
分诊需记录到工作流报告中。规模以改动文件和行数为参考:XS 为 1–3 个文件且改动不超过 100 行,S 不超过 15 个文件,M 不超过 60 个,L 不超过 300 个,XL 超过 300 个。类型可能包括:行为 bug、公共契约/API、数据/模式/迁移、安全敏感(认证、密钥、金钱、PII)、性能、UI 界面、仅测试、工具/配置、跨模块/跨服务。风险考虑不可逆性、数据、安全和跨模块因素;深度应随风险和不确定性提升,而不只是看文件数量。
三步典型路径
XS/S、单一归属层、代码 bug、无契约/数据/安全问题:调查 → 回归测试 + 修复 → 审查 → 验证(突变检查即 RED 证明)→ 收尾;$fix 内联规划;仅当该区域有规范时运行规格步骤。
M,或规格 bug,或多个测试用例:增加 $plan;当用例变更超过一个回归用例时,增加规格测试审查。
L/XL、跨模块、契约/数据/安全或原因不明:走完整序列;由 $plan 记录决策、负责人、风险和最终门;按模块分区进行验证与审查。
强制质量门
工作流结束时逐项检查证据:根因已追溯(从观测到的最终状态出发,经读取方 → 存储/投影 → 写入方 → 消费方/任务 → 生产方,覆盖每条供数路径,形成假设矩阵并将环境作为竞争原因权衡,记录归属修复层和前向收敛证明,均带文件与行号);代码 bug 与规格 bug 已分类并附保留说明(当前行为 → 预期行为 → 需保留的不变行为 → 回归证据);回归防护 RED → GREEN($integration-test 先编写可复现缺陷的测试但不运行,$fix 在修复改变接缝时调整该测试,验证步骤的突变检查回退修复使测试失败、恢复修复使测试通过;无法在此环境运行的复现测试标记为环境阻塞并上报,绝不假定为通过);测试通过(本次运行中所有被修改的行为都有运行通过的测试覆盖);规格已同步(当有规范或测试用例文档管辖该区域且行为或公共契约变化,或该规范缺少缺陷暴露的用例时;若无规范管辖该区域则记为不适用,记录搜索路径并提供 $spec 作为后续);审查已收敛(阻塞性发现已修复,并在整个改动包上重新审查);目标满足且运行关闭(目标满足矩阵以 PASS/FAIL/BLOCKED 将根因和 RED/GREEN 证据映射到已保存的成功标准)。
代码 bug 与规格 bug 门
代码 bug(CODE-WRONG):规范描述了预期行为而代码偏离,则为预期行为编写回归用例,然后修复代码。规格 bug(SPEC-STALE):规范记录了错误行为而代码忠实实现,则先通过 $spec [mode=amend] 修正规范,再为修正后的行为编写用例。歧义情况需询问用户或产品负责人意图行为。始终对齐规范意图,不得把偏离规范化到当前恰好通过的一侧。
步骤与角色
按默认顺序:$investigate --mode=debug(门,根因追溯)→ $spec [mode=amend](可选,规格陈述意图)→ $work-item --mode=mockup --explore(可选,仅当修复规模为 M+ 且创建全新的用户界面如新页面、组件或对话框时运行;仅修复现有界面内的内容则跳过)→ $plan(可选,修复计划)→ $spec [mode=tests](可选,回归用例)→ $work-item --mode=review --type=spec-tests(可选,用例质量)→ $integration-test(门,在修复前编写可复现缺陷的回归测试,此处不运行)→ $fix(核心,在归属层修改并调整预写测试)→ $spec [mode=sync](可选,同步规格)→ $workflow-review-changes --tests=defer(门,在主会话内联执行审查)→ $integration-test --mode=verify(门,唯一验证,运行完整测试套件和突变检查)→ $workflow-e2e --source=context(可选,E2E 证据)→ $demo-guide(可选,演示路径)→ $workflow-end(门,运行关闭,未运行 $watzup 时打印回顾)→ $watzup(可选,按需或多工作流汇总会话报告)。
性能问题路径
性能缺陷(延迟、吞吐、内存、查询速度、负载行为)走 $performance-review,需提供 SLA/基准证据:目标指标、基线、测量命令和可接受的回归预算。性能范围不得绕过功能无回归检查。SLA、性能约束或行为边界变化需更新规格和文档。
编排自由度
可选择内联或子代理、并行波次或串行、批处理与顺序,在同等质量下优化实际耗时和 token 成本。但存在固定的数据依赖约束:根因追溯必须先于任何修复计划、回归用例或修复;RED 证明即验证步骤的突变检查,无独立 RED 运行;改动先于审查和测试存在;规格同步先于检查它的审查;测试只运行一次,且静态审查最后进行;验证步骤所做的修复需重跑审查,再审查所做的修复需重跑验证;$workflow-end 最后运行。$workflow-review-changes 必须在主会话内联执行,不得作为子代理。等待用户批准的门(歧义分类、计划批准)不得并行化。建议 XS/S 内联执行;独立只读调查可作为一个并行波次;L/XL 的验证和审查按模块分区为有界批次。
记录与报告
每个阶段一个任务,每个选定步骤或方面一行,以便上下文压缩后不丢失。首次发现前创建 tmp/reports/workflow-bugfix-{YYMMDD}-{HHmm}-{slug}.md 报告文件,逐步追加分诊、追溯、RED/GREEN 证据和偏差,压缩后重新阅读该文件和当前任务列表。子代理简报将写报告作为第一交付物。开始时按目标契约解析活动目标,并将同一目标文件传给每个子步骤,在 $workflow-end 之前输出目标满足矩阵。
兼容性与调用
Codex 兼容说明指出:调用 $skill-name 即加载已注册的 .agents/skills/<name>/SKILL.md 并用 Codex 工具执行,无需单独的 Skill 工具或 Claude 模式切换。当工作流步骤指定某技能时,需自己完整阅读该文件(每行,不设行数限制;仅在输出被截断时分段)。宿主拒绝调用(仅用户可调用的技能)或没有技能调用时,完整阅读 SKILL.md 并以相同参数执行。仅命名技能不算执行。上下文压缩后,继续前需重读进行中步骤的 SKILL.md。需要将外部工具名称映射到可用宿主能力;实际不可用的必备能力需在适配前停止并询问用户。
限制
该技能是一个编排规范,依赖宿主环境支持技能调用、待办工具、子代理和报告文件;它本身不提供具体缺陷修复代码或自动测试能力。规模数值为参考性指导而非硬性定律。执行需遵循项目根指令和跟踪工作约定。规范是否适用取决于项目是否存在管辖该区域的规范文档;缺失时相关门记为不适用。