authoring-feature-spec

authoring-feature-spec — SKILL.md

变体： standard · 使用时机： 将 PRD 中提及的功能细化为全面、可测试的功能规格说明，达到下游构建可以据此规划和验证的标准。适用于全新项目，或对已批准规格说明进行版本化修订。

概述

这项技能讲的是如何编写出色的功能规格说明——也就是 PRD 之下的这一层。PRD 说明产品做什么以及为什么，并列出其功能；功能规格说明则详细说明每项已列出的功能如何运行，达到足以据此构建和测试的程度。这项技能承载的是撰写者的判断——研究方法和质量标准——而不是章节列表。它假定有两种协作者：提供章节结构的功能规格说明模板工具，以及用证据为各项功能提供依据的深度研究能力。撰写者拿到的是已批准的 PRD（以及任何上游背景信息），必须拆解并细化其中的功能——绝不能输出通用套话。需要达到的标准是：每项功能都可实现、可测试——工程师可以据此构建，测试人员可以据此验证，无需询问作者；规划人员也可以据此拆分任务。

方法主干与出色的功能规格说明保持一致；此版本深入细化了如何撰写明确无歧义的行为描述（EARS、用例流程、需求异味目录），明确加入了状态转换表和决策表，针对每项功能增加了非功能需求规范和类型叠加要求（根据功能性质调整其侧重点），处理了概率型／ML功能（使用阈值标准，而非“能用”），并为常见的已批准规格说明变更场景增加了修订方法。

何时启用

• 根据已批准且列出一组功能的 PRD 编写功能规格说明。
• 将一项功能（或一组边界明确的功能）细化为可测试的行为、输入／输出、状态、边界情况和验收标准。
• 修订已批准的功能规格说明（增量变更：功能／行为／验收标准／状态发生更改或新增）——你会拿到现有规格说明和变更请求。
• 填写功能规格说明模板，并为每项功能提供经过研究、决策完备的内容。

以下情况不要启用：

• 编写 PRD 本身（问题、用户、指标、MVP 边界）→ 使用 PRD 编写技能。PRD 是这里的上游输入。
• 审查或评估已完成的功能规格说明 → 使用功能规格说明审查技能。
• 编写工程设计文档（ADR、RFC、架构）——那是本技能下游的“如何编码”层。

输入

阅读计划交给你的每份文档——即你的 depends_on 集合（上游文档，由 discovery 确定为本文档提供信息）——并追溯本文档内容的来源。通常，上游文档是已批准的 PRD；UI 功能也可能会收到用户流程图／线框图／设计系统；数据／ML 功能也可能会收到数据规范。这些是方法指导，不是固定上限。保持自包含——根据你实际收到的任意上下文撰写；若缺少预期的参考文档，就基于现有信息继续，并将缺口明确列为假设，绝不要编造内容来填补。并且，在具备研究能力时使用该能力（deep-research），让文档内容全面，而不只是填充模板。进行修订时，还会额外提供现有规范和变更请求（以及在需要检查影响范围时提供相关下游文档）。

能力上下文（如有提供）： 如果调用方注入了 capability_record（来自 capability-map.yaml product_capabilities 的记录），请在 Step 1 之前阅读。它定义了你的范围边界：owns = 你涵盖的实体；refs = 你会引用但不负责的实体；publishes／consumes = 你会提及的事件；entry_points／exit_points = 用户进入和离开的方式；has_ui／has_api／has_persistence = 适用的界面。存在此记录时，必须将其视为硬性约束——不得偏离它定义的边界。

工作流

Step 1：采用模板工具提供的结构——不要自行拟定大纲

从功能规范模板工具（全面版）获取章节结构。此处不要重述或重新推导章节列表；本技能提供的是填充这些章节的方法。全面版模板会重复每个功能的区块，并包含版本标头、行为（含决策表）、I/O 与数据契约、状态转换表、边缘情况、错误处理、验收标准、非功能性需求章节、依赖项、待解决问题，以及版本／变更日志章节。若没有可用模板，请获取全面的功能规范结构（请求／创建一个，或退回到规范的逐功能集合），然后继续。**适度原则：**模板内容全面；填写内容应与功能规模相称——对于简单功能，状态表、决策表、NFR 或变更日志可以留空。

如果提供了 capability_record：规范必须涵盖完整的 scope 声明、所有 owns 实体，以及所有 publishes／consumes 事件。不得涵盖 refs 实体或属于 depends_on 能力的内容（这些内容有各自的功能规范）。

