AI 编程概念与 Harness 工程实践入门

引言：AI 写代码之后，真正的挑战才刚开始

过去几年，AI 编程工具的发展速度远超许多人的预期。从最初的代码补全，到对话式助手，再到如今能够读取文件、修改代码、执行命令、运行测试的智能 Agent，可以说技术迭代几乎是一步一个台阶。很多团队初次接触 AI Coding 时，都会有相似的感受：它确实能够生成代码，而且速度飞快。

然而，一旦 AI 进入真实的工程项目，各种问题便开始浮现：

• AI 生成速度快，但不保证正确性。
• AI 能够理解需求，但常常忽略历史约束。
• AI 会使用工具，却可能无法识别风险工具。
• AI 能产出大量代码，但团队可能难以逐一审查。
• AI 今天修正的问题，明天换个会话又会重复出错。
• AI 在演示项目中表现顺畅，但在复杂的业务代码库中容易偏离方向。

这些问题指向了一个核心矛盾：AI 编程的瓶颈已经不再是“模型会不会写代码”，而是“如何让模型在真实的工程环境中稳定、可控、可验证地工作”。

这正是 Harness Engineering 所要解决的核心课题。

用一句话来概括：AI 编程并非简单地把需求丢给模型等待结果，而是要为模型搭建一套工程化的运行轨道，使其在正确的上下文、明确的边界、自动化的验证和持续的反馈中高效完成任务。

一、先理解几个基础概念

1. LLM：擅长“续写”的智能引擎

从本质上来说，大语言模型是一个极其强大的文本预测系统。当你给它一段输入，它会基于训练过程中学到的语言、代码、知识和模式，预测出接下来最合理的内容。

这听起来像“自动补全”，但当模型足够强大时，它可以展现出推理、总结、翻译、规划、代码生成等综合能力。

但需要注意的是，模型本身并不了解你的项目结构、团队规范、历史决策、线上事故以及业务边界。它只有在当前上下文中看到这些信息，才可能正确地运用它们。

因此，AI 编程的首要规律是：模型能力固然重要，但模型所能“看见”的内容同样至关重要。

2. Prompt Engineering：清晰表达任务

Prompt Engineering 通常被翻译为“提示词工程”，它解决的是“如何向模型准确表达任务”的问题。

举个例子，同样是让 AI 编写一个登录模块，不同的提示词会得到截然不同的结果：

写一个登录页面。

这个提示过于模糊，AI 只能根据通用经验来生成。

请用 Vue 3 + TypeScript 写一个登录页面，包含手机号、验证码、登录按钮，使用项目已有的 Button 组件，表单校验失败时展示错误提示，不要引入新的 UI 库。

这个提示更接近真实的工程任务，因为它明确了技术栈、功能范围、复用要求以及限制条件。

Prompt Engineering 的价值在于让模型理解你的意图。但它有明显的局限：即使你描述得再清楚，如果模型不知道项目现有组件的位置、接口契约的内容，或者团队禁止直接引用第三方组件的规定，它依然可能出错。

3. Context Engineering：提供恰当的信息

Context Engineering 解决的是“模型在执行任务时应该知晓哪些信息”。

在真实项目中，关键知识往往分散在各处：代码、README 文档、接口说明、需求单、设计稿、历史 PR、团队规范、线上事故复盘、业务术语表等。人类工程师可以依靠经验和沟通来补齐这些信息，但 AI 做不到。AI 只能使用它当前可见或可以检索到的上下文。

因此，Context Engineering 的核心任务，就是以合适的粒度将正确的信息提供给模型。

常见的做法包括：

• 使用 AGENTS.md 或规则文件来保存项目协作规范。
• 通过 context/ 目录来沉淀团队规范、业务知识和历史经验。
• 利用服务矩阵或依赖表来描述微服务之间的关联关系。
• 采用领域模型来描述页面、组件、接口和数据结构。
• 借助 RAG 检索系统按需注入知识，而非将所有文档一次性塞入上下文。
• 运用滚动摘要、记忆分层和上下文压缩技术，减少无关信息的干扰。

Context Engineering 的目标不是“提供得越多越好”，而是“在正确的时间，为模型提供最有价值的信息”。

4. Agent：能够行动的模型

普通的聊天模型只会回答问题。而 Agent 则在模型之外接入了工具，使得模型不仅能“说”，还能“做”。

