Writing Requirements That Work
The most useful thing you can do is write clear stories with explicit success conditions. A good story has four parts.
The four-part story structure
Section titled “The four-part story structure”| Part | The question it answers |
|---|---|
| Subject | Who is doing this? A user, an admin, a guest, or the system. |
| Action | What are they doing? |
| Context | Under what conditions? |
| Success condition | How do you know it worked? |
In plain English:
As a [user type], I can [action] [in what context], and when I do, [what should happen].
With an edge case:
If [the email field is empty / the session has expired / there are no results], [what should happen instead].
You don’t need formal notation. A clear paragraph works. Including the success condition and at least one edge case makes a large difference to what gets built.
Two versions of the same story
Section titled “Two versions of the same story”Well written:
A registered user can log in using their email address and password. After successful login they are taken to the dashboard. If the credentials are wrong, they see an error message below the form, not a full-page error. The form keeps the email they typed but clears the password. If they’ve had five failed attempts, the login button is disabled for 15 minutes.
Under-specified:
Add a login page.
Same feature. Completely different results.
Include edge cases
Section titled “Include edge cases”For each story, include at least one of these: an empty or no-results state, an error state, or a validation failure.
These are the cases developers forget and users hit. If you don’t describe them, Claude makes a reasonable choice, but it may not be the one you wanted.
Edge cases worth specifying:
- “If the search returns no results, show a ‘No items found’ message.”
- “If the API call fails, show an error banner. Don’t fail silently.”
- “If the form is submitted with an empty required field, highlight that field in red.”
Say what you don’t want yet
Section titled “Say what you don’t want yet”A boundary is as useful as a requirement. “No social login and no password reset for now” stops Claude adding stories you’d only remove at review. See Before You Begin.