Comet设计哲学 如何基于不可靠执行者构建可靠AI编程工作流

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

先说一个核心判断。Comet 看起来做的，是把 OpenSpec（告诉 agent“做什么”）和 Superpowers（告诉 agent“怎么做”）拼成一整套工作流。但要只看到这一层，那可就错过真正的精髓了。 Comet 真正要解决的，其实是信任问题。 要回答这个问题，得先正视一个现实：LLM agent 天生带着三个你挥之不去的不可靠性。 **会遗忘。** 长对话进行到后半程，早期聊过的内容会被上下文压缩成一团模糊的摘要。agent 在第一轮认认真真读过的 proposal，到第二十轮可能只剩下“根据之前讨论的需求”这么一句话。它开始凭印象，而不是凭原文做决策。 **会走捷径。** agent 天生倾向于选择最短路径。需求看起来挺清楚？那直接写代码吧，技术设计环节可以跳过了。task 看着也不复杂？测试就算了吧。每一步单独来看都不算什么大问题，但累积起来，整个流程就被悄悄架空了。 **不可预测。** 同一个 prompt，不同模型的表现天差地别。即便用同一个模型，不同会话的表现也可能大相径庭。你永远没法打包票说“这次它会像上次一样乖乖遵守规则”。 这三个问题叠加在一起，指向一个残酷的事实：你不能指望 agent 的自觉性。任何把希望寄托在 agent“能记住”、“会遵守”、“保持一致”的设计，最终总会在某些时刻栽跟头。 Comet 的设计哲学，正是建立在这个清醒认知之上。

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

这可能是理解 Comet 所有后续设计的关键基石。 在 Comet 出现之前，典型的 AI 编程工作流靠的是对话历史来传递状态：agent 在第一阶段创建了 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`。但在 `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 遵守，靠操作系统级 hook。对抗越权。 - **传递层**：跨阶段上下文不靠 agent 复述，靠确定性快照加校验链。对抗信息失真。 - **资源层**：上下文预算显式管理，一次性推理用完即焚。对抗注意力稀释。 - **弹性层**：捷径有明确边界，规模超标强制升级。对抗范围蔓延。 每一层都在做同一件事：把信任从 agent 身上，转移到那些不依赖 agent 自觉的东西上。文件不会忘，脚本不会偷懒，hook 不会妥协，hash 不会说谎。 这或许是 Comet 留给我们最重要的启示：AI 编程工程化的真正壁垒，从来就不在于模型能力有多强，而在于你的流程约束能在多大程度上脱离对模型自觉的依赖。能转移的信任越多，系统的可靠性就越高。 不是因为模型不可靠——而是因为，“可靠”这个词的定义，本身就不应该是“依赖某一个执行者的自觉”。