一个代码 Agent 通常具备以下能力：

• 读取文件内容。
• 搜索代码片段。
• 修改文件内容。
• 运行测试用例。
• 执行命令行指令。
• 查看日志文件。
• 访问浏览器。
• 查询接口文档。
• 调用内部平台。

Agent 的能力来源于“模型 + 工具 + 上下文 + 控制流程”的组合。

这也带来了风险：工具的能力越强，潜在的破坏力也越大。一个能写入文件的 Agent 可能改错代码；一个能执行命令的 Agent 可能误删文件；一个能访问数据库的 Agent 可能读取到不应访问的数据。

因此，Agent 不能仅仅依赖“模型自觉”，必须要设置工程边界。

5. Skill：将能力封装为操作手册

许多 AI IDE 或 Agent 平台都支持 Skill。Skill 可以理解为一份可复用的任务指导手册，通常包含以下内容：

• 这个 Skill 适用于什么场景。
• 触发后应遵循怎样的流程。
• 可以使用哪些工具。
• 需要读取哪些参考资料。
• 输出格式和校验标准是什么。

从底层协议来看，Skill 往往不是模型 API 的原生概念。它通常会被应用层转换为以下几类资源：

• 注入到 system 或 developer message 中的说明文本。
• 可供模型调用的工具 schema。
• 模型按需读取的 SKILL.md、脚本和参考文件。
• 多轮 tool calling 的执行循环。

换句话说，Skill 的本质就是“给 Agent 的可执行工作手册”。

6. Harness：让 AI 稳定工作的工程底座

Harness 的原意是马具、挽具，也可以理解为将强大力量接入可控系统的装置。

在 AI 工程领域，Harness 指的是包裹在模型外部的整套工程系统。它并不替代模型，而是决定模型如何被使用。

一个最简单的公式是：

Agent = Model + Harness

模型提供智能，而 Harness 则让智能转化为可靠的生产力。

Harness 通常负责以下职责：

• 任务如何进入系统。
• 如何拆解需求并规划步骤。
• 哪个 Agent 负责哪类任务。
• 工具如何注册、授权和审计。
• 上下文如何加载、压缩和更新。
• 执行过程如何记录 Trace。
• 失败后如何重试、降级或终止。
• 成本如何控制。
• 质量如何评估。
• 经验如何沉淀到下一次任务中。

如果说 Prompt 是“怎么说”，Context 是“给什么信息”，那么 Harness 就是“整个 AI 系统如何可靠运行”的保障。

二、AI 编程的三次工程演进

AI 编程的演进可以大致分为三个层次：Prompt Engineering、Context Engineering、Harness Engineering。这三者并非替代关系，而是逐层叠加递进的。

1. 第一阶段：Prompt Engineering

这个阶段的核心问题是：如何让模型理解任务？

常见的技术包括：

• 角色设定：让模型以资深工程师、测试专家、架构师等特定身份来工作。
• 少样本提示：提供几个输入与输出的示例。
• 思维链：引导模型分步骤进行推理。
• 结构化输出：要求模型输出 JSON、Markdown 表格或固定模板。
• 任务拆分：将复杂任务拆解为多个小提示。

Prompt Engineering 可以显著提升单次交互的质量，但它无法解决长期协作、复杂上下文和工程验证等问题。

2. 第二阶段：Context Engineering

这个阶段的核心问题是：如何让模型获取正确的知识？

当 AI 进入企业代码库时，最大的瓶颈通常不是模型不会写代码，而是它不了解项目中的隐性规则。例如：

• 某个接口字段不能修改，因为下游有强依赖。
• 某个组件必须从项目封装层引用，不能直接从第三方库引用。
• 某个服务的分页查询必须有上限，因为历史上曾导致下游系统崩溃。
• 某类错误码有固定的区间范围。
• 某些页面必须同时兼容 CSR 和 SSR。

如果这些知识只存在于人脑中、群聊记录里或旧版文档中，那么 AI 就无法稳定地遵循它们。

Context Engineering 会将这些知识沉淀为机器可读的工程资产，例如：

context/team/git.md
logging.md
error-code.md
project/order-service/architecture.md
api.md
experience/pagination-limit.md
harness-framework/workflow.md
gates.md

其关键原则是构建单一事实来源：团队规范、业务知识和历史经验应放置在可版本化、可审查、可追溯的位置，而不是散落在不可控的聊天记录中。

