从Prompt工程 到 Harness 工程的实践

1提示词工程-Prompt Engineering提示词工程的本质很直接——怎么说决定了 AI 怎么做。LLM 是接龙式生成上下文决定输出方向。你描述得越清楚它的结果越准确。 三段式起步角色你是一个专精 [领域] 的高级工程师 任务帮我完成 [具体描述] 约束 - 需要兼容 [具体场景] - 不要使用 [某技术/某库] 拆分任务别让 AI 做超纲大题把复杂任务拆成几步设计数据模型 → 写接口定义 → 实现业务逻辑 → 写单元测试。每一步都给它上一步的输出作为参考。 Few-shot给例子比讲规则高效直接给输入输出示例AI 照着格式来比写一大段输出格式要包含 code、msg、data 字段...高效得多。有了提示词工程的指导就可以为每一个 Agent 配置一套专属的角色来实现一些复杂的逻辑。也可以参考 Anthropic 这篇文章来自己手搓一个多智能框架。2上下文工程-Context Engineering提示词工程解决了怎么说但还有一个问题——信息太多也是一种灾难。很多人觉得多给 AI 信息总是好的于是把项目所有文档都塞进上下文。但 Anthropic 这篇文章指出了一个事实LLM 有注意力预算限制上下文越长模型准确回忆信息的能力越差——这叫Context Rot上下文腐败。所以上下文工程的本质不是做加法而是做减法——找到最小的有效token集合最大化期望结果的可能性。但是到了2026 年大清已经亡了114年了。市面上已经有非常多成熟的 AI Coding 工具——Cursor、Claude Code、开源社区的 Continue...咱们公司内部也有 CodeFlicker 和 Takumi。这些工具都非常的好用本身已经很强大了。这里想聊的上下文工程不是让你手搓一个 AI Coding 工具而是告诉你怎么更好地用好这些工具。工具有了缺的只是你给它一份好的项目说明书。来看几个主流工具的上下文工程实践️ Claude Code 的上下文工程Claude Code 使用 CLAUDE.md 作为上下文配置文件有几个实用的设计 1. 分层加载避免重复配置 Claude Code 支持三层配置逐层覆盖 用户级~/.claude/CLAUDE.md你的个人偏好比如总是用 pnpm 而不是 npm 项目级项目根目录 CLAUDE.md团队共享的项目规范比如技术栈、代码风格 本地级.local.md本地特殊配置比如本地数据库端口、开发环境的特殊路径 举个例子用户级配置了我用中文对话项目级配置了这个项目用 Java本地级配置了本地 MySQL 端口是 3307——三层叠加各不干扰。 2. Skills把高频知识打包成模块 Skills 是 Claude Code 独特的机制把高频使用的知识打包成可复用的模块 .claude/skills/api-testing/ ├── SKILL.md # 概述用于 REST API 的集成测试 ├── REST-PATTERNS.md # 最佳实践认证、错误处理、分页 └── scripts/ └── run-api-tests.sh # 自动化脚本 当你让 Claude 写 API 测试时它会自动激活 api-testing 这个 Skill看到对应的规范和脚本。再比如你可以创建一个 sql-review Skill封装团队的数据查询规范。 3. 子代理复杂任务的解药 当任务太复杂时上下文窗口会变得拥挤。Claude Code 支持用子代理处理子任务 主代理负责规划和协调给子代理分配具体任务 每个子代理在独立上下文运行互不干扰 子代理完成后返回摘要通常 1000-2000 token主代理整合结果 举个例子重构一个大模块时可以让子代理 A 处理数据模型、子代理 B 处理业务逻辑、子代理 C 写单元测试最后主代理汇总。 建议第一次使用 Claude Code 时执行 /init 命令它会引导你创建一份基础的 CLAUDE.md包含项目基本信息、技术栈、目录结构等。⌨️ Cursor 的上下文工程Cursor 已经从单文件 .cursorrules 演进到 .cursor/rules/*.mdc 多文件规则系统更灵活、更细粒度。 1. .mdc 文件格式规则也有元数据 每个 .mdc 文件头部有 YAML 格式的 frontmatter控制规则的激活条件 --- description: API 错误响应格式规范 alwaysApply: false globs: app/api/**/*.java --- # API 错误响应规范 所有 API 错误响应必须符合以下结构... ## 规则 - 永远不要返回原始异常堆栈给客户端 - 使用统一的 ErrorResponse 类 - HTTP 状态码按以下映射... 这里的 description 是规则说明alwaysApply: false 表示只有被引用时才生效globs 指定只在 app/api/**/*.java 下生效。 2. 作用域控制不同规则管不同文件 你可以把规则拆分成多个文件精准控制生效范围 .cursor/rules/ ├── project-context.mdc # 始终生效alwaysApply: true项目概述 ├── java-style.mdc # glob: **/*.javaJava 代码规范 ├── api-rules.mdc # glob: app/api/**API 开发规范 ├── test-rules.mdc # glob: **/test/**测试规范 └── react-components.mdc # glob: frontend/components/**React 组件规范 当你编辑 app/api/UserController.java 时Cursor 会自动加载 project-context.mdc、java-style.mdc 和 api-rules.mdc——不需要手动指定。 3. 规则 vs 文档各司其职 Cursor 的 .mdc 是规则docs/ 下的 Markdown 是文档两者职责不同 类型 放什么 怎么写 .mdc 规则 AI 必须遵守的约束 命令式必须使用、禁止 docs/ 文档 需要理解的背景 描述式这个模块使用...、原因是... 举个例子 规则禁止使用 SELECT *必须明确列出字段 文档支付模块使用 Stripe主要流程是创建 PaymentIntent → 客户端确认 → 回调通知... 4. 实践建议从简单开始 不要一开始就写一堆规则。只有当 Cursor 反复犯同一个错误时才添加对应规则。比如 Cursor 总是忘记加 DataSourceRouting → 加一条规则 Cursor 不知道我们用 ResultView 返回 → 加一条规则 Cursor 不了解业务背景 → 在 docs/ 下加文档而不是规则举个例子我的一个项目里的.md给大家抛砖引玉一下。这些都是 AI 猜不到、但又高频需要的高信号信息。少而精比多而杂有效得多。项目定位素材中台 爬山虎广告平台两个业务系统的边界 数据流向从素材到广告创意的完整链路图 ▼ ▼ yunfan_import_material 站内高热素材表 云帆素材代理-Excel导入 快手站内视频高热素材 │ │ └───────────────┬───────────────┘ │ ▼ final_pic / final_video最终素材 │ ▼ffmpeg 规格加工裁剪、拼接等 creative_pic / creative_video广告创意 │ ▼AdPortalService 上传 creative_mapping映射表──► dynamic_creative爬山虎动态创意 │ ▼ 广告投放系统 核心表关系不是所有表只列出关键表和关联逻辑如 creative_mapping 决定关联哪张表 编码规范线程池loading cache大表必须用 CursorIterator等等如果需要同时用多种开发工具也可以维护一份 AGENTS.md主流的工具都默认支持 Cursor、GitHub Copilot、Claude Code 等。其实就是用规则文件控制行为Markdown 文档提供背景。不要在规则里塞大量描述性内容也不要在文档里写命令式语句就行。核心始终是给它一张精简的地图它反而能走得更远。其实到这里已经足够应付一些常规的需求了。可以开开心心 vibe coding 了。只要上下文工程做的好即使基础模型没升级也能让性能大幅提升 同一个模型换个环境十倍差距LangChain 在 Terminal Bench 2.0 测试里没动模型只是优化了 Agent 的工作环境——改了文档结构、加了验证回路、接入了追踪系统。排名从第 30 跳到第 5得分从 52.8% 到 66.5%。 安全研究员 Can Boluk 做了个更极端的实验。他只改了 Agent 编辑代码的格式Grok Code Fast 1 的得分从 6.7% 飙到 68.3%。同一个模型换个输出格式十倍差距。 OpenAI 的报告更直接7 个工程师5 个月交付了 100 万行生产级代码。规则是——不许写一行代码全靠 Codex Agent。目前的局限在一些复杂的工程项目里很少有从 0 到 1 的。绝大部分同学维护的是祖传代码——几十号人迭代了多年各有各的风格和写法。一个代码库里十几个 component真严格按照上下文工程做的话先不说编写的成本可能每个 component 都会有自己的 CLAUDE.md、AGENTS.md、PROJECT_CONTEXT.md...加起来可能占了 50% 的上下文。同时团队又沉淀了十几个 Skills——接口开发 Skill、SQL 规范 Skill、代码审查 Skill、测试 Skill...每个 Skill 又是几百行。加上这些 Skills又占了剩下的 50%然后就发现上下文满了一行代码都写不了了。这可怎么办其实这就是下个话题驾驭工程-Harness Engineering 要解决的问题如何更好地管理和使用这些 Skills 和md而不是一味地往上下文里塞东西。3驾驭工程-Harness Engineering说实话第一次看openai的文章标题时是懵逼的Harness engineering: leveraging Codex in an agent-first world。上次看到harness这个词的时候还是在搓塞尔达他怎么就和AI扯上关系了。仔细读了几遍发现其实非常好的总结了我们在实际复杂项目中一直在做的事搭建一套让 Agent 可靠工作的基础设施。不是教它做事Prompt不是给它教材Context而是给它顺手的工具、验证回路、和可控的环境。核心理念Humans steer. Agents execute.人类掌舵Agent 执行。想了半天感觉叫驾驭工程比较信达雅一些吧。openai的文章中有几个关键实践也和大家一起分享一下 让 Agent 能观测和验证OpenAI 早期进度比预期慢不是因为 Agent 能力不足而是环境描述不足。解决方案是让 Agent 能够观测和验证 集成日志和监控系统Agent 可以查日志、指标、追踪 让 Agent 能够启动和驱动应用实例验证修复是否有效 确保服务启动在 800ms 内完成 成为可执行的任务 一句话Agent 看不到的 不存在。给它可观测性它才能真正验证自己的输出。 知识管理AGENTS.md 是目录不是百科全书OpenAI 踩过的坑巨大的 AGENTS.md1000 页反而导致上下文稀缺、过度引导、快速过时。 正确的做法 AGENTS.md目录Table of Contents约 100 行告诉你去哪找 docs/系统的事实来源System of Recorddesign-docs/、product-specs/、references/ 机械强制用 linter CI 验证文档时效性防止过时⚙️ 架构强制让 AI 遵守边界OpenAI 采用了分层领域架构强制约束 Types → Config → Repo → Service → Runtime → UI 跨域关注点auth、connectors、telemetry必须通过单一接口 Providers 引入 用 linter 验证依赖方向防止 Agent 写出违反架构的代码。一个好架构不只是给人看的也要给 Agent 看。我们其实也不需要真的像Openai文章里写的这样完全再手搓一遍。开源社区有一些不错的工具值得参考他们可以极大地提高我们驾驭复杂项目的效率。好用的开源工具框架使用场景一些特性superpowers需要严格工程纪律的团队子智能体驱动开发、两阶段审查、强制 TDD、Git Worktree 隔离oh-my-claudecode大型项目需要角色分工专业智能体角色、监督者协调、结构化工作流agent-scripts需要可复用脚本和跨仓库同步的团队Pointer-Style AGENTS、浏览器工具、提交助手、文档列表器agent-zero快速启动轻量级治理四大规则、Memory Bank、零配置启动体验下来感觉superpowers的设计比较符合我的个人口味有很强的指令遵循设计也和大家分享一下 Superpowers强制工作流的 Skills 框架比如说这个工程有10多个模块是一个迭代了多年的广告创意相关的业务相对有点复杂我们让他设计一个创意审核的quota分配功能。直接跑的话会这样移除了部分内容方便展示原生claude code v2.1.81⏺ 这是一个需要规划的功能实现任务。让我先进入计划模式探索代码库了解现有架构和模式。 ⏺ 我已经了解了项目的整体架构和现有代码我需要进一步了解你的具体需求 xxx ⏺ 需求已经明确 - 租户维度: 按业务类型划分 - 配额限制: 日级送审数量 - 超限处理: 直接拒绝 让我启动一个Plan agent来设计实现方案。 ⏺ 计划已完成。 创意审核Quota分配功能实现计划 实现方案 1. 数据库表设计 xxx 2. 配置存储 (Kconf) xxx 3. 核心类设计 3.1 枚举类 3.2 配额控制服务 (参考 CreateQuotaControlService) 3.3 配置管理服务 3.4 数据模型 3.5 DAO层 3.6 API Controller 4. 审核流程集成 修改 /component/dsp/service/impl/DspCreativeAuditServiceImpl.java: 1. 在 sendAuditByBizType 方法开头添加配额检查 2. 送审成功后调用 increaseQuota 增加使用量 5. 需要修改的现有文件 6. 实现步骤 │ 1 │ 创建数据模型类 │ 2 │ 创建枚举类 │ 3 │ 创建DAO │ 4 │ 创建核心配额服务 │ 5 │ 添加Kconf配置 │ 6 │ 创建配置管理服务 │ 7 │ 创建API Controller │ 8 │ 集成到审核流程 │ 9 │ 创建数据库表 7. 验证方案 xxx其实猛地一看还挺像那么回事借鉴了现有的代码逻辑公司内部的kconf之类的中间件也能很好利用。并且claude code自带的plan mode也很好的和你互动明确需求最后完成了整体的设计以及测试方案。但是真这么简单就不叫祖传代码了。审核链路根本不走他说的DspCreativeAuditService这个流程这是一个早就废弃的链路大概率他用这里做入口是因为这个服务叫创意审核服务。而实际审核的流转是完全依赖一个binlog resolver监听material_info表的几个字段流转完成的而这个表看起来和创意审核毫不相关。安装superpowers插件安装之后会发现claude code里多了一堆skills已经自动配置好开箱即用。这是和他交互的过程⏺ 我来使用brainstorming skill帮你梳理这个创意审核quota分配功能的需求。 ⏺ Skill(superpowers:brainstorming) ⏺ 我来帮你设计这个创意审核的quota分配功能。首先让我探索一下项目上下文了解现有的审核流程。 ⏺ 我已经理解审核流程链路。这是一个复杂的审核系统包含 - 初审 → 复审 → 质量审 → 业务审 的多阶段流程 - 支持免审、人审、机审、AI审等多种审核类型 - 通过binlog监听触发审核流程 在进一步探索之前我需要先理解你说的 创意审核的quota分配功能 具体是什么意思。 ⏺ 好的现在我理解了 - 配额维度按二级策略池 - 周期每天固定配额 - 超限处理直接拒绝 ⏺ 这个 CreativeStrategy 看起来是一个关联创意和策略的表。让我搜索一下二级策略池相关的字段或概念。 ⏺ 我看到 DynamicCreative 模型中没有直接包含 subStrategyId。让我看看 MaterialInfo 模型因为审核是基于素材的。 ⏺ 我在 MaterialInfo 和 DynamicCreative 模型中没有找到二级策略池相关的字段。让我直接问您。 ⏺ User answered Claudes questions: ⎿ · 二级策略池ID具体存在哪个字段或者叫什么名字 → CreativeStrategy表关联 ⏺ 明白了二级策略池ID是通过 CreativeStrategy 表的 strategyId 字段关联查询得到的。关系链是 MaterialInfo → creativeId → DynamicCreative → CreativeStrategy → strategyId 让我继续了解配额的存储和配置方式。 ⏺ 很好现在我对需求有了清晰的了解 xxx ⏺ 让我现在提出设计方案。基于现有模式我有几种实现方式。 xxx ⏺ User answered Claudes questions: xxx ⏺ 现在我已经收集了足够的信息让我提出设计方案。 xxx ⏺ User answered Claudes questions: ⎿ · 以上设计方案是否符合你的预期 → 确认继续 ⏺ 好的让我更新任务状态并开始写设计文档。然后调用 writing计划技能。。 ⏺ Write(docs/superpowers/specs/2026-03-24-audit-quota-allocation-design.md) ⏺ Skill(superpowers:writing-plans) ⎿ Successfully loaded skill ⏺ 我正在使用 writing-plans skill 创建实现计划。 Skill(superpowers:writing-plans) ⎿ Successfully loaded skill ⏺ 我正在使用 writing-plans skill 创建实现计划。 首先让我确认设计文档的位置并创建实现计划。 ⏺ Write(docs/superpowers/plans/2026-03-24-audit-quota-allocation.md) xxxx Ready to execute?在我完全没有提示的前提下他自己头脑风暴理解了项目的内容准确找到了”通过binlog监听触发审核流程“。更神奇的是他竟然能问出来我在 MaterialInfo 和 DynamicCreative 模型中没有找到二级策略池相关的字段。让我直接问您。他真的能问出来业务实际使用的问题并且在对话的过程中他其实也在执行子任务做规划非常神奇。最后也会逐步和你沟通确认生成技术设计文档和实现计划文档简直是喂饭喂到嘴里。仔细观察就会发现他最后写完文档会释放掉一些上下文的空间。然后阅读他刚写的这两个文档最后生成完整的子任务列表清单再一个一个实现过程中对上下文长度的把控非常好一直维持在40%-60%之间结合上面的例子我们其实不难发现superpowers的这种工作方式非常契合Harness Engineering的思想在他的加持下我们可以真的用AI实现一些现实中复杂的业务需求他是强制工作流而不是建议工作流。Agent 不会一上来就写代码而是按这个流程来1️⃣ brainstorming写代码前先讨论设计AI 会展示方案给你确认你点头才开始2️⃣ writing-plans把任务拆成 2-5 分钟的小任务每个有精确的文件路径和验证步骤3️⃣ test-driven-development强制 RED-GREEN-REFACTOR 循环——先写测试让它失败再写最小代码让它通过4️⃣ subagent-driven-development子代理驱动开发两阶段审查规范合规性 → 代码质量5️⃣ requesting-code-review完成后提交代码审查按严重程度报告问题整个流程就像是给 Agent 装了一个强制引导程序——它不能跳过设计讨论不能跳过计划制定必须按流程走。 不过这种方式也有两个弊端一个是增加了交互的次数用起来稍微有点烦, 写一个需求得先和他聊半个小时。第二个是token消耗量还是比较大的经常把我模型打到限额了不过这个主要是我的问题。AI Coding的未来随着大模型能力提升这些工程还有意义吗以后模型能处理1000w 一个亿token、注意力完全不跑偏。这时候Context Engineering、Harness Engineering 岂不是多此一举但实践告诉我们一个反直觉的事实模型的上下文永远不够用。不是因为模型太笨而是因为——代码在增长、业务在复杂、团队在扩张。你塞给它的信息越多它能精准调用的反而越少。所以提供必要且精确的上下文信息——不管是写 CLAUDE.md、设计 Superpowers 工作流、还是维护团队知识库——在可预见的未来都是 AI Coding 里非常重要的一环。这让我想到一个有点焦虑的命题以后可能只有两种程序员了——会给自己写说明书的和不会的。玩笑归玩笑但认真想想你上一次给项目写 README 是什么时候会把自己踩过的坑写成文档吗怎么才能配置一个让 AI 高效工作的环境吗这些能力正在变得越来越重要。与其担心被 AI 替代不如学会给 AI 当一个好的导航员。