提示词是建议，Harness让规则落地：AI Coding 从个人实践到团队标准

2024-2025年，AI Coding 从「辅助补全」进入「对话式开发」。Claude Code、Cursor、Codex 让开发者用自然语言驱动代码修改、生成、重构。

工具能力不等于交付能力。AI 对话是自由形式的，工程交付需要可控流程。需求不清就开始编码、跳过方案直接出代码、评审后绕过门禁修改，这些不是偶发问题，而是自由对话模式的结构性缺陷。输出质量高度依赖操作者的提示词水平和个人纪律。

如何让 AI Coding 从“个人手艺”变成“团队工程”？我们的答案是：在 AI 对话外建立编排层，用流程约束、知识注入、质量门禁三个机制，把 AI 的自由能力装进可控的工程管道。我们把这套面向 AI Coding 的工程化方法称为 Harness 工程。

Harness 原指安全带、马具，在软件工程中也常用来表示对执行过程的约束与编排。本文借用这一概念，强调 AI 的能力不是被限制，而是被纳入一套可执行、可审计的软件工程体系。这套 Harness 工程融合了 Superpowers 的技能编排与 OpenSpec 的规格化变更流程，再通过 Hook 和门禁补上强制执行与可审计能力。

接下来，我们将沿着这套系统的演进过程，回答三个核心问题，并进一步讨论这套方案仍然存在的边界：为什么 Prompt 不够、为什么 Hook 必不可少，以及如何把个人实践沉淀为团队能力。

01

把约束从人身上迁移到系统里

Harness 并不是一套全新的 AI 开发框架，而是来自两类已有实践的融合：Superpowers 的技能编排、OpenSpec 的规格化变更。但两者单独使用时都缺少关键能力：流程强制力。因此团队把它们融合，并在外层加入 Hook、状态文件、门禁校验和双通道证据，形成本文所说的 Harness 工程。

这条路径不是一次规划好的，而是随实际问题持续迭代，完成了从依赖人管控到依托系统强制约束的三次升级。

▎第一次跨越：把流程写进 Prompt

初期团队各自使用不同 AI 开发工具，依靠个人经验与提示词管控工作：简单任务提效明显，复杂任务落地稳定性差。此时，约束在“人”身上，不在“流程”里。

后来首次尝试引入 /flow 命令作为统一入口，将开发拆分为需求分析、方案设计、编码、测试、评审等标准化环节，用结构化 Prompt 模板约束 AI。跳步骤现象有所减少，但暴露了根本局限：Prompt 是“软”约束。AI 仍可能绕过规则，上下文压缩后也可能“忘记”约束；更重要的是，这一阶段无法核验 AI 的实际操作，只能相信它的“自述”。由于早期版本尚未形成统一的状态结构和度量口径，团队不再将这一阶段换算为精确合规率。

▎第二次跨越：把约束下沉到 Hook

团队随后把约束从提示词层下沉到 Claude Code 的工具调用与执行控制层，在 PreToolUse / PostToolUse 生命周期挂载检查脚本：工具执行前检查当前阶段和准入条件，执行后记录关键事件。搭配 /flow 的阶段锁定机制，系统能够阻断纳入门禁范围的跨阶段操作。相比 Prompt 约束，这一阶段首次具备了可执行的流程强制力；由于前后版本的统计口径不同，本文不对两个阶段作百分比上的直接比较。

但这一阶段系统是“单体”的：Hooks、命令、门禁脚本、知识库均分散在各项目本地目录，靠 rsync / git pull 分发，升级与跨项目复用成本极高。同时管控仅能拦截违规操作，无法校验输出内容质量，AI 套用模板敷衍交付的问题依然存在。

▎第三次跨越：把约束沉淀为可复用能力

插件化、Fail-Closed 和证据机制共同完成了这一阶段，解决了分发、强制力和可审计性三个问题。

分发层面，整套管控逻辑被封装为 Claude Code 插件，通过内部 Marketplace 统一分发。维护者发布并更新目标版本后，启用自动更新的客户端会在 Claude Code 启动时检查并拉取新版本，随后通过重启会话或重新加载插件生效；SessionStart 同时负责幂等注入和环境自检。它替代了以往逐项目复制脚本的人工同步方式，但本质上是客户端启动时拉取，而不是服务端主动推送。