3. 第三阶段：Harness Engineering

这个阶段的核心问题是：如何让 AI 在真实的工程流程中稳定交付？

仅依靠 Prompt 和 Context 仍然远远不够，因为 AI 可能会：

• 没有运行测试，却声称已经通过验证。
• 修改了公共组件，却不了解其影响范围。
• 遇到错误后，反复重试同一个已经失败的方案。
• 在上下文过长后，遗忘了早期的约束条件。
• 为了完成任务，顺手重构了无关的代码。
• 生成了正确的答案，但中间使用了不合规的工具。

Harness Engineering 通过流程、门禁、工具治理、Trace、评估和反馈闭环来系统性地解决这些问题。

它将 AI 编程从“聊天式协作”升级为“工程化协作”模式。

三、Harness 的核心模块

一个生产级的 Harness 不一定一开始就非常复杂，但它通常会逐步发展出以下模块。

1. 任务编排：让 Agent 出主意，让 Harness 拿决定

许多系统之所以失败，是因为将过多的全局控制权交给了模型。

生产级的原则是：

Agent 负责局部智能，Harness 负责全局控制。

Agent 可以生成方案、分析代码、编写实现、进行审查，但 Harness 应掌握以下决策权：

• 任务生命周期管理：创建、分析、设计、开发、验证、交付、失败处理。
• 执行顺序控制：确定哪些步骤必须串行，哪些可以并行。
• Agent 路由：决定哪个任务交给需求分析 Agent，哪个任务交给代码审查 Agent。
• 失败处理策略：重试、回滚、降级、跳过或终止。
• 硬性限制：最大步骤数、最大工具调用次数、最大 Token 数、最大执行时长。

一个常见的流程是：

需求输入→ 需求拆分→ 风险审查→ 设计方案→ 方案门禁→ 编码执行→ 代码审查→ 测试验证→ 经验沉淀

在这个流程中，每一步都可以由 AI 参与，但能否进入下一步，应由 Harness 的门禁规则来决定。

2. 工具治理：工具不是函数，而是权限入口

Agent 的能力在很大程度上来源于工具。工具可以是读文件、写文件、Shell 命令、浏览器、数据库、内部 API、MCP Server 等。

工具治理的核心是 Tool Registry，即工具注册中心。

一个工具至少应该包含以下描述：

• 工具名称。
• 工具用途说明。
• 输入参数 schema。
• 输出结构定义。
• 允许调用的 Agent 列表。
• 风险等级评估。
• 超时时间和速率限制。
• 是否需要人工确认。
• 调用日志和审计策略。

高风险工具必须施加更严格的边界控制。例如：

• 删除文件操作需要人工确认。
• 写入数据库操作需要审批或使用沙箱环境。
• 外部网络请求需要进行脱敏检查。
• 执行 Shell 命令需要命令白名单或危险命令拦截机制。
• 修改配置文件需要额外的提示确认。

MCP 使得工具接入变得更加标准化，但也更容易导致“能力泛滥”。正确的做法不是将 MCP Server 直接暴露给 Agent，而是通过 Tool Registry 进行白名单、权限、配额和审计的管理。

3. 上下文治理：不是塞满，而是选准

上下文治理需要解决三个核心问题：

• 模型应该知道什么？
• 在什么时候知道？
• 以什么形式知道？

一个实用的分层方式是：

L1：每次都必须了解的核心规则
L2：特定场景才加载的规则
L3：按需检索的参考资料
L4：任务执行过程中产生的临时状态

例如：

• 每次都必须遵守的代码红线可以设置为 always apply。
• 提交规范只在提交场景下加载。
• API 文档只在涉及接口修改时加载。
• 历史事故经验只在相关模块被修改时加载。

这种方法可以显著降低 Token 成本，同时也能减少无关信息的干扰。

一个重要的经验是：上下文质量通常比上下文数量更为关键。过多的规则会让模型难以确定优先级，过长的历史记录会造成“中间遗忘”，而过多相互矛盾的文档则会让模型综合出错误的结论。

4. 状态与记忆：记住该记的，忘掉该忘的

状态和记忆容易混淆，但它们有所不同。

状态是当前任务运行所需的信息，例如当前步骤、已修改文件、测试结果、待解决问题等。它的生命周期较短，重点在于一致性。

