AI 编程工程化：从 Prompt 到 Harness

本文从 Prompt、Context 到 Harness 的演进出发，讨论如何围绕模型构建规则、工具、记忆、验证和编排机制，让 AI 编程进入真实研发流程。

引言

AI 编程的瓶颈正在从"模型会不会写代码"，转向"工程系统能否让它稳定交付"。

本文从 Prompt、Context 到 Harness 的演进出发，讨论如何围绕模型构建规则、工具、记忆、验证和编排机制，让 AI 编程进入真实研发流程。

一、AI 编程瓶颈的转移：从模型能力到工程系统

1、AI 编程的瓶颈

随着模型能力的提升，AI 已能完成大量编码任务，但真实项目的目标不是生成代码，而是交付可用、可验证、风险可控的结果。

从常见项目失败现象看，AI 编程的瓶颈正在从「能不能写」，转向「工程系统能否满足三个条件」：

|------------|---------------------------------------------------------------|--------------------------------------------|
| 工程化条件 | AI 典型失败现象 | 工程系统缺口 |
| 上下文完整度 | • 按字面需求新增字段 / 状态 / 接口，容易写错字段口径和兼容规则 • 只改当前文件，遗漏调用方、下游消费者和历史约定 | • 缺少项目知识、历史决策和业务约定 • 缺少代码全貌，只能生成局部正确的代码 |
| 可验证性 | • 代码能编译，但边界条件、异常分支或幂等逻辑错误 • 单测全绿，但只验证 happy path，真实问题未暴露 | • 缺少编译、测试、静态分析、CI 等外部反馈 • 缺少失败信号回传后的自动修复回路 |
| 风险可控性 | • 并发扣减、状态流转、补偿任务等方案看似完整，但关键风险判断错误 • 错误进入后续开发或上线链路，放大成数据或线上事故 | • 高风险任务缺少人工确认点 • 缺少权限边界、回滚范围和分阶段验证 |

这三个条件共同决定 AI 编程能否从「生成代码」进入「工程交付」：上下文决定它能否理解正确问题，可验证性决定错误能否被及时发现，风险边界决定错误能否被限制在可回滚范围内。

因此，AI 编程的核心瓶颈不再只是「模型能力不足」，而是「工程系统能否补齐上下文、验证回路和风险边界」。

2、AI 编程业界演化：从 Prompt 到 Context 再到 Harness

AI 编程的工程化演进，不是 Prompt、Context、Harness 三个阶段相互替代，而是能力边界逐层外扩：先优化单次输入，再组织上下文，最后把模型放进可执行、可验证、可沉淀的运行系统。

这里的「演进」不是替代关系：Harness 不取代 Prompt 和 Context，而是把 Prompt、Context 纳入可执行、可验证、可沉淀的工程系统中。

|-------------------|--------------------|------------------------------------------------------|---------------------------------------------------------|
| 演化阶段 | 关注点 | 核心问题 | 代表实践 |
| Prompt 工程（早期重点） | 单次提示词的措辞与结构 | • 让模型「听懂」一次性任务 • 解决「说什么」，优化输入侧 | 少样本示例（Few-shot）、思维链（CoT）、推理+行动（ReAct） |
| Context 工程（当前重点） | 上下文窗口内的信息组织 | • 把正确的信息在合适的时机提供给模型 • 解决「看什么」，仍主要发生在输入侧 | 检索增强（RAG）、上下文压缩、长短期记忆 |
| Harness 工程（新增重点） | 模型周围的规则、工具、环境与运行逻辑 | • 把模型变成可托管、可验证、可演进的系统组件 • 解决「做什么、怎么验证、如何沉淀」，覆盖完整运行过程 | 技能包（Skill）、工具调用（Tool）、上下文协议（MCP）、验证回路、编排（Orchestration） |

三个阶段叠加后，AI 编程的行业重心正在发生三类变化：

