如何用 Cursor 完成小型编程任务：从任务卡到 Git 复核

要用 Cursor 完成小型编程任务，先定义一个可观察的行为，限定它能修改的文件，写明测试命令，要求它先给只读计划，再只批准最小的有效修改。像审查其他开发者的代码一样审查生成的 diff，运行范围最窄的测试，并用 Git 记录实际改了什么。在获准时，Agent 可以检查、编辑和运行工具，但它流畅的解释不能证明代码正确。［1］［2］

本教程把这套流程用在一个刻意简单的例子上：给纯 JavaScript 工具函数 parseRetryCount 增加整数范围校验，并为新的边界行为补充单元测试。它不涉及网络请求、凭据、依赖更新、生成文件或大范围重构。数据和审批边界先看更全面的如何使用 AI；如果工作超出一个可审查的行为，请改用单独的 AI 编程指南。

关键要点

• 小任务只有一个行为、一组很窄的文件和一个可运行的验收检查。
• 把目标、非目标、允许文件、预期用例和命令写进任务卡。
• 第一轮只读，先核对计划再开始编辑；Cursor 为此提供了 Plan Mode。［4］
• 审查 diff 和终端命令时，不依赖 Agent 的总结。
• 先运行最相关的最小测试，再考虑更宽的项目门禁。
• 把 Cursor checkpoint 当作方便的撤销点，而不是 Git 历史的替代品。

1. 什么情况下适合用 Cursor 完成小型编程任务？

“小”看的是不确定性和影响范围，而不是提示词有多短。适合交给 Agent 的任务只改变你能检查的代码中的一个行为，涉及的文件少，最后有一个确定性的检查。“拒绝 0–10 之外的重试次数”是小任务；“改进我们的重试系统”不是，它可能涉及解析、API 契约、持久化、界面文案、遥测和兼容性。

打开 Agent 模式前，先问四个问题：

1. 能否用一句话描述这个行为，而不需要“然后再”？
2. 能否说出实现文件和测试文件，或通过只读搜索找到它们？
3. 能否列出正常、边界和非法用例？
4. 有没有一个安全的命令，能在不改变外部状态的前提下证明这个窄行为？

如果任务需要秘密、生产权限、数据库结构迁移、不熟悉的生成代码、新依赖、破坏性命令、跨服务契约变更，或尚无审查人拍板的设计决定，就停下来拆分任务。这些并非 Agent 做不了，而是需要不同的计划和审批级别。

示例假设仓库中已有 src/parseRetryCount.js 和 test/parseRetryCount.test.js。预期契约是：接受 0 到 10 的整数，或以 10 进制表示的整数字符串，返回该整数；解析出的整数超出范围时抛出 RangeError。格式错误输入的现有行为保持不变。最后这句话能防止 Agent“好心”重写全部解析语义。

2. 提示之前先写 Cursor 任务卡

任务卡把含糊的聊天变成可审查的变更请求。当 Agent 提议顺手清理相邻代码时，它也是一个稳定的参照。Cursor Rules 可以提供持久的项目指引，但当前任务的验收标准仍应写在请求里。规则是可复用的上下文，不能替代对本次改动的精确描述。［3］

目标
- 给 parseRetryCount 增加 0–10 范围校验。

非目标
- 不重构无关的解析代码。
- 不改导出、调用方、依赖、格式化配置或 package 脚本。

允许文件
- src/parseRetryCount.js
- test/parseRetryCount.test.js

预期行为
- 0 和 10 被接受。
- -1 和 11 抛出 RangeError。
- 格式错误输入的现有行为保持不变。

验证
- 运行现有的 parseRetryCount 单元测试命令。
- 报告准确的命令和退出结果。

安全
- 第一轮只检查。计划获批前不编辑、不运行命令。

不要仅仅因为某个文件就在旁边，就把它列为允许文件。如果 Agent 发现必须修改另一个文件，它应说明原因并等待。文件清单变化属于范围变更，不是实现细节。

3. 要求只读检查和计划

在可用时先使用提问或计划类交互，或者明确禁止编辑和运行命令。让 Cursor 找出函数、它的导出、直接调用方、现有测试惯例和最窄的测试命令。Cursor 的 Agent 文档描述了一个能搜索代码库和使用工具的环境；正因为有这些能力，权限边界更加重要。［1］［2］Cursor 当前的 Plan Mode 文档描述了在编码前研究代码库并生成实施计划的规划环节。［4］