记忆是跨任务复用的知识，例如用户偏好、团队规范、历史经验教训、某类问题的解决方案等。它的生命周期较长，重点在于相关性。

推荐拆分为以下结构：

Working State：当前步骤的临时上下文，任务结束后可丢弃。
Session State：一次会话内共享的状态，可以设置 TTL。
Execution Log：不可变的执行日志，用于审计、回放和评估。
Episodic Memory：事件记忆，记录踩坑经验和用户偏好。
Semantic Memory：语义记忆，记录业务规则和领域知识。

记忆系统还有一个反直觉但至关重要的机制：遗忘。

如果只新增不清理，记忆会变得越来越嘈杂。在实践中，可以按照访问频次、最近使用时间、重要性和可信度来计算保留分数：

• 高价值记忆保留原文。
• 中价值记忆压缩为摘要。
• 低价值或过期的记忆进行归档或删除。

记忆不是仓库，而是花园，需要持续修剪和打理。

5. 质量门禁：在成本最低的地方拦截错误

AI 编程最令人担忧的情况是错误一路流到代码审查甚至上线阶段。Harness 应该尽可能早地将错误拦截下来。

常见的门禁包括：

• 需求门禁：需求是否明确，验收标准是否完整。
• 设计门禁：方案是否覆盖了边界情况、依赖关系、风险和回滚策略。
• 开发门禁：任务拆分是否合理，目标文件是否明确。
• 工具门禁：是否调用了高风险工具，是否存在越权行为。
• 代码门禁：Lint、类型检查、单元测试、构建是否全部通过。
• 契约门禁：API、IDL、数据库 schema 是否兼容。
• 追溯门禁：代码变更是否能够追溯到具体的需求条目。

门禁应尽量实现机器可读，而不是仅凭“AI 口头说通过”。例如，测试结果、schema 校验、脚本输出、审查报告都应该落地存储，以便进行审计。

6. Trace 与可观测性：不要只看答案，要看过程

AI Agent 的错误常常不是最终的报错信息，而是过程中的偏差。

例如：

• 它调用了错误的工具，但最终结果看起来还行。
• 它读取了过期的文档，但表达得很自信。
• 它反复调用同一个工具，浪费了大量 Token。
• 它跳过了测试环节，却声称已经验证。
• 它在上下文压缩时丢失了关键的约束条件。

因此，Harness 必须记录完整的 Trace 信息：

• 用户的原始需求。
• 加载了哪些上下文。
• 生成了哪些计划。
• 调用了哪些工具。
• 工具的参数和返回结果是什么。
• 哪些门禁通过了，哪些失败了。
• 最终输出是如何生成的。

Trace 的价值不仅在于排查问题，还可以用于评估、回放、优化 Prompt、改进 Skill、训练团队规则。

7. 评估体系：从结果评估到轨迹评估

普通模型评估通常只看最终答案，但 Agent 系统还需要审视执行过程。

一个成熟的评估体系至少包含四个层次：

组件评估：单个 Agent 是否选对了工具、参数是否合规。
轨迹评估：步骤是否必要、顺序是否合理、是否存在重复调用。
任务评估：最终结果是否满足了用户的目标。
业务评估：用户是否采纳、返工率如何、单位成本是多少。

LLM-as-Judge 可以用于评估表达质量、逻辑完整性和开放式输出，但它不能替代确定性检查。代码能否运行、SQL 结果是否正确、权限是否合规、schema 是否匹配，这些应该优先使用程序来判断。

对于 AI 编程来说，Eval 就是测试体系。每次修改规则、更换模型、添加工具、调整 Skill，都应该运行回归评估。

8. 成本控制：Token Budget 是生命线

Multi-Agent 和长任务很容易消耗大量 Token。原因包括：

• 每个 Agent 都有自己的系统提示词。
• 每轮工具调用的结果都会进入上下文。
• 多 Agent 之间会复制部分历史记录。
• 失败后会自动重试。
• 长会话会积累大量无关信息。
• 如果规则和 Skill 设置为 always apply，会产生固定的成本。

Token 控制不应等到最后看账单，而应该融入调度层。

常见的策略包括：

• 简单任务使用小模型，复杂推理使用强模型。
• 简单的修改不需要加载完整的大型 Skill。
• 将规则分为核心规则和按需规则。
• 长对话达到一定阈值后进行 compact 压缩。
• 对工具输出进行摘要，避免将大段日志全部塞回模型。
• 流程型 Skill 尽量脚本化，减少模型的二次推理。
• 为任务设置 max tokens、max tool calls 和 max duration 限制。