Step 2：加载 PRD；依据其功能列表确保覆盖；识别每个功能的类型

阅读已批准的 PRD 及其依赖的所有上游文档——它们是你的输入，而非一张白纸。列出 PRD 中提及的每项功能；此列表就是你的覆盖检查清单。将 PRD 拆分为逐功能规范：每项功能都应有自己的区块。为每项功能标明其类型（UI · REST/API · 数据-ML · 批处理／异步作业 · 集成／webhook · CLI——一项功能可能同时属于多种类型）；不同类型会影响各章节的重要程度（见 Step 4）。开始撰写功能之前，先补足其行为方面的知识缺口；如果 PRD 内容不够充分，就将缺口明确列为待解决问题或声明为假设，绝不要含糊带过。如果 PRD 中某项功能甚至无法可信地展开说明，就将其标记为阻塞项，而不是编造行为。

Step 3：通过研究为每项功能提供依据

使用 deep-research 研究，基于证据明确每项功能的行为、领域规则和边缘情况——聚焦于本产品的具体领域，而不是“功能规范一般该怎么写”。如果没有可用的研究能力，就不要编造行为、限制或错误代码——应将它们明确标记为假设，并注明须在构建前验证。

Step 4：应用逐功能方法

按此方法填写模板中各功能对应的章节。每项功能重复此步骤；对于不需要某个章节的简单功能，请折叠该章节（没有状态 → 不需要状态表）。各方面的详细说明见 references/，需要完整说明时再加载。

• 目的与 PRD 追溯 — 说明此功能只解决哪一个问题，并将其关联到具体的 PRD 要求／目标／指标（双向追溯）。没有 PRD 条目支撑的功能属于范围蔓延；有 PRD 条目却没有对应功能，则属于覆盖缺口。引用／注明 PRD 中的确切条目。
• 行为与交互 — 描述系统可观察到的响应，且不涉及实现细节（做什么，而非如何实现）。将主要成功场景写成约 3–11 个步骤（每步均为“参与者执行 X → 系统响应 Y”）；然后写出替代流程（目标仍然达成的不同路径）和异常流程（目标未能达成的路径，并逐一说明处理方式）。尽量按每条行为陈述采用 EARS 表述（“当 <trigger> 时，系统应 <response>”；“在 <state> 状态下……”；“如果出现 <unwanted condition>，则……”），这样能使行为保持原子性，并与验收标准一一对应。逐步梳理并询问“这里可能会发生什么故障／变化？”，以此推导边缘情况。参见 references/requirement-and-behavior.md。
• 决策表（组合规则） — 当响应取决于多个条件的组合时，将其写成“条件 × 规则 → 操作”表，确保每种组合都有明确定义的操作，并能发现缺失或矛盾的规则。（辅助工具；行为不涉及组合规则时可跳过。）
• 输入／输出与数据 — 枚举每项输入（来源、类型、验证规则、必需／可选）和每项输出（响应结构、副作用、错误代码），作为调用方可据以验证的契约；对于每项输入，询问“什么是有效的、什么无效、边界在哪里”；对于每项输出，询问“调用方／UI 会观察到什么”。注明读取／写入的实体，以及数据是持久化还是临时的。
• 状态与转换 — 如果涉及状态，则指定状态转换表：当前状态 × 事件 → 下一状态；非法转换用短横线表示，并注明初始状态和终止状态。表格形式可用于检查非法转换。
• 边缘情况与错误处理 — 枚举边界／故障路径（边界值：每个限制的下限、临界值和上限；空值／空内容、重复／幂等性、并发／竞争、权限／可见性、限制／溢出）。每种边缘情况和错误都要说明预期处理方式——响应／消息／恢复方式，而非只说明其存在。（边缘情况 = 有效但不常见；错误 = 失败；两者都要说明。）
• 验收标准 — 每项行为和关键边缘情况／错误都要附上测试人员可判定通过／失败的标准：Given/When/Then（场景形式）或基于规则的检查清单。每个功能 1–3 条；通常 4 条及以上意味着一个功能中藏着两个功能——应拆分。对于概率型／ML功能，确定性的 G/W/T 不适用于输出——应针对具名数据集编写指标阈值标准（“在 <eval-set> 上的精确率 ≥ 0.85”），并说明低置信度／回退行为和数据要求（来源／范围／平衡性）。“模型准确”不是验收标准。参见 references/io-states-archetype-amend.md。
• 非功能性要求 — 列出此功能适用的 NFR 类别，并为每项注明可量化／可检查的目标（性能 p95；可靠性／幂等性；安全性／授权；隐私；UI 的无障碍 WCAG 2.2 AA；限制／配额；兼容性）。要求应与功能规模相称——简单功能无需列出；“应该快速／安全”不是 NFR。
• 原型重点 — 根据功能性质应用相应的补充重点（UI → 各状态下的行为 + 无障碍 + 微文案；API → 请求／响应架构 + 状态／错误模型 + 幂等性 + 速率限制［将线上的契约交给 api-spec］；数据 ML → 数据要求 + 阈值验收标准 + 漂移／回退；批处理 → 计划 + 幂等性 + 部分失败／重试；集成 → 交付语义 + 负载契约；CLI → 参数／标志 + 退出代码）。此补充重点用于辅助明确需要涵盖的内容，应与功能规模相称。参见 references/io-states-archetype-amend.md。
• 横切关注点（适用于各功能，不单独成节） — 每条陈述只表达一个想法（单一）；术语保持一致，不得自相矛盾；将每项要求／验收标准与需求异味目录逐一核对（主观措辞、含糊的副词、不可验证／力度不足的术语、没有参照对象的比较级、漏洞、开放式的“等等”），并将任何影响关键内容的命中项改写为可量化／可观察的陈述。

