编码智能体Harness实战：Plan、Rules、Skills与Hooks让代理不掉线

2026年1月，Cursor团队负责人Lee Robinson发表了《Best practices for coding with agents》，系统总结了让编码智能体真正好用的方法论。核心观点：现在的模型可以连续跑几个小时、完成大型多文件重构、一直迭代到测试通过——但能不能发挥出来，取决于你是否理解智能体的「harness」（驾驭框架），并掌握计划、上下文、规则与技能这四件套。这篇文章把官方最佳实践翻译成可执行的代码示例，帮你把智能体从「玩具」变成「队友」。

计划、上下文、规则、技能四件套

一、先理解Agent Harness：指令+工具+模型

Robinson指出，任何智能体harness都由三部分组成：指令（系统提示词和规则）、工具（文件编辑、代码搜索、终端执行）、模型（你为任务选的模型）。同一个提示词，不同模型反应完全不同——有的模型偏好grep而不是专门的搜索工具，有的模型需要明确指令才会在编辑后调用linter。理解这一点，你就明白为什么「换个模型就翻车」：不是模型差，是harness没调对。

二、先计划，再编码（最有效的一招）

文章最强调的实践是「编码前先计划」。芝加哥大学的研究发现，经验丰富的开发者更倾向于在生成代码前先做计划——计划迫使你把要做什么想清楚，也给智能体具体的目标。在Cursor里按Shift+Tab可以切换Plan Mode：智能体会先研究代码库、问澄清问题、生成带文件路径的实现计划，等你批准后才动手。计划以Markdown打开，可以直接编辑删减，还能保存到.cursor/plans/变成团队文档——中断的工作也更容易恢复。

# Start with a plan — Plan Mode research prompt
# Ask the agent to research before touching code
"""
Research the authentication flow in this repo.

1. Find every file that touches login, session, or token refresh.
2. Identify the current auth pattern (JWT, cookie, OAuth?).
3. Propose an implementation plan with exact file paths
   and the changes each file needs.
4. Ask me clarifying questions before writing any code.

Save the plan as a markdown file under .cursor/plans/.
"""

三、上下文管理：让智能体自己找，别硬塞

当你习惯让智能体写代码后，你的工作就变成了「给每个智能体它需要的上下文」。但你不必手动在提示词里标记每个文件——现代智能体有强大的搜索工具，能按需拉取上下文。你问「认证流程」，它自己会通过grep和语义搜索找到相关文件，哪怕你的提示词里没有这些词。原则很简单：你知道确切文件就标记它；不知道就让智能体自己找。塞入无关文件反而会污染上下文窗口。

四、Rules：检查进Git的团队约定

Rules（规则）是始终包含在上下文里的项目约定——命令、模式、规范示例。关键原则是保持精简：只写要运行的命令、要遵循的模式、以及指向规范文件的指针，而不是复制整个风格指南（那是linter的事）。代码示例2展示了一份合格的rules文件。规则要check进Git让全团队受益；每次智能体犯错，就更新规则——你甚至可以在GitHub issue或PR上@cursor让它自己更新规则。

# .cursor/rules — keep rules short, point at canonical examples
# Checked into git so the whole team benefits
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: import { foo } from 'bar'
- See components/Button.tsx for the canonical component structure
- Always run typecheck after a series of code changes
- API routes go in app/api/ following existing patterns

五、Skills与Hooks：动态能力与长循环

与始终加载的Rules不同，Skills（技能）是动态加载的：SKILL.md打包了领域知识、自定义命令和脚本，智能体觉得相关时才调用，保持上下文窗口干净。代码示例3是一个PR审查技能。更进阶的玩法是Hooks——代码示例4和5展示了一个「长循环」模式：用stop hook让智能体一直迭代到所有测试通过，最多5次。这是让智能体自主完成「测试不绿就不停」这类目标的利器。

# skills/check-pr/SKILL.md — dynamic capability, loaded only when relevant
---
name: check-pr
description: Review a pull request against repo conventions
---

When reviewing a PR:
1. Run the linter and typecheck first.
2. Check imports follow the ES module rule.
3. Flag any file over 400 lines for refactoring.
4. Output a short checklist, not a wall of prose.

Usage: /check-pr <branch>

# .cursor/hooks.json — long-running agent loop until tests pass
{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

// .cursor/hooks/grind.ts — keep the agent working until green
import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message:
      "[Iteration " + (input.loop_count + 1) + "/" + MAX_ITERATIONS + "] " +
      "Fix the remaining failing tests, update scratchpad.md, keep going.",
  }));
}

六、给你的智能体工作流升级清单

把官方最佳实践落地成四步：第一，为你的项目写一份精简rules并check进Git；第二，复杂任务一律先进Plan Mode，把计划保存到.cursor/plans/；第三，把高频操作（PR审查、依赖升级）封装成SKILL.md技能；第四，为「测试必须通过」类任务配置hooks长循环。记住核心心法：不是所有任务都需要详细计划——快速改动直接干；但大型重构，计划就是你的刹车和方向盘。