Comet 的设计哲学：怎样在不可靠的执行者之上构建可靠的 AI 编程工作流

Comet 的设计哲学：怎样在不可靠的执行者之上，构建可靠的 AI 编程工作流

不是整合问题，是信任问题

Comet 表面上在做的事情是：把 OpenSpec（管"做什么"）和 Superpowers（管"怎么做"）桥接成一套连贯的工作流。但如果你只看到这一层，你就错过了它真正重要的东西。

Comet 真正在解决的问题是信任问题。

LLM agent 有三个你无法消除的不可靠性：

会遗忘。 长对话中，早期轮次的内容会被上下文压缩成模糊摘要。agent 在第一轮仔细读过的 proposal，到第二十轮可能只剩一句"根据之前讨论的需求"。它开始凭印象而不是凭原文做决策。

会走捷径。 agent 倾向于选择最短路径。需求看起来很清楚？直接写代码吧，跳过技术设计。task 看起来很简单？不用写测试了。每一步单独看都只是"省了一小步"，但累积起来就是整套流程被架空。

不可预测。 同一个 prompt，不同模型表现不同。同一个模型，不同会话表现也可能不同。你永远不能假设 agent "这次会像上次一样遵守规则"。

这三个问题叠加在一起，意味着一个残酷的事实：你不能信任 agent 的自觉。 任何依赖 agent "记住"、"选择遵守"、"保持一致性"的设计，最终都会在某些情况下失效。

Comet 的设计哲学，就是建立在对这个事实的清醒认知之上。

原则一：状态的存在介质，决定了状态的可靠程度

这是 Comet 最根本的设计选择，也是理解它所有后续设计的基础。

在 Comet 出现之前，一套典型的 AI 编程工作流依赖对话历史来传递状态：agent 在第一阶段创建了 proposal，在第二阶段"记得" proposal 的内容并在其基础上做 brainstorming。这个"记得"靠的是对话历史——之前的消息还在上下文窗口里。

问题在于，对话历史是一个不可靠的存储介质。它会压缩（长对话早期内容被摘要化）、会丢失（/clear 或会话中断）、换了模型就没了。最关键的是——agent 不会告诉你它忘了。它会用模糊的印象填补缺失的细节，看起来仍然很自信，但依据已经不可靠了。

Comet 的答案是：把所有关键状态写进一个 YAML 文件。

openspec/changes//.comet.yaml

这个文件承载了当前阶段、产物路径、配置约束等全部状态。每次 /comet 启动，第一步不是"回想之前做了什么"，而是读这个文件。agent 可以忘了一切，但只要这个文件还在，状态就还在。

这个设计背后有一个值得深思的洞察：在 LLM agent 系统中，"持久化"的含义不同于传统软件。 传统软件中，状态持久化是为了容灾——进程挂了能恢复，这是小概率事件。LLM agent 系统中，状态持久化是为了对抗遗忘——agent 每时每刻都在被上下文压缩"遗忘"，持久化不是异常处理，是常态需求。

这也是为什么 Comet 的状态更新必须通过脚本（comet-state.sh）而不是让 agent 直接编辑 YAML——脚本的输出是确定性的，agent 的编辑不是。你在把信任从 agent 手上转移到脚本手上。

原则二：把信任从 agent 身上，转移到基础设施身上

理解了原则一，你就会发现 Comet 中一个反复出现的模式：凡是能和 agent 解耦的，就解耦出去。能用脚本的不用 agent，能放在系统层的绝不放在应用层。 每解耦一层，就少一层对 agent 自觉的依赖。

交接包：为什么不能让 agent 自己去读源文件？

跨阶段信息传递有一个典型场景：阶段 1（OpenSpec）产出了 proposal + design + tasks，阶段 2（Superpowers）的 brainstorming 需要这些内容作为输入。最"自然"的做法是让 agent 自己读一遍文件，然后开始 brainstorming。

但"agent 自己读一遍"意味着什么？意味着这些内容的可靠性取决于 agent 的阅读理解质量——它可能跳过了某些约束、可能理解偏差、可能在上下文压缩后只记得模糊的大意。你看不到它实际"读到"了什么，也没有办法验证。