步骤 5：修订已批准的规格（收到变更请求时）

当输入是现有的已批准规格和变更请求时，不要重新生成整份规格——应就地修订：

1. 界定变更范围——说明此次变更涉及哪些功能／行为／验收标准（AC）／状态／输入输出字段，以及明确不涉及哪些内容。
2. 就地编辑——只修改受影响的部分。
3. 重新确保功能内部链路一致——更改某项行为后，更新其 AC、状态表、输入输出和边界情况，确保该功能内部自洽。
4. 分析双向影响——上游（是否仍可追溯到某条 PRD？如果新增了无法追溯的功能，标记“必须先修订 PRD”）、内部（哪些 AC／状态／输入输出／边界情况已过时——在步骤 3 中修复）、下游（哪些技术设计决策／测试用例／API 规格条目已过时——列出受影响的内容）。
5. 版本 + 变更日志——提升文档自身的版本号；添加变更日志条目（谁／何时／做了什么／为什么）。
6. 标记已被取代的内容——标明过时的行为／标准／状态已被取代，并注明原因；不要悄悄删除。参见 references/io-states-archetype-amend.md。

步骤 6：交付前对照可实现性标准进行自检

确认以下各项均满足（这是评审者会据以审核的标准——作者和评审者遵循同一标准，避免标准偏移）：

1. 可追溯到 PRD——每项功能都对应到具体的 PRD 要求／指标；不存在孤立功能，也没有未覆盖的 PRD 条目。
2. 行为明确无歧义——每项行为都只能有一种解释，不涉及实现细节且可观察；流程已分类（主流程／备选流程／异常流程）；不存在承载关键要求的坏味道。
3. 输入输出 + 状态完整——已列出输入（含校验）和输出（含结构／副作用）；有状态的功能包含状态转换表（合法单元格 + 非法标记）；组合规则包含完整的决策表。
4. 边界情况及其处理方式均已覆盖——空值／空内容、重复／幂等性、并发、权限、限制均已明确列出，并注明预期错误／处理方式。
5. 验收标准可测试——每项行为／边界情况都有可独立测试的通过／失败标准（G/W/T 或基于规则；概率性功能使用指标阈值）。
6. 单一且一致——每项需求只表达一个想法，术语保持一致，内部没有矛盾。
7. 可行且可规划——能在既定约束内构建；输入输出和标准具体到足以拆分任务／里程碑。
8. 明确提出待解决的问题——明确说明真实的未知事项和未解决的决策（不能把它们说成已确定事实）；标明设计假设，不得默默猜测。
9. 在适用时设定非功能目标——对功能起关键作用的 NFR 类别设定数值目标（按比例确定）。
10. （仅限修订）变更范围明确、影响已理清、版本已更新——变更属于范围内，仍可追溯到 PRD（否则标明需先修订上游 PRD），内部链路保持一致，已说明下游影响，并更新版本 + 变更日志、标记已被取代的内容。

输入不足门槛：如果无法调研 PRD 功能的行为，也无法做出可信的假设，应将其列为阻塞项（“功能定义不足——需要产品决策”），而不是用臆造的行为来掩盖问题。

