以 Cursor 为例，探索如何用好 coding agent。
Coding agent 已经能独立完成多文件重构、跑测试、查 CI 失败原因。但同样的模型，有人觉得「几乎不用改」，有人却要反复纠正同一个错误——差别往往不在模型，而在你有没有把 上下文、边界和验收标准 给对。
本文从 Cursor Agent 的体系结构出发，讲清楚各组件分工，再落到日常可用的实践方法。
Agent 到底是什么
Cursor Agent 不是「更聪明的聊天框」，而是一个 能读代码、改文件、跑命令、调外部工具 的编程搭档。官方把它称为 Agent Harness（运行框架），由三层组成：
| 层 | 作用 | 类比 |
|---|---|---|
| Instructions | 告诉 Agent 怎么做事、遵守什么规范 | 员工手册 + SOP |
| Tools | 文件读写、搜索、终端、MCP 等 | 双手 + 工具箱 |
| Model | 推理与决策 | 大脑皮层 |
社区里有时把 Model + 被注入的 Instructions + 当前 Context 合称为 agent 的「大脑（Brain）」。Cursor 没有单独的 brain 配置文件——Brain 是运行时组装出来的，不是某个静态文件。
知识体系：静态 vs 动态
Cursor 把「知识」分成两类，对应 onboarding 新同事时的两种材料：永远要知道的，和 用到再查的。
User Rules — 个人全局偏好
- 位置：Cursor Settings → Rules
- 跨所有项目生效
- 适合：沟通风格、通用编码习惯、git 安全策略（如「不要主动 commit」）
Project Rules — 项目常驻规范
- 位置：
.cursor/rules/*.mdc - 触发方式：
| 类型 | 配置 | 何时加载 |
|---|---|---|
| 始终生效 | alwaysApply: true | 每次对话 |
| 文件匹配 | globs: **/*.ts | 相关文件在上下文中 |
| 智能应用 | 有 description，无 glob | Agent 判断相关时 |
| 手动引用 | @规则名 | 你主动 @ 时 |
- 适合：构建命令、目录约定、禁止改动的文件、指向 canonical 示例
- 优先级：Team Rules → Project Rules → User Rules
示例：
# Commands
- `npm run build`: 构建项目
- `npm run test`: 跑测试（优先单文件）
# Code style
- 用 ES modules，不用 CommonJS
- 组件结构参考 `components/Button.tsx`
# Guardrails
- 不要改 `migrations/` 下的历史文件
- 提交前必须跑 typecheck原则：Rules 要少。 它们常驻 context，写太多反而干扰 Agent。只放「Agent 反复犯同一个错」的约束；偶尔才用的流程，放进 Skill。
Skills — 按需加载的领域知识 + 工作流
- 位置：
.cursor/skills/（项目）或~/.cursor/skills/（个人） - 结构：
deploy-staging/
├── SKILL.md # 必需
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：详细文档
└── assets/ # 可选：模板、配置样例Rules 与 Skills 的核心区别：
| Rules | Skills | |
|---|---|---|
| 加载时机 | 常驻 / 按文件匹配 | 按需（Agent 判断相关，或 /skill-name 手动调用） |
| 内容 | 短规范、约束 | 多步骤流程、领域知识、可执行脚本 |
| 上下文成本 | 持续占用 | 只在需要时占用 |
| 典型用途 | 「永远用 Vitest」 | 「部署 staging 的 5 步流程」 |
SKILL.md 示例：
---
name: deploy-staging
description: Deploy to staging. Use when the user asks to deploy, ship, or push to staging.
---
# Deploy to staging
1. Run `npm run build` and confirm success
2. Run `npm run test` and confirm all tests pass
3. Run `npm run deploy:staging`
4. Check https://staging.example.com/health
5. Report deployment status and URL- 自动触发：Agent 根据
description判断相关 - 手动触发：输入
/deploy-staging - 强制手动：设置
disable-model-invocation: true（类似旧版 slash command）
运行时 Context（非文件型知识）
Agent 还会动态拉取：
- 打开的文件、你
@引用的文件/文件夹 - 代码库搜索（grep、语义搜索）
@Branch、@Past Chats- Plan 文件（
.cursor/plans/） - MCP 返回的外部数据
精准引用 > 海量投喂。 知道具体文件就 @ 它；不知道就让 Agent 自己搜——不必 @整个仓库。
工作流体系
Workflow 在 Cursor 里不是单一概念，而是多种机制的组合。
1. Skills = 可复用工作流
最典型的例子是 /pr：
git diff → 写 commit message → push → gh pr create → 返回 PR URL其他适合做成 Skill 的流程：
/fix-issue [number]：拉 issue → 定位代码 → 修复 → 开 PR/review：跑 linter → 检查常见问题 → 汇总/update-deps：逐个升级依赖，每次跑测试
Check in 到 git，整个团队都能用。
2. Hooks — 事件驱动的自动化
- 位置：
.cursor/hooks.json+.cursor/hooks/* - 在 Agent 生命周期中插入脚本：
| 事件 | 典型用途 |
|---|---|
beforeShellExecution | 拦截危险命令 |
afterFileEdit | 自动 format |
beforeSubmitPrompt | 检查 prompt 是否含密钥 |
stop | Agent 结束后自动 follow-up（如「测试没过继续修」） |
Hooks 把「做完 A 必须做 B」写进系统，而不是每次靠 prompt 提醒。例如 stop hook 可以让 Agent 在测试未通过时自动继续迭代，直到全绿。
3. Plan Mode — 先规划再动手
按 Shift+Tab 切换 Plan Mode。Agent 会：
- 调研代码库，找相关文件
- 提问澄清需求
- 生成可编辑的实现计划
- 等你批准后再写代码
计划可保存到 .cursor/plans/，供后续 Agent 复用。大重构、跨模块功能，先 Plan 再 Agent，比直接「全改完」稳得多。
4. Automations — 事件触发的 Agent
独立于 IDE 内对话，由外部事件触发：
- Git PR 打开 / CI 失败
- Cron 定时
- Slack @Cursor
- Webhook、PagerDuty 等
适合：定时 review、CI 失败自动修、Slack 里派活。
5. Subagents — 专门领域的子 Agent
- 位置：
.cursor/agents/*.md或~/.cursor/agents/ - 在隔离上下文里跑专门任务（code-reviewer、debugger、explore）
- 主 Agent 通过 Task 工具委派，适合并行探索、长时间子任务
外部连接：MCP 与 CLI
MCP（Model Context Protocol）
让 Agent 按需连接外部系统：Slack、Sentry、Datadog、数据库、Figma 等。Skill 写流程，MCP 提供数据和动作。
CLI 工具
Agent 可以直接跑终端里已安装的工具：gh、aws、kubectl、docker……无需额外配置。在 Rules 里指明偏好即可：
- 所有 GitHub 操作用 `gh`（issues、PRs、CI checks）
- 查 CI 失败：`gh pr checks` + `gh run view`选对模式
| 模式 | 何时用 |
|---|---|
| Ask | 只问不改，理解代码、做 review |
| Plan | 大改前先对齐方案 |
| Agent | 明确的功能/修复，直接动手 |
| Debug | 有报错、复现步骤，系统性排查 |
写好 Prompt：可验收，不可想象
| 模糊 | 清晰 |
|---|---|
| 优化这段代码 | 把 fetchUser 的错误处理改成和 fetchPost 一致，并补一个 404 测试 |
| 加个登录 | 用现有 JWT 中间件实现邮箱+密码登录，失败返回 401，不写新依赖 |
好的 prompt 通常包含四件事：
- 目标 — 要达成什么
- 范围 — 改哪些文件/模块
- 约束 — 不能做什么
- 验收 — 怎样算完成（测试通过、UI 行为、性能指标）
自主性与护栏
Agent 越强，越需要边界。
可以多给自主权的：
- 跑测试、查 linter、读相关文件
- 在约定范围内选实现方式
- 多文件联动的小重构
要收紧的：
- 数据库迁移、删文件、改依赖
- 涉及密钥、支付、权限的逻辑
- 没有测试覆盖的核心路径
用 Rules 写长期约定（不主动 commit、提交前跑哪些测试），用 Hooks 做 enforcement（format、secret scan），比每次重复提醒有效得多。
像结对编程一样迭代
Agent 很少一次做对。正常流程：
描述任务 → 看 diff → 指出偏差 → 补充约束 → 再跑一轮有效反馈：
- 「方向对，但不要用新库，用现有的
cache.ts」 - 「测试挂了，错误是 xxx，先修测试再改实现」
无效反馈：
- 「不对，重来」（没说明哪里不对）
- 「你看着办」（没有验收标准）
构建失败了，把 完整报错贴进去，比「build 挂了帮我修」有效十倍。
上下文管理
何时开新对话
开新对话：
- 切换到不同任务/功能
- Agent 反复犯同样错误、明显跑偏
- 一个逻辑单元已完成
继续当前对话：
- 在同一功能上迭代
- Agent 需要早前讨论的上下文
- 正在 debug 它刚写的代码
对话太长后，context 会积累噪音。效果下降时，用 @Past Chats 引用历史，而不是复制整段对话。
给可验证的目标
Agent 需要明确信号来判断对错：
- 类型系统 + linter
- 测试（尤其是 Agent 能自己跑的）
- 构建脚本
「测试全绿」比「看起来没问题」可靠得多。
推荐的分层配置
Layer 0: Model → 选对模型（复杂推理 vs 快速迭代）
Layer 1: User Rules → 个人偏好（少而精）
Layer 2: Project Rules → 项目约定（构建命令、目录结构）
Layer 3: Skills → 重复工作流（/pr、/deploy、/review）
Layer 4: Hooks → 自动化护栏（format、secret scan、grind loop）
Layer 5: MCP → 连外部系统
Layer 6: Subagents → 复杂任务委派与并行起步建议：
- 先不加 Rules，用默认 Agent 跑几个任务，观察它反复错在哪里
- 把重复流程做成 Skill（commit、PR、deploy）
- Rules 只补缺口（测试框架、目录约定、禁止事项）
- Hooks 做 enforcement（格式化、安全拦截、测试循环）
- 团队共享：Rules / Skills check in 到 git；用 Plugins 打包整套配置
概念速查
| 说法 | Cursor 对应 | 一句话 |
|---|---|---|
| Brain | Model + Instructions + Context | 运行时组装，不是配置文件 |
| 常驻知识 | User Rules + Project Rules | 每次都要知道的 |
| 按需知识 | Skills + MCP + 代码搜索 | 用到再加载 |
| Workflow | Skills + Hooks + Plan + Automations | 可重复的步骤与自动化 |
| Skill | .cursor/skills/*/SKILL.md | 可版本控制的技能包 |
| Guardrails | Rules + Hooks | 约束与拦截 |
| Specialist | Subagents | 专门领域的子 Agent |
小结
用好 Cursor Agent，核心不是写更长的 prompt，而是 分层配置上下文：
- Rules 管「永远遵守什么」
- Skills 管「特定任务怎么做」
- Hooks 管「系统自动 enforce 什么」
- MCP / CLI 管「连什么外部世界」
- Plan / Subagent 管「复杂任务怎么拆」
Agent 是加速器，审查 diff 和设定边界的责任仍在人。把重复劳动交给配置，把判断力留给自己——这才是 mastery 的方向。