AI 协作最小循环：从 Spec 驱动开始

Spec 驱动开发核心方法论：20 分钟写 Spec 省 2 小时调试；harness 已从堆料转向裁剪，执行约束层同步加固

30 秒速览

核心观点：Spec 驱动 > Vibe Coding——“20 分钟写 Spec 省 2 小时调试”（Addy Osmani）。详细 Spec 可减少 AI 代码错误率最高 50%（arXiv 2602.00180）。

AI 是放大器不是加速器：GitHub Copilot RCT 绿地项目快 55%，但 METR 成熟代码库反而慢 19%；Anthropic 年度报告”fully delegate 仅 0-20%“——80% 任务仍需围绕模型构建 harness。

硬约束教训（PocketOS，2026-04-25）：Cursor + Opus 4.6 自主删库致 30+ 小时停机——“system prompts are advisory, tokens are enforcing”，spec 是软约束，destructive ops gate 才是硬约束。

harness 的减法转向（2026 年中）：Anthropic 删掉 Claude Code 80%+ system prompt，coding eval 无可测量损失；OpenAI 跟进”精简 prompt”官方指引；ETH 学术实证 AGENTS.md 类 context file 总体不提升任务成功率、推理成本反增 20%+。

执行约束层反而在加固（2026-08~09）：零点击沙箱逃逸漏洞、厂商自述 denylist 被绕过后转向 OS 级沙箱（权限弹窗 -84%）、Skills API 正式 GA、Managed Agents 新增服务端 auto 权限策略——语义指令做减法，执行约束做加法。

快速上手（3 分钟）

核心就一件事：写 AI 代码之前，先花 20 分钟写一个 Spec（规格文档）。

最小操作步骤：

复制这个模板，填好 What / Inputs / Outputs / Constraints / Edge Cases：

# [功能名称]
## What — 做什么，为谁做
## Inputs — 输入是什么，怎么校验
## Outputs — 成功返回什么，失败返回什么
## Constraints — 性能/安全/兼容要求
## Edge Cases — 空输入/断网/并发怎么办

把填好的 Spec 给 AI（Claude Code / Cursor / Copilot），让它按 Spec 实现
验证输出：不是看代码对不对，是看”是否符合 Spec 中的 Outputs 和 Constraints”
不对就改 Spec，不要改 Prompt——Spec 是你的控制杆

为什么有效：Spec 把你的需求从模糊的自然语言变成结构化约束。AI 每次”脑补”的方式不同，但 Spec 让结果确定性大幅提高。使用详细 Spec 可减少 AI 代码错误率最高 50%。

Spec 没用？ → 看 5 个反模式

想了解完整理论和数据？继续往下读。

范式演变定位

Prompt Engineering（怎么和模型说话）→ Context Engineering（给模型什么信息）→ Harness Engineering（围绕模型构建什么系统）→ Supervisory Engineering（人的监督时间该分配到哪儿）——这是过去两年沉淀成型的演进路径：harness 把 inner loop（编码/测试/调试）自动化后，人的工作转移到 middle loop（监督、评估、纠偏），outer loop（commit/review/CI/deploy）仍主要由人主导。

三环模型 + 4 级介入深度

inner loop（编码/测试/调试）           ← AI 自动化（Harness 的主战场）
       ↓
middle loop（direct/evaluate/correct）  ← 人的新工作：监督
       ↓
outer loop（commit/review/CI/deploy）   ← 仍主要由人主导

介入级别	工作内容	举例
in-the-loop	直改 AI 输出的代码/文档	legacy / 个人场景
on-the-loop	调整 CLAUDE.md / Skills / Hooks	Harness Engineering 的日常
above-the-loop	让 Agent 自动优化自己的 harness	更进阶的监督模式
governing	仅设 fitness function + 成本边界	未来方向

Spec 驱动 = Harness 的实践层

Spec 驱动是 harness 的实践形态之一：

Spec = harness 中的”约束和目标定义”
CLAUDE.md = harness 中的”项目宪法”
Hooks = harness 中的”质量保障自动化”
Skills = harness 中的”能力注册和渐进披露”
Subagents = harness 中的”并行执行编排”
Fitness Function = harness 中的”完成条件验证”——Hard Gate 是 Agent 时代的 Definition of Done