规则

硬性规则（绝不违反）：

• 每项功能都要追溯到 PRD。 不得存在无对应依据的功能，也不得遗漏 PRD 中的功能。覆盖范围以 PRD 的功能列表为准。
• 行为必须可观察，且不涉及实现方式。 说明功能做什么，而非如何编码——后者属于下游设计层。
• 边缘情况和错误必须明确处理方式。 仅列出情况，却不说明预期响应，不算完成。
• 验收标准必须可测试。 使用 G/W/T、基于规则的标准（或针对概率性功能的指标阈值）。如果某项标准无法判定通过或失败，就说明行为尚未明确。
• 避免含糊表述。 将主观词语（“快速”“健壮”“易于使用”）及常见问题清单中的措辞，替换为可量化／可观察的描述（“p95 < 200 ms”“重复键时返回 409”）。“模型准确”不是验收标准。
• 绝不捏造行为。 不要为了显得完整而编造限制、错误代码或规则。没有依据时，应将其标记为明确标注的假设，并在构建前进行验证。
• 组合，不重复。 章节结构采用模板工具的结构；本技能负责填充内容。
• 细化 PRD，不要重写 PRD。 不要重述其中的问题、用户或指标，也不要重新决定有哪些功能。
• 原地修订，不要重新生成。 收到变更请求时，编辑受影响的区块、更新版本和变更日志、标记已被取代的内容，并分析双向影响；绝不能不加说明地重新输出整份规格说明。
• 必须可实现、可测试，否则不算完成。
• 能力边界（提供 capability_record 时）。 文档输出范围必须受该记录的边界约束。生成边界之外的内容（将 refs 实体视为归属对象，或设计超出 exit_point 的流程）即属范围违规，等同于捏造规格说明中不存在的内容。

偏好（可覆盖）：

• “全面”决定输出的目标；内容应适度——追求决策的完整性，而非字数。功能简单时，应省略不需要的章节（非功能需求、状态表、决策表，以及初稿中的变更日志）。
• 行为描述优先采用 EARS，场景优先采用 Given/When/Then；不变量／验证表优先采用基于规则的检查清单；概率性输出优先采用指标阈值。
• 每项功能的验收标准控制在 1–3 条；达到 4 条或更多，通常意味着应拆分功能（INVEST 中的“Small”“Testable”）。

注意事项

• 重新撰写 PRD 的规格说明。 重述问题、用户或指标，或重新决定功能范围——这些都是 PRD 工作。应进行分解和细化，而不是重新讨论范围。
• 泄露实现细节的行为描述。 “将令牌存储在 Redis 中，并设置 1 小时的 TTL”属于编码方式——应留给下游。应明确可观察的契约（“会话有效期为 1 小时，之后需要重新认证”）。
• 列出边界情况但未说明处理方式。 只写“边界情况：并发编辑”却没有解决方案，这只是个问题，不是规格说明。
• 无法测试的验收标准。 “功能正常运行”／“妥善处理错误”／“模型准确”都无法通过测试判定通过或失败。
• 为概率性功能设定确定性标准。 对模型／排序器，应针对指定数据集设置指标阈值，并明确回退方案，而不是围绕固定输出编写 Given/When/Then。
• 只列状态，不提供状态表。 列出状态，却把状态转换（尤其是非法转换）留给读者猜测，说明规格不充分——应使用“状态 × 事件”表，并用短横线标记非法单元格。
• 验收标准过于庞杂 = 隐藏的第二项功能。 4 条或更多验收标准通常意味着打包了两种行为，应拆分。
• 把架构类型／NFR 当成必须包含的章节。 叠加说明和 NFR 是按比例使用的辅助内容——精简功能可以合理省略它们；不要为了显得完整而填充内容。
• 通过重新生成来修订。 小改动时重新输出整份规格说明会丢失溯源信息，还可能造成不易察觉的偏差——应就地修订，并添加变更日志和影响分析。

对照示例——表面合规的模糊描述 vs 可实现的描述（用于自我检查）：

