从案例到范式

从观察到行动

案例页面走过了一份真实生产提示词里的 47 个设计动作。那是观察。这一页是行动 —— 把同样的材料转成一个你能照做的流程。

两部分：

10 步设计方法，从案例和前面的理论页面蒸馏而来。每一步说清做什么、为什么重要、如何检查你做到了。
升华：当单体 prompt 不再够用时，同样的 10 步会自然延伸到组合式设计 —— prompt 在运行时由多层装配而成。大多数不变量原封不动；少数换了形态；组合式设计本身引入了新问题。

目标是让读者合上这页就能开始写，并且知道什么时候该停止写散文、开始写分层。

第一部分 —— 方法

十步，大致按你真正写的顺序。

Step 1 —— 声明 Role、Medium、Power

做：写三句短的。Agent 是谁、产出什么媒介、和用户什么关系（同事？助手？向 manager 汇报？）。

为什么：具体的声明会渗透到下游每个决策 —— 语气、用词、行动意愿。抽象角色（“乐于助人的助手”）逼模型自己猜细节；具体角色（“TypeScript 后端的资深审查员，向用户汇报”）不用。

检查：新来的工程师读你开头三句话，能不能不问你就回答”这个 Agent 是做什么的、为谁服务”。

见提示词设计 → 角色声明是超比例杠杆；案例领域 1.1–1.2。

Step 2 —— 填满 Skeleton 解剖位

做：六个功能位全填 —— Role / Capabilities / Behavioral Rules / Workflow / Output Standards / Escape Hatch。缺任何一个都是已知的运行时翻车源。

为什么：Prompt 翻车最常不是规则写错，而是规则缺席。解剖位是每份 prompt 都需要的功能清单，和任务无关。

检查：指出处理”Agent 困惑时怎么办”的那一行。指不出来，逃生通道就缺了。

见提示词设计 → 提示词解剖学；案例领域 1.5。

Step 3 —— 红线规则配触发 + 正向对偶

做：每条安全/声誉关键的规则都写三部分：禁令、一个 Agent 在生成中能自检的自触发、一个给模型替代产出的正向替代。

为什么：单纯”不做 X”是愿景 —— 模型不知道该干什么。“If you find yourself saying X, stop” 是可执行的。正向替代防住”禁令但无路可走”的死锁。

检查：对每条红线规则，Agent 能不能在生成中对照自己的输出，且知道该产出什么替代。

见案例领域 1.3–1.4；提示词设计 → 说该做什么。

Step 4 —— 谨慎选择 Markdown vs XML

做：Markdown 用于 prompt 自己的段落（角色、工作流、规则）。XML 标签用于模型要当数据、不当指令处理的内容 —— 分析中的文档、few-shot 示例、用户输入负载。

为什么：模型需要知道”我在问什么”和”我在问关于什么”的区别。XML 边界给它毫不含糊的信号；纯 Markdown 或纯 XML 会让边界模糊。

检查：指出你 prompt 里每一个 XML 标签。每个都应该包着模型消费的数据，不是它该执行的指令。

见提示词设计 → 结构：XML vs Markdown。

Step 5 —— 安装强调层级

做：设三层 —— 裸文（默认）、加粗（扫读到）、CRITICAL（不可商量）。CRITICAL 留给有生产事故史的规则。每条 CRITICAL 都配原因 + 替代。

为什么：强调是有限资源。满屏 NEVER 和 MUST 的 prompt 会让模型脱敏；CRITICAL 出现 3-4 次的 prompt 才把它留响亮了。原因 + 替代让模型能泛化到你没穷举的情况。

检查：数一下最终 prompt 里 CRITICAL 的数量。300 行 prompt 里超过 5 次就可疑。每一个都要有原因和”改做什么”。

见案例领域 2.1–2.2。

Step 6 —— 给你想覆盖的默认命名

做：在很多真实任务上观察你模型的产出。记下它不被约束时会抓什么 —— 俗套措辞、默认设计选择、安全但错误的推断。把它们列为显式反模式 + 正向替代。

为什么：通用”避免差 X”会被忽略。具体命名的默认（“避免渐变背景、避免 Inter/Roboto、避免装饰用 emoji”）才会被覆盖。只有你真的观察过产出才能写；你没见过的默认没法命名。

检查：能不能把每条反模式回溯到一个你不喜欢的具体产出？不能的话，你在猜。

见案例领域 3.1–3.5；提示词设计 → 如何度量。

Step 7 —— 按缓存排序：稳定在前，动态在后

做：把 prompt 块按稳定度从高到低排。工具 → 身份 → 长期上下文 → 耐用示例 → 消息历史 → 当前轮。