Comet 的替代方案：用一个脚本（comet-handoff.sh）把源文件内容凝聚成一个确定性快照——交接包。每个来源文件标注精确路径 + 行号范围 + SHA256 哈希。超出预算标记 [TRUNCATED] 但保留源路径——宁可缺，也不捏造。

这里的关键词是确定性。同样的 proposal + design + tasks 输入，脚本永远输出同样的交接包。交接包的 SHA256 写入 .comet.yaml，阶段守卫在进入 build 前重新计算并比对——源文件被意外修改？hash 对不上，直接拦截。

交接包的设计常被误解为"节省 token"。不是的——交接包自己也是文本，也占 token。它的核心价值是可靠性：压缩丢不掉（最近读取优先保留）、丢失能找回（source path 精准定位）、篡改能发现（SHA256 校验链）。三道防线，共同对抗"agent 凭印象做设计"这个常见失败模式。

硬门控：唯一 agent 绕不过去的东西。

Comet 有三层门控，但只有一层是真正不可绕过的——硬门控 comet-hook-guard.sh。以 Claude Code 为例，它通过 PreToolUse Hook 注册在系统中，每次 agent 调用 Write 或 Edit 工具前被自动拦截执行。

这里有一个非常有趣的设计细节：agent 感知不到硬门控的存在。不是 agent "选择遵守"——是它的写入操作直接被操作系统层面拒绝。弹出一个 ASCII 横幅告诉用户"当前是 open 阶段，不能写源码"，agent 甚至不知道发生了什么。

这体现了 Comet 设计者对 LLM agent 能力边界最清醒的认知：你能无条件信任的只有文件系统和操作系统，不是 agent 的自觉。 如果一条约束依赖 agent "读到并遵守"，那它就不是真正的约束——它是一个约定。约定可以遵守 95% 的情况，但剩下 5% 就是整套流程失效的窗口。

一个值得注意的边界条件：PreToolUse Hook 是 Claude Code 平台特有的机制。Comet 支持 28 个平台，在其他不支持 hook 机制的平台上，硬门控可能以不同形式实现，或降级为由 agent 显式执行的脚本拦截。这不会推翻漏斗模型的逻辑——只是在不同平台上，最底层拦截的"硬度"有所不同。

门控的漏斗模型：从约定到强制的逐层收束。

Comet 三层门控的架构逻辑不是"三道平等的防线"，而是一个从广泛引导收敛到精准硬拦截的漏斗：

• 软门控（Rule 注入）：覆盖面最广——告诉 agent 什么阶段能做什么、不能做什么、必须加载什么 skill。但它只能引导，不能强制。agent 可以选择不遵守。
• 阶段守卫（Guard 脚本）：覆盖面中等——agent 必须主动执行脚本，脚本逐项检查产物完整性、字段合规性、构建状态。全部通过才推进 phase。agent 不执行？phase 卡住，流程无法继续。
• 硬门控（Hook）：覆盖面最窄——只管一件事："phase 不对，不准写源码"。但它的拦截是操作系统级别的，agent 不可控。

从软门控到硬门控，覆盖范围递减，但拦截力递增。这不是"三道防线都不够强所以需要三道"——这是不同层次应对不同风险：agent 配合时用软门控高效引导；agent 偷懒时用阶段守卫卡住；agent 完全不配合时用硬门控兜底。

这个漏斗模型有一个隐含的前提：设计者对 agent 的"最坏情况"有预期，并且为之做了准备。 不是乐观地假设 agent 总能遵守规则，而是悲观地假设 agent 可能在任意时刻偏离轨道，然后为每一种偏离模式设计了对应的拦截手段。

原则三：在 LLM agent 的世界里，"调用"就是"让 agent 读到正确的文字"

这可能是 Comet 最反直觉的设计洞察。

在传统软件中，"调用"意味着函数调用、RPC、消息队列、回调。但在 Comet 中，OpenSpec 和 Superpowers 之间的所有交互，都是 agent 读 SKILL.md 中的文本指令后主动执行的：

