Turning a vague prompt into requirements

“Design a link shortener.” Four words, and every number that matters is missing: how many links, how many visitors, how fast, for how long. Interview prompts are vague on purpose, and so are most feature requests at work. Before the first box goes on the board, turn the prompt into requirements: a short list of what the system must do and how well, written so that someone could check the finished system against it.

Two kinds of requirements

Functional requirements describe behaviour that a user or another system can see. Write each one as a sentence with an actor and a verb: “A signed-in user can create a short link for a long URL”, “Anyone who opens a short link is redirected to its long URL”. Each one is something a test could exercise.

Non-functional requirements describe how well the system must behave: how fast, how often available, how much data it keeps and for how long, how quickly a change becomes visible, what it must survive. They are also called quality attributes, and the next lesson is about them. NASA’s systems engineering handbook draws the same line: it separates the functions a system must perform from how well it must perform them, expects performance to be stated as a quantity, and asks that every requirement be written so that it can be verified once the product exists.

That last point is the test of a good non-functional requirement: could it fail? “Redirects must be fast” cannot fail, because nobody agreed what fast means. “99% of redirects are answered within 100 ms, measured at the server” can. The Site Reliability Engineering book calls the measured quantity a service level indicator (latency, error rate, throughput, availability) and the target for it a service level objective, and it prefers percentiles to averages, because an average can look healthy while a slow tail of requests is not.

Questions that change the design

A clarifying question is worth asking when its answer changes a number or a box on the diagram. These are the ones that most often do:

Some questions only fill time. “Which language should I use?” and “Should this be microservices?” are choices you make later, from the requirements; asking them first hands the design back to the interviewer. Ask about a constraint only if it is one: “Must this run on the company’s existing database?” is a fair question, “Which database do you like?” is not.

A worked example: the link shortener

Here is a first draft of the link shortener’s requirements, the version the same author wrote after asking those questions, and a small checker that reads both. The checker counts the requirements in each section, flags every non-functional requirement that has no number with a unit (or a percentage or a ratio) and names the vague words in it, and looks for a list of what is out of scope.

"""Check a requirements file before designing against it: is every non-functional requirement
measurable, and does the scope say what is left out?"""

import re
from pathlib import Path

# A number with a unit, a percentage or a ratio: "100 ms", "99.95%", "5 years", "100 to 1".
MEASURABLE = re.compile(
    r"\d[\d,.]*\s*(?:%|ms\b|s\b|seconds?\b|minutes?\b|hours?\b|days?\b|weeks?\b|months?\b|years?\b"
    r"|[KMGT]B\b|million\b|billion\b|requests?\b|links?\b|users?\b|data centres?\b|to \d)",
    re.IGNORECASE,
)
# Words that sound like requirements but cannot be checked without a number.
VAGUE = ("fast", "quick", "highly available", "scalable", "scale", "lots of",
         "reliable", "reliably", "real-time", "secure", "robust")


def sections(text):
    """The list items under each '## ' heading of a Markdown file."""
    found, current = {}, None
    for line in text.splitlines():
        if line.startswith("## "):
            current = line[3:].strip().lower()
            found[current] = []
        elif line.startswith("- ") and current is not None:
            found[current].append(line[2:].strip())
    return found


def vague_words(line):
    return [w for w in VAGUE if re.search(rf"(?<![\w-]){re.escape(w)}(?![\w-])", line, re.IGNORECASE)]


def check(path):
    found = sections(path.read_text(encoding="utf-8"))
    functional = found.get("functional requirements", [])
    quality = found.get("non-functional requirements", [])
    non_goals = found.get("out of scope", [])
    unmeasurable = [line for line in quality if not MEASURABLE.search(line)]

    print(path.name)
    print(f"  functional requirements: {len(functional)}")
    if unmeasurable:
        print(f"  non-functional requirements: {len(quality)}, not measurable: {len(unmeasurable)}")
        for line in unmeasurable:
            words = vague_words(line)
            print(f'    "{line}"' + (f" (vague: {', '.join(words)})" if words else ""))
    else:
        print(f"  non-functional requirements: {len(quality)}, all measurable")
    print(f"  non-goals: {len(non_goals)}" if non_goals else '  non-goals: none (add an "Out of scope" section)')
    ready = functional and quality and not unmeasurable and non_goals
    print(f"  verdict: {'ready for estimates' if ready else 'send back to the author'}")
    print()