|------------------------|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| 演化规律 | 行业趋势 | 对开发者的意义 |
| 工程作用域：从 Prompt 到模型周边全栈 | 【工程化外延至模型周边】 • 业界投入从「写 Prompt」扩展到 IDE 集成、自动测试、跨会话记忆和知识沉淀 • 主流工具竞争点已转向模型周边工程能力 | 【配齐周边能力优先于死磕 Prompt】 • 提升效率主要依赖 IDE 规则 / 记忆 / 验证 / 工具，而不是反复调 Prompt • 选型时应看工具覆盖多少编码环节；只支持 Prompt 优化的工具，天花板较低 |
| 优化重心：从输入侧到完整闭环 | 【闭环能力成主流标配】 • 主流编码 Agent 已开始标配自动测试、跨会话上下文和长任务拆步 • 标杆方案的差异在于能否自检自修、不丢上下文 | 【让 AI 自检 + 关键资产落盘】 • 自动运行测试 / 编译检查 / 静态代码检查，比手动回喂错误更高效 • 项目规约、踩坑历史和长任务进度应落盘，避免重复解释 |
| 模型角色：从主角到组件 | 【工程配置成为关键变量】 • 同一模型在不同上下文、工具和验证配置下，产出质量可能出现显著差异 • 模型之外的代码、工具和配置正在成为能力差距的重要来源 | 【打磨配置回报高于频繁换模型】 • 瓶颈不只在模型聪明度，也在 Rule / Skill / 工具配置 • 打磨规则、技能和工具配置，通常比频繁切换模型更可持续 |

这一演化说明，AI 编程的竞争点正在从「模型是否足够聪明」，转向「团队能否把模型放进稳定的工程系统」。这也是本文讨论 Harness 的起点。

二、Harness 是什么

本章先区分 LLM、Agent 与 Harness 的关系，再拆解 Harness 的六类组件，最后说明它在一次任务中的运行机制。

1、LLM、Agent 与 Harness 的关系

Harness 是支撑 AI Agent 稳定执行的工程化运行系统。它与 LLM、Agent 构成三层嵌套结构：

LLM 负责推理，Agent 负责行动，Harness 让行动可控、可验证、可沉淀。

三层关系可以压缩成一张表：

|-----------------|------------------------------------------|----------------|---------------------------------------|
| 层级 | 能力边界 | 解决的问题 | 能力缺口 |
| LLM 推理核心 | 理解、生成、判断和推理；但不直接读文件、执行命令、运行测试或保留跨会话状态 | 想什么、怎么判断 | 不能单独完成真实工程任务 |
| Agent 执行主体 | 在 LLM 外增加行动循环，可调用工具读写文件、搜索资料、运行命令和调用 API | 怎么行动 | 行动不天然可靠：可能上下文不足、破坏既有逻辑、缺少验证闭环或在长任务中漂移 |
| Harness 工程化运行系统 | 位于 Agent 外围，用规则、记忆、工具、编排、验证和沙箱托管执行过程 | 如何稳定、可控、可验证地行动 | 需要持续构建和演进，即 Harness Engineering |

Harness Engineering，就是构建并持续改进这套 Harness 的工程实践。它关注的不是单次 Prompt 优化，而是如何把规则、上下文、工具、记忆、编排和验证机制系统化，让 AI Agent 进入稳定、可复用的工程流程。

注：本文的 Harness 不是 Hermes Agent。

Hermes Agent 是 Nous Research 开源的自改进 AI Agent 项目，主打持久记忆、自动生成 Skills 和跨会话学习；
Harness 则是围绕 AI Agent 构建的工程化运行系统。两者只是拼写相近，概念层级不同。

2、Harness 六大组件

理解 Harness 六大组件，可以从 Agent 在真实工程中「已有能力但不够稳定」的环节倒推：输入需要更稳定，执行需要被托管，状态与反馈需要可沉淀、可回放。

对应到工程结构上，这六类组件可以归为三层：

输入约束层：约束 Agent 的输入、角色和行动边界，让输出更稳定。
执行处理层：提供工具、环境和编排能力，让 Agent 完成真实工程动作。
状态反馈层：沉淀上下文、进度和验证结果，让 Agent 持续修正。