管控强制力层面，团队搭建了三重故障闭锁机制：Bash 状态守卫检查可能修改受保护状态的命令；工具调用前置源码守卫在方案未完成校验前阻止修改业务代码；针对流程状态文件的直接写入统一拦截，仅允许通过专用接口更新。由此，约束从“建议”变成了受管控工具路径内不可直接绕过的规则。门禁引擎（workflow-gate.sh，约 2600 行）是执行核心，统一验证器完成 5 路检查：技能事件、CLI 事件、工件、度量和项目状态。任何一路失败，步骤标记都会被拒绝，不自动降级放行。

审计追溯层面，落地双通道存证规则：任一关键环节需同时留存“工件中的证据标记块”和“Hook 自动写入的事件记录”，二者缺一即判定流程不通过。后续迭代进一步收紧校验规则，拦截空白占位敷衍输出，并搭建三级审核机制，管控精度从流程阶段细化至细分任务。在 monorepo 场景下，通过路由解析确保一个时刻只允许一个子项目有活跃 Flow，跨子项目 commit 被拒绝。

到这里，Harness 已经完成了从 Prompt 到系统约束的演进。但这仍然只是一个项目里的能力。真正的问题是：如何把这些能力复制给团队里的每一个开发者？下面的内容，将回答这个问题。

02

软件工程不能相信 AI 自己说的话

AI Coding 改变了审计的前提。开发者最终看到的是一段代码，但真正的设计过程发生在 AI 与开发者的对话中。这意味着，软件工程的审计对象发生了变化。AI 可以告诉开发者“我已经分析过所有影响范围”，这些描述本质上都是模型生成的自然语言。软件工程不能把自然语言当作审计证据。

▎双通道证据

如果只依赖 AI 自己留下的记录，本质上仍然只是单一信息源；只有来自工程工件和工具执行层的独立证据相互印证，审计才真正成立。

为此，团队设计了一套双通道证据机制。任何关键步骤，都必须留下两份来源不同的证据：

• 工程工件：AI 在完成需求分析或技术方案后，在对应文档中记录本阶段使用的技能、完成时间及相关说明。
• 工具执行记录：当 AI 调用指定技能、执行关键命令时，Hook 自动记录事件并写入流程状态，不依赖 AI 主动记录。

验证时，系统同时检查这两个来源。工件中有证据但工具事件不存在，说明 AI 声称完成了某项操作却没有实际执行；工具事件存在但工件中缺少记录，说明工程产物不完整。两类证据同时满足，当前阶段才被认为真正完成。

AI自己归档记录时会出现遗忘。

▎质量门禁：约束从对话层下沉到执行层

仅有流程和产物记录仍然不够。因为 AI 是否真正遵循流程，不能依赖 AI 自己声明。约束必须从对话层下沉到执行层。当 AI 尝试执行关键操作：修改源码、提交代码或修改流程状态。系统首先检查当前流程是否满足进入条件。如果前置阶段尚未完成，则直接拒绝本次操作。具体通过三层拦截实现：

• 第一层：PreToolUse 源码守卫。 当 AI 尝试调用 Edit、Write 工具修改源码文件时，Hook 首先检查当前流程阶段。如果仍处于方案设计阶段，修改请求被直接阻断（exit 2 = 阻断工具调用），强制“方案未定，代码不动”。
• 第二层：PreToolUse Commit 守卫。 当 AI 尝试执行 git commit 时，门禁脚本校验所有前置步骤的产物是否已完整落盘。未完成流程，则无法提交。
• 第三层：Bash 状态守卫。 AI 可能试图通过 Bash 命令直接篡改记录流程状态的状态文件（.workflow-state.json）。守卫脚本审查每一条命令，仅放行白名单内的只读操作，任何写入企图都将被拦截。

现有可审计样本采用统一、可复核的口径：一个正式需求需在仓库中留下流程状态文件及对应归档工件，且状态记录中未跳过必经步骤，才计为“流程合规”。在2026年4月24日至6月5日的23个正式需求样本中，23个均完成流程归档，其中21个未跳过必经步骤，按此口径计算为21/23，约91.3%。需要说明的是，早期 Prompt、Hook 与插件化阶段的状态结构持续演进，因此这组数据用于描述当前可审计样本，不用于证明各阶段之间的因果提升。

