AionUi 功能规格说明书编写指南：基于 .specify/spec-template.md 的 Feature Spec 模板全解析

AionUi 功能规格说明书编写指南：基于 .specify/spec-template.md 的 Feature Spec 模板全解析

【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up｜Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi

本文以 AionUi 仓库中.specify/templates/spec-template.md为绝对主体，系统讲解该「功能规格说明书（Feature Specification）」模板的结构、编写规则与执行流程：从输入用户描述开始，如何提取概念、标记歧义、生成可测试的需求与验收场景，最终通过自动化的评审 GATE 产出可直接进入计划阶段（/plan）的规格文档。读完本文，你将掌握 WHAT/WHY 与 HOW 的边界判断、[NEEDS CLARIFICATION] 标记机制、FR 编号需求体系、Given/When/Then 验收场景写法，并了解该模板如何与仓库中的 constitution.md、plan-template.md、tasks-template.md 一起构成完整的「Spec → Plan → Tasks」三层工作流。

一、模板在仓库中的定位：Specify 工作流的第一环

.specify/templates/目录下存放着 AionUi 开发工作流的一组标准化模板，彼此以「输入 → 产物」的方式串联：

plan-template.md 中明确写明了这条链路：/plan命令第一步就是"Load feature spec from Input path"，从/specs/[###-feature-name]/spec.md读取规格文档，若文件不存在则报错ERROR "No feature spec at {path}"。这意味着 spec-template.md 生成的规格文档是整个自动化工作流的前置依赖——没有合格的 spec，后续的 research、contracts、tasks 都无法启动。

从仓库的目录约定（docs/contributing/file-structure.md）看，正式 PRD 由产品团队维护在docs/prds/（如 agent-browser/prd.md），而由模板驱动的规格产物则按 plan 模板约定输出到specs/[###-feature-name]/目录。模板服务的对象是"从用户一句描述出发、快速产出可评审、可测试的规格文档"，与产品团队手工维护的长篇 PRD 形成互补。

二、模板头部：元信息与八步执行主流程

模板头部定义了每条规格必需的元数据字段：

• Feature Branch：[###-feature-name]，如123-chat-search
• Created：创建日期
• Status：Draft（草稿态，评审通过后才进入规划）
• Input：User description: "$ARGUMENTS"，即触发本次规格生成的原始用户描述

紧随其后的Execution Flow (main)用伪代码完整描述了规格文档的生成算法，共八步：

1. Parse user description from Input → If empty: ERROR "No feature description provided" 2. Extract key concepts from description → Identify: actors, actions, data, constraints 3. For each unclear aspect: → Mark with [NEEDS CLARIFICATION: specific question] 4. Fill User Scenarios & Testing section → If no clear user flow: ERROR "Cannot determine user scenarios" 5. Generate Functional Requirements → Each requirement must be testable → Mark ambiguous requirements 6. Identify Key Entities (if data involved) 7. Run Review Checklist → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties" → If implementation details found: ERROR "Remove tech details" 8. Return: SUCCESS (spec ready for planning)

这八步揭示了模板的三大设计意图，值得在编写时时刻对照：

1. 输入校验前置：空描述直接报错，绝不猜测用户意图（步骤 1）；
2. 歧义显式化：任何不清楚的点都不得擅自假设，必须标记为[NEEDS CLARIFICATION: ...]（步骤 3、5）；
3. 内容边界硬约束：步骤 7 的双重检查是"质量关卡"——既不允许规格带着未澄清的歧义进入规划（WARN），也严格禁止出现技术实现细节（ERROR）。一旦发现语言、框架、API 等 HOW 层面的内容，整个规格会被判定失败。

三、Quick Guidelines：写 WHAT 与 WHY，不写 HOW

模板用三行闪电指南划定了规格文档的内容边界：

• ✅Focus on WHAT users need and WHY（用户需要什么、为什么需要）
• ❌Avoid HOW to implement（不得出现技术栈、API、代码结构）
• 👥Written for business stakeholders, not developers（面向业务干系人而非开发者）

Section Requirements（章节要求）

• Mandatory sections：每个 feature 都必须完成的章节；
• Optional sections：仅当与当前 feature 相关时才保留；
• 不适用即删除：当某章节不适用时，整节删除，不要留 "N/A" 占位。这是模板的一个硬性排版要求——空占位符对评审毫无价值。

For AI Generation（AI 生成时的四条铁律）

当从用户 prompt 生成规格时，模板要求：

1. 标记所有歧义：任何需要假设的地方都用[NEEDS CLARIFICATION: specific question]标记；
2. 不要猜测：prompt 没有明确的东西（例如只写了"login system"却没说认证方式），就必须标记；
3. 以测试者思维写作：任何模糊需求都应能通过"可测试且无歧义"这一检查项；
4. 常见未充分指定的领域（模板给出了五类高频盲区）：
   • 用户类型与权限（User types and permissions）
   • 数据保留/删除策略（Data retention/deletion policies）
   • 性能目标与规模（Performance targets and scale）
   • 错误处理行为（Error handling behaviors）
   • 集成需求（Integration requirements）
   • 安全/合规需求（Security/compliance needs）

四、User Scenarios & Testing（必填）：用户故事的三种写法

这是规格的必填章节，包含三个子部分：

Primary User Story（主用户旅程）

用平实语言描述主要用户旅程。注意"旅程"而非"功能列表"——它回答的是"用户在什么情境下、带着什么目标、经历哪些步骤达成目标"，为后续所有需求提供叙事锚点。

Acceptance Scenarios（验收场景）

采用 BDD 风格的Given / When / Then三段式：

1. **Given** [初始状态], **When** [动作], **Then** [预期结果] 2. **Given** [初始状态], **When** [动作], **Then** [预期结果]

每个场景必须可验证。仓库中的真实 PRD docs/prds/agent-browser/prd.md 第 6 节"验收标准"就是以这种可执行场景思维写成的（如"全新安装、不做任何配置，对 Agent 说打开 GitHub → 预览框展开、页面呈现、Agent 读到内容并回答"），可以对照体会"初始状态 → 动作 → 可观察结果"的颗粒度。

Edge Cases（边界情况）

模板给出了两个固定句式，强迫作者显式思考异常路径：

• What happens when [boundary condition]?（边界条件发生时怎么办？）
• How does system handle [error scenario]?（错误场景如何处理？）

在 AionUi 的 agent-browser PRD 中可以看到这类思考的成熟形态：如"输入不带 http:// 的域名自动补全协议""页面加载失败（断网、404）→ 页内给出可理解的错误提示 + 重试按钮，不白屏""同时开着两个 AionUi 窗口 → 各自的 Agent 只操作各自实例内的浏览器，互不串扰"。

五、Requirements（必填）：FR 编号需求体系与歧义标记

Functional Requirements（功能需求）

模板给出了统一编号格式FR-###，每条需求以 MUST 等强约束动词开头，保证可测试性：

• FR-001: System MUST [具体能力，如 "allow users to create accounts"]
• FR-002: System MUST [具体能力，如 "validate email addresses"]
• FR-003: Users MUST be able to [关键交互，如 "reset their password"]
• FR-004: System MUST [数据要求，如 "persist user preferences"]
• FR-005: System MUST [行为要求，如 "log all security events"]

编号的好处是让后续 plan、tasks、测试用例可以直接引用（如FR-003），形成需求追踪链。模板特意演示了如何标记模糊需求：

• FR-006: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
• FR-007: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

注意这里标记的粒度：不仅指出"不清楚"，还给出候选方向（email/password、SSO、OAuth？），让业务方能够用最小成本作答。

Key Entities（关键实体）

仅当功能涉及数据时包含。格式为实体名 + 其表示什么 + 关键属性（不含实现细节）：

• [Entity 1]: [代表什么，关键属性（不涉及实现）]
• [Entity 2]: [代表什么，与其他实体的关系]

这与下游 plan-template.md Phase 1 的衔接点一致——plan 模板会"从 feature spec 提取实体 → 生成>无实现细节（语言、框架、API）

Requirement Completeness（需求完备性）

• 无残留的 [NEEDS CLARIFICATION] 标记
• 需求可测试且无歧义
• 成功标准可度量
• 范围边界清晰
• 依赖与假设已识别

这两组检查分别对应 Execution Flow 步骤 7 中的 WARN 与 ERROR 分支：存在未澄清歧义 →WARN "Spec has uncertainties"；出现实现细节 →ERROR "Remove tech details"。规格只有同时通过两组检查，才返回SUCCESS (spec ready for planning)。

七、Execution Status：main() 实时更新的过程清单

模板末尾保留了由 main() 在处理过程中勾选的状态清单，本质是 Execution Flow 八步的可视化映射：

• User description parsed
• Key concepts extracted
• Ambiguities marked
• User scenarios defined
• Requirements generated
• Entities identified
• Review checklist passed

对照第二节的八步流程可发现：状态清单实际将第 8 步"Return: SUCCESS"之外的七个动作逐一物化。它的价值在于过程透明——评审者打开规格即可看出该文档处于生成链路中的哪个环节，哪一步还未完成。

八、模板与仓库工作流的纵深衔接

spec-template.md 不是孤立文档，它与仓库中其他 Specify 资产形成严密的上下游关系：

上游：constitution.md（宪法约束）

.specify/memory/constitution.md 是 AionUi 的"项目宪法"，定义多 Agent 集成、模块化架构、用户体验、安全隐私、开发者体验五条核心原则及技术标准。plan-template.md 的执行流程中专门有Constitution Check关卡（"基于 constitution 文档内容填写"），并要求在 Phase 0 前与 Phase 1 设计后各评审一次。这意味着 spec 中声明的需求与 Key Entities 若与宪法冲突（例如违反"本地存储会话历史""凭据隔离"等安全原则），会在 plan 阶段被拦截并要求简化方案（ERROR "Simplify approach first"）。

下游：plan-template.md 与 tasks-template.md

• plan-template.md 明确从 spec 提取三类输入：功能需求 → API contracts（每个用户动作 → 端点）；Key Entities → contenteditable="false">【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20+ more CLI Agent | Customize your assistants | Team them up｜Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi