feature-spec-writing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFeature Spec Writing
功能规格说明书编写
Purpose
目的
Creates implementation-ready feature specifications that break down PRD requirements into detailed, actionable specs with comprehensive edge case coverage.
创建可直接用于落地的功能规格说明书，将PRD需求拆解为详尽、可执行的规格文档，并全面覆盖边缘场景。
When NOT to Use This Skill
何时不使用此Skill
- Initial product requirements (use instead)
prd-writing - System architecture design (use instead)
technical-spec-writing - Reviewing existing specs (use instead)
feature-spec-reviewing - Bug fixes (no spec needed, just fix it)
- Minor enhancements < 1 day of work (overkill)
- 初始产品需求阶段（请使用）
prd-writing - 系统架构设计（请使用）
technical-spec-writing - 评审现有规格文档（请使用）
feature-spec-reviewing - Bug修复（无需规格文档，直接修复即可）
- 耗时少于1天的小功能优化（大材小用）
Key Differences from PRD
与PRD的核心差异
| Aspect | PRD | Feature Spec |
|---|---|---|
| Scope | Product/Initiative | Single Feature |
| Audience | Stakeholders | Engineers |
| Detail Level | High-level | Implementation-ready |
| Edge Cases | Summary | Exhaustive |
| User Stories | Multiple (3-7) | Single primary + variants |
| Success Metrics | Business outcomes | Feature-level KPIs |
| 维度 | PRD | 功能规格说明书 |
|---|---|---|
| 范围 | 产品/项目整体 | 单一功能 |
| 受众 | 利益相关方 | 开发工程师 |
| 详细程度 | 高层级概述 | 可直接落地 |
| 边缘场景 | 概要提及 | 全面覆盖 |
| 用户故事 | 多个（3-7个） | 单个核心故事+变体 |
| 成功指标 | 业务成果 | 功能级KPI |
Workflow
工作流程
Step 1: Context Gathering
步骤1：背景信息收集
Invoke to understand project context.
check-historyIf a parent PRD exists, reference it:
markdown
Questions to gather:
1. Which PRD/user story does this feature implement?
2. What's the single-sentence feature description?
3. Who is the primary user persona?
4. What technical constraints exist?
5. What's the target implementation timeline?调用以了解项目背景。
check-history若存在父级PRD，请参考该文档：
markdown
需要收集的问题：
1. 本功能对应哪个PRD/用户故事？
2. 用一句话描述该功能？
3. 核心用户角色是什么？
4. 存在哪些技术约束？
5. 目标落地时间线是什么？Step 2: Feature Definition
步骤2：功能定义
Write a clear, one-sentence feature definition:
markdown
**Feature:** [Verb] [what] for [whom] to [achieve outcome]
Examples:
✅ "Display shipping cost estimates on product pages for shoppers to compare options before checkout"
✅ "Allow admins to create custom permission roles to match their organization structure"
✅ "Send real-time push notifications for transactions to help users detect fraud immediately"
❌ "Improve the shipping experience" (too vague)
❌ "Add role management" (missing who and why)撰写清晰的一句话功能定义：
markdown
**功能：** [动作] [对象] 为了[用户] 达成[目标]
示例：
✅ "在商品页面展示运费估算，方便购物者在结账前对比选项"
✅ "允许管理员创建自定义权限角色，以匹配其组织架构"
✅ "发送交易实时推送通知，帮助用户立即检测欺诈行为"
❌ "优化配送体验"（过于模糊）
❌ "添加角色管理"（缺少用户和目标）Step 3: User Story
步骤3：用户故事
Write the primary user story with variants:
markdown
undefined撰写核心用户故事及变体：
markdown
undefinedPrimary User Story
核心用户故事
As a [specific user type]
I want [specific goal]
So that [concrete benefit]
作为 [具体用户类型]
我希望 [具体目标]
以便 [实际收益]
Story Variants (if applicable)
故事变体（如适用）
Variant A - [Scenario Name]:
As a [user], I want [alternative goal], so that [benefit]
Variant B - [Scenario Name]:
As a [user], I want [different goal], so that [benefit]
undefined变体A - [场景名称]:
作为[用户]，我希望[替代目标]，以便[收益]
变体B - [场景名称]:
作为[用户]，我希望[不同目标]，以便[收益]
undefinedStep 4: Acceptance Criteria
步骤4：验收标准
Define comprehensive acceptance criteria covering:
- Happy Path - Normal successful flow
- Input Validation - What's valid/invalid
- Edge Cases - Boundary conditions
- Error States - Failure handling
- Performance - Speed/resource expectations
- Security - Authentication/authorization
- Accessibility - A11y requirements (if UI)
gherkin
undefined定义全面的验收标准，涵盖：
- 正常流程 - 常规成功场景
- 输入验证 - 有效/无效输入规则
- 边缘场景 - 边界条件
- 错误状态 - 故障处理逻辑
- 性能要求 - 速度/资源预期
- 安全要求 - 认证/授权规则
- 可访问性 - A11y要求（若涉及UI）
gherkin
undefinedAcceptance Criteria
验收标准
Happy Path
正常流程
Scenario: Successful [action]
Given [precondition]
And [additional context]
When [user action]
Then [expected outcome]
And [additional outcome]
场景：成功执行[动作]
假设 [前置条件]
且 [额外上下文]
当 [用户操作]
则 [预期结果]
且 [额外结果]
Validation
输入验证
Scenario: Invalid [input type]
Given [context]
When [user provides invalid input]
Then [validation message shown]
And [action is prevented]
场景：无效[输入类型]
假设 [上下文]
当 [用户提供无效输入]
则 [显示验证提示]
且 [阻止操作执行]
Edge Cases
边缘场景
Scenario: [Boundary condition]
Given [edge case setup]
When [action at boundary]
Then [expected behavior]
场景：[边界条件]
假设 [边缘场景设置]
当 [执行边界操作]
则 [预期行为]
Error Handling
错误处理
Scenario: [Failure type]
Given [normal context]
And [dependency fails]
When [user action]
Then [graceful degradation]
And [user informed of issue]
场景：[故障类型]
假设 [正常上下文]
且 [依赖服务故障]
当 [用户操作]
则 [优雅降级]
且 [告知用户问题]
Performance
性能要求
Scenario: Response time under load
Given [load conditions]
When [action performed]
Then [response within X ms]
场景：高负载下的响应时间
假设 [负载条件]
当 [执行操作]
则 [响应时间在X毫秒内]
Security
安全要求
Scenario: Unauthorized access attempt
Given [user without permission]
When [user attempts action]
Then [access denied]
And [attempt logged]
undefined场景：未授权访问尝试
假设 [无权限用户]
当 [用户尝试操作]
则 [拒绝访问]
且 [记录尝试行为]
undefinedStep 5: Error States Matrix
步骤5：错误状态矩阵
Document all error conditions:
markdown
undefined记录所有错误条件：
markdown
undefinedError States
错误状态
| Error Condition | User Message | System Action | Recovery |
|---|---|---|---|
| Invalid input | "Please enter valid X" | Highlight field | User corrects |
| Network failure | "Connection lost. Retrying..." | Auto-retry 3x | Manual retry button |
| Server error | "Something went wrong" | Log error, alert oncall | Show support contact |
| Timeout | "Taking too long" | Cancel request | Offer retry |
| Not found | "Item not available" | 404 response | Suggest alternatives |
| Unauthorized | "Access denied" | 403 response | Redirect to login |
| Rate limited | "Too many requests" | 429 response | Show wait time |
undefined| 错误条件 | 用户提示 | 系统动作 | 恢复方式 |
|---|---|---|---|
| 无效输入 | "请输入有效的X" | 高亮字段 | 用户修正输入 |
| 网络故障 | "连接断开，正在重试..." | 自动重试3次 | 手动重试按钮 |
| 服务器错误 | "出现了一些问题" | 记录错误，通知值班人员 | 显示支持联系方式 |
| 请求超时 | "耗时过长" | 取消请求 | 提供重试选项 |
| 资源不存在 | "该商品不可用" | 返回404响应 | 推荐替代选项 |
| 未授权 | "访问被拒绝" | 返回403响应 | 重定向至登录页 |
| 请求频率受限 | "请求过于频繁" | 返回429响应 | 显示等待时间 |
undefinedStep 6: UI/UX Considerations (if applicable)
步骤6：UI/UX考量（如适用）
For user-facing features:
markdown
undefined面向用户的功能需包含：
markdown
undefinedUI/UX Notes
UI/UX说明
User Flow
用户流程
- Entry point: [Where user starts]
- Key interactions: [Click, type, swipe, etc.]
- Exit points: [Where user ends up]
- 入口：[用户起始位置]
- 关键交互：[点击、输入、滑动等]
- 出口：[用户最终位置]
Responsive Behavior
响应式行为
- Desktop: [Layout/behavior]
- Tablet: [Adaptations]
- Mobile: [Mobile-specific behavior]
- 桌面端：[布局/行为]
- 平板端：[适配方案]
- 移动端：[移动端专属行为]
Loading States
加载状态
- Initial load: [Skeleton/spinner]
- Action pending: [Button state, progress]
- Background refresh: [Indicator]
- 初始加载：[骨架屏/加载动画]
- 操作等待：[按钮状态、进度提示]
- 后台刷新：[状态指示器]
Empty States
空状态
- No data: [What to show]
- Error state: [Recovery UI]
- First-time user: [Onboarding]
- 无数据：[显示内容]
- 错误状态：[恢复UI]
- 首次使用：[引导流程]
Accessibility
可访问性
- Keyboard navigation: [Tab order, shortcuts]
- Screen reader: [ARIA labels, announcements]
- Color contrast: [WCAG AA compliance]
undefined- 键盘导航：[Tab顺序、快捷键]
- 屏幕阅读器：[ARIA标签、播报内容]
- 色彩对比度：[符合WCAG AA标准]
undefinedStep 7: Technical Constraints
步骤7：技术约束
Document implementation constraints:
markdown
undefined记录落地约束：
markdown
undefinedTechnical Constraints
技术约束
Dependencies
依赖项
| Dependency | Type | Status | Owner |
|---|---|---|---|
| [API/Service] | Internal | Ready/Pending | [Team] |
| [Third-party] | External | Integrated/Pending | [Vendor] |
| 依赖项 | 类型 | 状态 | 负责人 |
|---|---|---|---|
| [API/服务] | 内部 | 就绪/待就绪 | [团队] |
| [第三方服务] | 外部 | 已集成/待集成 | [供应商] |
Limitations
限制条件
- [Technical limitation 1 and workaround]
- [Technical limitation 2 and workaround]
- [技术限制1及解决方案]
- [技术限制2及解决方案]
Non-Functional Requirements
非功能需求
| Requirement | Target | Measurement |
|---|---|---|
| Response time | < 200ms p95 | APM |
| Availability | 99.9% | Monitoring |
| Throughput | 1000 req/s | Load test |
| 需求 | 目标 | 衡量方式 |
|---|---|---|
| 响应时间 | p95 < 200ms | APM监控 |
| 可用性 | 99.9% | 监控系统 |
| 吞吐量 | 1000 req/s | 负载测试 |
Data Requirements
数据需求
- Input: [Data types, formats, sizes]
- Output: [Response format, caching]
- Storage: [Persistence requirements]
undefined- 输入：[数据类型、格式、大小]
- 输出：[响应格式、缓存规则]
- 存储：[持久化要求]
undefinedStep 8: Output Generation
步骤8：输出生成
Generate the feature spec using TEMPLATE.md. Verify:
- Clear one-sentence feature definition
- Primary user story with variants if needed
- Comprehensive acceptance criteria (happy + edge + error)
- Error states matrix complete
- Technical constraints documented
- Definition of done checklist included
使用TEMPLATE.md生成功能规格说明书，并验证以下内容：
- 清晰的一句话功能定义
- 核心用户故事及必要变体
- 全面的验收标准（正常流程+边缘场景+错误处理）
- 完整的错误状态矩阵
- 已记录技术约束
- 包含完成定义检查清单
Examples
示例
Example 1: E-Commerce - Product Quick View
示例1：电商 - 商品快速预览
Feature: Display product quick view modal on hover for shoppers to preview details without leaving the catalog page.
Parent PRD: Catalog Browsing Experience (PRD-2024-015)
Primary Story:
As a shopper browsing the catalog,
I want to preview product details without leaving the page,
so that I can quickly evaluate products and continue browsing.Key Acceptance Criteria:
gherkin
Scenario: Quick view on hover
Given I am on the product catalog page
When I hover over a product card for 500ms
Then a quick view modal appears
And shows product image, name, price, and sizes
And shows "Add to Cart" and "View Details" buttons
Scenario: Quick view on mobile
Given I am on mobile device
When I tap the quick view icon on a product card
Then a bottom sheet slides up with product details
Scenario: Image gallery in quick view
Given the quick view modal is open
When I click the next arrow
Then the next product image displays
And current position indicator updatesError States:
| Condition | Message | Action |
|---|---|---|
| Image load failure | Shows placeholder | Retry on visibility |
| Product out of stock | "Sold Out" badge | Hide Add to Cart |
| Network timeout | "Loading..." | Show retry button |
功能： 购物者 hover 商品卡片时显示快速预览模态框，无需离开商品列表页即可查看详情。
父级PRD： 商品浏览体验（PRD-2024-015）
核心用户故事：
作为浏览商品列表的购物者，
我希望无需离开当前页面即可预览商品详情，
以便快速评估商品并继续浏览。关键验收标准：
gherkin
场景：Hover触发快速预览
假设我在商品列表页
当我hover商品卡片500ms
则快速预览模态框弹出
且显示商品图片、名称、价格和尺码
且显示"加入购物车"和"查看详情"按钮
场景：移动端快速预览
假设我使用移动设备
当我点击商品卡片上的快速预览图标
则底部滑出面板显示商品详情
场景：快速预览中的图片画廊
假设快速预览模态框已打开
当我点击下一页箭头
则显示下一张商品图片
且当前位置指示器更新错误状态：
| 条件 | 提示 | 动作 |
|---|---|---|
| 图片加载失败 | 显示占位图 | 可见时自动重试 |
| 商品售罄 | 显示"已售罄"徽章 | 隐藏加入购物车按钮 |
| 网络超时 | "加载中..." | 显示重试按钮 |
Example 2: SaaS - Role Permission Editor
示例2：SaaS - 角色权限编辑器
Feature: Allow admins to configure granular permissions for custom roles through a visual permission editor.
Parent PRD: Team Permissions System (PRD-2024-023)
Primary Story:
As an organization admin,
I want to configure exactly what each role can access,
so that I can enforce our security policies.Story Variants:
Variant A - Bulk Permission Update:
As an admin managing many roles,
I want to update permissions across multiple roles at once,
so that I can efficiently apply policy changes.
Variant B - Permission Templates:
As an admin setting up a new role,
I want to start from a template,
so that I don't have to configure from scratch.Acceptance Criteria:
gherkin
Scenario: Grant permission to role
Given I am editing the "Manager" role
And I expand the "Reports" permission group
When I toggle "View Financial Reports" to enabled
Then the permission is added to the role
And a "Save Changes" button appears
And no changes are persisted until I click Save
Scenario: Permission dependency
Given "Edit Reports" requires "View Reports"
When I enable "Edit Reports"
Then "View Reports" is automatically enabled
And shows "Required by Edit Reports" tooltip
Scenario: Conflicting permissions
Given the role has "View All Data"
When I try to add "Restrict to Own Data"
Then a conflict warning appears
And I must resolve before saving功能： 允许管理员通过可视化权限编辑器为自定义角色配置细粒度权限。
父级PRD： 团队权限系统（PRD-2024-023）
核心用户故事：
作为组织管理员，
我希望能精确配置每个角色的访问权限，
以便执行我们的安全策略。故事变体：
变体A - 批量权限更新：
作为管理多个角色的管理员，
我希望能一次性更新多个角色的权限，
以便高效应用策略变更。
变体B - 权限模板：
作为创建新角色的管理员，
我希望能从模板开始配置，
以便无需从零开始设置。验收标准：
gherkin
场景：为角色授予权限
假设我正在编辑"经理"角色
且我展开了"报表"权限组
当我将"查看财务报表"切换为启用状态
则该权限被添加至角色
且出现"保存更改"按钮
且点击保存前不会持久化更改
场景：权限依赖
假设"编辑报表"依赖"查看报表"
当我启用"编辑报表"
则"查看报表"自动启用
且显示"被编辑报表权限依赖"提示
场景：权限冲突
假设角色已拥有"查看所有数据"权限
当我尝试添加"仅查看自有数据"权限
则显示冲突警告
且必须解决冲突后才能保存Example 3: Fintech - Transaction Dispute Flow
示例3：金融科技 - 交易争议流程
Feature: Enable cardholders to dispute transactions directly from transaction alerts with guided flow and document upload.
Parent PRD: Fraud Detection & Response (PRD-2024-031)
Primary Story:
As a cardholder who received a suspicious transaction alert,
I want to dispute the charge immediately from the notification,
so that I can protect my account without calling support.Acceptance Criteria:
gherkin
Scenario: Initiate dispute from alert
Given I received a transaction alert
When I tap "Dispute This Charge"
Then I see dispute reason options
And can select "Fraudulent", "Duplicate", "Not Received", "Other"
Scenario: Upload supporting documents
Given I selected "Not Received" as dispute reason
When I reach the evidence step
Then I can upload photos or documents
And supported formats are JPG, PNG, PDF
And max file size is 10MB
Scenario: Dispute submission confirmation
Given I completed all dispute steps
When I tap "Submit Dispute"
Then I see confirmation with case number
And I receive email confirmation
And card is temporarily frozen pending reviewError States:
| Condition | Message | Action |
|---|---|---|
| File too large | "File exceeds 10MB limit" | Offer compression |
| Invalid file type | "Please upload JPG, PNG, or PDF" | Show accepted types |
| Submission failed | "Couldn't submit. Saved as draft." | Auto-save, retry later |
| Duplicate dispute | "Dispute already filed for this transaction" | Show existing case |
功能： 允许持卡人直接从交易通知中发起争议，提供引导流程和文档上传功能。
父级PRD： 欺诈检测与响应（PRD-2024-031）
核心用户故事：
作为收到可疑交易通知的持卡人，
我希望能直接从通知中立即发起争议，
以便无需联系客服即可保护我的账户。验收标准：
gherkin
场景：从通知发起争议
假设我收到了交易通知
当我点击"争议此交易"
则我看到争议原因选项
且可选择"欺诈交易"、"重复扣款"、"未收到商品"、"其他"
场景：上传支持文档
假设我选择"未收到商品"作为争议原因
当我进入证据步骤
则我可以上传照片或文档
且支持格式为JPG、PNG、PDF
且最大文件大小为10MB
场景：争议提交确认
假设我完成了所有争议步骤
当我点击"提交争议"
则我看到包含案件编号的确认信息
且我收到邮件确认
且卡片在审核期间被临时冻结错误状态：
| 条件 | 提示 | 动作 |
|---|---|---|
| 文件过大 | "文件超过10MB限制" | 提供压缩建议 |
| 无效文件类型 | "请上传JPG、PNG或PDF格式文件" | 显示支持的格式 |
| 提交失败 | "提交失败，已保存为草稿" | 自动保存，支持稍后重试 |
| 重复争议 | "此交易已提交争议" | 显示现有案件信息 |
Anti-Patterns to Avoid
需避免的反模式
Too Broad Scope
范围过宽
❌ "User authentication feature" (multiple features bundled)
✅ "Password reset via email flow" (single, focused feature)❌ "用户认证功能"（多个功能捆绑）
✅ "邮箱重置密码流程"（单一、聚焦的功能）Missing Edge Cases
遗漏边缘场景
❌ Only documenting happy path
✅ Including validation, errors, timeouts, rate limits❌ 仅记录正常流程
✅ 包含验证、错误、超时、频率限制等场景Vague Acceptance Criteria
验收标准模糊
❌ "User can see products quickly"
✅ "Quick view modal appears within 300ms of hover"❌ "用户可以快速查看商品"
✅ "hover后300ms内弹出快速预览模态框"No Error States
未记录错误状态
❌ Assuming everything works
✅ Documenting what happens when things fail❌ 假设所有流程都能正常运行
✅ 记录故障时的处理逻辑Implementation Details
包含实现细节
❌ "Use Redis for caching with 5-minute TTL"
✅ "Response should be cached for improved performance"
(Save implementation details for technical spec)❌ "使用Redis缓存，TTL为5分钟"
✅ "响应应被缓存以提升性能"
（实现细节请留到技术规格文档中）Integration with Other Skills
与其他Skill的集成
Receives From:
- - High-level requirements to break down
prd-writing - - Approved PRD ready for feature specs
prd-reviewing
Works With:
- - Review and validate feature specs
feature-spec-reviewing
Leads To:
- - Technical design for implementation
technical-spec-writing - - Implementation task breakdown
sparc-planning
接收自：
- - 需要拆解的高层级需求
prd-writing - - 已获批的PRD，可用于细化功能规格
prd-reviewing
协同使用：
- - 评审和验证功能规格文档
feature-spec-reviewing
导出至：
- - 用于落地的技术设计文档
technical-spec-writing - - 落地任务拆解
sparc-planning
Output Validation
输出验证
Before finalizing the feature spec:
- One-sentence feature definition is clear
- Primary user story follows format
- Happy path acceptance criteria defined
- Edge cases documented (minimum 3)
- Error states matrix complete
- Performance expectations stated
- Security considerations noted
- Definition of done checklist included
- Links to parent PRD if applicable
在最终确定功能规格说明书前，请检查：
- 一句话功能定义清晰
- 核心用户故事符合格式要求
- 定义了正常流程的验收标准
- 记录了至少3个边缘场景
- 错误状态矩阵完整
- 明确了性能预期
- 考虑了安全因素
- 包含完成定义检查清单
- 若有父级PRD，已添加链接
Resources
资源
- See TEMPLATE.md for the complete feature spec output format
- 完整的功能规格说明书输出格式请参考TEMPLATE.md
Related Agent
相关Agent
For comprehensive specification guidance that coordinates this and other spec skills, use the agent.
specification-architect如需协调此Skill及其他规格相关Skill的综合规格指导，请使用**** agent。
specification-architect