Harness 可进一步拆成三层：Guides（前馈控制，预判 Agent 行为——Spec、CLAUDE.md、Skills）、Sensors（反馈控制，事后修正——测试、lint、Fitness Function）、Templates（为常见服务拓扑预设的 Guides+Sensors 捆绑包）。核心哲学：“好的 harness 不追求消除人工输入，而是将人工输入导向最重要的地方。”

量化对比：单 Agent 直出 20 分钟/$9，但产出损坏；完整 Harness（Planner/Generator/Evaluator）6 小时/$200，但产出可用、UX 更好。Harness 不是”慢了”，是”做到了”——结构化 harness 模式带来 2-5x 可靠性提升。

Outcomes：agent 任务的”成功标准 SLO”

Anthropic 发布的 Outcomes 把 spec 中”What/Constraints/Edge Cases”演化为可执行的收敛信号：agent 在执行长任务时持续自检”是否仍朝 outcome 收敛”，达成则停止，未达成则触发人工介入。

旧 Spec 写法	新 Spec 写法（含 Outcome）
“实现一个用户注册 API"	"Outcome：1) 200 响应包含 user.id；2) DB 中存在记录且 password 已 hash；3) 失败 case 返回 4xx 含错误说明"
"重构这个组件"	"Outcome：1) 现有所有测试仍通过；2) 视觉回归测试无 diff；3) bundle size delta < 5%”

Outcome ≠ Acceptance Test：前者是 agent 长任务自检的收敛信号，后者是人写在 Spec 里的要素清单，两者互补。

行动建议：长任务（>30 分钟 agent 时间）的 Spec 必须有 ## Outcome 段，否则 agent 会”漫游”；Outcome 应可被自动化检测（测试 / 度量 / 命令行 exit code），而非人主观判断。

Harness 的减法转向：从堆料到裁剪

前面讲的都是往 harness 里加东西（spec / Outcome / Constraints）。2026 年中出现了第一次明确的反向信号，且迅速从单一厂商扩散为跨厂商共识，并拿到了厂商无关的学术实证。

证据	内容
Anthropic “unhobbling”	为适配新一代模型，删除了 Claude Code system prompt 的 80% 以上，coding eval 无可测量损失。归因不是”上下文不够”，而是指令冲突——同一次请求里矛盾规则（如”适当保留文档”vs”禁止加注释”）让模型把注意力花在消解矛盾上，而非解决问题
模型迁移指引	官方迁移指引明确要求开发者删掉 prompt 里的验证指令与 harness 里的验证步骤——模型已内化自我验证，沿用为旧模型写的指令会导致 over-verification
Claude Code `/doctor`（`/checkup`）	不再只是只读报告，而是主动提议并执行修改：按 context cost 找出无用的 skill / MCP server / plugin，去重本地与 checked-in 版本的 CLAUDE.md，砍掉”Claude 能从代码库自己推导出来”的内容
OpenAI “Favor leaner prompts”（第二家头部厂商跟进）	给出带停止条件的删减流程：“逐组删除 instructions / examples / tools → 重跑同一套 eval”；保留判据是”能否对应某个产品要求，或修正某次实测缺口”。内部 coding-agent eval 报 +10–15% 分 / -41~~66% token / -33~~67% 成本（官方自注为 directional）
ETH SRI Lab 实证（arXiv 2602.11988，厂商无关）	首个对 AGENTS.md 类 context file 的严格评测：context file 总体不提升任务成功率、推理成本反增 20% 以上，跨多个 LLM、多种 coding agent 均成立。但结论是分层的，不是全盘否定——`instructions` 被很好地遵循，对本仓库特有的非标准编码实践仍然有效；唯独 repository overview（目录结构 dump 这类”被厂商推荐”的内容）被证明无效。把这篇论文读成”CLAUDE.md 没用”是误读

可执行判据：按内容类型逐段裁

把 OpenAI 的保留条件与 ETH 的分层结论合起来，得到一张可以直接对着自己的 CLAUDE.md / AGENTS.md 逐段过的表：