一个简单但实用的原则是：昂贵模型用于关键判断，便宜模型用于低风险执行，确定性脚本用于可程序化的检查。

四、AI 编程工程实践：从个人到团队

1. 个人使用：从“让 AI 写”变成“让 AI 按轨道写”

个人使用 AI 编程时，可以先养成几个好习惯：

• 每次只专注于一个主题，避免在一个对话中混杂多个不同需求。
• 尽量使用 @文件:行号 来指定具体位置，减少 AI 的搜索成本。
• 明确说明现象、预期结果、限制条件和验收标准。
• 让 AI 先阅读现有代码，然后再进行修改。
• 让 AI 修改后运行实际的测试，而不是让其自我评价。
• 对于复杂任务，先让 AI 输出方案，待批准后再执行。
• 长会话要及时 compact 或开启新的会话。

一个优秀的 Bug 修复提示可以这样写：

@src/pages/Login.vue:86
现象：点击发送验证码后 loading 状态一直不恢复。
预期：请求成功、失败、提前返回这三种路径都必须恢复 loading 状态。
限制：不要重构整个登录流程，只修改验证码发送的相关逻辑。
验证：请运行相关的单元测试，并说明覆盖了哪些测试路径。

这样的提示同时提供了位置、现象、预期、边界和验证方法，AI 的输出差异性会明显降低。

2. 项目改造：让代码库更适合 AI 协作

很多项目并非 AI 写不好，而是项目本身不适合 AI 去理解和阅读。

适合 AI 协作的代码库通常具备以下特征：

• 规则是机器可读的。
• 命名是显式且可搜索的。
• 组件的入口是收敛的。
• 业务术语是统一的。
• 依赖关系是结构化的。
• 测试和门禁是可以自动运行的。
• 历史经验能够沉淀到仓库中。

以前端项目为例，可以进行如下改造：

openspec/rules/coding.mdc
style.mdcc
component-usage.mdc
src/components/ui/Button.tsx
Modal.tsx
src/themes/tokens/color.ts
spacing.ts
radius.ts

并通过 ESLint 规则禁止业务代码直接引用底层第三方组件：

业务代码只能从 src/components/ui 引入 Button，不能直接从 antd 引入。

这样一来，AI 就不会在多个“都能用”的路径之间随意选择了。

3. 团队实践：Knowledge as Code

团队级 Harness 的一个关键思想是 Knowledge as Code，即像管理代码一样管理知识。

这意味着：

• 规范写在仓库里，而不是只写在文档平台。
• 规则可以被代码审查。
• 需求、设计、任务、测试报告可以形成完整的追溯链条。
• 经验文件可以版本化管理并支持回滚。
• 不同的 AI 工具可以从同一份规范中生成各自的本地配置。

一个团队级的目录结构可能如下：

AGENTS.md
.codebuddy/skills/
agents/
commands/
hooks/
context/team/
harness-framework/
project/.service-matrix/dependencies.yaml
requirements/REQ-2026-001/requirement.md
design.md
tasks.json
review-report.md
delivery.md

这里的重点并非具体的目录名称，而是将流程、知识、门禁、经验和工具配置都转化为可维护的工程资产。

4. 多 Agent 分工：将复杂任务拆解给不同角色

对于复杂任务，不建议让一个 Agent 从头做到尾。更好的方式是进行角色分工。

常见的角色包括：

• Requirement Analyst：负责需求分析，识别目标和非目标。
• Planner：负责设计方案，拆分任务并识别风险。
• Reader：只读代码，收集上下文信息，不修改文件。
• Executor：按照方案执行代码修改。
• Reviewer：独立进行审查，不参与代码生成。
• Tester：运行测试并分析失败原因。
• Knowledge Curator：将新的经验沉淀到知识库中。

关键规则是：生成者和评估者必须隔离。让写代码的 Agent 自己评价代码，容易出现过度自信的问题。独立的 Reviewer 可以显著降低漏检率。

还有一条实践经验：所有需要用户确认的交互，应该由主流程来处理，子 Agent 只返回结果，不应直接卡住用户等待确认。否则容易出现多 Agent 死锁的情况。

5. 契约化开发：用领域模型减少猜测

