编程代理提示词的结构与要素

面向编程代理的提示词与面向聊天问答的提示词不同：最终交付物是可运行、可验证、边界清晰的代码变更，因此更强调约束、文件边界、验收标准和上下文供给方式。本节给出结构化要素、上下文供给原则，以及从模糊到优秀的提示词对照。

一、编程任务提示词的六要素

要素	要写清的内容	常见遗漏
任务与角色目标	要完成什么改动、希望代理承担什么（先调研/先实现/只给方案）	只说"优化"，不定义交付物
上下文与相关文件	项目现状、相关模块、关键文件或符号位置，让代理先读取理解	不提供定位，代理盲目全局搜索
明确目标	完成后系统应具备的行为或结果	目标与多个不相关要求混杂
约束与风格	兼容性、技术栈限制、命名/风格、禁止改动范围、依赖约束	不写排除项导致越界修改
验收标准	测试、构建、类型检查、具体行为与边界条件	缺少"怎样算完成"的判据
协作方式	先出计划还是直接改、是否分步确认、改动规模上限	默认一次性大改、难以审查

二、上下文供给原则：让代理读文件，而不是你贴全文

• 指向定位优于粘贴源码：给出文件路径、模块名、函数或报错位置，让代理用读取工具按需查阅；把整份源码粘进对话既占上下文又容易版本失真。
• 先理解后动手：对陌生代码先用计划模式（/plan）让代理阅读并说明思路，确认理解一致后再实现。
• 把关键事实写进 CLAUDE.md：反复出现的技术栈、构建与测试命令、约定沉淀到项目记忆，避免每轮重复交代。
• 提供可复现的失败现象：修复类任务要给复现步骤、报错关键信息与输入样例，而不是只说"这里有 bug"。

三、结构化提示模板（自然语言，非命令）

任务：实现/修复/重构 <一句话目标>，先出方案确认后再改代码。
上下文：项目为 <技术栈>，相关代码在 <文件/模块/符号>，当前现象是 <现象/报错/输入样例>。
目标：完成后应满足 <具体行为结果>。
约束：保持 <兼容性/签名/风格>；不要修改 <排除范围>；不新增不必要依赖。
验收：运行 <测试命令/构建命令/类型检查> 全部通过；覆盖 <边界条件>。
节奏：先给改动计划与影响文件清单，确认后分步实现，每步可单独验证。

四、提示词质量对照

等级	典型写法	结果倾向
模糊	"帮我把这个函数改好一点"	范围不清、标准缺失、反复返工
合格	说明目标与相关文件，要求先出方案、跑现有测试	方向基本可控，细节仍需多轮补充
优秀	六要素齐备，含排除范围、验收命令、边界条件与分步节奏	一轮即可得到边界清晰、易审查的改动

五、高频误区

• 单提示承载多个目标：如"修 Bug、加缓存、顺便改样式、补文档"，应拆分独立任务。
• 过度指定实现细节：强代理按你设想的具体写法可能忽略更合适的方案，通常应约束结果与约束、把实现选择留给探索。
• 缺少验证闭环：不指定测试与构建命令，代理缺少客观完成标准。
• 把不确定信息当成事实陈述：需求不明时应先澄清，而不是让代理替你猜测关键决策。