审计能力的意义不是追责，而是协作。当任何一位开发者打开一个需求，都能够快速知道 AI 已经完成了哪些工作、哪些决策已经确认、哪些问题仍待解决。

软件工程不相信 AI 的自述，只相信系统能够验证的证据。

上下文压缩后恢复时LLM忽略规则进行了跳过

03

从个人手艺到团队资产

AI 已经被纳入流程、知识、质量保障和审计体系，但这些能力此时仍主要沉淀在单个项目中。如何让每个项目、每个开发者都拥有同样的 AI 工程能力？

▎流程能力：AI 必须遵循统一的软件交付流程

软件工程需要的是一致性，而不是偶然成功。团队把需求分析、方案设计、编码实现、测试验证、代码评审等阶段组织成可执行的 /flow 工作流。每个阶段都具有明确的输入、输出和准入条件，AI 必须完成当前阶段要求，才能继续执行后续任务。

GP Inline Install 案例：

从需求分析 → 技术方案 → 编码 → 测试，完全在 /flow 编排的框架内完成。每个阶段产物落盘，关键决策形成审计记录。对比传统方式（自由对话 + AI 辅助），减少了3轮评审修改，减少了2个因需求理解偏差导致的功能缺陷。

关键过程：

1. brainstorm 阶段：AI 在交互中被约束必须先调用 superpowers:brainstorming，产物 brainstorm.md 记录了4个待澄清问题，包括安装时机、权限申请顺序、回滚策略和降级体验。其中“安装时机”一项，AI 初稿默认选了“应用启动时”，brainstorm 模板强制要求列至少2个备选方案，最终改选“用户首次触发广告场景时”——这是后续避免2个功能缺陷的关键决策。
2. propose 阶段：OpenSpec CLI 生成 proposal.md，门禁校验 CLI 调用事件存在 + 工件证据块匹配。一次 AI 跳过 CLI 直接生成 proposal，被门禁检测到流程事件缺失并阻断。
3. implement 阶段：三级审查（implementer / spec-review / quality-review）要求每个 task 都有“为什么这样写”的说明。其中 task-3 关于安装回调的注册顺序，implement-reviews 中记录了 spec 评审发现“与方案中的时序图不一致”，强制回退到 plan 阶段补充。
4. verify 阶段：回归测试覆盖了 brainstorm 阶段列出的4个待澄清问题的对应路径。

从这个案例中我们也学到了一件事：第一次跑完整流程时，brainstorm 阶段耗时偏长（约25分钟），原因是 AI 把“待澄清问题”展开得过细，列了11个。这不是 AI 的错，模板没有约束问题数量，AI 自然会尽量“全面”。后续在模板中加了“上限5个”的约束，耗时降回12分钟。约束不是一开始就设计好的，是被实际问题逼出来的。

流量分段平滑优化案例：

在另一个流量分段优化需求中，AI 按照 /flow 完成需求分析、方案设计、测试先行、编码实现和审查验证。方案阶段首先明确配置解析、参数校验、随机偏移、跨天边界等关键决策，再围绕这些决策生成测试。

真正有价值的不是测试数量，而是在 TDD 与门禁反馈过程中，连续暴露了三个容易被忽略的问题：目标类私有构造函数无法直接实例化、纯单元测试环境下 Context 为空导致 NPE，以及跨天测试受到系统默认时区影响。团队分别通过反射构造、空 Context 守卫和测试时区隔离完成修正，最终完成验证。

AI 并没有一次写对，真正发挥作用的是让问题尽可能提前暴露，并通过测试、门禁和审查形成持续修正的工程闭环。

▎知识能力：让 AI 拥有持续积累的工程记忆

统一流程解决的是“AI 应该怎么工作”，但仍然没有解决另一个问题：AI 每次都会重新开始。

团队首先为两个核心项目建设结构化模块知识库，初始分别覆盖22个和18个模块。随着第三个项目和跨项目知识补充，当前仓库已沉淀110份知识类 Markdown，内容覆盖模块职责、接口约束、核心数据流、调试方法和历史设计决策。

