Skip to main content
hotfix 是 Comet 的轻量预设之一,适合修复明确的 bug。它跳过完整 brainstorming 和完整 plan,走 open → build → verify → archive 四步,但仍保留 OpenSpec 状态、根因消除检查、验证和归档。 hotfix 不是”无流程”——它只是减少前期设计成本,同时保留恢复、验证和归档。

小鱼在 hotfix 维修桌前检查根因、贴上最小补丁、完成验证并归档,同时标记不扩范围

hotfix 快在前期设计成本更低,但根因、验证和归档仍然保留

正常情况下你只需要 /comet。 项目配置选择 Classic 后,内部 /comet-classic 会识别修复已有异常、回归或错误行为的意图,优先命中 hotfix 并自动调用 /comet-hotfix 。只有想手动控制时才直接输入预设命令。详见怎么触发

怎么触发

hotfix 通常不是你手敲的命令。用户调用 /comet 并进入 Classic 后,内部 /comet-classic 会在 Step 0 优先做预设检测 你也可以直接输入 /comet-hotfix。正常恢复仍使用 /comet;配置进入 Classic 后,内部 /comet-classic 会读取 .comet.yamlworkflow 字段,并在 phase: build 时路由回 /comet-hotfix

适合什么场景

适用条件(必须全部满足):
  • 修复已有功能的 bug,不新增 capability
  • 不涉及接口变更或架构调整
  • 改动范围可预估(文件数仅作提示,不是硬性升级条件)
不适合: 需要跨模块重新设计、数据库 schema 变更、引入新 capability 或 public API、需要产品方案讨论。如果修复过程命中升级信号,Comet 会暂停让你选择继续 hotfix 还是升级 full。

和 full、tweak 的关系

如果你不确定用 hotfix 还是 full,先用 hotfix——命中质变信号时 Comet 会暂停让你升级,不会走错。

你会经历什么

Step 1:快速开启(预设 open)

加载 openspec-new-change不做 openspec-explore 长探索),创建精简版产物: 初始化 hotfix 状态(init 写入的默认值见下表):
open guard 对 hotfix 不要求 design.md(只对 full 要求),所以 open 完成后直接跳到 build,跳过 design 阶段

hotfix 初始化的默认值

init <name> hotfix 写入 .comet.yaml 的默认值(和 tweak 完全一样,都跳过设计阶段): hotfix 会在入口暂停一次,让你显式选择当前分支、创建分支或创建 worktree;不会静默选择隔离模式。确认后,isolationbound_branch 会记录实际执行工作区,后续意外切换分支会被阻止。其余 build 字段使用预设值,guard 对预设工作流豁免 review_mode/tdd_mode 选择检查。build_mode: direct 默认只允许 hotfix/tweak,full 必须显式设 direct_override: true

Step 2:直接构建(预设 build)

使用默认值 build_mode: directtdd_mode: directreview_mode: off,并沿用入口时已确认的 isolation。跳过 brainstormingwriting-plans。逐任务执行:
  1. 读 tasks.md 未完成任务
  2. 每个任务:改代码 → 格式化 → 跑测试 → 勾选 - [x] → 提交(fix: <简述修复>
  3. 全部完成后显式运行项目测试和构建命令
执行中出现崩溃、测试失败、构建失败时,强制加载 systematic-debugging ——根因调查完成前不得修复源码。先加最小失败测试复现,再修源码,跑相关测试和构建确认。这是 build/hotfix/tweak 共享的异常调试协议
任务超过 3 个时转入 /comet-build 的计划与执行方式选择(注意:这不触发 full 升级,只切换执行方式,workflow 仍是 hotfix)。修复影响已有 spec 验收场景时,创建 delta spec(仅 ## MODIFIED Requirements)。

Step 3:根因消除检查(hotfix 专属)

这是 hotfix 独有的步骤(tweak 没有),在 build guard 之前执行,确保修复确实消除了问题根因:
  1. 读 proposal.md 的 bug 描述和根因
  2. 搜索验证问题代码不再存在
  3. 根因未消除 → 回 Step 2 继续修复(仍在 build 阶段,无需状态回退)
这一步本身也是升级信号来源:根因消除检查发现深层架构问题,或修复需要额外接口变更,命中质变信号,暂停交你决定。

Step 4:验证(预设 verify)

复用 /comet-verify,由规模评估决定 light 或 full: 想增加审查可在验证前手动设置:

Step 5:归档(预设 archive)

复用 /comet-archive。要求 verify_result: pass,并等待归档前最终确认。如有 delta spec,同步到 main spec。

升级判定(三层分工)

hotfix 的范围判定采用三层分工,避免”用纯文件数当硬性升级条件”误杀正常 bug 修复:

1. 质变信号(命中任一即暂停)

2. 文件数 tripwire(用户拍板)

改动文件数超过提示阈值(如超过 4 个)时暂停交你决定。文件数是提示触发器,不是硬性升级条件——文件多不等于有质变。

3. 验证级别(scale 脚本判定)

comet-state scale 只决定 verify_mode,不卡流程、不触发升级。

升级决策(停顿点)

命中信号或 tripwire 时,Comet 暂停让你二选一(不能自行升级或自行判定可继续): 选 B 后用合法升级通道(不能手工编辑 .comet.yaml):
原子地workflow: fullclassic_profile: fullphase 回退到 design、清空 design_doc,然后加载 /comet-design 补 Design Doc。已完成的代码、tasks 和 OpenSpec artifacts 都保留——你只补一个 Design Doc,不是从头来。preset-escalate 只能从 phase: build 的 hotfix/tweak 触发,其他情况会报错。

连续执行和必停点

hotfix 默认一次性连续执行——调用后自动推进,不主动停顿。但无论 auto_transition 取何值,以下情况必须暂停等你确认:
  1. 命中升级判定信号
  2. 任务超过 3 个转入 /comet-build 时的工作区和执行方式选择
  3. 验证阶段的验证失败决策,以及 Archive 阶段的归档与交付确认
  4. 归档前最终确认
auto_transition: false 时降级为逐阶段手动推进(每个 phase 边界停下,由你手动运行下一阶段命令)。
升级后绝不会自动归档——无论自动衔接还是手动,/comet-archive 都会先做归档前最终确认。

退出条件

  • Bug 已修复,测试通过
  • change 已归档
  • 如有 spec 变更,已同步到 main spec
  • 阶段守卫:build→verify 前 comet-guard <name> build --apply,verify→archive 前 comet-guard <name> verify --apply

恢复

hotfix 幂等。中断后用 /comet 恢复;配置进入 Classic 后,内部 /comet-classic 读取 .comet.yamlworkflow 字段,并在 phase: build 时路由回 /comet-hotfixcomet-state check <name> build --recover 给出恢复上下文,从 tasks.md 第一个未完成任务继续。

下一步

最后修改于 2026年7月24日