for name in ("link_shortener_draft.md", "link_shortener.md"):
    check(Path(name))

link_shortener_draft.md
  functional requirements: 3
  non-functional requirements: 5, not measurable: 5
    "Redirects must be fast." (vague: fast)
    "The service should be highly available." (vague: highly available)
    "It must scale to lots of users." (vague: scale, lots of)
    "Links are stored reliably." (vague: reliably)
    "Click counts are real-time." (vague: real-time)
  non-goals: none (add an "Out of scope" section)
  verdict: send back to the author

link_shortener.md
  functional requirements: 6
  non-functional requirements: 7, all measurable
  non-goals: 4
  verdict: ready for estimates

# Link shortener: requirements (first draft)

## Functional requirements

- Users can shorten links.
- Short links redirect.
- Links can expire.

## Non-functional requirements

- Redirects must be fast.
- The service should be highly available.
- It must scale to lots of users.
- Links are stored reliably.
- Click counts are real-time.

# Link shortener: requirements

## Functional requirements

- A signed-in user can create a short link for a long URL.
- A user can choose a custom alias if no one else has it.
- Anyone who opens a short link is redirected to its long URL.
- A link can have an expiry time; after it, the short link answers 410 Gone.
- A user can delete their own links.
- Every redirect is counted, and the owner sees the count for each link.

## Non-functional requirements

- Scale: up to 100 million new links a month; redirects outnumber new links about 100 to 1.
- Latency: 99% of redirects are answered within 100 ms, measured at the server.
- Availability: 99.95% of redirect requests succeed in each 30-day month.
- Durability: a link the API has confirmed survives the loss of any 1 data centre.
- Freshness: a new link redirects everywhere within 5 seconds of being created.
- Click counts: a redirect shows in its link's count within 60 seconds.
- Retention: links are kept for 5 years unless their owner deletes them.

## Out of scope

- Analytics dashboards beyond the click count for each link.
- Custom domains.
- Changing where an existing short link points.
- Link previews.

The draft goes back to its author. Every one of its non-functional requirements is an adjective, and nothing says what is left out. The second version passes, and comparing the two shows what changed:

• “Users can shorten links” became six functional requirements, including the ones the draft forgot: custom aliases, deleting a link, and what an expired link does. Answering 410 Gone rather than 404 Not Found tells clients that the link has been removed on purpose and is likely to stay gone, which is what HTTP defines status code 410 to mean.
• Each adjective became a number with a unit and, where it matters, where it is measured.
• “Click counts are real-time” turned into two decisions: counting every redirect is a functional requirement, “within 60 seconds” is its quality, and a dashboard is explicitly out of scope.

A checker like this finds missing numbers, and nothing more. It matches words, so it flags a requirement whose figure is spelled out (“any one data centre” rather than “any 1 data centre”) even though a failure test could check it. And it cannot tell whether 100 ms is the right number; only the people who need the system can. Treat the numbers as agreements: if the interviewer gives none, propose them out loud (“I’ll assume 100 million new links a month”) and carry on.

Write the scope down, with non-goals

Finish the requirements step with a short scope statement: one paragraph that says what this design covers and, just as important, what it does not.

Non-goals do three jobs. They stop the design from growing while you talk; they show the reviewer that you left something out on purpose rather than forgot it; and they turn a later addition into a decision someone takes, rather than something that creeps in. The requirements that shape the architecture most, the ones the architecture decision records community calls architecturally significant, are often on the non-functional list: scale, latency, durability and where data may live.

A common mistake: choosing the database first

“We’ll use a NoSQL database,” two minutes into a round, is a guess. A store is chosen by the way the system reads and writes its data, and those access patterns come from the requirements. For the link shortener they are now clear: the hot path is reading one row by its short code, about 100 times as often as a link is created; deletes are rare; nothing on the hot path needs a join; click counts are written constantly and may lag by a minute. Those facts, not a product’s reputation, decide where links and clicks are stored, and the data-modelling module of this track shows how.

Key takeaways

• Functional requirements say what the system does, as sentences with an actor and a verb; non-functional requirements say how well, as numbers with units that a test or a measurement could fail.
• Ask the questions whose answers change a number or a box: volume, read-to-write ratio, freshness, geography, retention, abuse and regulated data. Leave implementation choices for later.
• If the interviewer gives no numbers, propose them out loud and carry on.
• End with a scope statement that names the non-goals.
• Do not pick a database before the access patterns are known.