知识库并不是一次生成后永久可信。首次深度审计中，一个项目发现并修复了15项高风险、37项中风险和30项低风险知识错误，并补充64项遗漏。这推动团队建立知识刷新和验证管道，让 AI 读取的不只是“有文档”，而是经过持续校验的工程上下文。

在后续需求中，AI 已经能够在 brainstorm 阶段主动读取模块手册，并据此分析多个字段在不同实现类中的分布。不过，知识库对代码正确率和线上缺陷的量化影响仍缺少严格对照数据，团队暂不将其换算为提升百分比。

▎团队资产：从一个项目到所有项目

早期约束逻辑散落在每个项目目录中，靠 rsync 或 git pull 分发，版本不统一，门禁行为也不一致。团队通过插件化分发解决这一问题：将约束逻辑、门禁脚本和命令定义打包成独立的 Claude Code 插件，通过内部 Marketplace 统一发布。维护者更新项目引用的目标版本后，启用自动更新的客户端会在启动时检查并拉取新版本，开发者重启会话或重新加载插件后即可生效。插件架构包含三个关键设计：

• SessionStart 自举：每次会话启动时，插件自动执行幂等注入——检查目标项目的 hooks 配置是否需要更新，清理孤儿 hooks，确保门禁脚本版本匹配。开发者无需手动配置。
• 双策略同步：默认模式下插件每次覆盖目标项目中的门禁脚本和命令定义，保证一致性；也支持项目锁定特定版本，仅初始化缺失文件，不覆盖已有配置。
• 状态文件防篡改：.workflow-state.json 是受门禁保护的流程记录。PreToolUse 拦截 Edit/Write 对该文件的直接修改，Bash 状态守卫同时检查可能篡改状态的命令；流程更新的唯一受支持入口，是通过门禁验证后的 mark-step 子命令。在纳入管控的 Claude Code 工具路径内，AI 无法直接绕过流程状态。

代价是维护复杂度集中化，要求插件发版前有严格的回归验证。这标志着 AI 辅助开发，从一种依赖个人经验和纪律的“手工作坊”，正式演变为可分发、可升级、可审计的工程基础设施。

从2026年4月24日至6月5日，工作流覆盖了3个业务项目和6名开发者，完成23个正式需求的流程归档；同期仓库中另有123个带 AI 标记的提交，但 AI 标记提交不等同于完整 Flow，因此不计入流程合规样本。最大的变化不是 AI 写得更快，而是团队第一次拥有了统一的开发过程——不同项目使用同一套 Flow、同一套知识库和同一套门禁规则。AI 的行为不再依赖个人提示词，而变成了团队共享的工程能力。

团队最初最不适应的不是工具操作，而是“编码前必须把需求问清楚”。AI 会持续追问边界、异常路径、兼容策略和验收方式。对于习惯先写代码、遇到问题再调整的开发者来说，这种刨根问底的过程一开始很难接受。

使用一段时间后，大家认可的收益也不只是代码生成更快，而是开发设计有文档、各阶段耗时有记录、需求到实现的过程能够回看，并且流程不会因为赶进度而被轻易跳过。当前最集中的改进诉求是：为标准 Flow 提供低风险小需求的轻量路径，以及开发中途发现问题后的局部返工路径。

04

AI 距离真正成为团队成员还有多远

最初团队想解决的是“AI 为什么总是不按流程来”，但后来发现，问题并不是 AI 不听话，而是传统软件工程默认存在的人类约束，在 AI 参与后失效了。工具解决的是一个人能不能用好 AI，而团队需要的是所有人都能稳定地用好 AI。前者靠个人经验，后者靠系统设计。

截至2026年7月29日，这套体系已在3个项目中完成验证（数据见第三章）。除了流程和知识的沉淀，这套体系带来的更大变化，是开发方式本身发生了改变。

一是前置审查。在人工 Review 之前，产出先由 implementer 完成，再经过 spec-review 和 quality-review 两层自动审查。过去典型需求通常需要约两轮人工 Review；引入 Harness 后，并不是简单减少评审动作，而是把规格一致性、实现完整性和基础质量检查前置，让人工 Review 更聚焦于业务判断与架构取舍。开发者打开需求时，也能清楚看到哪些决策已经确认、哪些问题仍待解决，不再从零开始读代码。

