> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 经典 Spec 模式常见问题

> 解答 /comet 进入经典 Spec 模式后的五阶段工作流、状态恢复、阶段守卫和轻量预设常见疑问。

关于 `/comet` 按项目配置进入经典 Spec 模式后，五阶段工作流、状态、守卫和预设的常见问题。

## 基础概念

<AccordionGroup>
  <Accordion title="Comet 和 OpenSpec、Superpowers 是什么关系">
    Comet 不替代任何一方。OpenSpec 负责 WHAT（需求、提案、spec 生命周期、归档），Superpowers 负责 HOW（brainstorming、技术设计、计划、执行、验证）。Comet 把两者串成一条可恢复的五阶段工作流，并用状态机和守卫保证交接可靠。详见[工作流概念](/zh/concepts/workflow)。
  </Accordion>

  <Accordion title="/comet 和 /comet-any 有什么区别">
    用户统一调用 `/comet`；项目配置选择 Classic 后，内部永久入口 `/comet-classic` 驱动
    open/design/build/verify/archive 五阶段流程。`/comet` 是项目配置驱动的统一别名，可能进入 Native 或
    Classic。`/comet-any` 是 Skill Creator，用来创建、优化、组合可复用的 Skill；三者职责不同。
  </Accordion>

  <Accordion title="我必须用 OpenSpec 和 Superpowers 吗">
    经典 Spec 模式依赖两者——OpenSpec 记录需求规格，Superpowers 提供设计/执行方法论。使用 `comet init   --workflow classic` 时会安装两者；新的项目级 `comet init` 默认使用不依赖它们的
    Native。如果你只想用 Comet 的 Skill 平台能力（用 `/comet-any` 组合任意
    Skill，生成可验证、可评审、可分发的 Skill Bundle），可以从[组合任意 Skill
    快速上手](/zh/skill-creator/getting-started)开始。
  </Accordion>
</AccordionGroup>

## 与相似产品的区别