|--------|--------------------------------------|---------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 归类 | Agent 的不足 | Harness 组件 | 实现方式 | 常见技术实现 |
| 输入约束层 | Agent 的行为容易受提示词和上下文波动影响，需要按稳定规则行动 | System Prompt | 将角色、边界、流程和禁区写入系统提示或项目规则，并随任务自动加载 | System Prompt、Cursor Rules、CLAUDE.md / AGENTS.md、Skill.md |
| 执行处理层 | Agent 需要依赖外部工具，才能稳定读写代码、执行命令和调用 API | Tool | 把读写文件、执行命令、调用 API 和检索资料封装成可控工具 | MCP Server、Function Calling、Shell Tool、OpenAPI Tool |
| | Agent 的执行环境不一定完整、隔离或可复现，需要安全环境承载 | Bundled Infra | 提供沙箱、文件系统、依赖、浏览器和网络环境，保证执行可复现 | Docker、Dev Container、Sandbox、Playwright Browser |
| | Agent 在长任务中容易规划漂移、重试失控或续接断层，需要托管执行过程 | Orchestration | 用任务拆解、步骤状态、重试策略和终止条件托管执行过程 | LangGraph、Temporal、状态机、任务队列 |
| 状态反馈层 | Agent 的跨步骤、跨会话状态容易丢失，需要持续保存和注入上下文 | Memory | 将项目约定、历史决策、踩坑记录和任务进度落盘，并按需注入上下文 | Markdown 知识库、向量库 / RAG、SQLite、Memory Store |
| | Agent 生成结果后缺少稳定验证信号，需要外部反馈驱动修正 | Hooks & Verification | 在关键节点自动跑测试、编译和静态检查，并把失败结果反馈给 Agent 修正 | Git Hooks、CI / GitHub Actions、mvn test、Checkstyle / SpotBugs |

这六类组件共同构成一条工程闭环：用规则稳定输入，用工具和环境托管执行，再用记忆与验证沉淀反馈。组件定义结构，运行机制说明协同方式。

3、Harness 的运行机制

Harness整体运行闭环

从运行过程看，Harness 围绕模型形成一条「行动前约束 → 执行中托管 → 行动后反馈」的闭环。

Feedforward（前馈）：在 Agent 行动前注入规则、上下文和边界，减少错误发生。
Feedback（反馈）：在 Agent 行动后收集测试、日志、截图和 Review 等信号，驱动模型修正，并沉淀回规则或记忆。

Harness运行机制图

Harness 整体运行分为五个环节：

Context Injection（上下文注入）：注入提示词、记忆、技能和对话上下文。
Control（控制）：负责压缩、编排和续接，约束模型行动过程。
Action（行动）：调用工具、命令和 MCP，完成外部动作。
Persist（持久化）：持久化文件、任务进度和 Git 状态。
Observe & Verify（观察和验证）：用浏览器截图、测试结果和日志观察输出，并把反馈带回模型修正。

三、业界主流解法：Harness 如何工程化落地

Harness 落地的关键，是把概念转成可执行、可验证、可复用的研发系统。下面按 OpenAI 案例、通用落地杠杆和厂商方案定位展开。

1、标杆案例：OpenAI Codex Harness 怎么做的

OpenAI Codex Harness 的关键，不是让 Codex 单次生成更多代码，而是把仓库、规则、工具、反馈和人类决策组织成适合 Agent 执行的研发系统：

仓库沉淀上下文，规则约束行动，工具承载执行，PR 反馈驱动修正，人类负责目标、验收和 Harness 改进。

OpenAI 公开披露的结果是：约 5 个月内，一个小团队通过 Codex 驱动约 1500 个 PR，产出约 100 万行代码。重点不是代码量，而是 Codex 被放进了可持续运行的工程闭环。

1.1、工程资产：把仓库改造成 Agent 的工作系统

OpenAI 先让仓库具备 Agent 可读、可执行、可接力 的基础条件。

|----------------|---------------------------------------|--------------------------|
| 仓库资产 | 具体做法 | 作用 |
| AGENTS.md | 作为 Agent 的入口地图，说明项目理解方式、行动规则和资料位置 | 降低 Agent 进入项目的理解成本 |
| docs/ | 沉淀设计文档、架构文档、领域边界、质量评估和核心工程原则 | 把项目知识变成稳定事实来源 |
| Execution plan | 把复杂任务拆成计划，并版本化进度、决策日志和已知技术债 | 支持长任务续接，减少上下文丢失 |
| 初始脚手架 | 由 Codex 参与生成仓库结构、CI 配置、格式化规则、包管理和应用框架 | 让 Agent 从一开始就在可执行工程环境中工作 |