为什么：Prompt 缓存只命中稳定前缀。prompt 开头的动态 token 会废掉它之后的所有前缀 —— 而 prompt 每一轮都会被重读，缓存失误累积得飞快。

检查：指出缓存前缀结束的那个字符。它之前的一切都应该轮间不变。

见提示词设计 → 缓存感知的排序。

Step 8 —— 技能和工具做成注册表，不是倾倒

做：把可用能力（skills、starter、可选工具）按名字 + 一句话描述列出来。完整指令通过工具调用按需载入。

为什么：索引要在 prompt 里，Agent 才知道有什么存在；完整内容通常不用 —— 载入每个 skill 的完整 prompt 会是几千行注意力税，每个任务用到的只是其中一小部分。

检查：无论有多少能力，你的”可用能力”节能不能保持在 ~30 行以内？如果它线性增长，你就在背包袱。

见上下文管理 → 即时上下文；案例领域 5.1。

Step 9 —— 装度量回路

做：开始迭代之前就搭好一份固定的评测集 —— 20 到 50 条真实输入 + 期望行为。每次 prompt 改动都跑一遍。跟踪哪些通过、哪些失败、哪些失败模式变了。

为什么：没有度量，prompt 迭代就是随机游走。为修最新边界情况加第 47 条规则破坏规则 #1-46 的概率比你以为的高 —— 而没有这套装置，你看不到破坏。

检查：此刻，你能不能说出你当前 prompt 在一个固定评测集上的通过率？说不出来的话，你在猜。

见提示词设计 → 如何度量；overview 的”关于度量”。

Step 10 —— 写末轮收尾纪律

做：显式规定末轮输出应该是什么样 —— 格式、长度、内容。用规定性语言，不用愿景性语言。

为什么：模型默认会啰嗦。“保持简洁”是愿景；“只说 caveats 和下一步”是规定。规定赢。

检查：你的末轮规则具体到两个读者会对同一个简单请求写出同样的响应了吗？

见案例领域 4.7。

第二部分 —— 方法在哪里触顶

上面 10 步假设一份 prompt、一个 Agent、一种任务类型。这个假设会一直成立直到它不成立。有几种症状会宣告单体 prompt 已经到顶：

工具集合按任务变化。 不同种类请求需要不同工具。单 prompt 只能把 if/else 写成散文 —— “做 X 时用这三个；做 Y 时用那四个” —— 每个用户的每一轮都在为用不到的工具付注意力税。
Agent 架构有多个角色。 主 Agent、子 Agent、Verifier。每个需要不同身份核心但共享某些策略。单 prompt 要么把它们都塞进一个人格（主 Agent 的 prompt 同时当 Verifier 用，别扭），要么拆成 N 份文件且没有共享基础。
段落需要独立版本化。 你只想 A/B 测工作流一段、不想碰安全规则。你想更新输出规范、不想冒险让红线执行回归。单体文件让这件事变成 copy-paste 作业，没有干净的回退。
多租户需求不同。 不同用户、不同计划、不同地区要不同约束。静态 prompt 要么把所有东西给所有人、要么按租户分叉，两种都难扩。
Prompt 超过了一次坐着能读完的长度。 你不能再从头读到尾不跑神。CRITICAL 标记因为数量过多正在失去显著性。规则开始互相矛盾。

所有这些症状的根因：Prompt 是一份静态文件，而情境本该呼唤一个函数。函数以当前任务、用户、tier、Agent 角色、工具集作为输入，产出那份情境合适的 prompt。单体方法试图把那个函数编码成分支散文；散文终究追不上。

第三部分 —— 升华到组合式设计

当单体模式不再够用，转变是架构层面的：系统提示词变成一个函数，不是一份文件。每一轮，prompt 都从多个层装配出来，每层贡献一段。

一种典型的层分解

任何组合式系统通常有这种形态 —— 名字会变，功能会复现：

层	贡献	随什么变
Identity	角色、行为规则、红线、策略	Agent 变体（主 / 子）
Tool prompts	每个启用工具贡献一段指令	Tier / 工具可用性
Memory 层	本用户或会话相关的持久记忆索引	用户 / 会话
Environment	日期、沙箱态、tenant、会话元信息	每一轮
Variant core	类型专属指令（主 vs 子 vs team member 取不同核心）	Agent 角色

模型看到的系统提示词就是这些层的拼接，每一轮装配一次。原则上没有任何层可缺；但某些层可以为空。

什么保持不变

10 步方法里的多数原封不动转移。只是它们现在是装配后 prompt 的属性，不是单一文件的属性：