<AccordionGroup>
  <Accordion title="Comet 和 superpowers-bridge 有什么区别">
    两者都想把 OpenSpec 和 Superpowers结合成一条工作流，但实现形态和保障级别完全不同。

    **superpowers-bridge** 是一个 [OpenSpec 原生 schema bundle](https://github.com/JiangWay/openspec-schemas)：你把它拷进项目当前 OpenSpec 根目录的 `schemas/`（Classic 新项目默认是 `docs/openspec/schemas/`，保留旧布局的项目是 `openspec/schemas/`），用 `--schema superpowers-bridge` 按 change 选择。它是**纯 prompt 层集成**——不改 Superpowers 源码、不改 OpenSpec CLI，靠 `schema.yaml` 里的制品 DAG（`brainstorm → proposal → design → specs → tasks → plan → verify → retrospective`）和散文 `PRECHECK` 约束顺序。它还补了一个 Superpowers 原生缺失的、以证据为先的 `retrospective` 制品。

    **Comet** 是一个独立的 npm 包（`@rpamis/comet`），带跨平台 Node runtime、`.comet.yaml` 状态机、hook 硬拦截、诊断和恢复。两者核心差异：

    | 维度    | superpowers-bridge                                   | Comet                                                                                               |
    | ----- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
    | 形态    | OpenSpec schema bundle，拷进当前 OpenSpec 根目录的 `schemas/` | 独立 npm 包 + CLI + Node runtime                                                                       |
    | 集成层   | 纯 prompt 层，不改源码/CLI                                  | prompt 层 + 工程化 runtime（状态机、hook、guard）                                                              |
    | 编排    | 制品 DAG + 散文说明，靠模型/人工按序调 `/opsx:*`                    | 五阶段状态机，脚本驱动的[自动过渡](/zh/concepts/auto-transition)                                                    |
    | 状态/恢复 | 只有制品文件本身，无显式阶段状态                                     | [`.comet.yaml` 状态机](/zh/concepts/state-management) + [压缩恢复](/zh/concepts/context-compression)       |
    | 约束强度  | 散文 `PRECHECK`（读到但不强制）                                | [phase-guard 规则每轮注入 + hook 硬拦截](/zh/concepts/decision-points)                                       |
    | 平台要求  | 必须 subagent 平台，否则退回 spec-driven                      | 跨平台，不强制 subagent，有降级路径                                                                              |
    | 入口    | 只在 `/opsx:*` 命令生效，自然语言触发会漏气                          | [意图路由](/zh/concepts/intent-routing)从任意输入路由到阶段                                                       |
    | 分级    | 靠人工判断"要不要建 change"                                   | 内置 [hotfix](/zh/presets/hotfix)/[tweak](/zh/presets/tweak) 预设                                       |
    | 范围    | 一个开发工作流 schema                                       | 工作流 + Skill 平台（[组合](/zh/skill-creator/getting-started)/[评估](/zh/cli/eval)/[可视化](/zh/cli/dashboard)） |
  </Accordion>

  <Accordion title="既然都是 OpenSpec + Superpowers，Comet 的优势在哪">
    相对 superpowers-bridge 这类纯 schema 集成，Comet 的优势集中在四点：

    1. **可恢复的状态机**：`.comet.yaml` 显式记录 `phase`、`build_mode`、`tdd_mode`、`review_mode`，长任务或上下文压缩后能精确恢复断点，而不是靠"哪些制品文件已存在"倒推。
    2. **硬性执行防线**：Comet 有 `comet-hook-guard.mjs`（PreToolUse hook）做硬拦截，加上每轮注入的 phase-guard 规则——比如 design 阶段禁止写源码、非法空跳阶段会被拦下。纯 schema 的 `PRECHECK` 只是散文，模型可以"读到但不执行"。
    3. **入口健壮 + 跨平台**：意图路由能从任意用户输入路由到阶段，不存在"只有走 `/opsx:*` 才生效、自然语言触发就漏气"的前门问题；且不强制 subagent 平台。
    4. **不只是工作流，是 Skill 平台**：`/comet-any` 组合任意 Skill、`comet eval` 评估本地 Skill、`comet dashboard` 可视化每个 change，范围超出单一开发工作流。

    如果你只想在 OpenSpec 里加一层 Superpowers 且不介意手动驱动，superpowers-bridge 更轻量；要长任务可恢复性、防漂移强约束、多平台和 Skill 平台能力，Comet 更合适。想了解 Comet 的运行时、工作流、评估和 Skill 创作分别对应哪些业界实践，可以进一步阅读 [Comet 与业界实践对照](/zh/tech-blog/comet-vs-industry)。
  </Accordion>
</AccordionGroup>

## 状态与恢复

<AccordionGroup>
  <Accordion title="中断后再回来，Agent 怎么知道做到哪了">
    Comet 不依赖聊天历史。每次调用 `/comet` 并由配置进入 Classic 后，内部 `/comet-classic` 都会重新读取活跃 change 的 `.comet.yaml` 和 OpenSpec artifacts，判断当前阶段和证据是否一致，然后路由到正确的阶段 Skill。
  </Accordion>

  <Accordion title="comet status 看不到我的 change">
    这个 change 可能是用原始 `/opsx:new` 创建的，缺少 `.comet.yaml`，会被 `comet status` 静默跳过。在
    Agent 平台调用 `/comet` 并由配置进入 Classic
    让它接管补上状态文件。详见[存量项目接入](/zh/guides/existing-project)的"孤儿 change"。
  </Accordion>

  <Accordion title=".comet.yaml 能手工编辑吗">
    用户可见字段（workflow、phase、build\_mode 等）原则上通过 `/comet-classic` 和阶段守卫流转，不要手工改 `phase`。machine-owned Run 字段（在 `.comet/run-state.json` 或 `.comet/runs/<run-id>`）绝对不要手工改。排障时可以用 `comet-state` 命令，详见[状态管理](/zh/concepts/state-management)。
  </Accordion>

  <Accordion title="上下文压缩后丢了上下文怎么办">
    design 阶段写了 `brainstorm-summary.md` 作为恢复检查点，build 阶段的子代理有持久化 checkpoint。恢复时调用 `/comet`；配置进入 Classic 后，内部路由会从文件状态恢复而不是靠记忆。详见[恢复中断的工作](/zh/guides/resuming-workflow)。
  </Accordion>
</AccordionGroup>

## 阶段与守卫

<AccordionGroup>
  <Accordion title="为什么不能跳过 design 直接 build">
    Comet 的核心原则是 brainstorming 不可跳过（hotfix/tweak 预设除外）。完整工作流的 guard 会检查 `design_doc` 是否存在，缺失会 FATAL。跳过设计会导致后续阶段缺乏技术依据。
  </Accordion>

  <Accordion title="verify 失败了怎么办">
    不要直接归档。Comet 会让你选择：修复后回 build、接受偏差（在 design doc 追加说明）或退回重新
    brainstorming。`verify_result: fail` 时归档会被 guard 阻止。
  </Accordion>

  <Accordion title="阶段是怎么推进的，我需要手动操作吗">
    阶段推进由 guard 脚本 `comet-guard.mjs --apply` 完成。`auto_transition:
          true`（默认）时，一个阶段完成后自动调用下一个阶段 Skill；`auto_transition: false` 时暂停，按 HINT
    手动运行。阶段推进本身一定发生，这个设置只影响是否自动调用下一个 Skill。
  </Accordion>

  <Accordion title="handoff hash 不匹配报错是什么意思">
    说明 design 阶段生成 handoff 后，OpenSpec artifacts（proposal/design/tasks/spec）被修改了。解决方法是重新运行 `comet-handoff` 让 Superpowers 拿到当前 OpenSpec 上下文。详见[工作流概念](/zh/concepts/workflow)的"产物如何交接"。
  </Accordion>
</AccordionGroup>

## 轻量预设与大需求

<AccordionGroup>
  <Accordion title="hotfix 和 tweak 有什么区别">
    两者都跳过完整 brainstorming，保留 OpenSpec 状态、验证和归档。hotfix 适合复现路径明确的 bug 修复；tweak 适合范围明确的小改动。出现跨模块协调、新 public API、schema 变更时应升级 full。详见[hotfix 预设](/zh/presets/hotfix)。
  </Accordion>

  <Accordion title="大需求要怎么处理">
    `/comet-open` 会在创建 artifacts 前触发 PRD 拆分预检，把大需求拆成多个可独立设计、交付、归档的
    change。详见[大型 PRD 拆分](/zh/guides/prd-splitting)。
  </Accordion>

  <Accordion title="review_mode 有什么用">
    `review_mode`（off/standard/thorough）控制 build 和 verify 阶段的自动代码审查强度。full workflow 必须在离开 build 前选择；hotfix 默认 off。可在 `.comet/config.yaml` 的 `classic.review_mode` 设置项目默认值。
  </Accordion>
</AccordionGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="代码老是自动提交怎么办">
    自动提交为Superpowers源码行为，您可以让AI为你生成拦截git commit的hook或rule来防止该行为发生。
  </Accordion>

  <Accordion title="代码写到一半，我不满意方案怎么办">
    先让 Agent 停下，不要继续写代码。然后按你实际做过什么处理：

    * **你改了 spec、design 或 tasks**：直接再次调用 `/comet`。配置进入 Classic 后，Comet 会重新读取 `.comet.yaml` 和 OpenSpec artifacts，按当前 phase 恢复到正确阶段。
    * **你自己改了代码**：也再次调用 `/comet`，并告诉 Agent：“我改过代码，请按当前工作区恢复。” Comet 会按 dirty-worktree 协议检查并归因未提交改动。

    如果 spec 和代码都改了，也先用 `/comet` 恢复。你需要说明这些改动是否代表新方案；不要手工改 `.comet.yaml` 的 `phase` 或 `.comet/run-state.json`。Comet 以当前文件状态和持久化 artifacts 为准，而不是靠聊天记忆继续。
  </Accordion>

  <Accordion title="使用Comet之后Token消耗变大，时间变长">
    Comet Full流程为复杂需求/功能所需，会经过多轮澄清，以及可选的TDD执行和Review，过程较为严格，因此Token消耗较快。如果需要轻量快速的交付请使用comet-tweak和comet-hotfix预设。对于小需求/功能，也可以通过Plan或/loop替代。
  </Accordion>
</AccordionGroup>