在多端、多服务、复杂业务系统中，仅靠 AI 扫描代码是不够稳定的。更好的方式是将业务抽象为契约。

例如，多端前端项目可以定义四层领域模型：

pages.json：定义有哪些页面。
ui-modules.json：定义页面由哪些模块组成。
api-layer.json：定义接口和调用契约。
data-layer.json：定义核心数据结构。
glossary.json：统一业务术语。

通用契约描述“是什么”，项目映射描述“在哪里、怎么实现”。

{
"HomePage": {
"concept": "首页",
"web": "src/pages/index.tsx",
"tv": "src/pages/home.tsx",
"mobile": "src/pages/home/index.vue"
}
}

这样一来，AI 不需要在海量代码中猜测“首页在哪里”，也不需要猜测不同端的实现差异。

契约化的好处是：

• 新项目接入更快。
• 多端一致性更容易检查。
• AI 生成的代码更稳定。
• 测试和门禁可以基于契约自动生成。

6. Self-Refinement：让每次纠错都变成资产

AI 不具备天然的跨会话记忆能力。用户今天纠正了它，如果不进行沉淀，下一次它可能还会犯同样的错误。

Self-Refinement 的做法是建立一个闭环：

发现问题→ 分析原因→ 提炼规则或经验→ 写入 context/ 或 rules/→ 下一次任务自动加载或按需检索→ 避免重复犯错

例如，一次事故发现“所有分页接口必须设置上限”，就应该沉淀为经验：

context/project/order-service/experience/pagination-limit.md

内容包括：

• 问题背景。
• 触发条件。
• 错误的写法示例。
• 推荐的正确写法。
• 检查方式。
• 适用的模块范围。

这样，知识不再只存在于某次对话中，而是成为了团队共有的资产。

五、一个可落地的 Harness 建设路线图

不建议一开始就搭建一个庞大的平台。Harness 应该从小闭环开始，逐步增强。

Phase 1：个人和小团队起步

目标是让 AI 不再“凭感觉写代码”。

建议建设：

• 一个 AGENTS.md，清晰写明项目的基本规则。
• 一组核心规则文件，控制在少量高价值的规则上。
• 一个简单的从需求到代码的流程。
• 基础的验证命令，如 lint、type-check、test、build。
• 一个经验目录，用于沉淀常见的错误教训。

最低可用的流程：

读需求 → 搜代码 → 出方案 → 用户确认 → 修改代码 → 跑测试 → 总结经验

Phase 2：项目级工程化

目标是让 AI 能在真实项目中稳定交付。

建议建设：

• Skill：封装常见流程，如新功能开发、Bug 修复、提交代码、代码审查。
• Hooks：拦截危险命令、调试残留代码、大文件写入、配置修改等操作。
• 上下文分层：核心规则设为 always apply，场景规则按需加载。
• 质量门禁：在需求、设计、开发、测试各阶段都设置检查点。
• Trace：记录关键工具调用和验证结果。

此阶段的重点是将“口头约定”转变为“可执行的约束”。

Phase 3：团队级协作体系

目标是让 AI 成为团队工程流程的一部分。

建议建设：

• 统一的知识目录和规范仓库。
• 多 Agent 分工机制。
• 服务矩阵或领域模型。
• 跨仓、跨服务分支和追溯规则。
• 自动化评估体系和回归数据集。
• Token 成本看板。
• MCP 工具治理和审计机制。

此阶段的重点是实现团队规模化，不再依赖某个会使用 AI 的个人。

Phase 4：持续优化和自进化

目标是让 Harness 本身也可以被评估、迭代和回滚。

建议建设：

• Ground Truth 测试集。
• Dev/Holdout 分层评估机制。
• 每次修改规则或 Skill 都运行回归测试。
• 利用 Trace 诊断失败案例。
• 对规则、Prompt、Skill 进行版本化管理。
• 定期归档无效或过期的记忆。

这个阶段的思想类似于训练模型：你不再手工凭感觉调整 Skill，而是依靠数据、评估和门控来推动其迭代进化。

六、常见误区

误区 1：只要换更强模型就够了

强模型固然重要，但很多问题并非模型能力不足，而是上下文、工具边界和验证机制存在缺陷。

同一个模型，在不同的 Harness 下表现可能差异巨大。模型是发动机，而 Harness 则是方向盘、刹车、仪表盘和道路规则。