• "使用 Skill 工具加载 brainstorming"——这是 SKILL.md 里的一句话，agent 读到后执行
• "运行 openspec list --json"——这也是 SKILL.md 里的一句话

整个过程没有任何钩子、事件总线、自动触发、远程调用。 唯一的例外是 comet-archive.sh 内部执行的一行 openspec archive --yes，但就连那也是因为 agent 先执行了 comet-archive.sh。

这意味着什么？意味着在 LLM agent 的编程模型中，"集成"的本质不是设计 API 接口，而是设计文本指令在正确时机被 agent 读到。 你不需要为 OpenSpec 和 Superpowers 之间定义一套通信协议——你只需要在 SKILL.md 里，在正确的阶段，写清楚 agent 应该加载哪个 skill、执行哪条命令。

这也解释了为什么 Comet 不试图"合并"两套系统。如果你用传统软件工程的直觉，你可能会想：把 OpenSpec 和 Superpowers 的功能抽取成一套统一 API，然后 Comet 调用这个 API。但在 LLM agent 的世界里，这种合并不仅不必要，而且有害——它会创造耦合，让两套独立演进的系统互相锁定。

原则四：上下文是一种需要预算管理的稀缺资源

LLM agent 的上下文窗口不是无限的。更准确地说：即使技术上有 200K tokens 的窗口，有效上下文远小于这个数字——因为长对话中，早期内容会被压缩，agent 的注意力会稀释在大量无关信息中。

Comet 把这个问题提升到了设计层面来考虑。

子袋里离载：用完即焚。

制定实施计划（writing-plans）的过程产生大量中间推理——读 Design Doc、分析依赖、拆分任务。这些推理有价值，但价值只在写出 plan 文件的那一瞬间。plan 写好后，这几千字的推理过程对后续的 build 执行毫无帮助——它们是上下文垃圾。

Comet 的做法：把 writing-plans 派发给一个子袋里执行。子袋里完成工作后销毁——中间推理全部丢弃。主会话只收到一句话："plan 已生成，路径是 xxx"。后续几十轮 build 对话中，上下文窗口不会被这些已无用的中间步骤占用。

这不是"节省 token 费用"——这是在保护上下文空间的信噪比。每多一条无关信息，agent 对关键信息的注意力就稀释一分。子袋里离载的本质是：只把结果带回主会话，把过程留在子袋里的独立上下文中并随子袋里一起销毁。

什么值得离载，什么不值得？

Comet 中最典型的离载案例是 writing-plans——制定计划的中间推理（读 Design Doc、分析依赖、拆分任务）在计划文件写完后就成了上下文垃圾，必须清出主会话。但离载不止这一处。在 subagent-driven-development 模式下，每个 task 的 implementer、spec reviewer、quality reviewer 都是独立子袋里——它们各自在隔离的上下文中完成工作，只把结果（代码提交、审查结论）带回主会话。主会话的协调者始终只看到"这个 task 的审查通过了"这一条信息，看不到审查过程中的几十轮讨论。

Brainstorming 不能离载——因为"为什么选方案 A 不选方案 B"的讨论本身就是后续设计决策的重要上下文，离载等于把决策依据扔了。TDD 循环也不能离载——测试失败和修复之间的因果链需要完整历史才能理解。

判断标准是：一个任务的推理产物（过程）在你完成它之后的所有后续对话中是否只是噪音？ 如果是，就离载。如果不是——即使过程很长——也应该保留在主会话中。

原则五：流程纪律必须有弹性边界，但不能有暗门

Comet 提供了三条工作流：full（完整流程）、hotfix（紧急修复）、tweak（小改动）。hotfix 和 tweak 跳过 brainstorming，tweak 还跳过 writing-plans。

这里的设计问题是：你给了用户"捷径"，怎么防止捷径被滥用？

Comet 的答案分两层。

第一层：门控不打折。 hotfix 和 tweak 仍然经过完整的五阶段门控链——open → design → build → verify → archive。门控检查该查的一样不少：tasks 必须全部勾选、构建必须通过、stage guard 全部 PASS 才推进 phase。hotfix 不是"跳过 design 阶段"，而是"design 阶段不强制 brainstorming"。guard 脚本中，hotfix/tweak 的 design_doc 可以为空——这是预设例外，不是暗门。