使用这个提示：

以只读模式检查任务卡和仓库。

返回：
1. parseRetryCount 当前的行为，附文件和行号引用；
2. 定义格式错误输入行为的现有测试；
3. 逐文件列出的最小改动方案；
4. 准确的最窄测试命令；
5. 假设、风险，以及允许文件清单不够用的任何理由。

暂时不要编辑文件、安装包、改变 Git 状态或运行命令。

把回复与仓库对照。自己打开被引用的文件。确认建议的测试命令确实存在于项目配置中，并且 Agent 没有把名字相似的辅助函数弄混。如果计划里有“顺便清理解析器”，删掉这一步。如果它找不出格式错误输入的现有语义，要求它保留这些语义，并在改变行为前先提出刻画性测试。

4. 只授权最小修改

计划正确后，只授权修改这两个文件并运行获批的测试。有用的指令既写明允许做什么，也写明什么情况需要再次暂停：

只在两个允许文件中实现已批准的范围校验和测试。
保持公开导出和格式错误输入的现有行为不变。
不要重新格式化无关代码行，也不要引入依赖。
运行任何命令前先展示 diff。修改其他文件或运行其他命令前先询问。

实现可能是在现有解析之后加一段检查：

if (value < 0 || value > 10) {
  throw new RangeError("retry count must be between 0 and 10");
}

这段代码只是示意，并非适用于所有代码库的补丁。真实函数可能使用不同的变量、错误约定或类型策略。除非任务卡明确要改，Agent 应遵循本地现有模式。

拒绝以下自动命令：破坏性的、没有任务理由却要求提权的、访问秘密的、连接生产系统的、意外修改锁文件的、安装软件包的、改写 Git 历史的，或对无关文件运行大范围格式化的。命令效果不清楚时也要暂停。“应该是安全的”不是权限模型。

5. 除了总结，diff 里还要检查什么？

Agent 的总结只是导航辅助，diff 才是审查对象。逐行阅读每处改动，并从四个方面提问。

审查方面	问题
行为	0 和 10 是否被接受？-1 和 11 是否被拒绝？格式错误输入是否保持不变？
失败路径	错误类型是否一致？错误信息是否只在测试或调用方需要的地方保持稳定？
测试	测试是否覆盖上下边界和刚好越界的值？测试是否可能不经过新分支也能通过？
范围	是否只改了允许的文件？格式、导出、调用方、快照或配置是否意外变动？

留意类型转换带来的意外。JavaScript 比较可能把字符串转成数字，所以如果范围校验放在显式解析之前，可能会意外接受旧函数拒绝的值。留意会误拒 0 的宽泛真值判断。检查 NaN、小数、空白和带符号字符串是否已有定义好的行为。任务卡要求保留这些决定，而不是重新设计它们。

依赖、权限、秘密和危险命令，可用 AI 生成代码审查清单核对。如果 diff 超出你能有把握审查的范围，即使代码看起来合理，也应视为停止条件。

6. 先跑最窄的测试，再选择更宽的门禁

审查完 diff 后，运行获批的单元测试。记录准确的命令、退出码和相关结果。不要把“测试应该能通过”或看起来一片绿色的总结当作证据。如果命令安全且已获批，可以让 Cursor 运行，但你仍要检查输出。

合理的顺序是：

1. 运行 parseRetryCount 的测试文件或具名测试；
2. 通过后，运行覆盖直接调用方的最小软件包测试套件；
3. 只有仓库政策或影响范围要求时，才运行 lint、类型检查或完整测试套件；
4. 格式化工具或快照更新后，再看一遍 diff。

更宽的门禁是一种决策，不是仪式。两行的纯函数改动可能只需软件包测试和标准 CI；被许多地方调用的共享工具函数则可能需要更大的测试套件。如果无关测试失败，先单独记录，确认本次改动是否影响到它们，再决定是否继续改代码。

想把测试设计得更扎实，可以参考 AI 生成测试流程，其中讲解了正常、边界、失败和不变量用例。不要为了让测试套件变绿就让 Agent 削弱已有断言。

7. 为什么持久记录要靠 Git，而不是 checkpoint？

