Skip to main content
tweak 是 Comet 中复用 OpenSpec 原生流程的轻量预设。它走 open → build → verify → archive 四步,跳过 brainstorming 和完整 plan,把 delta spec 当作正式产物,并通过 OpenSpec 原生的 apply action 构建。

小鱼拿着 delta spec 在 tweak 调音台上做单点调整,连接 apply、full verify,并在范围变大时看到升级信号

tweak 使用 delta spec 记录变更,并通过 OpenSpec apply 执行

配置调整、文档优化和行为微调可以使用 tweak,前提是范围能够收敛为单个 change,且不需要完整 Design Doc 和实施计划。
正常使用时只要运行 /comet。 项目配置选择 Classic 后,内部 /comet-classic 会识别可收敛为单一 OpenSpec change、且无需完整设计的轻中量修改,并自动调用 /comet-tweak。 只有你想手动控制时,才需要直接输入预设命令。详见怎么触发

怎么触发

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

适合什么场景

以下条件必须同时满足:
  • 可收敛为单一 OpenSpec change
  • 不需要 Superpowers Design Doc 和完整 plan 才能澄清方案
  • 不涉及跨模块、跨层级的架构协调
  • 任务规模可预估(文件数和任务数仅作提示,不是硬性升级条件)
典型场景:
无法判断时,直接调用 /comet 并描述修改范围。路由证据不足或与风险信号冲突时,Comet 会请求确认。

和 full、hotfix 的关系

关键区别是 delta spec 的地位:hotfix 把 delta spec 当例外,tweak 把它当正常产物。 需要 delta spec 本身不构成升级理由。如果你的变更天然需要修改 spec,tweak 是正确选择。另一个关键区别是 build 方式:tweak 用 OpenSpec 原生 apply 路径(只属于 tweak,full 不得套用)。

你会经历什么

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

加载 openspec-new-change不做 openspec-explore 长探索),创建精简版产物: 初始化 tweak 状态:
open guard 对 tweak 不要求 design.md(只对 full 要求),所以 open 完成后直接跳到 build,跳过 design 阶段init 写入的默认值和入口的隔离选择机制(isolation 默认 null,由你显式选择当前分支、创建分支或创建 worktree,确认后记录 isolationbound_branch)与 hotfix 相同,默认值表和说明见 hotfix 预设 · 初始化的默认值

Step 2:OpenSpec apply 构建(tweak 专属 build)

这是 tweak 和 hotfix 最大的区别。 tweak 不用手动跑 tasks 循环,而是用 OpenSpec 原生的 openspec-apply-change 执行任务: 使用默认值 build_mode: direct,跳过 Superpowers brainstormingwriting-plans。apply 流程:
  1. 运行 openspec status --change "<name>" --json,确认 schema 和任务 artifact
  2. 运行 openspec instructions apply --change "<name>" --json,读取 apply 指令、contextFiles、任务进度和动态 instruction
  3. 读取 apply 指令列出的所有 context files(不得只凭旧对话或手写 tasks 循环实现)
  4. 按 apply 指令逐个完成未勾选任务,保持改动最小且聚焦
  5. 每完成一个任务后:格式化 → 跑相关测试 → 按 openspec-apply-change 规则勾选 → 提交(tweak: <简述变更>
  6. 全部任务完成后,显式运行项目相关测试和构建命令
  7. 运行 build guard 完成 build→verify 过渡
这条 apply 路径只属于 tweak。完整 /comet-classic workflow: full 不得套用 tweak 的 openspec-apply-change 构建路径。full 仍必须先通过 /comet-design 生成 Design Doc,再由 /comet-build 走 Superpowers 计划和执行。
执行中出现崩溃、测试失败、构建失败时,强制加载 systematic-debugging(共享的异常调试协议)。build 全程持续判断升级信号,并在 build→verify guard 前做集中复核。

Step 3:验证(预设 verify,按 delta spec 分流)

复用 /comet-verify验证路径取决于是否有 delta spec 有 delta spec 时显式设置:
想增加审查可在验证前手动设置:

Step 4:归档(预设 archive)

复用 /comet-archive。要求 verify_result: pass,等待归档前最终确认。如有 delta spec,按 ADDED/MODIFIED/REMOVED/RENAMED 语义同步到 main spec。

调用的 skill

  • brainstormingwriting-plans 同样跳过:tweak 不做技术设计和实施计划,直接按 delta spec 应用变更。
  • 没有 delta spec 时走 light 验证;verify、archive 的 Skill 加载与对应阶段页一致。

升级判定(三层分工)

tweak 的三层升级判定与 hotfix 共用同一套机制。 命中质变信号或超过文件数阈值时,Comet 会暂停让你二选一(继续 tweak 或升级 full)。 文件数只是提示触发器,不会自动升级。comet-state scale 只决定 verify_mode,不卡流程。 如果选择升级,只能走 preset-escalate 合法通道,不能自行升级或手工编辑 .comet.yaml。 完整机制(信号列表、升级决策和 preset-escalate 的一次性效果)见 hotfix 预设 · 升级判定 tweak 与 hotfix 只有两点差异:
  1. 质变信号第 2 条不同:tweak 是“需要拆分为多个 OpenSpec change”,hotfix 是“需要新增 capability”。因为 tweak 要求收敛为单一 change,hotfix 不新增能力。其余信号(跨模块协调修改、数据库 schema 变更、引入新的 public API、触及深层架构问题)两页一致。
  2. 文件数阈值更高:改动文件数超过 6 个时暂停交你决定(hotfix 是超过 4 个),因为 tweak 本身可能触及更多文件。文件数是提示触发器,不是硬性升级条件。文件多不等于有质变。

连续执行和必停点

默认行为和必停点与 hotfix 相同。tweak 默认一次性连续执行,调用后自动推进,不主动停顿。 无论 auto_transition 取何值,命中升级判定信号或文件数阈值、遇到验证失败决策、需要归档与交付确认时都必须暂停并等待你确认。 auto_transition: false 时降级为逐阶段手动推进。必停点完整清单见 hotfix 预设 · 连续执行和必停点 一处执行方式上的差异:tweak 始终用 OpenSpec apply 执行,任务数量不改变执行方式,也不会因此停下来确认。

退出条件

与 hotfix 相同,这里只改了对象表述:tweak 是“变更已完成,测试通过”,hotfix 是“Bug 已修复,测试通过”。 其余条件(change 已归档、spec 变更已同步到 main spec、build→verify 与 verify→archive 前的阶段守卫)见 hotfix 预设 · 退出条件

恢复

恢复机制与 hotfix 相同:tweak 幂等,中断后从 tasks.md 第一个未勾选任务继续,comet-state check <name> build --recover 会给出恢复上下文。中断后的阶段路由说明见 hotfix 预设 · 恢复,tweak 自己的路由入口在本文「怎么触发」。

下一步

最后修改于 2026年9月4日