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 upStar 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 开发工作流的一组标准化模板彼此以「输入 → 产物」的方式串联模板文件产物触发命令/阶段spec-template.md功能规格说明书本文主角需求阶段plan-template.md实现计划含 research、data-model、contracts/plan命令tasks-template.md编号任务清单T001…/tasks命令agent-file-template.mdAgent 上下文文件CLAUDE.md 等Phase 1 增量更新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-searchCreated创建日期StatusDraft草稿态评审通过后才进入规划InputUser 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歧义显式化任何不清楚的点都不得擅自假设必须标记为[NEEDS CLARIFICATION: ...]步骤 3、5内容边界硬约束步骤 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 GenerationAI 生成时的四条铁律当从用户 prompt 生成规格时模板要求标记所有歧义任何需要假设的地方都用[NEEDS CLARIFICATION: specific question]标记不要猜测prompt 没有明确的东西例如只写了login system却没说认证方式就必须标记以测试者思维写作任何模糊需求都应能通过可测试且无歧义这一检查项常见未充分指定的领域模板给出了五类高频盲区用户类型与权限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 Statusmain() 实时更新的过程清单模板末尾保留了由 main() 在处理过程中勾选的状态清单本质是 Execution Flow 八步的可视化映射User description parsedKey concepts extractedAmbiguities markedUser scenarios definedRequirements generatedEntities identifiedReview 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.mdplan-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 upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考