二是经验效率。根据同类需求常规排期与实际 Flow 耗时的经验对比，部分需求可节省约40%—50%的开发时间。这个数字是团队经验口径，不是严格对照实验；更准确地说，流程标准化让产出过程更可预期。

距离 AI 真正成为团队成员，还有几个关键差距需要弥合：

1. 平台锁定风险：深度依赖 Claude Code 的 Hook API，适配其他平台需重写门禁引擎。抽象层应面向“能力接口”而非特定产品。
2. Bus Factor = 1：整个约束引擎是一人维护的2600行 Bash，团队其他人看不懂也不敢改——这本身就违背了“工程化”的初衷。
3. 适用范围仍需扩展验证：这套方法不局限于 Monorepo，核心的阶段守卫、证据校验和质量门禁同样适用于单仓库或多仓库项目。当前样本主要来自 Monorepo，迁移到多仓库架构时仍需补充跨仓库状态协调、版本一致性和权限边界验证。
4. 标准流程偏重：对于低风险小改动，完整的需求分析、方案、TDD 和评审链路成本较高；开发中途发现问题时，也缺少足够自然的局部返工路径。团队下一阶段将重点探索轻量小需求 Flow 和问题返工 Flow。

此外，因果链尚未完全建立（合规率到业务结果的归因仍在积累样本）、双通道在 AI 自验证场景下会退化为单通道、知识注入在业务逻辑隐含约束上仍有天花板——这些开放问题正在迭代中。

05

附：给读者的最小可行版本

这套方案是内部插件，未开源。但如果你看完想在自己团队试一试，下面是一个不依赖任何内部基础设施的最小起步路径（仅要求使用 Claude Code）：

1. 第一步：一个状态文件 + 一个阶段守卫。 在项目根目录放 .workflow-state.json，内容只有 {"stage": "brainstorm"}。然后写一个 PreToolUse Hook，在 stage != "implement" 时拦截对 src/ 的 Edit/Write。它可以先约束 Claude Code 内置工具的直接源码修改；若希望形成“方案未定稿前不能写代码”的完整强约束，还需同时检查可能写入源码的 Bash 命令、MCP 工具及其他文件写入路径。
2. 第二步：给关键步骤加产物落盘。 用 PostToolUse Hook 在 AI 写完这些文件后自动往状态文件追加一条事件记录（注：最小版本未启用防篡改守卫，故可直接写；生产环境应改为通过专用 mark-step 子命令写入）。
3. 第三步：按需融合 OpenSpec / Superpowers。 当 OpenSpec 的规格化工件、Superpowers 的技能编排和 Hook 门禁三者接在一起时，才进入本文所说的 Harness 完整形态；但它不是起点。

不要一开始就做的事：不要一上来就写约2600行的 Bash 门禁引擎。先用50行左右的脚本跑通“一个状态文件 + 一个拦截器”，用一周观察 AI 的真实行为，再决定是否增加约束。约束是被实际问题推出来的，而不是一次规划完成的——这是这套系统多轮演进中最重要的教训。

一句话判断：如果痛点是“AI 写的代码不可审计、不可追溯”，这套方案能够直接改善；如果痛点是“AI 写的代码质量不够好”，它能提高问题被测试、门禁和评审提前发现的概率，但不能提升模型本身的能力上限。

-

软件工程的每一次重大跃迁，解决的都是同一个问题：如何把个人能力变成团队能力。版本控制解决了代码协作，CI/CD 解决了交付协作，Code Review 解决了质量协作。现在，AI 正在成为团队中新的执行者——但 AI 的能力不会自动变成团队能力。它需要流程、知识、质量和审计，才能真正参与软件工程。

如今，当一个新需求进入系统，AI 会先完成 brainstorm，列出待澄清问题，等待方案评审通过后才能开始写代码。整个过程留下的不是一段聊天记录，而是一条完整的工程审计链。无需依赖开发者反复提醒；在门禁覆盖的工具路径内，未满足前置条件的操作无法直接通过。

当 AI 开始参与软件工程时，真正需要被系统化的，不只是代码生成能力，而是团队的软件工程方法。提示词决定 AI 会说什么，Harness 决定 AI 能做什么。