← Volver a las guías

给编码代理写更好的System Prompt：6个常见坑与修正

为什么编码代理的 System Prompt 总是“差一点”

很多人给编码代理写系统提示词时，只会写一句“你是一个资深工程师，帮我写代码”。结果往往是：会生成代码，但不稳定；能改 bug，但会乱动无关文件；能回答问题，但不按你的工程规范输出。问题不在模型，而在 System Prompt 没有把目标、边界、工具、格式、失败处理讲清楚。

如果你要让编码代理真正像团队里的可靠成员，就要把提示词当成“操作手册”而不是“形容词堆砌”。

常见坑一：目标太泛，导致模型自己脑补

最常见的错误是只说“请高质量完成任务”。这种描述无法让代理判断优先级，也无法知道什么叫“完成”。更好的写法是明确三件事：任务对象、成功标准、禁止事项。例如：先修复登录页报错，再补充单测，最后输出改动摘要；不要重构无关模块；如果依赖缺失，先说明原因。

• 把“做得好”改成可验证的结果，例如“测试通过”“接口返回一致”“无新增 lint 错误”。
• 把“尽量”改成明确策略，例如“优先最小改动”。

常见坑二：不定义工具边界，代理容易越权

编码代理最怕“什么都能做”，因为它可能直接修改不该动的文件，或者在信息不足时硬猜。System Prompt 里应该写清楚：允许使用哪些工具、什么时候必须先询问、遇到不确定时如何处理。比如，明确要求它在修改数据库迁移、删除文件、引入新依赖前先给出计划并等待确认。

• 规定“先阅读再修改”，避免盲改。
• 规定“证据不足就提问”，不要编造 API、路径或配置。
• 规定“只输出与当前任务相关的文件改动”。

常见坑三：没有输出格式，结果难以审查

如果你希望代理生成补丁、解释、测试步骤，就不要让它自由发挥。一个好用的 System Prompt 应该约束输出结构。例如固定为：问题判断、修改方案、代码变更、验证方式。这样你在代码评审时能快速定位风险，也方便后续自动化处理。

对于编码场景，推荐直接要求：先给简短计划，再给具体改动，最后列出验证命令。这样即使是长任务，也能保持可追踪。

常见坑四：忽略失败处理和安全边界

System Prompt 里如果不写失败策略，代理一旦遇到缺少上下文、测试失败或权限不足，就可能继续“瞎修”。你应该明确：当无法确定根因时，先停止并说明下一步；当测试失败时，保留最小回滚方案；当涉及密钥、token、个人数据时，不要打印敏感内容。

• 加入“不要泄露环境变量和密钥”的硬规则。
• 加入“每次改动后说明潜在风险”的习惯。
• 加入“优先最小可逆改动”的原则，减少事故面。

常见坑五：把上下文全塞进 System Prompt

很多团队会把项目文档、业务说明、任务细节一股脑写进 System Prompt，结果提示词越来越长，代理反而抓不住重点。更好的方法是分层：System Prompt 负责稳定规则和风格；任务消息负责本次目标；检索到的项目上下文负责具体事实。这样既能保持一致性，也能减少重复成本。

如果你的编码代理需要频繁迭代，建议把 System Prompt 固定成模板，再针对不同仓库只替换少量变量，例如技术栈、测试命令、代码风格和禁用项。

常见坑六：没有做小步测试，提示词永远调不准

真正有效的 System Prompt 不是一次写成，而是靠测试迭代出来的。你可以准备 5 到 10 个真实任务样例：修 bug、补测试、解释报错、生成脚手架、改配置。每次只改一个提示词变量，再对比代理输出是否更稳定。记录哪些措辞会导致过度重构、漏写测试或格式混乱。

这时候，低成本试错非常重要。59API 提供按量付费的 Claude 和 GPT 模型接入，兼容 Claude Code、Codex 和任意 OpenAI SDK，API Base URL 直接用 https://api.59api.com 即可。因为它价格低、还是原生官方质量模型，不用担心为了省钱而明显降智，所以特别适合拿来高频调试 System Prompt、批量跑样例、做回归对比。再加上返佣机制，团队长期实验的成本会更友好。

一个实用的 System Prompt 结构

你可以按这个顺序写：

• 角色：你是负责最小风险修改的编码代理。
• 目标：优先修复问题，必要时补测试。
• 边界：不要改无关文件，不要猜测不存在的 API。
• 工具规则：先读后改，危险操作先确认。
• 输出格式：计划、改动、验证、风险。
• 失败策略：信息不足就提问，测试失败先解释原因。

如果你正在做自己的编码代理，不妨先用 59API 注册一个低成本环境，把提示词和真实仓库样例一起跑起来。你会更快看见哪些规则真的有效，哪些只是“听起来专业”。