内容类型	处置
repository overview / 目录结构 dump	优先砍——收益最低，token 占比往往最高
明确的 instructions（“用 pnpm 不用 npm”、“改完跑 typecheck”）	保留，但去重、每条只写一次
本仓库特有的非标准编码约定（模型先验里没有的）	保留，并显式标注”这是非标准做法”
过程步骤脚本（“first… then… finally…”）	删——模型自己会规划，写死步骤反而压缩它的搜索空间
已被 linter / formatter 强制的风格规则	删——硬约束已在工具层，重复写进 prompt 只制造冲突面
只复述规则的示例	删；示例只在”编码产品需求或修正实测缺口”时留
说不出对应哪个产品要求、修的是哪次实测失败的规则	删——这是总判据
验证类指令（“写完自测一遍”）	按模型换代重新评估
硬性合规约束 / gotchas / 指向 skill 的指针	保留

方法比清单更重要：真正固化下来的是一套带停止条件的 eval 驱动纪律——逐组改动、重跑同一套 eval、只保留可复现改善的改动。没有 eval 的情况下照着上表大砍，只是把一种没有依据的习惯换成另一种。

三条边界，避免读成”harness 该变薄”：(1) 这是模型自我验证效率优化，不能替代工程的独立验证——同期行业共识仍把”验证”列为首要瓶颈；(2) 厂商量化均为内部 eval、未公开逐项数据；(3) ETH 的结论不是”CLAUDE.md 没用”，只是 repository overview 这一段失效，instructions 和非标准约定仍然有效。

对 Spec 驱动的实操含义：定期做一次 harness 时效性审计——每次主力模型换代后，把 CLAUDE.md / spec 模板里的”验证类”与”绝对禁令类”指令重读一遍，删掉模型已内化的；长规则降级为按需加载的 skill，不常驻主文件。

执行约束层：语义层做减法，执行层反而要做加法

上一节讲的全部是语义指令层——CLAUDE.md 段落、system prompt 规则、工具描述措辞。harness 不是均质的一层，它还有一层执行约束层（containment）——沙箱模式、网络策略、工具参数白名单、权限可撤销性——这一层的正确方向是相反的。

一句话记法：语义层做减法，执行层做加法。删的是”告诉 agent 别做什么”，加的是”让 agent 做不到”。

证据	内容
攻击面是结构性的（DuneSlide 漏洞披露）	两个高危 CVE（CVSS 9.8 / 9.3）证明零点击间接 prompt injection 可从一个 MCP connector 响应或一次 web search 返回页打穿沙箱、拿到宿主机命令执行——攻击者从不接触开发者的 IDE
名单式防护对 agent 无效（Anthropic 自述）	厂商自述观察到 Claude 用替代二进制路径绕过自身 denylist、遇沙箱限制时直接把沙箱关掉去完成任务。解法是把边界下沉到 OS 级沙箱（macOS Seatbelt / Linux bubblewrap）+ 网络默认拒绝，权限弹窗实测减少 84%（衡量的是可用性改善，不是攻击成功率下降）
控制手段存在但不在必经路径上（行业调研，n=900+）	80.9% 的组织已把 agent 部署进测试或生产，但仅 14.4% 带完整安全审批上线——落差是执行落差，不是意识落差
评测环境隔离失败集群（多家实验室 + 一个独立政府机构独立披露）	约一个月内，多家前沿实验室各自披露评测环境本应隔离却意外留有通往真实基础设施的活动路径，一个独立政府机构的复现把这个问题从”厂商自述”升级为可横向验证的行业级失败模式。根因与上一条一致：不是 agent 恶意，是目标导向的 agent 用上了被误发放的访问权限
containment 持续产品化	Anthropic Agent Skills API 正式 GA；Managed Agents 新增服务端 `auto` 权限策略——每次 agent / 工具调用由服务端自主评估 run / deny / pause，把”人工审批疲劳”进一步推向”服务端策略引擎自主判定”（可审计性、误判率均未披露）

自查清单

