以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。
第 2 章解决了「做什么、不做什么」。从这一节开始,问题变成「怎么把要做的事写清楚」。很多团队在这一步会写出一份很长的需求文档:背景、目标、用户故事、流程图、提示词草稿,什么都有,唯独没有四件事:它吃什么、吐什么、怎么算做好、最多能花多少。
这四件事就是任务规格的四要素:输入清单、输出形态、验收标准、代价上限。它们不是文档模板的四个章节,而是四个必须能独立回答的问题。缺任何一项,规格都不能进入评审;不是因为它不完整,而是因为缺了它,后面的设计会失去约束。
四要素是什么
先给结论:四要素是任务规格的最小完备集。少一项,任务就有一个维度没有被定义;多一项,通常是实现细节,不属于规格层。
| 要素 | 回答的问题 | 产物 | 缺失后的典型症状 |
|---|---|---|---|
| 输入清单 | 它能看到什么、不能看到什么 | 用户给、系统给、禁止用三类列表 | 上线后才发现模型读了不该读的数据 |
| 输出形态 | 它交付的是答案、草稿还是动作 | 三选一,并写清字段 | 验收标准写在了错误的层级 |
| 验收标准 | 怎么判断这一次做对了 | 至少两条可独立判定的标准 | 评审变成「看起来还行」 |
| 代价上限 | 一次任务最多花多少人工和系统成本 | 系统成本 + 人工时间,分开写 | 上线后算不清账,节省率失真 |
四要素的顺序有讲究。输入和输出定义任务的形状,验收定义任务的对错,代价定义任务的边界。先写输入输出,再写验收,最后写代价;如果先写代价,很容易为了「便宜」砍掉必要的输入,最后验收更贵。
四要素也不是越细越好。输入清单写到「工单正文、账户与套餐、8 个队列定义、模板库」就够了,不需要写到具体字段名;验收标准写到「队列属于 8 个定义队列之一」就够了,不需要写判定代码。规格是给人评审的,不是给编译器执行的;它的详细程度以「另一个人能独立判断」为准。
输入清单:用户给、系统给、禁止用
输入清单要分三类写,缺一类都不算完整。
用户给:用户在这次任务里主动提供的内容。A Relay 的用户给的是新工单正文和客户补充回复;B Quill 的用户给的是客户数据包、上月报告和行业模板;C Runner 的用户给的是异常任务队列和动作偏好。用户给的内容有一个共同点:它是任务启动的必要条件,没有它任务无法开始。
系统给:系统在后台能取到的上下文。A 的系统给账户与套餐、8 个队列定义、首响模板库;B 的系统给图表渲染器、报告模板库、事实核查清单;C 的系统给商品目录快照、价格规则、库存和审计日志。系统给的内容决定了 Agent 能看到多少背景,也决定了它对系统集成的依赖。
禁止用:任务明确不能碰的数据。A 禁止用与分诊无关的支付卡号、客户未授权的历史订单;B 禁止用未脱敏的客户名单、其他客户的原始数据;C 禁止用供应商成本价、未授权的批量下架名单。禁止用这一类最容易被省略,因为它不参与「怎么完成任务」,只参与「不能怎么完成任务」。
三类输入缺一的后果不同。缺用户给,任务无法启动;缺系统给,Agent 只能靠用户现场补充,体验会退化成问答;缺禁止用,任务能跑,但会在某个边界上越权。第三类最危险,因为它在演示里不会暴露,只会在审计或事故里暴露。
写输入清单时有一个实用检查:每一类至少写两条,禁止用至少写一条。 只写一条用户给、一条系统给,通常说明任务边界还没想清楚;禁止用一条都没有,通常说明团队还没想过权限面。
输出形态:答案、草稿、动作
输出形态只有三种:答案、草稿、动作。它不是 UI 形态,而是责任形态。
| 形态 | 交付物 | 人接下来做什么 | 典型案例 |
|---|---|---|---|
| 答案 | 一个建议、一个分类、一个字段值 | 确认、修改或忽略 | A Relay 的队列、优先级、模板号 |
| 草稿 | 一份需要人加工的半成品 | 审改、补充、发布 | B Quill 的 12–20 页报告初稿 |
| 动作 | 一次已经发生的外部状态变更 | 事后审计、必要时回滚 | C Runner 的改价、改库存、下架 |
输出形态由自主档决定:建议档和审批档输出答案,草稿档输出草稿,执行档输出动作。这个映射不是文字游戏,它决定了验收标准该写在哪一层。答案的验收看「建议是否正确」,草稿的验收看「初稿是否可审改」,动作的验收看「执行是否可回滚、可审计」。
输出形态最常见的错误,是把动作写成答案。比如「Agent 帮我把价格改了,然后告诉我改了多少」——这已经是动作,不是答案;如果规格里写的是答案,验收就会漏掉回滚和审计。反过来,把答案写成动作也会出问题:一个只给建议的功能,如果规格按动作验收,团队会误以为它可以直接改数据。
写输出形态时,除了三选一,还要写清交付字段。A 的答案必须包含队列、优先级、模板号三个字段;B 的草稿必须包含页数、图表来源、事实核查清单;C 的动作必须包含任务号、动作类型、前后值、回滚句柄。字段是验收的抓手,没有字段,验收只能靠感觉。
验收标准:至少两条,形式与事实
验收标准是四要素里最容易被写虚的一项。常见写法是「回答准确」「内容专业」「用户满意」,这些都不是验收标准,而是愿望。验收标准必须能被机器或人独立判定,并且判定成本可接受。
最低要求是两条:一条管形式,一条管事实。
形式标准检查输出是否满足结构约束。A 的形式标准是「队列属于 8 个定义队列之一」「优先级是 P1–P4 之一」;B 的形式标准是「草稿在 12–20 页之间」;C 的形式标准是「价格变动在配置阈值内」。形式标准通常可以机器判定,成本很低。
事实标准检查输出是否与输入一致。A 的事实标准是「模板号能解析到已发布模板」;B 的事实标准是「每张图能追到数据包来源」;C 的事实标准是「审计日志记录动作前后值」。事实标准有时需要人判断,但它仍然要有明确的判断材料,不能是「看起来对」。
两条标准的分工,是让验收既有硬门槛,又有事实核查。只有形式标准,输出可能格式完美但内容错误;只有事实标准,输出可能内容正确但结构不可消费。两条都有,才能同时管住「能不能用」和「对不对」。
验收标准还要写判定成本。A 的验收发生在人确认的 45 秒里,所以标准必须一眼能看;B 的验收发生在 1.6 小时的审改里,所以标准可以细一些;C 的验收发生在 8% 抽检、单次 12 分钟里,所以标准必须能从事后日志里读出来。判定时间越短,标准越要外显;判定时间越长,标准越要可追溯。
代价上限:人工与系统分开
代价上限回答的是「一次任务最多能花多少」。它必须分两栏写:系统成本上限和人工时间上限。两栏不能合成一个数,因为两者的计价方式不同,混在一起会让节省率失真。
系统成本包括模型调用和基础设施分摊。A 是 0.017 美元/单(模型 0.011 + 基础设施 0.006);B 是 0.32 美元/份(模型 0.198 + 基础设施 0.122);C 是 0.072 美元/任务(模型 0.024 + 基础设施 0.048)。这些是案例事实表里的系统成本,不是人工成本。
人工时间上限是 Agent 介入后的人均耗时。A 是 0.75 分钟/单,B 是 1.6 小时/份(96 分钟),C 是 4.04 分钟/任务。注意 C 的 4.04 分钟包含审计摊销 0.96 分钟和转人工摊销 3.08 分钟;只算审计不算转人工,会把人工上限低估到 0.96 分钟,后面的节省率会从 73.7% 错成 90.8%。
代价上限不是实际成本,而是设计约束。实际成本可以低于上限,但不能高于上限;高于上限时,要么改任务边界,要么改自主档,要么承认这个任务不划算。把上限写成实际值,等于没有上限;把上限写成一个拍脑袋的整数,等于给后面埋一个无法解释的数字。
写代价上限还有一个好处:它强迫团队在规格阶段就把「人工」和「系统」分开。很多项目上线后算不清账,不是因为数字难算,而是因为规格里只有一个「总成本」,无法拆出人工和系统各自占多少。
缺一项会怎样
四要素缺任何一项,后果都能在上线后观察到:
| 缺失项 | 上线后的表现 | 根因 |
|---|---|---|
| 输入清单 | 模型读了不该读的数据,或任务经常缺上下文 | 权限面和上下文边界没有定义 |
| 输出形态 | 验收标准和交付方式不匹配,团队对「做完了」理解不一 | 责任形态没有定义 |
| 验收标准 | 评审靠印象,返工无法归因 | 对错没有独立判据 |
| 代价上限 | 节省率算不清,人工和系统成本混在一起 | 成本边界没有定义 |
这四种表现有一个共同点:它们都不是模型问题,而是规格问题。模型升级不会让缺失的输入清单自动出现,也不会让模糊的验收标准变清楚;它只会让问题更晚暴露,代价更高。把四要素落成工程需求与架构的写法,见 需求与案例 ;本节只给出产品侧的最小充分条件。
三案例缩略规格
把四要素套到三个案例上,得到三份缩略规格。它们不是完整需求文档,只是四个问题的答案。
| 要素 | A Relay | B Quill | C Runner |
|---|---|---|---|
| 输入清单 | 用户给工单与回复;系统给账户、8 个队列、模板库;禁止用无关支付信息 | 用户给数据包、上月报告、行业模板;系统给渲染器、模板库、核查清单;禁止用未脱敏名单 | 用户给异常队列、动作偏好;系统给目录、价格规则、库存、审计日志;禁止用供应商成本价 |
| 输出形态 | 答案:队列 + 优先级 + 模板号 | 草稿:12–20 页报告初稿 | 动作:改价、改库存、下架,带前后值与回滚句柄 |
| 验收标准 | 队列属于 8 类之一;优先级 P1–P4;模板号可解析 | 页数 12–20;图表可追源;附事实核查清单 | 动作有回滚句柄或标记不可回滚;日志记前后值;价格在阈值内 |
| 代价上限 | 系统 0.017 美元/单;人工 0.75 分钟/单 | 系统 0.32 美元/份;人工 1.6 小时/份 | 系统 0.072 美元/任务;人工 4.04 分钟/任务 |
这张表可以直接放进评审材料。它的价值不在于数字精确,而在于四个问题都有答案;评审时可以逐格问「这一格为什么这么写」,而不是笼统地问「这个方案行不行」。
代码:四要素检查器
把四要素写成检查器,输入是一份规格草稿,输出是「通过」或「缺哪一项」。检查器不判断任务好不好,只判断规格是否完备。
// file: src/task/03-1-spec-four-parts.ts
// tier: L2
// verify: node --test test/task/03-1-spec-four-parts.test.ts
// 任务规格四要素:输入清单、输出形态、验收标准、代价上限。
// 缺任何一项,规格都不能进入评审;代价上限把人工与系统分开写。
import { QUILL, RELAY, RUNNER } from "../cases.ts";
import { type Result, fail, ok } from "../core/result.ts";
export type PartName = "inputs" | "output" | "acceptance" | "cost-ceiling";
export const PART_ORDER: readonly PartName[] = [
"inputs",
"output",
"acceptance",
"cost-ceiling",
];
export const PART_LABEL: Record<PartName, string> = {
inputs: "输入清单",
output: "输出形态",
acceptance: "验收标准",
"cost-ceiling": "代价上限",
};
export type OutputKind = "answer" | "draft" | "action";
export const OUTPUT_KINDS: readonly OutputKind[] = ["answer", "draft", "action"];
export type InputInventory = {
readonly fromUser: readonly string[];
readonly fromSystem: readonly string[];
readonly forbidden: readonly string[];
};
export type CostCeiling = {
readonly systemCentsPerTask: number;
readonly humanMinutesPerTask: number;
};
export type SpecDraft = {
readonly taskId: string;
readonly inputs: InputInventory;
readonly output: OutputKind;
readonly acceptance: readonly string[];
readonly costCeiling: CostCeiling;
};
export type CompleteSpec = SpecDraft & {
readonly parts: readonly PartName[];
};
export function checkSpec(draft: SpecDraft): Result<CompleteSpec> {
const missing: PartName[] = [];
const errors: string[] = [];
if (
draft.inputs.fromUser.length === 0 ||
draft.inputs.fromSystem.length === 0 ||
draft.inputs.forbidden.length === 0
) {
missing.push("inputs");
errors.push("inputs need user, system and forbidden lists");
}
if (!OUTPUT_KINDS.includes(draft.output)) {
missing.push("output");
errors.push(`output ${String(draft.output)} is not one of answer, draft, action`);
}
if (draft.acceptance.length < 2) {
missing.push("acceptance");
errors.push("acceptance needs at least two criteria");
}
if (
draft.costCeiling.systemCentsPerTask <= 0 ||
draft.costCeiling.humanMinutesPerTask <= 0
) {
missing.push("cost-ceiling");
errors.push("cost ceiling needs system cents and human minutes");
}
if (missing.length > 0) {
return fail(errors.join("; "));
}
return ok({ ...draft, parts: PART_ORDER });
}
// 三份缩略规格。系统成本直接由案例事实表的两项相加,人工上限取 Agent 后的人工。
export const CASE_SPECS: Record<"A" | "B" | "C", SpecDraft> = {
A: {
taskId: "relay-ticket-triage",
inputs: {
fromUser: ["新工单正文", "客户补充回复"],
fromSystem: ["账户与套餐", "8 个队列定义", "首响模板库"],
forbidden: ["与分诊无关的支付卡号", "客户未授权的历史订单"],
},
output: "answer",
acceptance: [
"队列属于 8 个定义队列之一",
"优先级是 P1 到 P4 之一",
"模板号能解析到已发布模板",
],
costCeiling: {
systemCentsPerTask: RELAY.modelCents + RELAY.infraCents,
humanMinutesPerTask: RELAY.humanMinutes,
},
},
B: {
taskId: "quill-client-report",
inputs: {
fromUser: ["客户数据包", "上月报告", "行业模板"],
fromSystem: ["图表渲染器", "报告模板库", "事实核查清单"],
forbidden: ["未脱敏的客户名单", "其他客户的原始数据"],
},
output: "draft",
acceptance: [
"草稿在 12 到 20 页之间",
"每张图能追到数据包来源",
"发布前附事实核查清单",
],
costCeiling: {
systemCentsPerTask: QUILL.modelCents + QUILL.infraCents,
humanMinutesPerTask: QUILL.humanMinutes,
},
},
C: {
taskId: "runner-ops-action",
inputs: {
fromUser: ["异常任务队列", "动作偏好"],
fromSystem: ["商品目录快照", "价格规则", "库存", "审计日志"],
forbidden: ["供应商成本价", "未授权的批量下架名单"],
},
output: "action",
acceptance: [
"每个动作有回滚句柄或标记不可回滚",
"审计日志记录动作前后值",
"价格变动在配置阈值内",
],
costCeiling: {
systemCentsPerTask: RUNNER.modelCents + RUNNER.infraCents,
humanMinutesPerTask: RUNNER.humanMinutes,
},
},
};
export function buildAll(): readonly Result<CompleteSpec>[] {
return [CASE_SPECS.A, CASE_SPECS.B, CASE_SPECS.C].map((spec) =>
checkSpec(spec),
);
}
代码里的 checkSpec() 按四要素依次检查:输入清单三类是否都非空、输出形态是否在三种之内、验收标准是否至少两条、代价上限是否同时有系统成本和人工时间。任何一项不满足,返回 fail 并写明原因。
CASE_SPECS 里的三份规格直接从案例事实表取值:系统成本是模型成本加基础设施成本,人工上限是 Agent 介入后的人工时间。这样写有两个好处:第一,数字只有一处来源,不会在文章和代码之间漂移;第二,代价上限天然分成两栏,不会被合并成一个「总成本」。
buildAll() 把三份规格一起跑一遍。测试里会检查三份都通过,也会故意删掉禁止用列表、减到一条验收标准、把系统成本设成 0,确认检查器会在对应位置报错。检查器的价值不是拦住所有坏规格,而是让「缺哪一项」变成可复现的输出。
评审用法
四要素检查器适合在规格评审前跑一遍,不适合在评审会上当众跑。用法建议如下:
- 先让产品经理自检。 四要素各写一条,跑一次检查器;不通过的先补,不要带到会上。
- 评审时逐要素问依据。 输入清单问「禁止用为什么是这几条」,输出形态问「为什么是答案不是动作」,验收标准问「谁在几分钟内怎么判」,代价上限问「人工和系统为什么这么分」。
- 把不通过的项记成待办。 不要在会上现场改规格,改成待办,会后补完再跑一次。
- 规格通过后再写提示词。 提示词是实现,规格是边界;边界没定就写提示词,等于在流沙上盖房子。
这套用法和 1.3 的任务规格结构是衔接的:1.3 用 Assessment 和 TaskSpec 把产品假设写成可校验对象,3.1 的四要素是那个对象的内容要求。两者不重复:前者管结构,后者管内容。
小结
- 任务规格的最小完备集是四要素:输入清单、输出形态、验收标准、代价上限。
- 输入清单分三类:用户给、系统给、禁止用;缺禁止用最危险,因为它只在审计时暴露。
- 输出形态只有答案、草稿、动作三种,由自主档决定,不是 UI 形态。
- 验收标准至少两条:一条管形式,一条管事实;每条都要能独立判定。
- 代价上限必须把系统成本和人工时间分开写,不能合成一个「总成本」。
- C Runner 的人工上限 4.04 分钟包含审计 0.96 分钟和转人工 3.08 分钟,漏掉转人工会把节省率算错。
- 四要素缺任何一项,问题都会在上线后以「模型不准」的假象出现,实际是规格缺失。
- 规格通过后再写提示词;边界没定,提示词优化没有终点。
阅读导航:上一节:2.3 不该交给 Agent 的任务清单 · 下一节:3.2 从「答得好」到可判定的验收标准 。
常见错误与边界
- 把四要素写成四个章节。 四要素是四个必须回答的问题,不是文档目录;每一要素都要有具体内容,不能只写标题。
- 输入清单只写用户给。 系统给决定 Agent 能看到多少背景,禁止用决定它不能碰什么;三类缺一,规格都不完整。
- 把动作写成答案。 动作会改变外部状态,必须按动作验收,写清前后值、回滚句柄和审计日志;按答案验收会漏掉这些。
- 验收标准只写「准确」「专业」。 这些是愿望,不是标准;至少两条,一条管形式,一条管事实,每条都要有判断材料。
- 把人工和系统成本合成一个数。 合成之后无法拆出节省率,也无法判断是模型贵还是人贵;两栏必须分开。
- 漏掉转人工成本。 C Runner 的人工上限是 4.04 分钟,不是 0.96 分钟;只算审计会把节省率从 73.7% 夸大成 90.8%。
四要素检查器只能保证规格「写全了」,不能保证规格「写对了」。下一节专门处理其中最难的要素:验收标准,看看怎么把「答得好」翻译成可判定的条款。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。