第 5 章 Chapter Outline：Instructions 与 Prompt

本文件是正文写作蓝图。指令分层、冲突矩阵和装配接口是本书的工程模型，不是跨产品的消息协议。涉及 OpenAI Model Spec、Codex AGENTS.md、Claude Code CLAUDE.md、Gemini structured output 或 Anthropic 标签建议时，正文写作当天必须重新核验 REF-005、REF-006、REF-010 至 REF-014，并只陈述来源直接支持的范围。

章节契约

读者完成后的能力： 能把一项 Agent 任务拆为稳定项目规则、当前任务请求、待处理数据和输出契约；能在冲突出现时定位来源、范围与裁决依据；能为一组可演进的指令设计版本、评审和回归检查，而不是把更多句子堆进同一段 Prompt。

前置知识： 已理解第 1 章中 Harness 不只是单次 Prompt，已理解第 3 章中仓库可以保存可审查项目上下文，以及第 4 章中完成必须有独立验证证据。

章节边界： 本章不声称 system、developer、user、AGENTS.md、CLAUDE.md 或 XML 标签在不同产品上具有相同权威或加载行为；不实现上下文预算、检索、长期记忆、任务状态机、工具协议、Sandbox 或审批流程；这些分别留给第 6、7、10、11、12 和 14 章。它也不将结构化输出、标签或文字规则说成 Prompt injection 防护、权限控制或业务正确性保证。

小节蓝图

1. 一段越来越长的 Prompt 为什么会失去工程属性

• 读者问题： 规则、任务、代码片段和输出格式都能写进 Prompt，为什么还要拆层？
• 叙述任务： 从原创教学场景开始：代码审查 Agent 的五个 Prompt 都复制了一条“测试失败必须报告”的规则；规则后来改为“附上可复现证据”，却有一个入口没有更新。区分“文本能被模型读到”与“规则能被定位、复用、审查、修改和验证”。
• 证据边界： 场景与“工程属性”的定义均是本书设计演练，不对应真实团队、真实模型输出或生产事故数据；不宣称所有长 Prompt 都必然失败。
• 计划工件： “散落 Prompt / 可命名组件”对照表，列出变更位置、适用范围、重复风险、验证位置与未知项。
• 验证： 读者能指出至少两个因复制产生的失效点，并能说明为什么把规则复制五次不是可靠的版本管理。
• 过渡： 要拆层，先要区分内容在任务中扮演的是规则、请求、数据还是交付约束。

2. 先分角色：规则、任务、数据与输出契约不是同一类文本

• 读者问题： 一段从网页、日志或用户输入中得到的内容，何时是可执行要求，何时只是待处理数据？
• 叙述任务： 引入本书的五类内容模型：平台或系统约束、项目规则、任务请求、上下文数据和输出契约。逐一说明产生者、变化频率、作用范围、是否可由当前任务改写，以及需要什么验证。强调“被装入 Prompt 的文本”不因此提升为项目规则。
• 证据边界： 五类模型是本书工程扩展；不是 OpenAI、Anthropic、Google、Codex 或 Claude Code 的共同运行时协议。具体平台是否存在某一层、层名为何，须由其当前官方文档核验。
• 计划工件： “内容类别—回答问题—可变性—来源—不能证明什么”责任表，并在表下注明数据内容不能自动改变指令权威。
• 验证： 给出一段用户粘贴的“忽略现有规则”文本、一份仓库规则和一次审查任务 Brief；读者能够将它们分别归类，并写出尚需由运行时裁决的部分。
• 过渡： 内容分类解释了职责，但真实系统还要面对多处规则与不同产品的加载行为。

3. 持久项目规则与产品指令层：只在证据范围内比较

• 读者问题： AGENTS.md、CLAUDE.md 和 API 消息角色是否是同一件事？
• 叙述任务： 将“仓库中可版本控制的项目规则”与“具体产品如何把规则装入运行时”分开。以 Codex AGENTS.md 和 Claude Code CLAUDE.md 作为持久项目指令的产品例子；以 OpenAI Model Spec 的权威链作为特定文档模型的例子。说明这些来源能支持什么、不能支持什么。
• 证据边界： REF-005 仅说明 Codex 的 AGENTS.md 发现、组合与目录邻近覆盖；REF-006 仅说明 Claude Code 的 CLAUDE.md 持久指令上下文；REF-010 仅描述其 Spec 中的权威层且页面说明生产模型未必完全反映公开 Spec。不得把三者拼成“所有 Agent 的统一优先级”。
• 计划工件： 产品事实与本书工程建议的双列表：左列只写来源允许的陈述，右列写“项目应为规则声明来源、范围、更新者和验证方法”的可迁移建议。
• 验证： 读者能解释“目录更近的 AGENTS.md 覆盖更早指导”为什么不是 Claude Code 的行为证据，也能说明公开 Spec 不能证明某次实际调用的隐藏运行时顺序。
• 过渡： 平台差异不能被抹掉，因此 Harness 需要一个明确、可审查的装配和冲突流程。