测试之后，从仓库而不只是聊天面板查看 Git 状态和 diff。确认未跟踪文件、生成产物、锁文件和配置没有意外变化。如果团队要创建提交，提交应只包含已审查的范围，并走正常的评审流程。

Cursor checkpoint 可以帮你回到 Agent 之前的某个状态。把它当作编辑器本地的恢复辅助，而不是版本控制：checkpoint 可能不包含你的手动修改，可能只存在于本地编辑器中，也不是共享、可审查的项目历史。

短期试验可以用 checkpoint。持久的来源记录和协作应使用 Git 状态、diff、分支、提交和远程评审。恢复任何 checkpoint 之前，先检查会覆盖什么，并保护无关的工作。

8. 任务何时算完成，何时应该停下？

只有预期行为、已审查的 diff、测试和范围四者一致，任务才算完成。保存一份简洁的完成记录：

任务：parseRetryCount 范围校验
已审查文件：src/parseRetryCount.js、test/parseRetryCount.test.js
行为：接受 0–10；拒绝范围外的整数
保留：导出和格式错误输入的行为
测试命令：[准确命令]
结果：[退出码和简要结果]
Git 范围：[已审查的 diff 或提交引用]
未决问题：[无，或明确列出]
审查人：[姓名]

如果 Agent 需要未获批的文件、无法解释某处改动、提议新增依赖、遇到相互冲突的测试、需要凭据、要求运行破坏性命令、扩大了公开契约，或产出的 diff 大到无法作为一个行为来审查，就停下来重新规划。停下来是成功的范围控制，不是自动化失败。

Cursor 任务提示与 diff 检查表应包含什么？

根据附带的任务卡完成一个小型编程任务。
第一阶段只读：检查代码和测试，返回计划、风险、对允许文件的判断
以及准确的验证命令。等待批准。

批准后，只编辑列出的文件，保留无关行为和风格。
运行命令前先展示 diff。涉及额外文件、依赖、网络访问、提权、
破坏性命令或更宽测试时，先询问。

最后列出：变更的行为、修改的文件、准确的命令和退出码、
剩余假设和 Git diff 范围。绝不能把未运行的测试说成已通过。

接受之前，核对：只有一个行为；只改了允许文件；没有意外依赖；有正常和边界测试；覆盖失败路径；有准确的命令输出；没有无关格式化；剩余未知项已清楚说明；Git diff 与任务卡一致。

常见问题

什么样的编程任务算小？

它只有一个可观察的行为、一组很窄且可审查的文件、较低的外部风险和一个确定性测试。如果它改变多个契约或需要设计决策，就拆分或重新规划。

应该用 Ask 类模式还是 Agent 类模式？

发现问题和审查风险时，用只读的提问或计划交互。只有在计划、文件范围和命令获批后，才使用能编辑的 Agent。模式名称可能变化，权限边界更重要。

如何让 Cursor 不越出文件边界？

列出允许文件，并告诉它在触碰其他文件前停下。然后核对仓库状态和完整 diff。提示只是指令，Git 输出才是证据。

什么时候应该拒绝 Cursor 自动命令？

对于作用不清、破坏性、需要提权、读取秘密、面向生产、安装依赖或修改 Git 历史的命令，以及任何超出已批准任务卡的命令，都应拒绝或暂停。

应该如何审查 diff？

检查预期行为、错误路径、边界测试、公开接口，以及每一个意外的文件或格式变化。不要只依赖文字总结。

应该运行哪些测试？

从最窄的单元测试开始，再根据直接调用方、仓库政策和影响范围扩大。记录准确的命令和结果，并把无关的失败分开记录。

Cursor checkpoint 和 Git 一样吗？

不一样。把 checkpoint 当作 Agent 改动的本地恢复点。Git 提供持久、可检查的项目历史和协作能力，所以 checkpoint 绝不能替代已审查的 Git diff。

来源

Sources checked 2026 年 8 月 31 日。

1. Cursor, “Agent overview” — https://cursor.com/docs/agent/overview
2. Cursor, “Agent security and run modes” — https://cursor.com/docs/agent/security/run-modes
3. Cursor, “Rules” — https://cursor.com/docs/rules
4. Cursor, “Plan Mode” — https://cursor.com/docs/agent/plan-mode

延伸阅读

• 如何使用 AI
• 如何用 AI 编程
• 如何审查 AI 生成的代码