open → build → verify → archive 四步,跳过 brainstorming 和完整 plan,把 delta spec 当作正式产物,并通过 OpenSpec 原生的 apply action 构建。

tweak 使用 delta spec 记录变更,并通过 OpenSpec apply 执行
配置调整、文档优化和行为微调可以使用 tweak,前提是范围能够收敛为单个 change,且不需要完整 Design Doc 和实施计划。怎么触发
tweak 通常不是手动输入的命令。用户调用/comet 并进入 Classic 后,内部 /comet-classic 会在 Step 0 先做预设检测:
你也可以直接输入
/comet-tweak。
正常恢复仍使用 /comet。配置进入 Classic 后,内部 /comet-classic 会读取 .comet.yaml 的 workflow 字段,并在 phase: build 时路由回 /comet-tweak。
适合什么场景
以下条件必须同时满足:- 可收敛为单一 OpenSpec change
- 不需要 Superpowers Design Doc 和完整 plan 才能澄清方案
- 不涉及跨模块、跨层级的架构协调
- 任务规模可预估(文件数和任务数仅作提示,不是硬性升级条件)
和 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 状态:
design.md(只对 full 要求),所以 open 完成后直接跳到 build,跳过 design 阶段。init 写入的默认值和入口的隔离选择机制(isolation 默认 null,由你显式选择当前分支、创建分支或创建 worktree,确认后记录 isolation 和 bound_branch)与 hotfix 相同,默认值表和说明见 hotfix 预设 · 初始化的默认值。
Step 2:OpenSpec apply 构建(tweak 专属 build)
这是 tweak 和 hotfix 最大的区别。 tweak 不用手动跑 tasks 循环,而是用 OpenSpec 原生的openspec-apply-change 执行任务:
使用默认值 build_mode: direct,跳过 Superpowers brainstorming 和 writing-plans。apply 流程:
- 运行
openspec status --change "<name>" --json,确认 schema 和任务 artifact - 运行
openspec instructions apply --change "<name>" --json,读取 apply 指令、contextFiles、任务进度和动态 instruction - 读取 apply 指令列出的所有 context files(不得只凭旧对话或手写 tasks 循环实现)
- 按 apply 指令逐个完成未勾选任务,保持改动最小且聚焦
- 每完成一个任务后:格式化 → 跑相关测试 → 按
openspec-apply-change规则勾选 → 提交(tweak: <简述变更>) - 全部任务完成后,显式运行项目相关测试和构建命令
- 运行 build guard 完成 build→verify 过渡
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
brainstorming和writing-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 只有两点差异:
- 质变信号第 2 条不同:tweak 是“需要拆分为多个 OpenSpec change”,hotfix 是“需要新增 capability”。因为 tweak 要求收敛为单一 change,hotfix 不新增能力。其余信号(跨模块协调修改、数据库 schema 变更、引入新的 public API、触及深层架构问题)两页一致。
- 文件数阈值更高:改动文件数超过 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 自己的路由入口在本文「怎么触发」。
下一步
- hotfix 预设 — 另一个轻量预设(修 bug)
- 自动推进机制 — 预设的连续执行、升级和
preset-escalate - 五阶段停顿点和用户选择点 — tweak 的停顿点
- verify 阶段 — tweak 复用的验证流程

