Cursor高阶用法（2）：Agent模式实战 — 从单文件到完整功能开发

一、Agent模式是什么？和普通对话有什么区别？

Agent模式相较于其他模式，提供了更高级的交互能力。以下是三种模式的简要对比:

Agent模式的核心能力包括自主决策文件操作、执行终端命令、多轮自主迭代和Checkpoint回滚。要开启Agent模式，可以通过Cmd/Ctrl + Shift + I打开Composer，并选择Agent模式。

二、什么任务适合用Agent？

适合Agent的任务

• 新增完整功能：例如实现用户登录功能，包含前端表单、API接口、数据库操作。

• 跨文件重构：例如将现有的REST API迁移到GraphQL。

• 编写完整测试：为UserService的所有方法编写单元测试。

• 初始化项目脚手架：使用Next.js + Prisma + shadcn创建一个博客系统基础结构。

• 修复复杂Bug：运行测试后有3个用例失败，帮助找到根本原因并修复。

不适合Agent的任务（用Chat更快）

• 解释这段代码的逻辑。

• 把这个函数的变量名改得更清晰。

• 这里有个typo，帮我改。

三、启动Agent的关键：任务描述的质量

Agent的输出质量很大程度上取决于你的任务描述质量。以下是“差的描述”与“好的描述”的对比示例。

// 差的描述（AI 会乱猜）
帮我做一个用户管理功能

// 好的描述（AI 可以精准执行）
在现有项目基础上新增「用户管理」功能，具体要求：
【数据模型】
- 在 Prisma schema 中新增 User 表：id（UUID）、email（unique）、name、role（enum: ADMIN/USER）、createdAt、updatedAt
- 新增 UserProfile 表（一对一关联 User）：avatar_url、bio、phone

【API 接口】（遵循已有的 /src/app/api/ 目录结构）
- GET /api/users — 分页列表，支持 ?page=&limit=&role= 筛选
- GET /api/users/[id] — 用户详情（含 profile）
- PATCH /api/users/[id] — 更新用户信息（仅 name、role 字段）
- DELETE /api/users/[id] — 软删除（新增 deletedAt 字段，不物理删除）

【前端页面】
- 新建 /app/admin/users/page.tsx — 用户列表页
  - 使用 TanStack Table v8（项目已安装）实现可排序表格
  - 分页组件复用 src/components/ui/Pagination.tsx
  - 搜索框、角色筛选下拉（复用 shadcn Select）
- 新建 /app/admin/users/[id]/page.tsx — 用户详情/编辑页

【其他要求】
- API 路由必须验证 JWT（复用 src/lib/auth.ts 中的 verifyToken()）
- 所有操作记录到 src/lib/audit-log.ts 的 logAction() 函数
- 运行完记得执行 pnpm prisma migrate dev 和 pnpm test

四、在执行过程中的有效干预

4.1 实时纠偏（发现偏差时）

Agent在修改文件时，如果方向偏了，可以直接在输入框追加指令，如：“等一下，UserProfile不需要单独的表，直接加字段到User表即可”。Agent会暂停当前操作，重新规划。

4.2 提供额外上下文

“注意：项目中已经有src/lib/pagination.ts实现了分页逻辑，不需要重写，直接引用它就行”。

4.3 批准/拒绝命令执行

Agent要运行命令时会弹出确认框，可以选择Run允许执行，Skip跳过该命令，或者修改命令内容后再Run。

五、Checkpoint回滚机制

Agent模式最重要的安全网是Checkpoint回滚机制。每次Agent开始一轮修改前，Cursor会自动保存当前文件状态。在对话历史中找到对应的Checkpoint气泡，点击Restore，所有文件恢复到该时刻的状态。

最佳实践包括任务开始前确保Git是干净状态，Agent完成后用git diff审查所有改动再提交。

六、调试场景：让Agent自动修复报错

这是Agent最省时的用法之一。场景：你跑测试发现有失败用例。正确姿势包括在终端运行测试，复制完整的错误输出，打开Composer（Agent模式），粘贴错误信息，并提供说明。Agent会读取相关文件，分析错误原因，修改代码，自动再次运行测试确认，如果还有失败，继续迭代。

七、复杂任务的拆解策略

策略1：里程碑式拆分

把大任务分成3-5个小Agent任务，每完成一个就commit一次。例如，任务1：新增Prisma schema（只改schema.prisma和执行迁移，不动代码），任务2：实现API层（只动src/app/api/目录），任务3：实现前端页面（只动src/app/admin/目录），任务4：集成测试（只在tests/目录新建测试文件）。

策略2：给Agent明确的边界

“本次任务只允许修改以下目录：src/app/api/auth/，src/lib/auth.ts。禁止修改任何已有测试文件，src/app/page.tsx（主页），prisma/schema.prisma（schema上次已经确认过了）”。

八、实战演示：用Agent从零构建一个完整功能

以“评论功能”为例，完整的Agent Prompt如下：

基于现有的博客系统，新增文章评论功能。

【数据模型】（添加到已有 schema.prisma）
model Comment {
  id        String   @id @default(cuid())
  content   String   @db.Text
  authorId  String
  postId    String
  parentId  String?  // 支持嵌套回复
  createdAt DateTime @default(now())
  author    User     @relation(fields: [authorId], references: [id])
  post      Post     @relation(fields: [postId], references: [id], onDelete: Cascade)
  parent    Comment? @relation("CommentReplies", fields: [parentId], references: [id])
  replies   Comment[] @relation("CommentReplies")
}

【API 接口】
- GET /api/posts/[id]/comments — 获取文章评论树（含嵌套回复）
- POST /api/posts/[id]/comments — 发布评论（需登录）
- DELETE /api/comments/[id] — 删除评论（仅作者或管理员）

【前端组件】
- 创建 src/components/post/CommentSection.tsx
  - 评论列表展示（树形结构）
  - 评论输入框（使用 Textarea from shadcn）
  - 回复按钮（点击后在该评论下方出现输入框）
  - 删除按钮（仅本人评论显示）
- 在 src/app/posts/[slug]/page.tsx 底部引入 CommentSection

完成后执行：
1. pnpm prisma migrate dev --name add-comments
2. pnpm test -- --grep="comment"（如果测试失败请修复）

九、小结与常见坑

效率最高的Agent用法包括描述清晰、任务适中和人工审查。常见踩坑包括让Agent同时重构多个模块，不告诉Agent项目已有哪些工具函数，跳过Checkpoint，以及不先review diff再commit。

下一章我们将探讨Composer的跨文件重构能力：如何在不破坏现有功能的情况下大规模改造代码库。感谢您的关注，敬请期待！