Spec Harness 详解：把长程开发装进可验收的任务包

AI 编程智能体最不缺的是写代码的带宽，最缺的是记忆。一个跨了好几轮会话的任务，改到一半的方案、已经否决的路线、验收口径，散落在聊天记录里就等于丢了——换一个会话、重启一次终端，上下文归零。Spec Harness 解决的就是这个问题：它是一个面向 AI 编程智能体的任务包工作流工具，把长程改动保存为可恢复、可验证的 Development Record，用范围、证据和 Git 门禁管住全程。它不提供模型，也不替你做产品决策。

一句话概括它的世界观：当一个编码任务的寿命超过一段对话，缺的不是更聪明的模型，而是一份大家（包括未来的你）都能读的合同。

一、核心抽象：任务包

所有工作装进 .spec/specs/YYYY-MM-DD_slug/ 目录，核心是两个文件：spec.md 写范围、假设与取舍（还有一节很特别的”已证伪路径”，后面细说），tasks.md 写任务清单。收尾后整包归档到 .spec/specs/archive/，归档目录本身就是项目的工程日志。

每个任务必须带两行合同——boundary（这个任务能动哪些文件）和 verify（怎么证明做完了）。verify 是只读断言，跑出退出码 0 才许勾选。拿这个博客真实归档的 2026-10-26_blog-5f 包里 T3 任务举例：

boundary 划定”能动什么”，verify 划定”怎么证明做完”——两行齐备，缺一不勾。这不是形式主义：多 agent 并行时，boundary 就是车道之间的护栏（我们的实践里，全局样式文件只许主线动，车道要新变量走申请）；verify 则把”看起来好了”和”证明做完了”区分开，口头”过了”永远不算数。

spec.md 里最有味道的一节是已证伪路径：被否决的方案连否定理由一起入库。我们的 blog-5f 包里记着三条——首屏 banner 化（视觉裁定否决）、热力图换绿（破坏灰阶骨架）、标题 27px 收到 22px（层级锚点，要轻减字重不减号）。下次谁想再试一遍，先读档案，少烧一轮预算。

二、阶段流水线：五个核心命令与它们把守的门

五个核心命令串起一条可验证链：目标 → 范围 → 任务 → 验证 → 归档 → 提交 → 推送。每个阶段之间都有门把守：spec.md 有模板占位符就拒绝进入 run；done 要求每个任务 boundary/verify 齐备、验收面全绿且至少有一条非占位证据（脚本输出、测试结果）；push 只合并 spec/ 前缀的集成分支，文件改动与提交永远分开做，禁用 --no-verify。

被阻塞的任务会打 ! 标记上浮给用户，绝不静默跳过；复核轮（check）发现的可执行问题必须当轮写回任务包并修复，不允许把”待办”当交付物甩给用户。

中断恢复是常态设计——这是它对“任务寿命超过对话”最直接的回答：任意时刻重跑 /spec:run，从 tasks.md 的勾选状态续跑，不依赖任何对话记忆。更进一步，/spec:autoplan 做交互式规划（澄清目标后过框架、细节、复核三轮，规划就绪即停，不自动开工），/spec:autorun 按规划逐包执行，默认最多 5 轮自动链（--max-rounds 可调），暂停后从同一步恢复；一键式入口 /spec:goal 则把规划、执行、复核、归档、提交一次跑完。

命令面共 12 个阶段命令：core 档装五个核心命令，full 档补齐 goal / autoplan / autorun / update / status / doctor / organize 七个扩展件——doctor 做环境自检与修复，organize 做结构审计。还有一个容易被忽略的细节：安装只是放文件，不会主动逐任务评估；想让它在你动手前主动问一句“这事要不要开包”，需要显式接线一次 install_activation_hooks.py --mode on。判据看交付形状——独立验收面、实际实施者、可恢复的在途任务；小修、只读调查、一次性实验都直接做。它防的是“忘了评估”，不防刻意瞒报——文档里对此毫不讳言。

三、多 agent 编排：一个编排者，有边界的帮工

Spec Harness 对多 agent 的态度很克制：主会话是唯一的编排者，路由、集成、验收和 done/push 门禁永远不出主线。旁支工作（探索、构建、审查这类上下文无关的活）可以委托，但要先过机器路由决策（scripts/route_decision.py）并写下任务合同：目标、范围、排除区、产出、验证方式五项齐备才许派。它甚至为”跨会话交接”准备了可选的 handoff.md——生成式快照头加 append-only 条目日志，单人、多人、agent、集群四种协作模式各有一套必填小节。

扩展位（slots）机制则把”别的团队流程”插进来：team-loop 管团队循环、workflow-runner 管工作流扇出，各自带 README 协议和测试。源码库里还附了 orchestrator/planner/reviewer/confirmer 四个编排代理定义。

四、安装：一个安装器，十余个宿主

Spec Harness 是 Python 3.9+ 的标准库实现（PolyForm Noncommercial 许可），安装就三步：

git clone https://github.com/MicTx/spec-harness.git /tmp/spec-harness
cd /tmp/spec-harness
git checkout v0.22.2
bash install.sh

安装器支持十余个宿主：Claude Code、Codex、Gemini CLI、Grok、OpenCode、OpenClaw、Hermes、Pi、ZCode、DeepSeek Harness、Devin、Cursor……不指定时自动探测已装的宿主。安装档位分 core / full：core 只装五个核心阶段命令加 Git 钩子；full 补齐全部 12 个阶段命令和 slots、agents 扩展组件。我们在 Pi 上用 INSTALL_HOSTS=pi bash install.sh，装完 /spec 系列命令直接可用。

五、跑在一个真实博客上

这个博客就是它的用户。归档目录里躺着从裸 clone 构建改造、移动端布局修复到 SEO 解封的一串任务包：blog-5f 一个包八个任务、三条车道（两条 mesh 终端加主线）并行，每个任务的 verify 都是能在命令行跑出退出码的断言，页面类任务统一挂 E2E——E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs，34 项全过才算数。包与包接力，一天 19 个提交全绿落地。

门禁也真的拦过烂账：一次一个全 manual、从未执行的任务包混进了 .spec/specs/，check 门禁直接判 blocked，连带拦下所有携带归档路径的提交——直到把它移出。门禁防的不只是烂尾，还有“看起来有规划”的空包。

工具会迭代，但这套思路不会过期：把”要干什么”写成合同，把”做完了”写成证据，把过程归档成日志。 无论协作方是人还是 agent，这三件事都是长程工程的地基。