Requirements Writing Guide
How to write clear, structured, and testable product and feature requirements.
This guide explains how to write Requirements Documents in Software Factory.
What Are Requirements?
Requirements capture the intent for a product. They define what the product must do and why it exists. When requirements are clear and thorough, everyone working on the product shares the same understanding of what they're building and why.
Software Factory organizes requirements into two types: Product Overview Documents and Feature Requirements Documents.
| Document | Scope | The why | The what | Use it to |
|---|---|---|---|---|
| Product Overview | The entire product | Business motivation, unmet KPIs, and North Star goals | The product and how its parts fit together | Give every stakeholder shared context |
| Feature Requirements (FRD) | One feature or sub-feature | The user's need and desired outcome | Specific, testable behavior | Define what engineering should build |
A useful rule of thumb
Product Overview Documents explain the landscape. FRDs define one independently testable piece of the product within that landscape.
Product Overview Documents
Default Product Overview Documents
Every Software Factory project is initialized with a set of default Product Overview Documents. Users can create additional Product Overview Documents as needed.
| Document | Purpose |
|---|---|
| Business Problem | The pain points the product addresses and why they matter. |
| Current State | The status quo the product improves upon. |
| Personas | The users, their goals, and what success looks like for them. |
| Product Description | What the product is and how its parts fit together. |
| Success Metrics | The key metrics used to measure the success of the product. |
| Technical Requirements | The technical constraints and requirements that the product must meet. |
Writing Guidance
Write in plain language. These documents should be understandable by anyone in the company.
Focus on motivation. A Business Problem document should make the reader feel why this problem matters. A Personas document should make the users feel real.
Feature Requirements Documents
Default Feature Requirements Documents
Software Factory projects are not initialized with any default Feature Requirements Documents. Use the Getting Started alert in Requirements to work with the agent to create the initial set of features. You can calibrate how many features to create in the first pass depending on whether the team prefers a more agile or more sequential planning approach.
When a Feature Requirements Document is created, it uses a default template with an opinionated structure. Customize the template from Settings → Modules → Requirements.
Feature Requirements Documents follow a consistent structure with three sections: Overview, Terminology, and Requirements.
Overview Section
Write 1–2 narrative paragraphs explaining what the feature does and why users need it. A stakeholder should understand the feature's purpose in under a minute. Focus on the problem being solved and the value delivered—not mechanisms or implementation.
Example: The Checkout module handles the purchase flow from cart review through payment confirmation. Customers need a clear path from deciding to buy to completing their purchase, with immediate feedback if something goes wrong. This module integrates with the product catalog for pricing and inventory validation, and with the notification system to confirm successful orders.
Terminology Section
Define terms specific to this feature that might be ambiguous. Use brief, precise definitions. Only include terms directly relevant to understanding this feature—do not define obvious industry-standard terms.
Example:
- Cart: The working collection of items a customer intends to purchase.
- Order: A finalized purchase record created when checkout completes.
- Fulfillment Hold: A temporary block on order processing pending manual review.
Requirements Section
Each requirement represents one cohesive capability and must be independently testable. A requirement has three parts:
Give it a stable ID and title
Use REQ-[PREFIX]-NNN: Requirement Name, with a short feature prefix and a
zero-padded sequence number. For example, use CHK for Checkout. Child
features append their own suffix, such as REQ-AUTH-PR-001 for Password
Reset under Auth.
State the user outcome
Write one sentence in this format:
As a [role], I want to [action], so that I can [outcome].
Make the behavior testable
Add one or more criteria using AC-[PREFIX]-NNN.N. Begin each criterion
with When [condition], the system shall [behavior].
Use shall for mandatory behavior, should for recommended, and may for optional.
Requirements should be:
- User-centered — Describe what users need, not how the system is built internally.
- Testable — Every acceptance criterion should be clear enough to write a test for.
- Atomic — Each acceptance criterion covers one behavior. Split compound behaviors into separate criteria.
Compare a strong and weak requirement
Specific, outcome-focused, and testable
REQ-CHK-003: Payment Confirmation
User story: As a customer, I want to receive confirmation after my payment is processed, so that I know my order was placed successfully.
Acceptance criteria:
- AC-CHK-003.1: When payment processing succeeds, the system shall display a confirmation page with the order number and estimated delivery date.
- AC-CHK-003.2: When payment processing fails, the system shall return the user to the payment form with an error message describing the failure reason.
- AC-CHK-003.3: When the user navigates away during processing, the system shall complete the transaction and display the confirmation on their next visit.
Sub-Features
Large features can be broken into sub-features. A parent feature delivers complete value on its own. A child feature extends that value but is not required for the parent to function. The parent works without the child; the child is meaningless without the parent.
Example: "Search" finds items by keyword—complete on its own. "Search Filters" adds faceted filtering. Search works without filters; filters need search.
Decide whether to split, merge, or nest
| Choose | When |
|---|---|
| Split | Each feature delivers value independently, or different roles own the work |
| Merge | The requirements break without each other, complete one task together, or fit naturally into one sentence |
| Nest | The parent already delivers value, while the child is optional and meaningless without the parent |
Example:
Parent Feature: User Management
User Management lets administrators create, view, edit, and deactivate user accounts. Admins can reset passwords and manage basic profile information. This core functionality delivers value on its own—organizations can manage their users without any of the child features below.
Sub-Features
- User Roles: Lets admins assign roles to control what users can access. User management works without roles; roles are meaningless without users.
- User Groups: Lets admins organize users into groups for bulk operations. User management works without groups; groups are meaningless without users.
- User Audit Log: Tracks changes to user records for compliance reporting. User management works without audit logs; audit logs are meaningless without users.