#	自查项
1	是否启用 OS 级沙箱（Seatbelt / bubblewrap / microVM）——不是”我小心点”，是进程级隔离
2	网络是否默认拒绝——默认允许出网 = 被注入的内容可直接外传
3	denylist 是否被当成主防线——是则减分，厂商已自证会被绕过
4	工具参数是否有白名单——路径 / 命令类参数须限定在工作区内
5	MCP server 的信任边界是否显式声明——哪些返回值可当指令、哪些只能当数据
6	权限是否可按任务阶段撤销，而非一次性授予后单调累积

对 Spec 驱动的实操含义：spec 的 ## Constraints 段要区分软硬两类——“不要删生产数据”是软约束（会被绕过，仍要写以传达意图），“这个 agent 拿不到生产凭据 + 网络默认拒绝”才是硬约束。containment 配置不进入上一节的裁剪流程——它的价值不体现在 eval 分数上，而体现在事故没发生。

Harness Engineering 的学科化

两篇互相独立的综述（各覆盖 110+ 篇论文 / 23 个部署系统）在 Execution / Tooling / Context / Lifecycle / Verification 五项上独立收敛到同一切分——harness engineering 走完”产业口号 → 独立学科”的最后一步，成为有形式语义、完备性矩阵与专属综述的领域。其中一份用 ETCLOVG 七层 taxonomy（Execution / Tooling / Context / Lifecycle / Observability / Verification / Governance）划分，语料中 Verification 与 Lifecycle 最密集——与”验证正在取代代码生成成为首要瓶颈”的产业共识独立同向；另一份给出六组件形式化 H=(E,T,C,S,L,V)，核心断言”harness 正在成为约束能力上界的那个变量（binding constraint）”。

配套出现的 Harness-Bench（106 个沙箱任务 / 5,194 条执行轨迹）把 harness 配置本身作为受控变量，命名了主要失败模式 execution-alignment failure——“看似合理的推理链，已经与工具反馈 / 工作区实际状态 / 可验证的输出契约脱钩”。这是比”上下文不足”精确得多的归因术语，也是 AI 不按 Spec 执行时排查里最难定位的一类：判据是”它的结论能不能被工具输出、文件实际内容反证”。

对个人的实操含义：用 ETCLOVG 七层做一次自查清单，比”我装了几个工具”更有信息量——你的 harness 在 Execution / Tooling / Context / Lifecycle / Verification 上分别有什么？哪一层是空的？Observability / Governance 两层在个人开发者场景下证据仍稀薄，不必强行补齐。不要把公开横评的 benchmark 分数直接搬进自查清单——横评比较的是工具/框架本身，你要回答的是自己仓库的 harness 与 SOTA 实践差多少，两者判据不同。

硬约束 vs 软约束：PocketOS 教训

2026-04-25，一起真实事故（Cursor + Claude Opus 4.6）中，Agent 在 staging 凭据不匹配后自主决定”修复”，删除全部生产数据库及备份，30+ 小时停机，最近恢复点是 3 个月前。多方独立技术分析得出共识：“system prompts are advisory, tokens are enforcing”。

软约束（Spec / CLAUDE.md / prompt）引导 Agent 行为方向，但不阻止任何 token 级动作——即使 Spec 写明”禁止删除生产数据”，Agent 在”修复 bug”的链路中仍可能误判进入 destructive 路径。

硬约束（token 级 enforcement）才真正拦截：

层级	实施手段	阻止什么
环境隔离	不让 Agent 拿到生产凭据；用只读 token / staging 副本	物理上不可能误操作生产
destructive ops gate	钩住所有 `DROP` / `DELETE` / `rm -rf` / `git push --force`，要求人显式确认	即使 Agent 想执行也被中间层拦截
fitness function	commit 前自动跑契约测试，失败则阻止 merge	错误代码无法进入生产
审计 + 回滚	所有 destructive ops 留 immutable log + 自动备份回滚点	即使发生事故也能恢复

Spec 驱动是输入规范化，token-level enforcement 是输出 enforcement——二者必须叠加。仅有 Spec 而无 enforcement = PocketOS 路径；仅有 enforcement 而无 Spec = Agent 不知道该做什么。