上下文不能只留在聊天窗口里，必须沉淀成仓库资产。否则每次任务都要重新解释背景，长任务也难以续接。

1.2、执行约束：把工程规则变成机械检查

上下文只能让 Agent「知道背景」，不能保证它稳定遵守边界。OpenAI 的做法是把规则做成检查机制。

|--------------|-----------------------------|-----------------|
| 约束机制 | 检查对象 | 对 Agent 的意义 |
| 自定义 lint | 命名、文件大小、日志结构、schema、类型规范 | 把编码规范变成自动拦截 |
| 结构测试 | 模块边界、依赖方向、允许调用关系 | 防止架构被破坏 |
| CI 检查 | 文档、代码、架构规则的一致性 | 防止规则与实现脱节 |
| 可操作错误提示 | lint（静态代码检查）/ test 失败后的修复路径 | 把失败信号转成下一步上下文 |

关键点是：规则写在文档里只是提醒；规则进入 lint、测试和 CI，才会形成拦截与修正循环。

1.3、执行与反馈：把任务推进放进 PR 闭环

Codex 被接入真实研发工具链，可以获取上下文、执行动作、读取反馈。

|----------|----------------------------------|--------------------|
| 能力类型 | 具体工具 / 信号 | 作用 |
| 仓库操作 | gh 等命令行工具 | 处理 PR、review 和仓库操作 |
| 项目执行 | 本地脚本、仓库内置 skills | 执行项目内的标准任务 |
| 隔离环境 | 独立 worktree | 承载任务执行，避免不同任务互相污染 |
| 可观测性 | logs、metrics、traces、LogQL、PromQL | 观察运行结果，定位问题 |
| 审查反馈 | PR review feedback | 获取人类或 Agent 的审查意见 |

PR 在这里不是提交终点，而是反馈容器：

|--------------|--------------------------------------------|-------------------|
| PR 反馈循环 | 动作 | 目的 |
| 1. PR 创建 | Codex 根据任务修改代码并打开 PR | 把生成结果放入工程协作流程 |
| 2. 本地自检 | Codex review 自己的改动 | 先做自动自检 |
| 3. 审查反馈 | Agent review 和人类 review 给出反馈 | 补充机器与人的审查信号 |
| 4. 持续修正 | Codex 根据 CI、测试、日志、指标和 review feedback 修复问题 | 让失败信号驱动修复 |
| 5. 合并就绪 | PR 达到可合并状态 | 把结果推进到可验证、可审查、可交付 |

OpenAI 不假设 Codex 一次生成正确，而是用工具、环境、可观测性和 PR review，把结果推进到可合并状态。

1.4、人类角色：从写代码转向改进 Harness

OpenAI 案例中，人类没有退出工程过程，而是把重心上移到目标、验收和系统改进。

|-------------|----------------------------------------------|-------------------------|
| 人类角色变化 | 对应动作 | 意义 |
| 从直接写代码到设定目标 | 设定任务优先级，把用户反馈转成验收标准 | 让 Agent 先解决正确问题，并让结果可判断 |
| 从人工排查到业务验收 | 判断结果是否符合业务目标 | 把人力放在高价值判断上 |
| 从反复重试到系统改进 | 识别 Agent 卡住时缺少什么能力，并补回工具、文档、规则、测试或 guardrail | 把单次失败转成系统能力 |

2、从标杆案例到通用落地地图

主流方案可按五类能力缺口判断：上下文、规则、工具、验证和编排。这样才能从「知道有哪些工具」，转向「判断自己应该先补什么工程能力」。

2.1、从 OpenAI 案例抽象出的五个 Harness 杠杆

|-------------------|----------------|---------------------------------------|
| 工程问题 | Harness 杠杆 | 优先动作 |
| AI 经常误解项目背景 | 上下文沉淀 | 把架构、领域规则、历史决策和执行计划沉淀到仓库文档中 |
| AI 知道规则但执行不稳定 | 规则可执行化 | 把命名、模块边界、日志结构等规范变成 lint、结构测试和 CI 检查 |
| AI 只能生成代码，不能推进任务 | 工具链接入 | 接入命令行、本地脚本、Git、PR 工具、MCP Server 和内部系统 |
| AI 输出不可控，依赖人工肉眼检查 | 验证反馈闭环 | 接入单测、编译、静态检查、CI、PR review、日志和指标 |
| 长任务容易漂移、断档 | 状态与编排 | 用任务拆解、阶段验收、进度落盘和终止条件托管执行过程 |

