任务提示词结构与上下文提供

第 3 章讲了单条任务的五要素，本节再进一步，解决提示词内部如何组织、上下文材料如何高效供给的问题。结构化的提示词让代理先定位、再判断、后动手，避免在无关内容上反复检索；本节方法同时适用于 codex 交互会话与 codex exec 非交互任务。

一、提示词的六层结构

层次	回答什么问题	推荐写法	缺失后果
角色/任务定位	这次要完成什么性质的工作	一句话说明任务类型，如"修复接口超时 Bug""给现有模块补测试"	代理把任务按泛化方向处理，重点偏移
背景现状	为什么做、当前处于什么状态	说明相关模块、已有行为、已知问题线索与基线前提	凭空假设现状，结论脱离代码实际
明确目标	成功的结果是什么	写成可检验的结果陈述，而非形容词堆砌	无法判断是否完成，只能反复改稿
范围与约束	允许做什么、禁止做什么	列出可改目录、不可改签名/依赖/风格项，否定项单独写明	夹带重构、越权修改、改动面失控
验收标准	用什么证据确认完成	指向可运行的构建/测试/行为结果，列出不得出现的问题	以"看起来差不多"收场，遗留隐患
输出与流程要求	先给方案还是直接实现、结果如何呈现	中等任务要求先列方案与文件清单；明确改动说明应包含哪些要点	节奏不可控，缺少可供复核的中间产物

二、上下文材料的高效提供

材料类型	推荐提供方式	常见错误
相关代码位置	指明关键文件路径、函数名或模块名，让代理按需阅读	把整个仓库源码大段粘贴进提示词，稀释重点、增加噪声
项目既有约定	给出约定所在位置或摘要，如命名风格、错误处理惯例	不交代约定，代理按通用风格随意发挥
验证入口	给出运行测试、构建或复现问题的命令入口（以项目实际脚本为准）	不给验证方式，代理无法自证改动有效
参考样例	提供一个同类正确实现作为对照，说明要模仿的做法	只描述抽象标准，缺少可参照的具体例子
当前工作区状态	开始前用 git status 确认基线干净，避免把未提交改动混进新任务	在脏工作区下达任务，新旧改动难以区分回退

三、按"探索—方案—实现"组织表达节奏

1. 先界定探索范围：要求先只读了解相关实现与调用关系，不直接改文件，对应保守/只读的起步姿态。
2. 再输出方案：让代理汇总拟修改文件、实现步骤、风险点与验证方式，人工确认后再进入实现。
3. 后执行实现：方案确认后给出实现指令，配合范围约束与验收标准，使每一步都可复核。
4. 每步留检查点：把大目标拆成可独立验证的小步，避免一次产出难以审查的大量改动。

四、上下文冗余、冲突与时效

• 去重：同一约定只在上下文里说一次，重复表述会占用篇幅且可能被理解为强调特例。
• 消除矛盾：避免同时给出"不要改风格"和"统一命名风格"这类相互冲突的要求；先确定取舍再写入。
• 区分时效：把长期项目约定与本次任务的临时约束分开表述，避免临时要求被当成永久规则延续。
• 最新指令覆盖：多轮推进中若前一轮约束被调整，明确说明"以本轮为准的部分"，防止旧约束残留干扰。

五、FAQ

问题	处理建议
提示词是不是越长越好	不是；六要素齐全且重点突出即可，冗余粘贴会降低信噪比与代理定位效率。
仓库很大怎么给上下文	给模块路径与关键符号，让代理按需探索，而不是一次性投喂全量代码。
需要先让代理调研再实现怎么表达	在流程要求层写明"先只读调研并给出方案清单，确认后再修改"，再配合保守起步策略。
非交互任务如何套用六层结构	把六层全部写进单条 codex exec 任务描述；无人值守缺少现场对话，约束与验收必须前置写死。

六、动手练习

• 练习：选取一个真实小任务，按六层结构重写提示词，标注每层对应内容；再与"一句话需求"版本对比代理产出的偏差和可审查性。