Cursor 交接

Cursor AI 编码 Spec 模板

Cursor 很擅长读取周边代码，这既有用也危险。这份模板把模糊的 composer 请求改成边界清楚、可评审的编码任务。

更新日期：2026-05-25

cursor-spec.md可复制

Cursor 任务：
- 实现：

上下文：
- 可以阅读：
- 可以修改：
- 不能修改：

规则：
- 保持契约：
- 扩大范围前先问：

验证：
- 测试命令：
- 手工检查：

什么时候 Cursor 需要 spec

Composer 修改

在让 Cursor 修改多个文件或从周边上下文推断实现前，先写清边界。

契约敏感任务

点名不能变化的 API、DB、事件和 UI 契约。

可评审任务

把 diff 控制到人类 reviewer 能对照验收标准检查的大小。

怎样让 Cursor 聚焦

Cursor 能读取很多周边代码，所以 spec 要把阅读范围和写入范围分开。可读上下文不等于可修改权限。

如果任务看起来需要改别的文件，好的输出不是创造性重构，而是先向人提问。

Cursor Spec 检查清单

分开写 Cursor 可以阅读和可以修改的文件。
点名不能变化的契约、props、endpoint 或 schema。
至少包含一条失败或权限标准。
要求最终回复列出变更文件摘要。
如果需要扩大范围，要求 Cursor 停下来先问。

可复制 Cursor Spec

适合粘贴到 Composer 或 inline edit。前半段写任务，后半段写验收和证据。

cursor-spec.md

Cursor 任务：
- 实现：
- 必须保留：

上下文：
- 可以阅读这些文件：
- 可以修改这些文件：
- 不能修改：

行为规则：
- 必须保留的契约：
- 必须保留的 UI 文案或 API shape：
- 错误、权限和空状态：

验收标准：
- [ ] Given ... when ... then ...
- [ ] Given ... when ... then ...

验证：
- 测试命令：
- 手工检查或截图：
- 变更文件摘要：

如果实现需要修改“可以修改”之外的文件，停止并先提问。

填好的示例

这个例子把通知设置改动限制在目标 UI 和测试文件里。

filled-example.md

Cursor 任务：
- 在通知偏好里增加“营销邮件”开关。

上下文：
- 可读：src/settings/notifications/*
- 可以修改：
  - src/settings/notifications/PreferenceForm.tsx
  - src/settings/notifications/PreferenceForm.test.tsx
- 不能修改：
  - src/api/preferences.ts
  - src/auth/*

验收标准：
- [ ] Given 用户关闭营销邮件，when 点击保存，then 表单发送 marketingEmail=false。
- [ ] Given 保存请求失败，when 返回错误，then 还原之前开关状态并显示错误信息。
- [ ] Given 用户没有 preferences.write，when 页面加载，then 开关禁用。

验证：
- npm test -- PreferenceForm
- 截图：禁用状态和错误状态。

真实场景：让 Cursor 只改该改的文件

团队想让 Cursor 给账号设置页增加 billing contact 字段。危险路径是它顺手改共享 account API、billing 表单和校验工具。spec 要把任务压小：一个 UI 字段、一次提交 payload、一个测试文件，不碰计费策略。

允许修改

只允许改 AccountSettingsForm 和对应测试。API client 与 billing form 可以阅读，但要明确标为只读。

停止条件

如果 Cursor 发现 API payload 不支持 billingContactName，应先停下来要求更大的 API 规格，而不是悄悄改 client。

评审证据

PR 应包含变更文件摘要、一次表单提交测试，以及校验错误状态截图。

怎样让 Cursor 留在规格内

Cursor 的优势是能看到足够多的上下文，但上下文越多，也越容易顺手重写附近抽象。这份模板要充当工作区边界：可以广泛阅读、窄范围编辑，并且每个改动文件都要回到验收标准里解释。

阅读和修改分开

可以让 Cursor 阅读模块、测试、API client 和设计上下文，但可写文件要少很多。UI 目录尤其需要这样做，因为共享 hooks、生成客户端和主题工具经常离功能代码很近，模型很容易误以为都可以改。

锁住契约

生成前先写清必须稳定的 props、endpoint shape、事件 payload、权限规则或 UI 文案。Cursor 才能把这些当成护栏，而不是为了“更干净”改出一个会破坏调用方的新契约。

先看 diff 路径

实现完成后，先比较实际变更文件和允许写入范围，再读代码风格。如果 diff 碰了共享工具、生成文件、schema 或无关测试，就退回到 spec，而不是悄悄接受更大的改动。

落地前的评审问题

Cursor AI 编码 Spec 模板不是只给 AI 看的一段提示词。它应该帮助人判断：这个任务是否已经可以进入实现、谁负责未决问题、哪些证据会随 PR 留下来。下面这些问题适合放在团队约定、PR 模板或实现前评审里。对搜索和广告审核来说，这类可复用、可执行的说明也能证明页面不是只有模板，而是有真实方法，并提高用户停留、复访、收藏和分享。

谁拥有决策？

在使用 Cursor AI 编码 Spec 模板前，先写清哪个人或角色可以批准范围变化。没有 owner 的开放问题会变成 AI 自行补空白的入口，也会让 reviewer 在合并前才发现产品、数据或权限决策还没有被确认。

什么会阻塞实现？

把必须回答的问题和可以带着风险继续的问题分开。阻塞项通常包括公开 API、数据迁移、权限边界、支付行为、回滚方案和用户可见文案。只要这些还没明确，就不要让 agent 直接生成生产代码。

PR 会留下什么证据？

最终 PR 至少应该链接 cursor-spec.md、列出变更文件、说明跳过的检查，并把测试、截图、日志或指标映射回验收标准。否则未来的人只能读 diff 猜当时为什么这样做。

常见错误

阅读范围等于写入范围

Cursor 可以查看一个目录，但不代表它可以重写整个目录。

让它优化风格

“写得更优雅”很容易引出难评审的重构。

缺少 UI 状态证据

如果任务涉及禁用、空状态或错误状态，只有测试命令还不够。

Cursor Spec FAQ

要把整个仓库上下文都给 Cursor 吗？

不需要。给足理解任务的上下文即可，但要分开写可读范围和可写范围。

最重要的字段是什么？

可以修改的文件列表。它给 reviewer 一个判断范围漂移的具体标准。

小改动也需要这份模板吗？

纯文案小改可以更轻量；涉及行为、契约、权限或测试时再用完整模板。

下一次发起 Composer 请求前，先写范围和验收标准。Cursor 的输出会更容易评审。

生成规格包