方面	模糊／无法构建（应拒绝）	可实现（可交付）
PRD 追溯	“此功能与发票有关。”	“实现 PRD §4.2 自动提醒；推进指标‘将付款中位天数从 21 天降至 14 天’。”
行为	“系统会发送提醒。”	“当发票逾期 3 天且尚未付款时，系统会向客户端发送提醒模板邮件；并记录 reminder_sent 事件。”
边界情况	“处理发票已付款的情况。”	“如果发票在满 3 天前已付款，不发送提醒；已经排队的提醒会被取消。”
错误处理	“处理邮件错误。”	“如果邮件服务提供商返回 5xx，则采用退避策略重试 3 次；之后标记为 reminder_failed，并在控制面板中显示。”
验收（确定性）	“提醒功能正常。”	“给定一张逾期 3 天且未付款的发票，当每日任务运行时，恰好发送一封提醒邮件，并记录 reminder_sent 事件。”
验收（概率性）	“相关性模型准确。”	“在 2026-Q2-holdout 数据集上，precision@10 ≥ 0.80 且 recall@10 ≥ 0.65；当置信度 < 0.4 时，结果回退为按时间最近程度排序。”

如果你填写的内容读起来像左栏——适用于任何功能、没有触发条件、没有可观察结果、没有处理方式——那就还没完成。

反模式

• “我会用自己的话重述 PRD 中的功能。” 这不是细化——应补充 PRD 未涵盖的行为、输入／输出、状态、边界情况和标准。
• “我会描述具体实现方式，以确保精确。” 实现细节属于下游设计层。
• “我会列出边界情况；处理方式显而易见。” 必须说明每种情况的预期处理方式，否则它就是一个未解决的问题。
• “‘按预期运行’／‘模型准确’是合适的验收标准。” 这无法测试——禁止使用。应使其可观察（或针对数据集设置指标阈值）。
• “把所有功能放在一个大块中更连贯。” 4 条或更多标准／行为过于庞杂，意味着应拆分。
• “我会添加 UI／API／ML／NFR 章节，让内容看起来更全面。” 架构类型和 NFR 应按比例添加——只有在功能需要时才添加。
• “我直接重新生成这次变更的规格说明。” 应就地修订；更新版本、变更日志并分析影响。
• “我自己编写大纲。” 这会重复模板工具已有的内容。

输出

全面的功能规格说明（或范围明确、带版本号的修订版），满足 第 6 步可实施性标准（每项功能均可追溯至 PRD，具有明确且可观察的行为及分类流程、完整的输入/输出和状态转换表、决策表中的组合规则、已涵盖并说明处理方式的边缘情况、可测试的验收标准 [G/W/T 或指标阈值]、适用的 NFR 目标、内容单一且一致、可行且可规划，并已提出未决问题；修订版还须明确范围、清除连带影响并带有版本号）。抽象使用者包括下游规划阶段、负责构建的工程师、负责验证的测试人员，以及负责确认是否达到相同标准的评审人员。功能规格说明依赖 PRD 作为输入；其结构来自模板工具；此技能提供内容质量。媒介：目前的产物是文本型 Markdown 文档；该方法与媒介无关（规格说明存储在其他位置时同样适用）。

相关内容

• 功能规格说明模板工具（例如内容/模板网关）——提供此技能要填充的各功能章节结构。与其组合使用；切勿重复其大纲。
• 深度研究能力——以证据为依据，明确每项功能的行为、领域规则和边缘情况。
• PRD 编写技能——生成此技能所依赖的上游 PRD。若修订版新增了无法追溯的功能，须先修订 PRD。
• 功能规格说明评审技能——对完成的规格说明采用相同的可实施性/可测试性标准（包括针对增量范围的修订版评审）；作者和评审人员共用同一标准，避免标准偏离。
• 下游使用者——technical-design（实现方式）、test-plan（验证方式）、api-spec（线路契约）会使用此规格说明；连带影响分析会列出变更影响到的对象。

渐进式披露

• references/requirement-and-behavior.md — ISO/IEC/IEEE 29148 质量属性、EARS 模式集、需求异味目录，以及用例主流程/备选流程/异常流程方法。编写或完善行为与验收标准时加载。
• references/io-states-archetype-amend.md — I/O 数据契约、状态转换表和决策表格式、带数值标准的功能级 NFR 分类、六种类型叠加（包括概率型/ML），以及修订版连带影响处理流程。当功能具有状态、组合逻辑、特定类型，或正在修订时加载。
• references/sources.md — 方法和质量标准的研究来源。仅在审查指导内容的来源时加载。

正文篇幅预算

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文约 500 行 / 5,000 个词元（软性目标——质量优先；若持续超过 700 行 / 7,000 个词元，请标出）。
• 大量内容放在 references/ 中，按需加载。