这五个杠杆共同构成一条落地路径：先补稳定上下文，再补可执行约束，然后接入工具链，最后用验证和状态管理形成闭环。

2.2、业界常见 Harness 方案

|----------------|------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|---------------------------------------------------------------|
| Harness 杠杆 | 代表方案 | 方案切入点 | 适用前提与边界 |
| 上下文沉淀 | • OpenAI Codex Harness • Cursor、通义灵码 / Qoder、Trae / MarsCode | • 仓库入口：AGENTS.md / docs/ / Execution Plan • 编码现场：代码库索引、上下文注入、企业知识库 | • 适合已有项目文档、规则沉淀或代码库索引需求的团队 • 上下文多不等于上下文准，文档过期会直接污染输出 |
| 规则可执行化 | • 自定义 lint、结构测试、CI 检查 • Cursor Rules • 项目 Rules / Skills • Anthropic Agent Skills | • 把规范写入可检查机制：命名、模块边界、日志结构、schema • 把重复流程封装成规则、技能或交付模板 | • 适合已有工程规范和重复流程的团队 • 规则过细会增加维护成本 • Skill / Rule 过多可能产生冲突和过期知识 |
| 工具链接入 | • MCP 生态 • gh、内部 API • Playwright MCP • 数据库、监控、设计工具连接器 | • 用 MCP Server、Tool 接口和数据源连接器接入外部系统 • 让 Agent 调用 Git、浏览器、数据库、监控和内部服务 | • 适合需要接入多工具链的团队 • 效果取决于工具质量、权限边界和错误反馈质量 |
| 验证反馈闭环 | • Aider、通义灵码 TestAgent • CI、PR Review • OpenAI Codex Harness 的 PR / CI / Review feedback 闭环 • 日志、指标和可观测性工具 | • 本地循环：编辑 → 测试 → 失败修复 • 协作循环：PR → CI → Review → 日志 / 指标反馈 | • 适合已有测试、CI、Review 或可观测性基础的团队 • 验证信号不足时，自动修复会放大错误 |
| 状态与编排 | • Cognition Devin、Trae SOLO • Anthropic Managed Agents • Execution Plan、任务进度落盘 • 独立 worktree / 云端执行环境 | • 长任务拆解、阶段验收、后台执行和任务续接 • 用独立 worktree / 云端环境隔离执行过程 | • 适合任务边界清晰、验收标准明确、失败代价可控的工程任务 • 过早引入托管运行时会增加系统复杂度和平台绑定成本 |

选型时应先定位能力缺口：上下文、规则、工具、验证还是编排；再选择对应方案。OpenAI 展示的是完整闭环，其他方案通常补强其中一段。

四、经验借鉴

1、AI 编程任务可达性评估

使用 AI 前，先判断任务能不能交给 AI、能交给 AI 到哪一步。判断不清会带来两种浪费：

低估 AI，把简单 CRUD、单测补充、接口字段调整、PR 描述等任务继续由人手工完成；
高估 AI，把并发方案、上线策略、跨系统架构设计等高风险任务直接交给 AI，最后仍需要人工重做。

AI 编程任务可达性评估的目的，不是判断「AI 强不强」，而是判断： 在当前上下文、验证条件和风险边界下，这个任务适合让 AI 承担到什么程度。

可以从三个维度判断：

|------------|-----------------------|-----------------------------------|--------------------------------|
| 评估维度 | 核心问题 | AI 更适合处理的情况 | AI 不宜独立处理的情况 |
| 上下文完整度 | 任务所需信息是否能被 AI 获得？ | 需求、代码、接口、规则、历史文档、相似实现都能被检索或注入 | 依赖未成文经验、组织意图、客户偏好、历史踩坑、跨团队隐性约定 |
| 可验证性 | AI 做错后，错误能否被自动或低成本发现？ | 编译、单测、静态检查、接口测试、CI、Review 能给出明确反馈 | 错误需要线上运行数天后才暴露，或只能靠专家经验判断 |
| 风险可控性 | 如果判断错误，风险是否可控？ | 影响范围局限在 PR、测试失败或局部返工，回滚和修正成本低 | 可能造成数据不一致、资金损失、线上事故、组织信任损失 |

