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 承接可收敛的中等调整

不少用户反馈 full 流程对配置调整、文档优化、行为微调这类变更太重。tweak 就是为这类场景设计的:保留 OpenSpec 的 spec 生命周期和归档,去掉前期深度设计成本。
正常情况下你只需要 /comet。 项目配置选择 Classic 后,内部 /comet-classic 会识别可收敛为单一 OpenSpec change、无需完整设计的轻中量修改,优先命中 tweak 并自动调用 /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 才能澄清方案
  • 不涉及跨模块、跨层级的架构协调
  • 任务规模可预估(文件数和任务数仅作提示,不是硬性升级条件)
典型场景:
如果你不确定用 tweak 还是 full,先用 tweak。命中质变信号时 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 写入和 hotfix 相同的轻量执行默认值(build_mode: directtdd_mode: directreview_mode: offverify_mode: light),但 isolation 保持 null,入口会让你显式选择当前分支、创建分支或创建 worktree。确认后记录 isolationbound_branch,后续意外切换分支会被阻止。详见 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。

升级判定(三层分工)

和 hotfix 一样的三层分工,但文件数 tripwire 阈值更高(超过 6 个文件,因为 tweak 本身可能触及更多文件):

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

注意 tweak 的第二个信号是「需要拆分为多个 OpenSpec changes」,而 hotfix 是「需要新增 capability」——这反映了两者适用条件的差异(tweak 要求单一 change)。

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

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

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 触发。

连续执行和必停点

tweak 默认一次性连续执行——调用后自动推进,不主动停顿。但无论 auto_transition 取何值,以下情况必须暂停等你确认:
  1. 命中升级判定信号
  2. 验证阶段的验证失败决策,以及 Archive 阶段的归档与交付确认
  3. 归档前最终确认
(tweak 没有 hotfix 那个”任务超过 3 个转入 /comet-build”的停顿点——因为它始终用 OpenSpec apply,不切换执行方式。) auto_transition: false 时降级为逐阶段手动推进。

退出条件

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

恢复

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

下一步

最后修改于 2026年7月24日