Harness Engineering 实战指南（非常详细），AI 写代码从入门到精通，收藏这一篇就够了！

你不是在编写智能你是在构建智能运行的世界。如果你最近关注 AI 编程领域一定听过一个越来越火的词——Harness Engineering约束工程。2025 年是 AI Agent 证明自己能写代码的一年而 2026 年我们学到了一个更深刻的教训Agent 不是难点Harness 才是。这篇文章会用最通俗的方式带你理解什么是 Harness Engineering为什么它如此重要以及如何用 Claude Code 实践它。即使你从未用过 AI 编程工具读完也能上手。一、从一个真实的痛点说起假设你正在用 AI 编程助手比如 Claude Code、Cursor、Codex开发一个项目。你兴奋地输入一条指令帮我用 Next.js 搭建一个博客要有文章列表、标签筛选、暗色模式。AI 开始工作了。它读文件、写代码、装依赖看起来很专业。但过了一会儿你发现——它用了你项目里根本不用的 CSS 框架命名风格跟你现有代码完全不一致它改了一个文件结果把另一个功能搞坏了你让它改一下样式它把整个页面重写了听起来熟悉吗这不是 AI 不够聪明。事实上当今的大语言模型如 Claude、GPT已经非常强大。问题出在你没有告诉它在什么环境里、按什么规则工作。这就是 Harness Engineering 要解决的问题。二、什么是 Harness Engineering2.1 一个类比赛马与缰绳Harness这个词来自马具——缰绳、马鞍、马嚼子——一整套用来引导强大但不可预测的动物朝正确方向奔跑的装备。这个比喻很精确比喻对应马 AI 模型Claude、GPT 等缰绳 约束和规则CLAUDE.md、lint、类型检查跑道 ️项目环境目录结构、技术栈、依赖骑师 你制定方向、审查结果马很强壮、很快但它不知道该往哪跑。骑师的工作不是替马跑步而是给它方向和边界。同样Harness Engineering 就是设计 AI Agent 运行的世界——约束、反馈循环、文档、验证机制——让 AI 可靠地完成工作。2.2 正式定义用一句话概括Agent Model HarnessModel模型AI 的大脑负责理解需求、推理、生成代码Harness套具模型之外的一切——工具、规则、上下文、反馈循环、安全护栏你无法让模型变得更聪明那是 Anthropic、OpenAI 的工作但你可以通过构建更好的 Harness让同一个模型表现得更出色。一个来自 LangChain 的真实数据他们的编程 Agent 在 Terminal Bench 2.0 基准测试中仅通过改进 Harness模型完全不变得分从 52.8% 跳到了 66.5%直接从第 30 名冲进前 5。同一匹马不同的缰绳天壤之别。三、Harness 的核心组成部分一个完整的 Harness 通常包含以下几个层次3.1 上下文层Context LayerAI 只能看到你放在它面前的东西。那些存在于 Slack 聊天记录、Google Docs、或你脑海中的知识对 AI 来说等于不存在。上下文层的核心工具是CLAUDE.md在 Claude Code 中或AGENTS.md在 Codex 中。它是一个放在项目根目录的 Markdown 文件告诉 AI这是什么项目技术栈是什么目录结构长什么样有哪些编码规范有哪些禁止事项以下是一个实际的CLAUDE.md示例# My Blog — 项目上下文## 概述一个使用 Next.js 15 构建的个人技术博客。内容以 MDX 格式存储在 /content/posts/ 目录下。## 技术栈- Next.js 15 (App Router)- TypeScript (严格模式)- Tailwind CSS v4- MDX 用于内容- 部署到 Vercel## 目录结构- src/app/ → 页面和布局- src/components/ → 可复用组件- src/lib/ → 工具函数、MDX 处理- content/posts/ → 博客文章.mdx 格式- public/ → 静态资源## 编码规范- 使用函数式组件 TypeScript interface- 组件放在 src/components/PascalCase 命名- 仅使用 Tailwind 工具类不写自定义 CSS 文件- 每篇文章的 frontmatter 必须包含 title, date, description, tags- 所有图片使用 next/image- 组件超过 150 行必须拆分## 常用命令- npm run dev → 启动开发服务器- npm run build → 生产环境构建- npm run lint → ESLint 检查- npx tsc --noEmit → 类型检查## 禁止事项- 禁止使用 any 类型- 禁止在提交代码中保留 console.log- 禁止修改 package.json 而不说明原因- 禁止删除现有测试而不提供替代方案为什么这么重要因为没有这个文件AI 每次开始工作时都在猜你想要什么。有了它AI 第一时间就知道上下文和边界。OpenAI 的团队在实践中发现与其把 AGENTS.md 当成百科全书不如把它当成目录——指向更详细文档的入口。3.2 技能层Skills LayerSkills技能是一种渐进式披露机制。与其把所有指令都塞进 CLAUDE.md不如把特定任务的详细流程拆分成独立的 Skill 文件让 AI 在需要时才加载。这解决了一个现实问题上下文窗口是有限的。如果你把所有规则都塞进系统提示AI 反而会变差——关键信息被淹没了。举个例子你可以创建一个新建博客文章的 Skill!-- .claude/skills/new-post.md --# 技能创建新博客文章## 何时使用当用户要求创建新的博客文章或文章时。## 执行步骤1. 询问文章信息标题、描述、标签2. 根据标题生成 slugkebab-case 格式3. 在 content/posts/{slug}.mdx 创建文件4. 包含标准 frontmatter 模板 --- title: 文章标题 date: YYYY-MM-DD description: 文章描述 tags: [标签1, 标签2] published: false ---5. 生成包含 h2 章节的内容骨架6. 验证文章能否正常渲染运行 npm run dev关键思维转变你不是在教 AI 怎么编程它已经会了你是在告诉它你的项目里怎么做事。3.3 护栏层Guardrails Layer这是安全工程与 Harness Engineering 的交汇点。护栏确保 AI 的每一步操作都在可控范围内。在 Claude Code 中Hooks 是实现护栏的主要机制——在 Agent 生命周期的关键节点自动执行脚本// .claude/settings.json{ hooks: { preCommit: [ npx tsc --noEmit, npm run lint ] }}这意味着 Claude Code 在每次提交代码之前必须先通过类型检查和 lint 检查。如果失败就不能提交。更完整的护栏体系包括提交前护栏Pre-commit├── TypeScript 类型检查 → 确保类型安全├── ESLint 检查 → 确保代码风格一致├── 构建检查 → 确保项目能正常构建└── 敏感信息扫描 → 确保不提交 API 密钥等运行时护栏Runtime├── 文件访问控制 → 限制 AI 只能修改特定目录├── 破坏性操作审批 → rm -rf 等需要人工确认└── 依赖安装审查 → 新增依赖需要说明原因3.4 验证反馈循环Verification Loop这是 Harness 最容易被忽略但最有价值的部分。没有反馈循环AI 会说我觉得没问题有了反馈循环AI 必须证明测试通过、lint 干净、类型检查通过。写代码 → 运行测试 → 检查 lint → 类型检查 → 构建验证 ↑ | └──────────── 失败则修复并重试 ←────────────────┘在 Claude Code 中你可以在 CLAUDE.md 的质量门禁部分定义这个循环## 质量门禁每次提交前必须通过1. npx tsc --noEmit 必须通过2. npm run lint 必须通过3. npm run build 必须成功4. 不允许提交包含 console.log 的代码四、动手实践用 Claude Code 搭建一个博客现在让我们把理论变为实践。以下是完整的操作步骤。4.1 安装 Claude Code在 macOS 终端运行# 安装 Claude Code原生安装无需 Node.jscurl -fsSL https://cli.claude.com/install.sh | sh# 验证安装claude --version首次运行claude命令后会打开浏览器进行 OAuth 认证。你需要一个 Pro月或100/月订阅。如果你已经有 Claude 的 $20 订阅你已经可以使用 Claude Code 了。当然你也可以配置其他LLM的Coding Plan比如说GLM、MiniMax等这里可以推荐一个Claude Code的可视化配置工具cc-switchhttps://github.com/farion1231/cc-switch可以让你随时切换LLM。4.2 创建项目并初始化 Harness# 创建项目目录mkdir my-blog cd my-blog# 启动 Claude Codeclaude进入 Claude Code 后输入你的第一条指令初始化一个 Next.js 15 博客项目使用 App Router TypeScript Tailwind CSS。支持 MDX 渲染博客文章。创建首页文章列表和文章详情页。Claude Code 会自动完成以下工作运行npx create-next-applatest安装 MDX 相关依赖创建页面路由和组件设置 Tailwind 配置4.3 创建 CLAUDE.md这是搭建 Harness 的第一步也是最重要的一步。在 Claude Code 中输入在项目根目录创建 CLAUDE.md包含以下内容项目概述、技术栈、目录结构、编码规范、常用命令、质量门禁和禁止事项。参考项目当前的实际结构来写。Claude Code 会根据刚才创建的项目结构自动生成一个准确的 CLAUDE.md。小技巧CLAUDE.md 应该简洁有力不超过 60 行最多不要超过500行。把它当成目录而不是百科全书。如果某个主题需要详细说明放到单独的文档中。4.4 创建 Skills# 在 Claude Code 中输入创建 .claude/skills/ 目录并创建以下三个 skill 文件1. new-post.md - 创建新博客文章的标准流程2. new-component.md - 创建新 React 组件的标准流程3. pre-deploy.md - 部署前检查清单每个 Skill 文件的结构都遵循相同模式# 技能名称## 何时使用描述触发条件## 执行步骤1. 第一步2. 第二步3. ...## 验证标准- 如何确认这个任务完成了4.5 建立验证机制# 在 Claude Code 中输入帮我在项目中配置以下验证机制1. ESLint 配置 strict 规则2. TypeScript strict mode3. 添加一个 pre-commit 检查脚本4. 在 CLAUDE.md 中添加质量门禁章节4.6 创建进度追踪文件!-- progress.md --# 开发进度## 已完成- [x] 项目初始化- [x] CLAUDE.md 创建- [x] Skills 配置- [x] 首页文章列表## 进行中- [ ] 文章详情页 MDX 渲染## 待开发- [ ] 标签筛选- [ ] 暗色模式- [ ] RSS 订阅- [ ] SEO 优化这个文件的价值在于当你开启新的 Claude Code 会话时Claude 会自动读取它和 CLAUDE.md瞬间了解项目状态并从中断处继续。五、Harness Engineering 的核心原则通过以上实践我们可以提炼出几条核心原则原则 1约束解放生产力这听起来矛盾但约束实际上让 AI 更高效。当 AI 可以生成任何代码时它会浪费 token 探索死胡同。当 Harness 定义了清晰的边界AI 会更快收敛到正确方案。没有 HarnessAI 自由发挥风格混乱需要反复修改有 HarnessAI 在规则内高效输出一次到位原则 2仓库即知识库把所有项目知识放进仓库——而不是聊天记录、Slack 消息、或你的脑子里。❌ 你在 Slack 里说咱们用 Tailwind 不用 CSS Modules✅ 你在 CLAUDE.md 里写仅使用 Tailwind 工具类不写自定义 CSS 文件AI 只能看到仓库里的东西。任何它不能在上下文中访问的知识对它来说等于不存在。原则 3失败驱动改进当 AI 犯错时不要只修复输出——要工程化地防止同类错误再次发生。第一次AI 提交了带 console.log 的代码 → 修复删掉 console.log ❌治标不治本 → 改进在 lint 规则中禁止 console.log ✅永久解决第二次AI 用了 any 类型 → 修复手动改成正确类型 ❌ → 改进在 CLAUDE.md 禁止事项中加入禁止使用 any ✅原则 4保持 Harness 轻量不要过度工程化。OpenAI 的团队给出的建议是YAGNI不需要的东西不要提前构建先简单再优化写最直接的方案有问题再改大胆删除代码越少bug 越少一个好的 Harness 应该是可以随时撕掉重建的。模型在快速进步今天需要复杂管控的地方明天可能一个提示就能搞定。六、从 Vibe Coding 到 Harness EngineeringAI 编程的发展经历了三个阶段阶段时间特征类比Vibe Coding2024-2025凭直觉写提示词看 AI 自由发挥放开缰绳让马自己跑Spec Coding2025写详细规格说明逻辑约束给马画一条路线Harness Engineering2026构建完整运行时环境给马装上全套马具 跑道 裁判Vibe Coding 很有趣但不可靠。Spec Coding 更好但 AI 仍然可能偏离规格。Harness Engineering 是系统性的解决方案——你不仅告诉 AI “做什么”还构建了一个确保它做对的环境。七、你的 Harness 清单如果你想现在就开始实践 Harness Engineering以下是一个最小可行清单## 最小可行 Harness□ CLAUDE.md / AGENTS.md - 项目概述3-5 句话 - 技术栈列出关键依赖 - 目录结构主要目录说明 - 编码规范5-10 条最重要的规则 - 常用命令 - 禁止事项□ 至少 1 个 Skill - 你最常执行的重复性任务□ 基础护栏 - TypeScript strict mode - ESLint 配置 - 提交前自动检查□ 进度文件 - progress.md 记录已完成 / 进行中 / 待开发不需要一步到位。先从 CLAUDE.md 开始遇到问题时再逐步添加 Skill 和护栏。记住那条黄金法则当 Agent 犯错时工程化一个方案让它不再犯同样的错。八、结语Harness Engineering 不是什么高深的技术。它的本质是一种思维方式的转变从写代码到构建 AI 写代码的环境。最好的 AI 产品不是拥有最强模型的团队做出来的而是拥有最成熟 Harness 工程实践的团队做出来的。模型是可替换的零件Harness 才是真正的产品。如果你正在使用 Claude Code、Cursor、Codex 或任何 AI 编程工具今天就开始为你的项目创建一个 CLAUDE.md把你脑海中的编码规范写下来添加基础的 lint 和类型检查当 AI 犯错时把修复变成规则你不需要让马变得更聪明。你需要给它更好的缰绳。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】