第二层：自动升级机制。 当你修一个"一行改动的 bug"，修着修着发现要加一个新接口、引入一个新依赖、新增 5+ 测试用例——你已经不是在修 bug 了，你是在做设计。Comet 的升级条件检测到这些信号后，自动触发升级为 full workflow，阻塞等待用户确认，补充产物后才继续。

升级条件的阈值是客观的、可脚本验证的：3+ 文件（hotfix）、5+ 文件（tweak）、新模块/接口/依赖、数据库 schema 变更、需要 delta spec。这些不是靠 agent 自觉判断——comet-state scale 脚本自动评估改动规模。

这个设计的精妙之处在于：弹性是显式的、可审计的、有边界的。 你在状态文件中可以看到一个 hotfix 是正常完成的，还是中途触发升级变成了 full——整个决策链可追溯。没有"悄悄走捷径"这回事。

硬币的另一面：防御性设计保证下限，便利性设计提高上限

前面五条原则全部从"对抗不可靠性"的角度切入——这是 Comet 设计中最深刻的部分，但不是全部。

Comet 同样在降低用户的心智负担上做了大量设计，这些设计不是"防坏"，是"做好"：

一条命令，自动定位。 用户永远只需要输入 /comet。入口 skill 自动检测当前阶段——读 .comet.yaml，发现 phase=design 就分派到 /comet-design，发现 build_pause=plan-ready 就恢复到计划暂停点。用户不需要记住"上次做到哪了"、"现在该加载哪个 skill"——状态机替你记住了。

断点恢复，跨会话无缝衔接。 你今天做了 brainstorming，关了电脑。明天打开终端，输入 /comet，它自动知道该进入 build 阶段——因为 .comet.yaml 里写着 phase: build。跨会话、跨模型、上下文清空，都不影响流程继续。这不是防御，是"让工具适配人"。

28 个平台的统一工作流。 不管你在 Claude Code、Codex、Gemini CLI 还是其他平台，/comet 的行为是一致的。底层的 hook 机制可能不同，但 SKILL.md 指令和 guard 脚本在所有平台上按相同逻辑执行。

这些设计放在防御性框架旁边看，构成了 Comet 完整的产品逻辑：防御性设计保证"不会出错"，便利性设计保证"愿意用"。 如果只有防御没有便利，用户会觉得流程太重、心智负担太大，最终绕过 Comet 直接用 OpenSpec 或 Superpowers。如果只有便利没有防御，那它就是又一个"靠 agent 自觉"的工具。

两面的平衡，才是 Comet 作为产品的完整设计。

总结：AI 编程工程化的核心命题

Comet 最终要回答的问题是：当流程的执行者不可靠时，你怎么设计一个可靠的流程？

它的答案是分层的：

• 存储层：状态不存对话历史，存文件。对抗遗忘。
• 验证层：关键步骤不靠 agent 自觉，靠脚本检查。对抗偷懒。
• 拦截层：底层违规不靠 agent 遵守，靠 OS 级 hook。对抗越权。
• 传递层：跨阶段上下文不靠 agent 复述，靠确定性快照 + 校验链。对抗信息失真。
• 资源层：上下文预算显式管理，一次性推理用完即焚。对抗注意力稀释。
• 弹性层：捷径有明确边界，规模超标强制升级。对抗范围蔓延。

每一层都在做同一件事：把信任从 agent 身上，转移到不依赖 agent 自觉的东西上。 文件不会忘，脚本不会偷懒，hook 不会妥协，hash 不会说谎。

这可能是 Comet 留给我们最重要的启示：AI 编程工程化的真正壁垒不在于模型能力有多强，而在于你的流程约束能在多大程度上脱离对模型自觉的依赖。 能转移的信任越多，系统的可靠性就越高。

不是因为模型不可靠——而是因为，"可靠"这个词的定义本身就是"不依赖任何单一执行者的自觉"。