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 可以查看一个目录，但不代表它可以重写整个目录。

让它优化风格

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

缺少 UI 状态证据

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

Cursor Spec FAQ

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

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

最重要的字段是什么？

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

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

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

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

生成规格包