Step 1 —— Role / medium / power。 住在 Identity 层。具体角色仍然胜过抽象角色。
Step 2 —— Skeleton 解剖。 现在分布在各层。角色 + 规则在 identity；能力在 tool prompts；工作流在 identity 或 variant。
Step 3 —— 红线配触发 + 对偶。 在 Identity 层；形态不变。
Step 5 —— 强调层级。 “CRITICAL 稀缺”的策略每层都要遵守，整个装配也要遵守。Identity 里用两次 + 某个工具 prompt 里用两次就已经是 4 次 —— 稀缺必须是全局的。
Step 6 —— 命名默认。 在 Identity 里。观察模型默认这件事无论 prompt 是单体还是组合都一样要做。
Step 9 —— 度量。 概念不变。你评测的是装配后的 prompt，不是单独的层 —— 不过追溯哪一层导致了回归现在是一份新工作。

什么换了形态

十步里有四步在组合时长得不一样：

Step 4 —— Markdown vs XML。 现在有两级：每层内部的结构 + 层之间的结构。层间分隔通常就是稳定的 markdown 标题；层内结构规则和之前一致。
Step 7 —— 缓存感知排序。 不再是关于文件里的字符位置。现在每一层声明自己的稳定度 —— 有的层跨任务缓存（identity、tool prompts），有的跨会话缓存（memory 层），有的从不缓存（environment）。装配代码按稳定度把层排到前或后，但声明住在层里，不在装配器里。
Step 8 —— 技能注册表。 在组合式系统里，这有时就不是 prompt 的一段了；它就是 tool prompts 层本身。启用的工具贡献自己那段；禁用的工具什么都不贡献。注册表就在”层是否在场”里隐含着。
Step 10 —— 末轮收尾纪律。 常常放在 variant 层，因为主 Agent 和子 Agent 有不同输出契约。主 Agent 写面向用户的摘要；子 Agent 写供父 Agent 消费的结构化结果。同一原则，不同变体下的不同细节。

组合式设计引入的新问题

组合式不是免费的。它制造了一类单体 prompt 没有的问题：

顺序契约。 层必须按确定顺序拼接。谁声明这个顺序？是配置、约定、还是装配器里硬编码？每个真实系统都要回答这个。
冲突解决。 如果 Identity 层说”总要和用户确认”、某个工具 prompt 说”立即行动”，谁赢？组合式系统需要：(a) 优先级规则，(b) 禁止层与 identity 矛盾的策略，或 (c) 装配前的 lint 检查。
版本化。 每层有自己的发布周期。回滚 identity 层的坏改动不应该撤回工具 prompt 的无关改进。文件级 Git 版本化在这里表现不佳；你需要某种层级抽象。
测试。 你的评测集必须覆盖组合。“identity + 工具 A+B” 通过的 prompt 可能 “identity + 工具 A+C” 失败。组合数增长飞快；好的系统靠 tier 覆盖收窄、不靠穷举。
可调试性。 Agent 表现不好时，是哪一层导致的？单体失败指向一份文件；组合式失败要求装配后的 prompt 被日志或从当时激活的层重建。

这些问题是升华的代价。症状真实时值得付；症状不存在时是多余开销。

关于选择

不是每份 prompt 都该组合。组合是有真实成本的工程选择：

单 Agent、稳定工具集、小团队 —— 单体就是对的。组合加上了你收不回的开销。
多 tier / 多子 Agent / 动态工具 / 多租户 —— 单体最终会撞到第二部分里的症状。能从一开始就组合则一开始就组合，或规划好迁移。
不确定 —— 症状出现之前保持单体。过早组合是最常见的 prompt 工程错误之一。症状到来时很响；你不会错过。

最清晰的升华信号是：你发现自己在手动重装配 —— 为不同模式 copy-paste 不同版本的 prompt、或维护两份在某一段分叉了的近乎同款 prompt。那一刻就是 prompt 想变成函数而不是文本的时刻。

组合也是可逆的。有些系统开始是组合的、发现实际只有一个 variant、扁平回单体。任一方向都可以，只要选择是被度量驱动、不是被审美驱动。

小结

10 步方法给出写一份好 prompt 的程序。对多数 Agent 第一天就足够。
方法的不变量（角色、altitude、强调层级、命名默认、缓存、度量）在升华到组合式设计时原则不变，四步换了形态。
升华是有真实成本的架构选择。症状要求时就升；症状没出现时保持单体。
两种架构下，底层原则相同：最小的高信号 token 集合，最大化产生期望结果的可能性。架构只决定这些 token 从哪里来。

来源

Effective Context Engineering for AI Agents — Anthropic, 2026
Prompting best practices — Anthropic, Claude API 文档
CL4R1T4S: ANTHROPIC/Claude-Design-Sys-Prompt.txt —— 第一部分的单体参照点