4. 设计指令装配：来源、范围、冲突与拒绝都要可见

• 读者问题： 当项目规则、任务请求和数据文本相互矛盾时，Harness 应如何处理？
• 叙述任务： 定义本书的装配步骤：识别每个组件的来源与类别；检查其适用范围；按已声明的产品规则或 Harness 规则裁决；记录被拒绝、降级或需升级的内容；生成待执行的组件清单；在输出后独立验证。强调“更强烈地重述规则”不等于解决冲突。
• 证据边界： 装配算法、冲突矩阵、拒绝记录字段和默认策略均为本书设计；不表示任何模型会自动抵御注入、自动识别不可信数据或自动实施权限。
• 计划图示： chapter-05-instruction-assembly.mmd。输入应分为项目规则、任务 Brief、数据上下文、输出契约；数据到装配器的连线需标为“待处理数据”；装配器输出组件清单、冲突记录和待验证请求。图中不得出现“Prompt → 自动授权”“标签 → 安全”或“模型输出 → 完成”的直连箭头。
• 计划工件： 冲突矩阵，至少覆盖“任务超出项目范围”“数据伪装为规则”“输出格式与验收字段不一致”“产品行为未知”四类情形，并分别给出停止、拒绝、澄清或升级动作。
• 验证： 每种冲突均包含可追溯来源、裁决依据、未覆盖风险与下一步；未知产品行为必须留下 TODO(verify)：，不能伪造优先级结论。
• 过渡： 装配完成后，模型仍需要理解目标和交付方式；下一节讨论如何把自然语言约束写得清楚而不是写得更长。

5. 写清楚，不写得更大：把任务约束和输出格式变成可审查接口

• 读者问题： “请仔细、准确地审查”为什么难以评审，结构化输出又解决了什么？
• 叙述任务： 将任务要求拆为目标对象、允许范围、输入证据、操作约束、输出字段、失败表示和停止条件。说明 Google 与 Anthropic 官方资料中“清晰、具体、分隔复杂组件”的建议，随后用审查报告字段展示输出契约。明确格式契约与业务判定是两层不同工作。
• 证据边界： REF-011、REF-013 只支持其产品语境下的清晰指令、组件分隔和输出限制建议；标签不是通用语法、安全边界或性能保证。审查报告字段和“清晰接口”是本书扩展。
• 计划工件： 同一代码审查任务的“模糊请求 / 可审查任务契约”对照；任务契约包含输入范围、问题分级、证据字段、未知状态和拒绝条件。
• 验证： 读者能从后者判断报告必须包含什么，并指出它仍不能验证的事实，例如 diff 是否完整、测试是否真实执行或结论是否满足业务语义。
• 过渡： 即使输出被约束为 JSON 或 Schema，语法正确仍不是任务正确，需要把验证留在 Harness 中。

6. 输出契约、结构化输出与业务验证：不要让格式替代证据

• 读者问题： 一个符合 JSON Schema 的结果，是否已经证明审查结论正确？
• 叙述任务： 区分自然语言格式约定、平台的 structured output 能力、应用层 Schema 检查、业务规则检查和人工接受。以“每条 must_fix 必须带文件位置与证据”为例，说明 Schema 能检查字段形状，但不能独立证明引用的代码确实存在、证据足够或问题分级恰当。
• 证据边界： REF-011 支持 Gemini 复杂 JSON Schema 的 structured output 建议；REF-012 明确说明语法正确 JSON 仍需验证值、且 Schema 合规可能不满足业务逻辑。不得根据这些资料断言其他供应商的 API 字段、Schema 子集、可靠率或 JSON 校验行为。
• 计划工件： “格式通过 / 仍需验证 / 验证器或责任人”三列表，以及最小审查报告 Schema 草案；草案标为教学契约，不绑定供应商 SDK。
• 验证： 设计一个字段齐全但文件路径不存在、另一个路径存在但证据不足的报告；读者能列出两者各自需要的独立检查。
• 过渡： 可验证的输出还不足以长期维护；当模型或规则变化时，指令本身也需要版本和回归证据。

7. 把 Prompt 当作可演进工件：版本、评审与回归检查