基于这三个维度，可以把 AI 编程任务分成三类：

|------------|-----------------------------------|-----------------------------------------|------------------------|
| 任务类型 | 典型任务 | AI 适合做到哪一步 | 人工介入重点 |
| AI 主导型 | 样板代码、字段映射、简单 CRUD、单测补充、文档摘要、PR 描述 | AI 可以主导完成，并通过编译、测试或 Review 验证结果 | 确认项目风格、业务口径和边界条件是否符合预期 |
| 人机协作型 | 局部功能开发、接口改造、已有模式下的新逻辑实现、复杂测试补充 | AI 负责分析、初稿、代码实现和自测，人按阶段验收 | 确认业务逻辑、兼容性、影响范围和关键分支 |
| 人主导型 | 复杂状态机、并发一致性、跨系统链路、灰度回滚方案、高风险上线决策 | AI 只作为辅助，负责整理信息、列风险、补 checklist 和生成方案草稿 | 人负责核心判断、风险取舍、方案决策和最终验收 |

不同任务对应不同协作深度：能自动验证、风险可控的任务，可以更多交给 AI；需要经验判断的任务，应采用人机协作；风险较高或验证滞后的任务，必须保留人工主导。

2、落地实现：分层验证与观察

引入方式应按风险、耦合度和验证成本划分：低风险、非强制、可回退的能力可直接试用；依赖工具链、权限或验证回路的能力先做试点；高自治能力保持观察。

|------------|-----------------------------|---------------------------------------------------|-------------------------------|
| 引入方式 | 判断标准 | 适合参考的能力 | 观察重点 |
| 可直接试用 | 低风险、低耦合、容易回退，不改变现有研发主流程 | 低风险的 Rules / Skills、阶段产出落盘、AI 自审清单、PR 描述生成、测试报告总结 | 输出是否稳定、是否减少重复劳动、是否容易回退 |
| 需要试点验证 | 收益可能较高，但依赖工具链、权限、上下文质量或验证回路 | Playwright MCP、内部知识检索、自动补测试、编译 / 单测自动修复、长任务续接 | 上下文是否准确、失败信号是否明确、AI 是否能根据反馈收敛 |
| 持续观察 | 自动化程度高，但风险、成本或组织影响暂时不可控 | 全自主 PR、本地自治执行、托管式 Managed Agents、多 Agent 自动协作 | 任务边界、验证回路、权限治理和失败影响是否可控 |

五、实践：把 Harness 落实到服务开发流程中

以下实践基于 Cursor 工具展开，以 Java 后端服务开发为例，说明如何用 Rules、Skills 和 MCP 搭建一套轻量 Harness。改造思路不替代原有研发流程，而是把 AI 嵌入需求、设计、编码、测试和 Review。

1、场景与改造目标

改造目标可以概括为三点：

让 AI 在每个研发阶段都有明确输入和输出；
沉淀阶段产物，避免每次重新解释上下文；
保留人工确认点，让 AI 负责整理、生成、验证和补充。

2、从研发流程到 Harness 支撑机制

下面按真实研发流程拆解 Harness 如何介入。

|-----------------|------------------------|-----------------------------|-----------|
| 阶段 | AI 主要承担 | 人主要负责 | 沉淀产物 |
| 需求分析 | 抓取需求、整理功能点、识别影响范围、列出疑问 | 确认业务理解，补充隐性约束和历史上下文 | 需求分析摘要 |
| 方案设计 | 生成方案骨架、参考已有实现、列出风险点 | 判断并发、一致性、上线策略等关键方案 | 方案设计文档 |
| 开发编码 | 按方案分步编码，执行编译检查和局部修复 | 按步骤 Review 关键逻辑，必要时直接改写复杂部分 | 编码进度记录 |
| 自测验证 | 补充测试、执行验证、根据失败信号修复 | 补充业务边界场景，确认测试覆盖是否合理 | 测试报告 |
| Code Review | 结构化自审，按严重程度输出风险分级 | 判断是否修改、提交和合并 | Review 报告 |

这张表的核心不是增加流程，而是把原本隐性的研发动作显性化：需求阶段沉淀业务理解，设计阶段沉淀方案和风险，编码阶段沉淀进度，测试阶段沉淀验证结果，Review 阶段沉淀风险判断。