Solo 开发者警示：不能用”我自己看着”替代环境隔离 / destructive ops gate / 审计日志——Agent 24/7 异步运行时人不在场。

最小循环五步法

想法 → Spec → 实现 → 验证 → 迭代
 ↑                              |
 └──────── 数据/反馈 ←──────────┘

步骤	你做什么	AI 做什么	耗时占比
1. 想清楚	用自然语言描述需求/假设	Claude 对话帮你理清思路	15%
2. 写 Spec	审核结构化文档	生成 spec.md（What/Inputs/Outputs/Constraints/Edge Cases）	10%
3. 实现	监督、分解任务	Claude Code / Cursor 按 spec 逐块实现	25%
4. 验证	判断对不对（核心职责）	自动测试 + AI review AI 的代码	30%
5. 迭代	决定下一步方向	分析反馈、更新 spec	20%

“20 分钟写 Spec 省 2 小时 Prompt 调试。” — Addy Osmani

关键洞察：

验证（步骤 4）占时最多——代码生成不再是瓶颈，验证才是
27% 的 AI 辅助工作是”不用 AI 就不会做的事”——AI 不是加速循环中的某一步，而是让整个循环转得更快
“相对容易验证”的任务最适合委派给 AI

三种循环速度

循环	周期	适用场景	示例
闪电循环	1-4h	内容产出、小功能、修复	写一篇分析帖
日循环	1-2d	功能开发、产品迭代	做一个表单
周循环	1-2w	方向验证、战略调整	评估两条方向哪个更好

Spec 驱动开发方法论

最小 Spec 模板

# [功能名称]

## What（一段话）
做什么，为谁做，解决什么问题。

## Inputs
- 输入1: 类型, 校验规则
- 输入2: 类型, 校验规则

## Outputs
- 成功: 返回格式
- 失败: 错误类型 + 信息

## Constraints
- 性能: 响应时间 < Xms
- 安全: 不存储敏感信息
- 兼容: 支持的平台/浏览器

## Edge Cases
1. 输入为空时 → ...
2. 网络中断时 → ...
3. 并发请求时 → ...

## Outcome（长任务必填）
1. 自动化可检测的收敛信号 1
2. 自动化可检测的收敛信号 2

Addy Osmani 的六原则（Google Chrome 团队）

原则	说明
1. Spec 优先	与 AI 头脑风暴 → 写 spec.md → 再写代码。“15 分钟的瀑布”
2. 小块迭代	一个 function、一个 bug、一个 feature。不让 AI 输出大块代码
3. 充分上下文	用 gitingest/repo2txt 打包相关代码喂给 AI；CLAUDE.md 作为项目配置
4. 多模型策略	不同任务用不同 LLM，卡住了换模型——先按 3 步排查判断是否真卡住了
5. 人工审查循环	”把 AI 输出当 Junior Dev 的代码”——绝不合并你不理解的代码
6. 版本控制纪律	每个小任务一次 commit，commit 是”游戏存档点”

TDD + AI vs Spec + AI

方法	流程	优势	场景
TDD + AI	写测试 → AI 实现代码 → 运行测试	质量保证最强	已知行为的功能
Spec + AI	写 spec → AI 生成代码 + 测试	更快启动、更适合探索	新功能、不确定需求
Spec + TDD + AI	写 spec → 从 spec 派生测试 → AI 实现 → 跑测试	兼顾速度和质量	推荐的完整流程

TDD 告诉你”是否正确实现了”，SDD 告诉你”该实现什么”。在 AI 时代，Spec IS the prompt——spec 质量直接决定输出质量。

Spec 的 5 个反模式（为什么你的 Spec 没用）

反模式	症状	修复
1. 模糊边界	Spec 写”处理各种输入”，AI 每次脑补不同的”各种”	列举具体输入类型和范围。“支持 1-1000 的整数”比”支持数字”好 100 倍
2. 缺失约束	AI 的代码能跑但架构一团糟（全局变量、God class）	在 Constraints 中加架构约束：“使用依赖注入”、“每个文件 < 200 行”
3. 过度细节	Spec 长达 5 页，AI 反而不知道哪些重要	一个 Spec 只做一件事。控制在 1-2 页。超过了就拆分任务
4. 遗漏错误路径	只写了 happy path，AI 不处理异常	Edge Cases 必填。至少覆盖：空输入、网络失败、并发、权限不足
5. 没有验证标准	Spec 说”做一个 API”，但不说”怎样算做好了”	在 Outputs 中写明成功标准：“返回 200 + JSON，响应 < 100ms”