误区 2：规则越多越好

规则是有成本的。每条设为 always apply 的规则都会占用上下文空间，还可能与其他规则发生冲突。

好的规则应该：

• 来源于真实问题。
• 表达清晰明确。
• 可执行或可检查。
• 有明确的优先级。
• 能够按场景加载。

误区 3：让 AI 自己判断是否完成就行

AI 很容易过度自信。它可能没有运行测试，却声称“应该没问题”。

生产级流程应该将“声称完成”转变为“验证完成”。验证结果必须来自命令、测试、日志、截图、schema 校验或审查报告。

误区 4：把所有文档都塞给 AI

上下文并非越大越好。无关信息会稀释注意力，冲突文档会误导模型，过长的历史记录会增加成本并降低遵循率。

更好的方式是索引化、分层化、按需加载。

误区 5：AI 生成快，所以可以少做设计

AI 虽然加速了编码过程，但也加快了错误产生的速度。如果没有设计和门禁，错误会以更快的速度进入代码库。

越是复杂任务，越应该先让 AI 输出方案，并在编码前确认好边界。

误区 6：Harness 是大公司才需要的东西

小团队同样需要 Harness，只是其形态可以非常轻量。

一个 AGENTS.md 文件、几条高价值的规则、一个固定的开发流程、几个验证命令，就是最小的 Harness 雏形。

七、给工程团队的实践清单

1. 先做规则盘点

将团队反复纠正 AI 的问题列举出来，优先将它们沉淀为规则。

例如：

• 禁止直接引用底层 UI 库。
• 修改公共组件前必须分析其引用方。
• 异步 loading 状态必须覆盖成功、失败、提前返回等所有路径。
• 生成代码后必须运行指定的测试用例。
• 禁止在业务代码中硬编码调试开关。

2. 建立单一事实来源

确定哪些文件是规范的源头，避免规则散落各处。

例如：

AGENTS.md：全局协作规则。
context/team/：团队级规范。
context/project/：项目级知识。
rules/：AI 工具可加载的规则。
skills/：可复用的流程。

3. 把高频流程封装成 Skill

优先封装以下流程：

• Bug 修复。
• 新功能开发。
• 代码审查。
• 提交信息生成。
• 接口契约同步。
• 设计稿转代码。
• 需求拆分。
• 经验沉淀。

Skill 的价值不在于编写长提示词，而在于让流程稳定且可复用。

4. 加最少但关键的 Hooks

Hooks 适用于拦截那些“不能靠模型自觉”的问题。

推荐优先实现：

• 危险命令拦截。
• 调试残留代码检查。
• 大文件写入提醒。
• 配置文件修改确认。
• 公共组件影响面分析。
• 停止前自动提示运行质量检查。

5. 用评估数据驱动改进

不要仅凭感觉来判断 Harness 的好坏。

可以记录以下指标：

• 首次通过率。
• 返工次数。
• 平均 Token 消耗量。
• 平均工具调用次数。
• 测试失败的类型分布。
• 审查发现的问题数量。
• 重复问题复发率。

当你能看到这些指标时，AI 编程就从“玄学调参”进入了“工程优化”阶段。

结语：AI 编程的未来，是人掌舵，Agent 执行

AI 编程不会让软件工程消失，反而会进一步放大软件工程的重要性。

过去，工程师的价值很大程度上体现在“亲手写代码”上。如今，越来越多的代码可以由 AI 生成，工程师的价值正在向上游转移：

• 清晰地定义问题。
• 设计合理的系统架构。
• 提供可信赖的上下文信息。
• 设定工具的使用边界。
• 建立验证闭环。
• 判断关键的技术取舍。
• 将个人经验沉淀为系统能力。

这就是“Human Steer, Agents Execute”的理念：人类掌舵，Agent 执行。

Prompt Engineering 教会我们如何对 AI 表达意图。Context Engineering 教会我们如何为 AI 提供知识。而 Harness Engineering 则教会我们如何将 AI 融入真实的工程系统，使其稳定、可控、可审计、可演进地工作。

未来的竞争，不在于谁能让 AI 写出更多的代码，而在于谁能设计出更优秀的工程系统，让 AI 所写的代码更可靠、更经济、更易于维护。

没有 Harness，AI 编程只是一次次聪明的即兴表演。有了 Harness，AI 才能成为真正可持续的工程生产力。