|----------------|------------------------------|------------------------|
| 类型 | 适合交给 AI 的部分 | 仍需人主导的部分 |
| 需求与设计 | 需求摘要、影响范围初筛、方案骨架、风险点整理 | 业务目标判断、隐性约束补充、关键技术方案选择 |
| 编码与测试 | 样板代码、字段映射、局部功能实现、单测补充、失败日志修复 | 复杂状态机、并发一致性、跨系统影响判断 |
| Review 与交付 | Review 清单、风险分级、PR 描述、测试报告总结 | 上线策略、回滚方案、高风险变更决策 |

适用前提：项目有稳定代码结构、可运行的编译 / 测试 / 静态检查基础，需求和历史知识可检索，团队愿意沉淀流程和阶段产物。

3、落地配置与维护边界

落地时先区分「项目事实来源」「AI 行动规则」和「本地运行配置」。不同资产放在不同位置，避免把所有内容都塞进提示词或业务仓库。

|----------------------|----------------------------|------------------------------|
| 资产类型 | 放置位置 | 作用 |
| 项目知识、架构说明、历史决策 | 业务仓库 docs/ 或团队 wiki | 作为事实来源，供 AI 检索和引用 |
| 编码规范、流程入口、知识检索路径 | Rule | 控制 AI 如何工作、按什么顺序工作、去哪里找资料 |
| 阶段化工作流 | Skill | 复用需求分析、方案设计、编码、测试和 Review 流程 |
| 通用 Rules / Skills 模板 | 独立 prompt 仓库 | 统一维护、版本管理和分发 |
| 本地 Cursor 配置 | 本地 .cursor/ 目录，通常不提交业务仓库 | 作为个人或团队本地运行入口 |

这种分工的价值是：项目知识进入业务仓库或 Wiki，通用 Rules / Skills 独立维护，再分发到具体项目的 .cursor/ 目录中。

3.1、Rules 与 Skills 模板：从思路到落地

这套实践的核心不是直接贴完整提示词，而是把稳定约束做成 Rule，把阶段流程做成 Skill。正文只保留设计思路和目录结构，完整模板放到文末获取。

配套模板可以拆成两类：Rule 负责「什么时候加载什么」，Skill 负责「某个阶段具体怎么做」。

|--------|---------------------------------------------------------------------------------|-----------------------------------------------|
| 类型 | 文件 / 目录 | 核心职责 |
| Rule | develop-pipeline.mdc | 作为统一入口，识别当前研发阶段，并加载对应 Skill |
| | project-knowledge-sources.mdc | 定义项目知识源读取顺序，如需求文档、架构文档、历史方案和代码实现 |
| Skill | requirement-analysis、solution-design 、 coding 、 testing 、 code-review | 沉淀需求分析、方案设计、编码、自测和 Review 各阶段的执行步骤、输出格式和人工确认点 |

模板设计保留三条原则：

先判断阶段：让 AI 先识别当前处于需求分析、方案设计、编码实现、自测验证还是 Code Review，再进入对应流程。
再读取上下文：优先读取需求文档、项目文档、历史方案、相似代码、测试结果，以及公司 Confluence / Wiki 中沉淀的技术文档，避免脱离项目背景直接生成。
最后输出阶段产物：每个阶段都要沉淀明确结果；涉及并发一致性、数据修复、上线回滚等高风险判断时，必须列为人工确认事项。

如果要在项目中复用这套结构，可以在目标项目的 .cursor/ 目录下放置 rules 和 skills：

.cursor/ 目录建议加入项目的 .gitignore，避免把个人或团队本地配置直接提交到业务仓库。通用 Rules / Skills 可以放在独立模板仓库中统一维护，再分发到具体项目。

使用时，在 Cursor 对话框中输入 @develop-pipeline.mdc（会自动补全），然后描述任务，例如：

复制代码

@develop-pipeline.mdc 新需求，需求文档地址：https://jira.xxx.com/browse/PROJ-1234

@develop-pipeline.mdc 继续方案设计

AI 会先识别当前阶段，再加载对应 Skill 执行。这样可以避免每次重新解释流程，也能让阶段产物持续沉淀。

本文示例中的 Rules / Skills 可以整理成配套模板包，作为资料获取：