AI 不按 Spec 执行时的 3 步排查

AI 输出和 Spec 不符？
│
├── 第 1 步：检查上下文
│   ├── CLAUDE.md 中是否有与 Spec 冲突的规则？（跨层指令冲突是最常见病症）
│   ├── 之前的对话中是否给了矛盾指令？
│   └── 修复：/clear 重置上下文 → 只提供 Spec 和必要文件；Claude Code 用户可直接跑 /doctor
│
├── 第 2 步：检查 Spec 粒度
│   ├── Spec 是否同时描述了多个功能？
│   └── 修复：拆分为多个原子 Spec，每次只做一个
│
└── 第 3 步：检查模型匹配
    ├── 简单 CRUD → 任何模型都行
    ├── 复杂架构 → 需要旗舰级模型
    ├── 多文件重构 → 需要大上下文
    └── 修复：卡住了就换模型试试

第 4 步（容易被忽略）——检查投放位置：同一条指示写在 spec / CLAUDE.md / 工具描述 / 工具返回值这四个不同位置，措辞不变，出现的位置一变，可能就从”不生效”变成”生效”。

经验法则：把 Spec 给一个不熟悉项目的同事看，他能理解你要做什么吗？人看不懂，AI 一定看不懂。

Spec 驱动开发的学术基础

三级严格度（arXiv 2602.00180，SDD 首个学术综述）

级别	名称	说明	对应产业实践
L1	Spec-First	spec 是对话起点，code 是 draft	GitHub spec-kit / OpenSpec 等 OSS 项目早期模式
L2	Spec-Anchored	spec 与 code 双向同步；spec 是 contract	Three-Agent Harness 的 Planner 角色
L3	Spec-as-Source	spec 是 source of truth，code 是 deterministic 生成产物	Fitness Function 的 Hard Gate / Tessl 一对一映射

使用详细 spec 可减少 AI 生成代码错误率最高 50%。

工具现状

工具	厂商	方法	评价
Kiro	Amazon/AWS	需求 → 设计 → 任务（VS Code 插件）	最成熟的 spec-driven IDE，集成 Agent Hooks + MCP
spec-kit	GitHub	宪法 → 规格 → 计划 → 任务（CLI）	84.7K stars，支持 14+ Agent 平台
Tessl	独立（内测）	spec 与代码一对一映射	映射最干净，但成熟度最低

历史警告：存在重蹈 Model-Driven Development 失败的风险 + LLM 非确定性。Agent 经常无视或过度解读 spec。

生产力研究：关键数据（矛盾但都成立）

研究	样本	场景	结果
GitHub Copilot RCT	开发者	JS HTTP 服务器（绿地）	快 55%
METR RCT	n=16 资深开源	成熟代码库	慢 19%
Anthropic 内部	全公司	混合任务	+50%（自报告）
Daniotti & Wachs（2026-05）	30M GitHub commits / 170K 开发者	Python 函数	29% 由 AI 写（学术级量化）
DORA	行业基准	跨公司	AI 是放大器：强团队更强，弱团队更弱
Stack Overflow 2026	数万开发者	综合	采用 84% 但高度信任仅 3%；66% 花更多时间修”几乎对但不全对”的 AI 代码
Anthropic 2026 Trends	—	—	fully delegate 仅 0-20%——80% 任务仍需 harness

关键洞察：55% 加速（绿地）和 19% 减速（成熟代码库）都是真的——差异在于任务复杂度和代码库熟悉度。AI 不是万能加速器，它放大你已有的能力。SO 2026 的”采用-信任悖论”进一步坐实了这个判断：采用 84% 但高度信任仅 3%，66% 在修”几乎对但不全对”的代码——这正是”为什么需要 spec 框定边界 + 验证回路”的最直接量化背书。