write-spec
從問題或想法寫出功能規格與 PRD
中文翻譯
--- name: write-spec description: 從問題陳述或功能想法寫出功能規格或 PRD。當要把模糊的想法或使用者需求變成結構化文件、用目標與非目標界定功能範圍、定義成功指標與驗收標準，或是把大需求拆成分階段的規格時使用。 argument-hint: "<feature or problem statement>" --- # 撰寫規格 > 如果看到不熟悉的 placeholder，或需要確認目前連接了哪些工具，請見 [CONNECTORS.md](../../CONNECTORS.md)。 撰寫功能規格或產品需求文件（PRD）。 ## 用法 ``` /write-spec $ARGUMENTS ``` ## 工作流程 ### 1. 理解這個功能 問使用者想為什麼寫規格。以下任何一種都接受： - 功能名稱（「SSO support」） - 問題陳述（「Enterprise customers keep asking for centralized auth」） - 使用者需求（「Users want to export their data as CSV」） - 模糊的想法（「We should do something about onboarding drop-off」） ### 2. 蒐集背景 向使用者詢問下列事項。要用對話的方式問，不要一次把所有問題丟出來。先問最重要的，再邊做邊補缺口： - **使用者問題**：這解決什麼問題？誰會遇到？ - **目標使用者**：這服務哪些使用者客群？ - **成功指標**：我們怎麼知道這有效？ - **限制**：技術限制、時程、法規要求、相依項目 - **先前做法**：以前有人試過嗎？已經有現成的解法嗎？ ### 3. 從已連接的工具拉取背景 如果已連接 **~~project tracker**： - 搜尋相關的 ticket、epic 或功能 - 帶入任何既有的需求或驗收標準 - 找出對其他工作項目的相依 如果已連接 **~~knowledge base**： - 搜尋相關的研究文件、先前的規格或設計文件 - 帶入相關的使用者研究發現 - 找出相關的會議記錄或決策紀錄 如果已連接 **~~design**： - 拉取相關的 mockup、wireframe 或設計探索 - 搜尋和這個功能相關的 design system 元件 如果這些工具沒有連接，就完全依使用者提供的內容來做。不要要求使用者去連接工具，直接用手上有的資訊往下走。 ### 4. 產生 PRD 產出有以下章節的結構化 PRD。每個章節該放什麼的詳細指引，見下方的 **PRD 結構**。 - **問題陳述**：使用者的問題、誰受影響，以及不解決的影響（2-3 句） - **目標**：3-5 個具體、可衡量、並和使用者或商業指標掛勾的成果 - **非目標**：3-5 件明確排除在範圍外的事，每件附上簡短理由 - **使用者故事**：標準格式（「As a [user type], I want [capability] so that [benefit]」），依 persona 分組 - **需求**：分成 Must-Have（P0）、Nice-to-Have（P1）和 Future Considerations（P2），每項附驗收標準 - **成功指標**：領先指標（變化快）和落後指標（隨時間變化），附上具體目標值 - **待解決問題**：尚未解決的問題，標明需要誰來回答（工程、設計、法務、資料） - **時程考量**：硬性期限、相依項目和分階段 ### 5. 檢視與迭代 產生 PRD 之後： - 問使用者有沒有哪些章節需要調整 - 主動提議擴充特定章節 - 主動提議建立後續產出物（設計 brief、工程 ticket 拆解、給利害關係人的提案） ## PRD 結構 ### 問題陳述 - 用 2-3 句話描述使用者的問題 - 誰遇到這個問題、多常遇到 - 不解決的代價是什麼（使用者的痛苦、商業影響、競爭風險） - 用證據支撐：使用者研究、客服資料、指標或客戶回饋 ### 目標 - 這個功能應該達成的 3-5 個具體、可衡量的成果 - 每個目標都要能回答：「我們怎麼知道這成功了？」 - 區分使用者目標（使用者得到什麼）和商業目標（公司得到什麼） - 目標應該是成果，不是產出（「把首次體驗價值的時間縮短 50%」，而不是「做一個 onboarding 精靈」） ### 非目標 - 這個功能明確「不會」做的 3-5 件事 - 這個版本範圍之外的相鄰能力 - 每個非目標都簡短說明為什麼排除（影響不夠大、太複雜、屬於另一個專案、時機太早） - 非目標可以避免實作過程中範圍蔓延，也能和利害關係人先對齊期待 ### 使用者故事 用標準格式寫使用者故事：「As a [user type], I want [capability] so that [benefit]」 指引： - 使用者類型要具體到有意義（「enterprise admin」，而不是只寫「user」） - 能力要描述他們想達成什麼，而不是怎麼做 - 效益要說明「為什麼」：這帶來什麼價值 - 要包含邊界情況：錯誤狀態、空狀態、邊界條件 - 如果功能服務多種 persona，就納入不同的使用者類型 - 依優先順序排列，最重要的故事放前面 範例： - 「As a team admin, I want to configure SSO for my organization so that my team members can log in with their corporate credentials」 - 「As a team member, I want to be automatically redirected to my company's SSO login so that I do not need to remember a separate password」 - 「As a team admin, I want to see which members have logged in via SSO so that I can verify the rollout is working」 ### 需求 **Must-Have（P0）**：沒有這些，功能就不能上線。它們代表功能的最小可行版本。問：「如果砍掉這個，功能還能解決核心問題嗎？」如果不能，就是 P0。 **Nice-to-Have（P1）**：能明顯改善體驗，但沒有它們核心情境也能運作。這些常常會在上線後變成快速跟進項目。 **Future Considerations（P2）**：明確排除在 v1 之外，但我們希望設計時留下以後支援的空間。把這些寫下來，可以避免不小心做出讓它們日後變得很難實現的架構決定。 每個需求都要： - 清楚、無歧義地描述預期行為 - 附上驗收標準（見下方） - 註明任何技術考量或限制 - 標記對其他團隊或系統的相依 ### 待解決問題 - 在實作前或實作中需要答案的問題 - 每個都標明該由誰回答（工程、設計、法務、資料、利害關係人） - 區分阻擋性問題（開始前必須回答）和非阻擋性問題（實作中可以再解決） ### 時程考量 - 硬性期限（合約承諾、活動、法遵日期） - 對其他團隊的工作或發布的相依 - 如果功能大到一個版本放不下，建議的分階段方式 ## 撰寫使用者故事 好的使用者故事具備： - **Independent（獨立）**：可以自己開發、自己交付 - **Negotiable（可協商）**：細節可以討論，故事不是合約 - **Valuable（有價值）**：對使用者（而不只是對團隊）帶來價值 - **Estimable（可估算）**：團隊能大致估出工作量 - **Small（小）**：一個 sprint/iteration 內能完成 - **Testable（可測試）**：有明確的方式驗證它有效 ### 使用者故事的常見錯誤 - 太模糊：「As a user, I want the product to be faster」：具體是哪裡要變快？ - 規定了解法：「As a user, I want a dropdown menu」：描述需求，不要描述 UI 元件 - 沒有效益：「As a user, I want to click a button」：為什麼？這能達成什麼？ - 太大：「As a user, I want to manage my team」：拆成具體的能力 - 以內部為焦點：「As the engineering team, we want to refactor the database」：這是任務，不是使用者故事 ## 需求分類 ### MoSCoW 框架 - **Must have**：沒有這些，功能就不可行。沒得談。 - **Should have**：重要但不是上線的必要條件。高優先的快速跟進項目。 - **Could have**：時間允許的話最好有。砍掉不會延誤交付。 - **Won't have (this time)**：明確排除在範圍外。未來版本可能再回頭看。 ### 分類的小技巧 - 對 P0 要狠一點。must-have 清單越精簡，你就越快上線、越快學到東西。 - 如果每件事都是 P0，就沒有任何一件是 P0。挑戰每一個 must-have：「沒有它，我們真的不會上線嗎？」 - P1 應該是你有信心很快會做的事，不是願望清單。 - P2 是架構上的保險：就算現在不做，它們也會引導設計決策。 ## 定義成功指標 ### 領先指標 上線後變化很快的指標（幾天到幾週）： - **採用率**：有資格的使用者中，試用這個功能的 % - **啟用率**：完成核心動作的使用者 % - **任務完成率**：成功達成目標的使用者 % - **完成時間**：核心流程花多久 - **錯誤率**：使用者遇到錯誤或死路的頻率 - **功能使用頻率**：使用者多常回來使用這個功能 ### 落後指標 需要時間才會顯現的指標（幾週到幾個月）： - **留存影響**：這個功能有改善使用者留存嗎？ - **營收影響**：這有帶動升級、擴展或新營收嗎？ - **NPS / 滿意度變化**：這有改善使用者對產品的感受嗎？ - **客服 ticket 減少**：這有降低客服負擔嗎？ - **競爭勝率**：這有幫助贏得更多案子嗎？ ### 設定目標值 - 目標值要具體：「30 天內採用率達 50%」，而不是「高採用率」 - 目標值以可比的功能、業界基準或明確的假設為依據 - 設定一個「成功」門檻和一個「stretch」目標 - 定義衡量方式：用什麼工具、什麼查詢、什麼時間視窗 - 指定何時評估：上線後 1 週、1 個月、1 季 ## 驗收標準 用 Given/When/Then 格式或檢查清單來寫驗收標準： **Given/When/Then**： - Given [前置條件或情境] - When [使用者採取的動作] - Then [預期的結果] 範例： - Given 管理員已經為他的組織設定好 SSO - When 團隊成員造訪登入頁面 - Then 他們會被自動導向組織的 SSO 供應商 **檢查清單格式**： - [ ] 管理員可以在組織設定中輸入 SSO 供應商 URL - [ ] 團隊成員在登入頁面看到「Log in with SSO」按鈕 - [ ] 如果帳號不存在，SSO 登入會建立新帳號 - [ ] 如果 email 相符，SSO 登入會連結到既有帳號 - [ ] SSO 登入失敗時會顯示清楚的錯誤訊息 ### 驗收標準的小技巧 - 涵蓋正常路徑、錯誤情況和邊界情況 - 具體說明預期行為，不是實作方式 - 包含「不該」發生的事（負面測試案例） - 每項標準都應該可以獨立測試 - 避免含糊的詞：「fast」「user-friendly」「intuitive」，要具體定義這些詞的意思 ## 範圍管理 ### 辨識範圍蔓延 範圍蔓延發生在： - 規格核准後，需求還不斷被加進來 - 「小」的追加累積成明顯更大的專案 - 團隊在做沒有任何使用者要求的功能（「既然都做到這裡了…」） - 上線日期一直往後延，卻沒有明確地重新界定範圍 - 利害關係人加了需求，卻沒有拿掉任何東西 ### 預防範圍蔓延 - 每份規格都寫上明確的非目標 - 要求任何範圍追加都要搭配範圍縮減或時程延長 - 在規格中清楚區分「v1」和「v2」 - 用原始的問題陳述回頭檢視規格：所有內容都在服務它嗎？ - 調查要設時間盒：「如果 2 天內搞不清楚 X，就砍掉」 - 為不在範圍內的好點子建立一個「parking lot」 ## 輸出格式 使用有清楚標題的 markdown。讓文件方便掃讀：忙碌的利害關係人只讀標題和粗體字，就應該能掌握大意。 ## 小提醒 - 對範圍要有主見。一份精簡、定義清楚的規格，比一份龐大模糊的好。 - 如果使用者的想法大到一份規格裝不下，就建議拆成階段，並為第一階段寫規格。 - 成功指標要具體、可衡量，不要含糊（「improve user experience」）。 - 非目標跟目標一樣重要。它們能防止實作過程中的範圍蔓延。 - 待解決問題應該是真的開放的問題：從背景就能回答的問題，不要放進去。
英文原文
---
name: write-spec
description: Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document, scoping a feature with goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into a phased spec.
argument-hint: "<feature or problem statement>"
---
# Write Spec
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
Write a feature specification or product requirements document (PRD).
## Usage
```
/write-spec $ARGUMENTS
```
## Workflow
### 1. Understand the Feature
Ask the user what they want to spec. Accept any of:
- A feature name ("SSO support")
- A problem statement ("Enterprise customers keep asking for centralized auth")
- A user request ("Users want to export their data as CSV")
- A vague idea ("We should do something about onboarding drop-off")
### 2. Gather Context
Ask the user for the following. Be conversational — do not dump all questions at once. Ask the most important ones first and fill in gaps as you go:
- **User problem**: What problem does this solve? Who experiences it?
- **Target users**: Which user segment(s) does this serve?
- **Success metrics**: How will we know this worked?
- **Constraints**: Technical constraints, timeline, regulatory requirements, dependencies
- **Prior art**: Has this been attempted before? Are there existing solutions?
### 3. Pull Context from Connected Tools
If **~~project tracker** is connected:
- Search for related tickets, epics, or features
- Pull in any existing requirements or acceptance criteria
- Identify dependencies on other work items
If **~~knowledge base** is connected:
- Search for related research documents, prior specs, or design docs
- Pull in relevant user research findings
- Find related meeting notes or decision records
If **~~design** is connected:
- Pull related mockups, wireframes, or design explorations
- Search for design system components relevant to the feature
If these tools are not connected, work entirely from what the user provides. Do not ask the user to connect tools — just proceed with available information.
### 4. Generate the PRD
Produce a structured PRD with these sections. See **PRD Structure** below for detailed guidance on what each section should contain.
- **Problem Statement**: The user problem, who is affected, and impact of not solving it (2-3 sentences)
- **Goals**: 3-5 specific, measurable outcomes tied to user or business metrics
- **Non-Goals**: 3-5 things explicitly out of scope, with brief rationale for each
- **User Stories**: Standard format ("As a [user type], I want [capability] so that [benefit]"), grouped by persona
- **Requirements**: Categorized as Must-Have (P0), Nice-to-Have (P1), and Future Considerations (P2), each with acceptance criteria
- **Success Metrics**: Leading indicators (change quickly) and lagging indicators (change over time), with specific targets
- **Open Questions**: Unresolved questions tagged with who needs to answer (engineering, design, legal, data)
- **Timeline Considerations**: Hard deadlines, dependencies, and phasing
### 5. Review and Iterate
After generating the PRD:
- Ask the user if any sections need adjustment
- Offer to expand on specific sections
- Offer to create follow-up artifacts (design brief, engineering ticket breakdown, stakeholder pitch)
## PRD Structure
### Problem Statement
- Describe the user problem in 2-3 sentences
- Who experiences this problem and how often
- What is the cost of not solving it (user pain, business impact, competitive risk)
- Ground this in evidence: user research, support data, metrics, or customer feedback
### Goals
- 3-5 specific, measurable outcomes this feature should achieve
- Each goal should answer: "How will we know this succeeded?"
- Distinguish between user goals (what users get) and business goals (what the company gets)
- Goals should be outcomes, not outputs ("reduce time to first value by 50%" not "build onboarding wizard")
### Non-Goals
- 3-5 things this feature explicitly will NOT do
- Adjacent capabilities that are out of scope for this version
- For each non-goal, briefly explain why it is out of scope (not enough impact, too complex, separate initiative, premature)
- Non-goals prevent scope creep during implementation and set expectations with stakeholders
### User Stories
Write user stories in standard format: "As a [user type], I want [capability] so that [benefit]"
Guidelines:
- The user type should be specific enough to be meaningful ("enterprise admin" not just "user")
- The capability should describe what they want to accomplish, not how
- The benefit should explain the "why" — what value does this deliver
- Include edge cases: error states, empty states, boundary conditions
- Include different user types if the feature serves multiple personas
- Order by priority — most important stories first
Example:
- "As a team admin, I want to configure SSO for my organization so that my team members can log in with their corporate credentials"
- "As a team member, I want to be automatically redirected to my company's SSO login so that I do not need to remember a separate password"
- "As a team admin, I want to see which members have logged in via SSO so that I can verify the rollout is working"
### Requirements
**Must-Have (P0)**: The feature cannot ship without these. These represent the minimum viable version of the feature. Ask: "If we cut this, does the feature still solve the core problem?" If no, it is P0.
**Nice-to-Have (P1)**: Significantly improves the experience but the core use case works without them. These often become fast follow-ups after launch.
**Future Considerations (P2)**: Explicitly out of scope for v1 but we want to design in a way that supports them later. Documenting these prevents accidental architectural decisions that make them hard later.
For each requirement:
- Write a clear, unambiguous description of the expected behavior
- Include acceptance criteria (see below)
- Note any technical considerations or constraints
- Flag dependencies on other teams or systems
### Open Questions
- Questions that need answers before or during implementation
- Tag each with who should answer (engineering, design, legal, data, stakeholder)
- Distinguish between blocking questions (must answer before starting) and non-blocking (can resolve during implementation)
### Timeline Considerations
- Hard deadlines (contractual commitments, events, compliance dates)
- Dependencies on other teams' work or releases
- Suggested phasing if the feature is too large for one release
## User Story Writing
Good user stories are:
- **Independent**: Can be developed and delivered on their own
- **Negotiable**: Details can be discussed, the story is not a contract
- **Valuable**: Delivers value to the user (not just the team)
- **Estimable**: The team can roughly estimate the effort
- **Small**: Can be completed in one sprint/iteration
- **Testable**: There is a clear way to verify it works
### Common Mistakes in User Stories
- Too vague: "As a user, I want the product to be faster" — what specifically should be faster?
- Solution-prescriptive: "As a user, I want a dropdown menu" — describe the need, not the UI widget
- No benefit: "As a user, I want to click a button" — why? What does it accomplish?
- Too large: "As a user, I want to manage my team" — break this into specific capabilities
- Internal focus: "As the engineering team, we want to refactor the database" — this is a task, not a user story
## Requirements Categorization
### MoSCoW Framework
- **Must have**: Without these, the feature is not viable. Non-negotiable.
- **Should have**: Important but not critical for launch. High-priority fast follows.
- **Could have**: Desirable if time permits. Will not delay delivery if cut.
- **Won't have (this time)**: Explicitly out of scope. May revisit in future versions.
### Tips for Categorization
- Be ruthless about P0s. The tighter the must-have list, the faster you ship and learn.
- If everything is P0, nothing is P0. Challenge every must-have: "Would we really not ship without this?"
- P1s should be things you are confident you will build soon, not a wish list.
- P2s are architectural insurance — they guide design decisions even though you are not building them now.
## Success Metrics Definition
### Leading Indicators
Metrics that change quickly after launch (days to weeks):
- **Adoption rate**: % of eligible users who try the feature
- **Activation rate**: % of users who complete the core action
- **Task completion rate**: % of users who successfully accomplish their goal
- **Time to complete**: How long the core workflow takes
- **Error rate**: How often users encounter errors or dead ends
- **Feature usage frequency**: How often users return to use the feature
### Lagging Indicators
Metrics that take time to develop (weeks to months):
- **Retention impact**: Does this feature improve user retention?
- **Revenue impact**: Does this drive upgrades, expansion, or new revenue?
- **NPS / satisfaction change**: Does this improve how users feel about the product?
- **Support ticket reduction**: Does this reduce support load?
- **Competitive win rate**: Does this help win more deals?
### Setting Targets
- Targets should be specific: "50% adoption within 30 days" not "high adoption"
- Base targets on comparable features, industry benchmarks, or explicit hypotheses
- Set a "success" threshold and a "stretch" target
- Define the measurement method: what tool, what query, what time window
- Specify when you will evaluate: 1 week, 1 month, 1 quarter post-launch
## Acceptance Criteria
Write acceptance criteria in Given/When/Then format or as a checklist:
**Given/When/Then**:
- Given [precondition or context]
- When [action the user takes]
- Then [expected outcome]
Example:
- Given the admin has configured SSO for their organization
- When a team member visits the login page
- Then they are automatically redirected to the organization's SSO provider
**Checklist format**:
- [ ] Admin can enter SSO provider URL in organization settings
- [ ] Team members see "Log in with SSO" button on login page
- [ ] SSO login creates a new account if one does not exist
- [ ] SSO login links to existing account if email matches
- [ ] Failed SSO attempts show a clear error message
### Tips for Acceptance Criteria
- Cover the happy path, error cases, and edge cases
- Be specific about the expected behavior, not the implementation
- Include what should NOT happen (negative test cases)
- Each criterion should be independently testable
- Avoid ambiguous words: "fast", "user-friendly", "intuitive" — define what these mean concretely
## Scope Management
### Recognizing Scope Creep
Scope creep happens when:
- Requirements keep getting added after the spec is approved
- "Small" additions accumulate into a significantly larger project
- The team is building features no user asked for ("while we're at it...")
- The launch date keeps moving without explicit re-scoping
- Stakeholders add requirements without removing anything
### Preventing Scope Creep
- Write explicit non-goals in every spec
- Require that any scope addition comes with a scope removal or timeline extension
- Separate "v1" from "v2" clearly in the spec
- Review the spec against the original problem statement — does everything serve it?
- Time-box investigations: "If we cannot figure out X in 2 days, we cut it"
- Create a "parking lot" for good ideas that are not in scope
## Output Format
Use markdown with clear headers. Keep the document scannable — busy stakeholders should be able to read just the headers and bold text to get the gist.
## Tips
- Be opinionated about scope. It is better to have a tight, well-defined spec than an expansive vague one.
- If the user's idea is too big for one spec, suggest breaking it into phases and spec the first phase.
- Success metrics should be specific and measurable, not vague ("improve user experience").
- Non-goals are as important as goals. They prevent scope creep during implementation.
- Open questions should be genuinely open — do not include questions you can answer from context.