获取方式：发送邮件到editor@51cto.com，回复「Harness」
使用建议：模板只作为工程化实践参考，使用前应根据团队代码规范、项目知识源和研发流程做二次调整

3.2、Playwright MCP 配置

Playwright 是一个浏览器自动化工具，在这里主要用于补充 Cursor 读取文档上下文的能力：

AI 根据当前任务自行生成关键词；
通过 Playwright MCP 操作公司 Confluence 的搜索框，检索产品需求和技术文档；
读取到的是文档上下文，代码上下文仍由 Cursor 直接读取本地代码库。

另一种常见做法是公司用 Dify 沉淀知识库，再开放给 Cursor 访问。

复制代码

{
  "playwright": {
    "command": "npx",
    "args": [
      "@playwright/mcp@latest",
      "--browser=chrome",
      "--output-dir=D:/data/logs",
      "--user-data-dir=C:/Users/chench/.playwright-mcp-profile"
    ]
  }
}

3.3、Rule 与 Skill 的选择原则

|-----------|---------------------------|------------------------------------------|--------------------------------------------------------|
| 类型 | 适合的内容 | 加载方式 | 示例 |
| Rule | 编码规范、知识源路径、流程入口、始终生效的行为准则 | alwaysApply 每次对话注入，或 globs 编辑匹配文件时注入 | project-knowledge-sources.mdc、develop-pipeline.mdc |
| Skill | 多步骤工作流、有明确触发条件的阶段流程 | 按需加载，AI 判断相关时才读取 | coding、testing |

Rule 写作原则：

写流程，不写复杂判断：Rule 主要承载流程约束、加载方式和输出格式，不承载复杂技术判断。
指向知识源，不替代知识源：具体架构知识、领域规则和历史决策应放在 docs 或 Wiki 中，由 Rule 指引 AI 检索和使用。
越短越好：过多指令相互干扰会让 AI 顾此失彼；具体知识让 AI 自己在代码库与 Wiki 中检索。

六、总结

AI 编程的长期竞争点不是单次 Prompt，而是围绕模型建设 Harness：沉淀上下文、机械化规则、接入验证信号、保存任务状态，并把人工判断放在关键节点。

Harness Engineering 能提升 AI 编程稳定性，但不能消除所有工程风险：

|----------------------------|----------------------------------------------|--------------------------------|
| 开放问题 | 原因 | 应对方式 |
| 跨服务架构设计仍需人主导 | 组织边界、历史债务、上线窗口、数据一致性和灰度策略难以完整写进上下文，也难以通过单测验证 | AI 负责信息整理、风险枚举和方案草稿，人负责最终架构判断 |
| Rules 与 Skills 会产生维护成本 | 规则和技能增多后，可能出现冲突、边界重叠、旧知识污染和执行链路变长 | 建立版本管理、适用范围、更新机制和淘汰机制 |
| Harness 可能复杂度反噬 | 过早引入复杂编排、多 Agent、托管运行时和重型平台，可能让维护成本超过收益 | 只在能减少重复劳动、提升稳定性、降低定位成本时继续增加复杂度 |

模型提供基础能力，Harness 决定这些能力能否稳定进入工程交付。

Prompt → Context → Harness 的本质变化是：AI 编程不再只是提示词技巧，而是一项围绕模型构建工程系统的长期能力。

附录：参考资料

The Anatomy of an Agent Harness --- LangChain / Vivek Trivedy：建立 Harness 的基本概念、组件边界和系统视角，避免把 Harness 误解成单个工具或提示词技巧。
Harness engineering for coding agent users --- Martin Fowler：从软件工程视角理解 Harness：重点不是模型本身，而是围绕模型建立前馈、反馈和约束系统。
Harness Engineering: Leveraging Codex in an Agent-First World --- OpenAI：最完整的工程案例，展示 Harness 如何落到仓库、文档、规则、CI、PR 和 Review 流程中。
Writing effective tools for AI agents --- Anthropic：适合理解 Tool / MCP 的设计原则：好工具要给 Agent 清晰输入、可操作反馈和稳定失败信号。
Building Effective Agents --- Anthropic：帮助形成落地克制：优先选择简单、可验证、可组合的流程，而不是一开始追求复杂编排和全自动。