Requirements Writing Guide
How to write clear, structured, and testable product and feature requirements.
This guide explains how to write Requirements Documents in 8090 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.
8090 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 everyone 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 8090 Software Factory project starts with six Product Overview Documents. You can add more 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. |
| Product Description | What the product is and how its parts fit together. |
| Personas | The users, their goals, and what success looks like for them. |
| 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
Projects start with no Feature Requirements Documents. While the Feature Requirements section is empty, a Get Started button appears under it. Select it to work with the Agent on your first features. For a new app, the Agent asks whether to define one feature first or cover every feature for your MVP. Choose based on how far ahead your team plans.
Each new Feature Requirements Document starts from a default template with an opinionated structure. To change it, edit Feature Document Template in Settings → Modules → Requirements.
Feature Requirements Documents follow a consistent structure with four sections: Overview, Terminology, Requirements, and Feature Behavior & Rules.
Overview Section
Write one or two narrative paragraphs explaining what the feature does and why users need it. A reader 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 behavior, and may for optional behavior.
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.
Feature Behavior & Rules Section
Use paragraphs and logical groupings to clarify how the requirements behave in practice and how they interact with each other. Explain cross-requirement interactions, defaults, constraints, and edge conditions. Do not prescribe UI layouts or user flows; focus on system behavior.
Example: Payment confirmation (REQ-CHK-003) happens only after inventory validation passes. If stock changes between cart review and payment, the customer returns to cart review before any charge. An order that fails fraud screening goes into a Fulfillment Hold instead of confirming, and the customer sees it as pending until the review completes.
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 and is 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.