Writing Requirements That Work

The single most impactful thing you can do is write clear stories with explicit success conditions. A good story has four parts.

The Four-Part Story Structure

1. Subject: who is doing this? (user, admin, guest, system)
2. Action: what are they doing?
3. Context: under what conditions?
4. Success condition: how do you know it worked?

Plain English format:

As a [user type], I can [action] [in what context], and when I do, [what should happen].

With edge cases:

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. But including the success condition and at least one edge case makes a significant difference to what gets built.

A Tale of Two Stories

Well-written story:

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 story:

Add a login page.

Same feature. Completely different outputs.

Include Edge Cases

At minimum, for each story, include one: empty/no-results state, error state, or validation failure.

These are the cases developers forget and users hit. If you don’t describe them, Claude will make a reasonable choice, but it may not be the one you wanted.

Examples of 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 silently fail.”
• “If the form is submitted with an empty required field, highlight that field in red”