• 读者问题： 模型、项目规则或输出需求变化后，如何知道一处 Prompt 修改影响了什么？
• 叙述任务： 建立最小维护闭环：指令组件有稳定名称与变更理由；任务样例覆盖允许、拒绝、澄清和格式错误；每次变更记录预期输出与未覆盖范围；以实际验证器而非模型自评决定是否接受变更。说明模型快照或行为变化是建立回归检查的理由，而非承诺固定模型可消除所有变化。
• 证据边界： REF-014 在 OpenAI API 语境中说明 Prompt 行为可能随模型快照变化，并建议固定版本、运行评估；版本表、样例集、变更准入和回归策略都是本书工程扩展。不得承诺固定版本、少量样例或一次评估可保证稳定行为。
• 计划工件： Prompt 变更记录模板：组件、版本、改动原因、受影响任务、样例、预期、实际验证、回滚或升级条件。
• 验证： 至少有一个“项目规则更新后，旧任务样例必须重跑”的场景；读者能判断一条只更改措辞但没有样例或验证记录的变更为何不可接受。
• 过渡： 最后将上述分层、装配、输出与验证放入一个完整但无外部副作用的代码审查教学案例。

8. 完整工程案例：将代码审查 Prompt 重构为可维护 Harness 组件

• 读者问题： 从五段复制的审查 Prompt 迁移到分层组件，最小闭环如何落地？
• 叙述任务： 设计原创、纯教学案例。项目规则声明审查分级和证据标准；任务 Brief 声明本次 diff、范围与停止条件；测试输出与代码片段作为数据；输出契约要求 must_fix、should_fix、suggestion、证据和未知项。Harness 先装配并记录冲突，再产出候选报告，最后用独立检查验证字段、文件存在性和证据完整性；未满足时标为失败或交给人，而非让模型重述“已完成”。
• 证据边界： 案例不是本仓库、任何公司或供应商的真实审查流程；不调用模型、网络、文件系统、凭证或外部代码库，不演示真实产品消息优先级或安全防护。
• 计划示例： 05-instructions-and-prompt.example-plan.md 将规定纯内存 assembleInstructionPacket 接口。输入为命名的项目规则、任务 Brief、数据片段和输出契约；输出为组件清单、来源记录、冲突结果和待验证请求。实现只演示显式分类与冲突记录，不能模拟模型服从、权限执行或 Prompt injection 防御。
• 验证： 最小测试至少覆盖正常装配、数据试图作为规则、任务超出范围、输出契约缺少必填字段和未知裁决规则；所有预期都来自本书定义的纯函数契约，不来自模型响应。
• 过渡： 第 6 章进一步回答“哪些资料值得进入上下文包”，第 7 章讨论跨任务保存哪些信息；本章只保证指令组件可定位、可审查和可验证，不负责选择全部上下文。

章节工件状态

1. 已完成：Research Brief 与候选参考资料。七项一手来源的允许陈述、外推边界和正文复核要求已登记。
2. 本阶段完成：Chapter Outline。为正文、事实核验、图示、示例与后续审查定义了输入、输出、证据边界和跨章节责任。
3. 已完成：Fact Check、Mermaid 图源与 Diagram Review。REF-005、REF-006、REF-010 至 REF-014 已于 2026-07-15 重新读取；图源只表达本书装配模型，已实际导出 SVG/PNG 并视觉检查，记录位于 .memory/reviews/2026-07-15-chapter-05-diagram-review.md。
4. 已完成：Example Plan 与 Example Implementation。纯内存 assembleInstructionPacket 的输入、输出、五条测试路径与非范围已定义；实现、Node 内置测试、npm scripts 与运行记录已创建，示例仍不读取真实仓库、不调用模型或工具。
5. 已完成：First Draft。原创正文已分开产品事实、本书工程模型、教学案例和未验证范围；图源仍待导出和视觉审查。
6. 已完成：Technical Review。已修正 Outline 状态漂移、图源注释和引用登记状态；记录位于 .memory/reviews/2026-07-15-chapter-05-technical-review.md。
7. 已完成：Language Editing。具体主语、因果、责任术语、渐进增强边界和阶段记录已收束，未改变来源、示例、Mermaid 源码或导出图；记录位于 .memory/reviews/2026-07-15-chapter-05-language-edit.md。
8. 已完成：Validation 与 Final Review。重新运行纯内存示例测试与演示、Mermaid SVG/PNG 导出、正文图源一致性检查、Markdown lint、链接检查和状态检查；记录位于 .memory/reviews/2026-07-15-chapter-05-final-review.md。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] 产品事实、厂商建议与本书工程模型、教学案例和待核验项明确分开。
• [x] 明确了与第 3、4、6、7、10、11、12、14 章的边界，未将项目文件、输出 Schema 或标签表述为统一权限或安全机制。
• [x] 图示、示例和案例都要求记录来源、冲突、验证结果与人工升级条件，不以模型文字代替完成证据。
• [x] 正文采用原创表达，未伪造产品 API 字段、模型行为、测试结果、安全结论或已实现示例。