外观
第 5 章 Research Brief：Instructions 与 Prompt
任务与读者问题
第 4 章把可靠性落实为目标、约束、观察和验证。第 5 章要回答一个更小但更常见的问题：当一个 Agent 需要长期遵守项目规则、完成某次任务、读取外部资料并交付固定格式时，怎样避免把所有内容拼成一段无法审查的 Prompt？
读者完成本章后，应能为一个任务区分稳定规则、项目规则、任务请求、待处理数据与输出契约；能在冲突时先定位来源、作用范围和优先级，而不是靠增加句子或强调语气解决问题。
范围与非范围
范围： 研究指令层的分层、冲突处理、清晰表达、结构化输出、Prompt 版本化与测试。使用 Codex 和 Claude Code 的项目文件作为“项目指令可以持久化”的产品例子；使用 OpenAI Model Spec 作为特定产品的指令权威链例子；使用 Google 与 Anthropic 的官方文档限定 Prompt 清晰性、结构化内容与输出验证的建议范围。
非范围： 不把 system、developer、user、AGENTS.md 或 CLAUDE.md 写成跨产品的统一协议；不复刻任一厂商的 Prompt 模板；不承诺 Prompt 可以绕过安全、权限或工具边界；不把语法正确的 JSON 写成业务正确的结论；不在本章设计检索、长期记忆、工作流状态机、工具协议或 Sandbox。
研究问题与当前结论
| 研究问题 | 所需一手证据 | 当前限定结论 |
|---|---|---|
| 发生冲突时，某个产品如何区分指令权威？ | 模型或平台公开的指令层级说明。 | REF-010 描述 OpenAI Model Spec 中 root、system、developer、user、guideline 的权威链。它是该 Spec 的预期行为与文档模型，不是所有模型或所有 API 的通用层级，也不保证生产模型完全实现该 Spec。 |
| 项目规则能否作为持久上下文而不是每次粘贴？ | 工具官方文档。 | REF-005 描述 Codex 的 AGENTS.md 发现、组合与目录邻近覆盖行为；REF-006 描述 Claude Code 的 CLAUDE.md 作为持久指令上下文。二者都只支持各自产品。 |
| 复杂 Prompt 如何提高可读性与可维护性？ | 官方 Prompt 指南。 | REF-011 建议使用清晰、具体的指令，并把复杂 Prompt 拆成更简单的组件；REF-013 建议将输出格式、约束和步骤说清，并用结构化标签区分指令、上下文、示例与输入。它们是各产品的 Prompt 建议，不是正确性的保证。 |
| 输出契约何时需要独立于自然语言 Prompt？ | 官方结构化输出文档。 | REF-011 建议复杂 JSON Schema 使用结构化输出特性；REF-012 说明语法正确 JSON 仍需在应用中验证值和业务语义。具体 API 形态与支持的 Schema 子集是动态信息。 |
| 为什么 Prompt 需要版本化和回归测试？ | 官方 API 行为说明。 | REF-014 明确模型快照之间的 Prompt 行为可能变化，并建议固定模型版本和运行评估；该建议只适用于其公开 API 语境，但可作为本章建立 Prompt 回归检查的来源背景。 |
已核验来源与可用陈述
| ID | 本章允许使用的陈述 | 来源类型与访问日期 | 不可外推范围 |
|---|---|---|---|
| REF-010 | OpenAI Model Spec 2025-10-27 将指令放入带权威级别的链中，高级别覆盖低级别。页面同时说明生产模型未必完全反映公开 Spec。 | OpenAI 公开 Spec，2026-07-15 访问；文档版本日期 2025-10-27。 | 不写成所有供应商、所有模型、所有消息 API 或所有运行时的真实优先级。 |
| REF-005 | Codex 可组合全局与目录层级的 AGENTS.md，靠近当前目录的文件在组合提示中覆盖更早指导。 | Codex 官方手册，2026-07-15 访问。 | 不作为 Claude Code、其他 Agent 或模型消息层级的实现说明。 |
| REF-006 | Claude Code 文档将 CLAUDE.md 描述为用户编写的持久指令上下文，并与自动记忆区分。 | Anthropic 官方文档，2026-07-15 访问。 | 不作为 Codex 加载、强制执行或权限机制的证据。 |
| REF-011 | Gemini API 文档建议清晰、具体指令；复杂 Prompt 可拆成组件；复杂 JSON Schema 建议采用该产品的 structured output。 | Google 官方文档，2026-06-10 更新，2026-07-15 访问。 | 不保证其他模型相同表现，也不保证响应语义正确。 |
| REF-012 | Gemini structured output 文档说明语法正确的 JSON 仍必须由应用验证值；Schema 合规结果也可能不满足业务逻辑。 | Google 官方文档，2026-07-07 更新，2026-07-15 访问。 | 不将该产品的 Schema 支持范围、SDK 或 API 字段写成通用 JSON 契约。 |
| REF-013 | Anthropic Prompting best practices 建议清晰、明确地表达输出与约束；可用 XML 标签将指令、上下文、示例和输入分开。 | Anthropic 官方文档，2026-07-15 访问；页面未显示稳定发布日期。 | 不把标签当成安全边界、通用语法或跨模型性能承诺。 |
| REF-014 | OpenAI API 文档说明模型快照之间的 Prompt 行为可能变化，并建议固定模型版本、使用 evals 保持一致性。 | OpenAI API 文档，2026-07-15 访问；页面未显示稳定发布日期。 | 不保证固定版本消除输出变化，也不把某一评估 API 作为本章的唯一实现。 |
本书的工程扩展
以下是本书为可维护 Harness 提出的内容模型，不是任何来源给出的统一产品协议：
- 平台或系统约束： 由运行平台或部署方规定的不可由任务文本随意改变的规则。该层是否可见、名称为何、是否存在，必须由具体产品核验。
- 项目规则： 仓库、团队或服务的稳定约定，例如允许的目录、审查标准、验证命令和禁止事项。它应被版本控制、可审查且可定位。
- 任务请求： 当前目标、输入、范围、验收条件和停止条件。它应随任务变更，不能覆盖更高层已声明的约束。
- 上下文数据： 文档、日志、网页、代码片段和工具结果。它们用于解决任务，但不能仅因被包含在 Prompt 中就获得指令权威。
- 输出契约： 需要返回的字段、格式、证据和失败表示。格式契约应与业务验证分开；Schema 通过不等于任务通过。
本章会明确“项目规则”在具体产品中可能被装配为不同角色或不同上下文位置。因此它不在书中预设绝对优先级，而是要求 Harness 在装配时写明来源、作用范围、冲突策略和验证方式。
计划叙述与工件
- 用“同一段代码审查要求被复制到五个 Prompt，规则修正后仍有一处漏改”的教学场景解释 Prompt 碎片化。
- 给出稳定规则、项目规则、任务请求、上下文数据和输出契约的分层表，并说明它是本书工程模型。
- 建立冲突处理流程：识别来源与作用范围 → 按已声明的产品或 Harness 规则裁决 → 记录拒绝或降级的内容 → 验证输出，而不是继续叠加指令。
- 解释“清晰、具体、可分段”与“内容必须更长”不同；将复杂 Prompt 拆成可独立审查的组件。
- 解释输出格式、JSON Schema、业务验证的边界，并用 Prompt 回归样例说明版本化的必要性。
计划图示、案例与示例
计划图示： chapter-05-instruction-assembly.mmd 将展示项目规则、任务请求、数据上下文和输出契约如何被 Harness 装配；数据进入时标记为数据而不是规则；最终由冲突处理和验证返回可观察结果。图不描绘任何特定产品的内部提示词、隐藏指令或真实消息顺序。
计划案例： “代码审查 Agent 的规则化重构”。将散落在聊天 Prompt 中的稳定审查规则收敛为项目规则，将本次 diff、测试输出和问题描述放入任务与数据层，将 must_fix、should_fix、suggestion 和证据字段定义为输出契约。案例是教学设计，不是本仓库或外部团队的真实审查记录。
计划示例： 一个纯内存的 assembleInstructionPacket 接口：输入为已命名的项目规则、任务 Brief、数据片段和输出契约；输出为组件清单、来源清单、冲突结果与待验证的结构化请求。它不会调用模型、网络、真实文件、环境变量、凭证或外部工具，也不验证任何供应商的消息优先级。
研究风险与待核验项
TODO(verify)：正文写作当天重新访问 REF-005、REF-006、REF-010 至 REF-014；其中产品加载规则、模型指令行为、结构化输出限制和 API 说明可能变化。TODO(verify)：若正文展示任何产品 SDK、请求字段、模型名、模型快照、Schema 子集或版本，必须使用当日官方 API 参考重新建立字段级证据，不得从本 Brief 推断。TODO(verify)：若案例加入 Prompt injection、敏感数据、权限或工具调用细节，必须引入第 11、12、41 章所需的一手安全与协议资料；本 Brief 不将标签、分层或输出 Schema 当作安全控制。- 当前没有声明可运行示例、Mermaid 导出、产品 API 调用或 Prompt 性能基准已经实现或验证。
Research 完成检查
- [x] 明确了本章的读者问题、范围、非范围和相邻章节边界。
- [x] 重新核验了七项一手来源，并为每项限定允许与禁止用途。
- [x] 将系统/项目/任务/数据/输出契约写为本书工程模型，而不是统一产品层级。
- [x] 建立了计划图示、教学案例、纯内存示例边界和待核验项。
- [x] 未提前写入正文、产品 SDK、性能主张、真实工具行为或未验证的安全结论。