Cloud Agent Best Practices
基于 Cursor 官方 Best Practices 文档整理 Cloud Agent 环境、上下文、skills、MCP、工具设计和验收清单。
Cloud Agent 的可靠性主要取决于环境、上下文、工具和验收方式，而不是 prompt 写得多长。
阅读目标：读完本章，你应该能把 Cloud Agent 从“能用”提升到“可重复上线使用”，并知道失败时优先补哪里。
1. 官方建议的核心
Cursor 官方 Best Practices 可以压成一句话：把 Cloud Agent 当成低上下文但很能干的远程开发者，提前给它环境、信息和工具。
| 维度 | 不可靠做法 | 稳定做法 |
|---|---|---|
| 环境 | 让 agent 自己猜依赖和启动方式 | 先配置 Cloud agent setup |
| secrets | prompt 里贴 key 或让 agent 追问 | dashboard Secrets tab |
| 网络 | 运行后才发现出站被挡 | 提前配 egress allowlist |
| 测试 | 项目本地都跑不起来 | repo 能像人类开发者一样本地测试 |
| 上下文 | 只给一句“修一下” | agents.md、rules、skills、明确任务 spec |
| 工具 | 只靠 shell 和搜索 | MCP、自定义 CLI、项目专用工具 |
Cloud Agent 不是魔法 runner。人类开发者本地都难以复现的问题，agent 在 VM 里通常也会更难。
2. 先把环境配好
先读并落实 Cloud agent setup。最少要能完成：
- clone repo。
- install dependencies。
- run build。
- run tests。
- start app。
- access required external services。
- read necessary secrets。
环境配置可以包含 Dockerfile、environment setup commands、start commands、secrets、network rules 和 repo-specific instructions。
如果 Cloud Agent 经常卡在安装依赖、找不到命令、端口冲突、缺少 token，这不是“模型不行”，是环境没准备好。
3. 检查访问边界
Cloud Agent 开始前先检查三类访问。
| 类别 | 检查点 |
|---|---|
| Secrets | API keys、database credentials、third-party tokens 是否在 Secrets tab 中配置 |
| Egress controls | 网络限制开启后，本地开发需要的 URL 是否都 whitelisted |
| Local testability | repo 是否能在不依赖不可达外部服务的情况下跑核心测试 |
对商业项目，建议把这些内容写到 repo 里的 agent instructions：哪些服务可用，哪些必须 mock，哪些命令是官方验收路径。
4. 用 skills 和 agents.md 给上下文
官方建议用 skills 和 agents.md 配置 agent。目标不是堆文档，而是把项目里人类开发者反复需要知道的事结构化。
agents.md 适合写：
- monorepo 中常用 package 的启动和测试方式。
- 关键 microservices 的调试入口。
- 代码修改边界。
- 常见失败日志的解释。
- PR 交付标准。
- 禁止触碰的路径和安全红线。
skills 适合写：
- 某个服务如何本地调试。
- 第三方依赖如何临时配置。
- 复杂测试数据如何构造。
- 浏览器验证流程。
- release、migration、benchmark 这类固定工作流。
判断标准很简单：如果同一条说明已经对人类新人讲过三次，就应该沉淀给 agent。
5. 给 agent 合适的工具
官方也强调，agent 很多时候受限于工具访问。MCP 和 custom tools 能让它接触和人类开发者一样的系统。
可以补的工具：
| 工具类型 | 用途 |
|---|---|
| MCP | 数据库、issue tracker、日志系统、内部 API、文档系统 |
| Custom CLI | 启动服务、查日志、重放测试、生成 fixture、跑诊断 |
| Scripted checks | format、lint、unit、e2e、security scan、content audit |
| Browser tools | 打开应用、截图、验证 UI flow |
但工具不是越多越好。每个工具都应该有用途、权限边界和验收信号。敏感工具优先用 HTTP MCP 或受控服务端代理，减少直接把凭据暴露给 VM 的机会。
6. 把工具塑造成 agent 好用的形状
官方提到，某些模型会忘记 package.json 自定义命令的参数，也会被噪音 build logs 分散。解决方向不是继续写更长 prompt，而是把工具改成更适合 agent 调用。
更好的工具通常具备：
- 一个命令完成一个明确动作。
- 默认参数安全。
- 输出短、稳定、可 grep。
- 失败时给下一步建议。
- 支持
--json或机器可读摘要。 - 把噪音日志折叠到文件，终端只输出结论。
- 能在 CI、Cloud Agent 和本地一致运行。
例如，与其让 agent 记住一串 workspace 命令，不如提供 repo-dev start api、repo-dev test checkout、repo-dev diagnose auth 这类稳定入口。
7. 任务 spec 模板
每次交给 Cloud Agent 的任务，至少要包含：
| 字段 | 内容 |
|---|---|
| Goal | 要达成的用户可见结果 |
| Scope | 允许修改的文件、模块、页面或服务 |
| Non-goals | 明确不做的事 |
| Context | 相关 issue、日志、截图、失败命令、业务规则 |
| Commands | 必跑的 build / test / audit / screenshot 命令 |
| Secrets | 需要哪些 secrets，以及不能输出什么 |
| Evidence | 期待的 diff、日志、artifact、PR comment 或截图 |
| Rollback | 出错时如何撤回或关闭 automation |
任务越像正式工单，Cloud Agent 越容易交付可 review 的结果。
8. 商业级验收
Cloud Agent 输出后，不要只看 summary。按证据验收：
- PR diff 是否只触碰 scope 内文件。
- build / lint / tests 是否真实运行。
- UI 改动是否有 screenshot 或 video artifact。
- MCP / external tool 调用是否符合权限预期。
- secrets、客户数据、后台截图是否没有进入 artifacts。
- CI failure autofix 是否没有超过团队允许边界。
- 失败时是否能从 logs 看清下一步。
如果一次任务需要人工大量补问，先修 instructions、环境和工具，再继续放更多任务。
9. 迭代顺序
当 Cloud Agent 质量不稳定，按这个顺序修：
- 环境：依赖、start、test、secrets、网络。
- 上下文：
agents.md、rules、skills、示例。 - 工具：MCP、自定义 CLI、短输出诊断命令。
- 任务 spec：目标、scope、验收、禁止项。
- 自动化：只有前四项稳定后再加 schedule、webhook 或 PR trigger。
不要先做 Automations。自动化会放大不稳定性。
本章自检
- repo 是否能被 Cloud Agent 像人类开发者一样安装、启动、测试？
- secrets 和 egress 是否在 dashboard 和网络规则中准备好？
agents.md或 skills 是否覆盖常见服务和测试路径？- 是否给 agent 提供了短、稳、可验证的工具？
- 每个任务是否有明确 evidence，而不是只要自然语言总结？
通过标准：你能连续运行 3 个 Cloud Agent 任务，且每次都有可复现命令、清晰 diff、必要 artifacts 和低返工率。
官方来源
- Cursor Cloud Agent Best Practices —— 官方环境、secrets、egress、skills、agents.md、MCP 和 custom tools 建议。
- Cursor Cloud Agent Setup —— 官方环境配置。
- Cursor Skills —— 官方 skills 背景。
- Cursor MCP —— 官方 MCP 背景。
- Cursor Cloud Agent Security —— 官方网络和安全边界。