Hello again. In the previous lesson, you traced an AI request through the client, backend service, data stores, model provider, and response safeguards. That trace is more than an architecture diagram: it is a practical checklist for discovering what a feature must do and the conditions under which it must do it.
This lesson turns that architecture into a delivery-ready specification. By the end, you should be able to begin with a user-facing AI feature, express its purpose as a user story, separate functional requirements from non-functional requirements, and write measurable conditions that engineering and stakeholders can verify.
We will continue with an internal IT knowledge assistant, but the method applies equally to a support copilot, document-analysis tool, sales assistant, or agentic workflow.
From a feature request to an engineering agreement
A stakeholder might say:
“Build an AI assistant that helps employees solve VPN problems.”
That is a useful starting point, but it is not yet a requirement. It leaves important decisions unanswered:
- Which employees can use it?
- What kinds of VPN questions should it handle?
- What should happen when the knowledge base has no approved answer?
- What does “helps” mean in a way a team can test?
- How fast must the answer arrive?
- May the system send internal troubleshooting content to an external model provider?
- What happens if the model service is unavailable?
- What evidence will show whether the feature is working after deployment?
A feature communicates a broad capability. A requirement creates a specific obligation. It tells the team what must be true for a feature to be acceptable.
A useful progression is:
- Start with the user and the outcome they need.
- Identify the behavior the system must provide.
- Identify the quality, security, operational, and cost conditions that make that behavior viable.
- Define how each condition will be verified.
- Record unresolved decisions as explicit questions or assumptions, rather than silently inventing them.
This work is especially important for AI systems. An answer can look fluent while being unsupported, inaccessible to the wrong user, too slow for the workflow, too expensive at scale, or impossible to diagnose after a complaint.
Functional, non-functional, and constraint requirements
A compact distinction is:
- Functional requirements specify what the system must do: a behavior, capability, or response to a condition.
- Non-functional requirements (NFRs) specify measurable qualities or operating conditions: performance, reliability, security, usability, maintainability, and similar attributes.
- Constraints limit the solution space: for example, a required cloud region, identity provider, approved model provider, or data-retention policy.
The distinction is not merely documentation style. It changes architecture and testing. A missing functional requirement means a feature is absent. A missing NFR can yield a feature that appears to work in a demo but fails under real traffic, violates access controls, or costs too much to operate.
Read Jama Software’s concise guide for the core distinction and the discipline of expressing one testable obligation per requirement.
Functional vs. Non-Functional Requirements
Read “Functional vs Non-Functional Requirements” by Jama Software. It establishes the difference between behavior and quality attributes, then shows why vague or combined statements are difficult to verify.
In “What Are Functional and Non-Functional Requirements?”, read the core definitions. Then, in “How to Write a Testable Functional Requirement,” read the trigger-response pattern. Continue through “What a Non-Functional Requirement Specifies” and its opening discussion; focus on why NFRs shape architecture early. Finally, in “Common Pitfalls,” read the warning against combining obligations, followed by the discussion of vague language such as “respond quickly.”
Consider these examples for the VPN assistant:
| Statement | Classification | Why |
|---|---|---|
| “An authenticated employee shall submit a support question and receive an answer with source references.” | Functional | It specifies an observable capability. |
| “For the approved VPN-support benchmark, the service shall return a completed response within 6 seconds at the 95th percentile under 20 concurrent sessions.” | Non-functional: performance | It defines a measurable quality under stated conditions. |
| “The system shall not return content from a document the employee is not authorized to read.” | Non-functional: security | It defines an access-control property that applies across requests. |
| “The service must use the organization’s approved identity provider.” | Constraint | It restricts the implementation choices. |
| “The assistant shall be fast, accurate, and secure.” | Not yet a usable requirement | It mixes concerns and provides no measurable threshold or condition. |
The familiar shortcut of “what” for functional and “how well” for non-functional is helpful, but do not apply it mechanically. For example, logging a request ID is a system behavior, yet its purpose is an operational quality: observability. Classify a statement by the engineering concern it addresses, then make its verification method clear.
Start with a user story, but do not stop there
A user story preserves the reason the feature exists. A standard form is:
As a [specific actor], I want [capability], so that [valuable outcome].
For our example:
As an employee with an IT access issue, I want to ask the internal assistant for approved VPN troubleshooting guidance, so that I can resolve routine problems without opening a support ticket.
This is deliberately not a technical design. It does not say “use a vector database,” “call model X,” or “build a FastAPI endpoint.” Those may become design choices or constraints, but they are not the user’s desired outcome.
Watch this short portion of User Stories and Acceptance Criteria EXAMPLE from The Business Analysis Doctor. It distinguishes the user story’s role, capability, and benefit from the acceptance conditions that define completion.
User Stories and Acceptance Criteria EXAMPLE (Agile Story Tutorial)
Watch “User Stories and Acceptance Criteria EXAMPLE” by The Business Analysis Doctor - IIBA Certification. It gives a practical format for connecting user value to verifiable delivery conditions.
Watch the user story template to see how role, capability, and benefit keep a feature user-centered. Then watch acceptance criteria basics, especially the distinction between functional, security, and latency conditions. Finish with a Given When Then scenario to see one way of making a user-facing behavior executable as a test.
A story does not provide sufficient detail to build or test the feature. It creates the agenda for a discovery conversation.
For the VPN assistant, that conversation should make the following areas explicit:
| Discovery area | Questions to resolve |
|---|---|
| Actor and access | Are contractors included? Does access differ by region, device type, or department? |
| Workflow | Is the goal self-service resolution, ticket triage, or handoff to a human agent? |
| Knowledge sources | Which documents are approved? Who owns and updates them? |
| Risk | What harm occurs if the assistant gives outdated or unauthorized guidance? |
| Failure behavior | Should the assistant abstain, show sources only, create a ticket, or offer a support channel? |
| Demand | How many concurrent users are expected during an outage? |
| Success | Is success a resolved issue, reduced ticket volume, lower handling time, higher user satisfaction, or a combination? |
| Data handling | Can user questions or diagnostic details be sent to a hosted provider? What must not be logged? |
A forward-deployed engineer should resist filling in these answers alone. Some answers come from users and process owners; others, especially security, performance, and reliability targets, require input from architects, platform engineers, security teams, and operations staff.
Write functional requirements as observable system behavior
A functional requirement becomes testable when it states:
- A condition or trigger.
- The required system behavior.
- The required observable result, including relevant business rules.
A useful form is:
When [condition or trigger], the system shall [behavior], so that the observable result is [outcome].
Not every functional requirement needs a timing number. But it should be possible to decide whether the behavior occurred correctly.
Example functional requirements: internal IT assistant
The following set translates the VPN-assistant story into independently testable behavior.
| ID | Functional requirement | How it could be verified |
|---|---|---|
| FR-1 | When an authenticated employee submits a VPN-support question, the system shall return either an answer or a defined unable-to-answer outcome. | Submit valid questions using a test employee account. |
| FR-2 | For an answer presented as internal IT guidance, the system shall display at least one source reference containing the document title and section or page reference. | Use known source documents and inspect the returned response. |
| FR-3 | When the approved knowledge sources do not contain sufficient evidence for a question, the system shall state that it cannot provide approved guidance and present the configured IT support escalation path. | Submit a question outside the supported knowledge set. |
| FR-4 | When a user is not authorized to access a source document, the system shall not display that document’s content or citation in the response. | Execute an authorization test using accounts with different permissions. |
| FR-5 | When the upstream model provider cannot complete a request, the system shall return a user-safe failure message without exposing provider credentials, internal stack traces, or raw system prompts. | Simulate a provider failure and inspect the client response. |
| FR-6 | When an employee asks a supported question, the system shall return a response containing an answer field, zero or more citations, and a request identifier. | Validate the response against its API contract. |
Notice several design choices that these requirements intentionally leave open:
- FR-2 requires source references but does not require a specific vector database.
- FR-3 requires an abstention and escalation outcome but does not mandate a particular prompt.
- FR-5 requires safe failure behavior but does not prescribe the retry library or exact hosting platform.
- FR-6 requires a stable response contract but does not force the client to understand a particular model provider’s API.
That flexibility is valuable. Requirements define necessary outcomes; design later selects an implementation that meets them.
Scenario-based acceptance criteria
For a user-facing behavior, Given–When–Then scenarios make conditions visible. They are particularly useful for permissions and failure states that can be overlooked in a happy-path demo.
Scenario: supported VPN question
- Given an authenticated employee is authorized to access current VPN support guidance,
- When the employee asks a supported VPN troubleshooting question,
- Then the system returns an answer with at least one approved source reference.
Scenario: insufficient evidence
- Given an authenticated employee asks a question outside the approved support knowledge,
- When no sufficient supporting evidence is available,
- Then the system does not invent an approved procedure and instead displays the defined escalation path.
These are acceptance conditions for specific functional outcomes. They are not a replacement for the broader NFRs that govern performance, privacy, reliability, and operating cost across the service.
Make quality requirements measurable
“Fast,” “reliable,” “secure,” “helpful,” and “low cost” are product aspirations. They become requirements only when you define what will be measured, under which conditions, and what value counts as passing.
For each NFR, specify a measurement contract:
| Element | Example question |
|---|---|
| Metric | What is measured: latency, availability, unauthorized exposure, grounded-answer rate, cost? |
| Scope | Which endpoint, user group, request type, or feature does it cover? |
| Conditions | At what concurrency, payload size, provider state, or time period? |
| Threshold | What exact value distinguishes pass from fail? |
| Window or sample | Over what time period or how many representative requests? |
| Method | Which test, dashboard, audit, or review produces the evidence? |
Without these details, a team cannot fairly verify the requirement. For example:
- “The assistant shall respond quickly” leaves every word open to interpretation.
- “The assistant shall respond within 6 seconds” is better, but still omits workload, percentile, and where timing begins and ends.
- “For valid VPN-support requests, the API shall return a complete response within 6 seconds at the 95th percentile, measured from backend receipt to final response under 20 concurrent sessions” is operationally testable.
Example non-functional requirements
The values below are illustrative pilot targets, not universal recommendations. A production team should derive the numbers from workflow needs, risk tolerance, expected load, provider limits, and available budget.
| ID | Quality concern | Measurable requirement | Verification |
|---|---|---|---|
| NFR-1 | Performance | For valid VPN-support requests, the service shall return a complete response in no more than 6 seconds at the 95th percentile under 20 concurrent sessions, measured from backend receipt to response completion. | Load test using a representative request set. |
| NFR-2 | Availability | The VPN-assistant endpoint shall achieve at least 99.5% monthly availability, excluding announced maintenance windows. Availability is measured as the proportion of valid requests receiving a successful or defined safe fallback response. | Production monitoring and monthly availability report. |
| NFR-3 | Grounded quality | On a versioned evaluation set of 50 supported VPN questions, at least 90% of responses shall meet the documented groundedness threshold and include valid citations. | Repeatable pre-release evaluation against a scored dataset. |
| NFR-4 | Security | In authorization integration tests covering the approved role-and-document access matrix, the system shall expose zero passages or citations from sources denied to the requesting account. | Automated integration tests with permission-separated test accounts. |
| NFR-5 | Privacy and logging | Standard application logs shall contain a request identifier, timestamps, status, latency, and non-sensitive operational metadata, but shall not contain raw access tokens, model-provider credentials, or full user-question text. | Automated log inspection using representative and seeded-sensitive test data. |
| NFR-6 | Cost control | Under the representative VPN-support evaluation workload, the estimated model and retrieval cost shall not exceed the agreed per-request budget at the 95th percentile. | Cost report based on measured token usage and retrieval calls. |
| NFR-7 | Observability | Every response shall contain a request identifier, and every model invocation attempt shall emit a correlated operational record containing model identifier, latency, outcome, and token-usage metadata when available. | Trace and log integration test. |
Several lessons from the previous request trace appear directly in this table:
- Because the backend controls provider calls, it can measure end-to-end latency, model usage, and failures.
- Because retrieval is permission-aware, access control must be tested at the boundary between user identity and knowledge sources.
- Because model output is not automatically trustworthy, quality must include grounding and citation conditions.
- Because a hosted provider is a dependency, availability must define a safe fallback behavior rather than assuming every request produces a model answer.
AI quality needs a benchmark, not intuition
For conventional software, a test may compare one exact output with an expected output. Generative systems are different: many well-worded answers may be acceptable, and the same prompt can yield variation across runs.
That does not make quality unmeasurable. It means the requirement must define properties rather than demand one exact sentence. For an internal support assistant, useful properties include:
- Correctness: Does the advice match the approved procedure?
- Groundedness: Are factual claims supported by supplied or approved sources?
- Relevance: Does the response address the employee’s question?
- Citation quality: Do citations identify the actual evidence used?
- Abstention behavior: Does the assistant avoid presenting unsupported guidance as fact?
A statement such as “the assistant must be accurate” is not enough. A usable quality requirement identifies a representative question set, a scoring method, an acceptance threshold, and the source version used during testing. Later in the course, you will build these evaluation sets and calibrate automated scoring. For now, the key skill is recognizing that the measurement design belongs in the requirement.
Keep requirements atomic and avoid hidden design decisions
A frequent failure mode is a statement like:
“The system shall authenticate users within 500 milliseconds using encrypted tokens and return secure, accurate answers.”
This appears thorough, but it actually contains several independent obligations:
- Authenticate users.
- Meet an authentication-latency target.
- Use a particular security mechanism.
- Protect the system appropriately.
- Generate accurate answers.
Each has different owners, tests, risks, and likely change rates. Split them.
| Weak combined statement | Better decomposition |
|---|---|
| “The assistant shall give secure answers quickly.” | A performance NFR defines end-to-end latency. A security requirement defines authorization and data boundaries. A quality NFR defines grounded-answer performance on a benchmark. |
| “The assistant shall use pgvector to search documents.” | If the technology is truly mandated, record it as a constraint. Otherwise express the needed outcome: authorized, relevant source retrieval. |
| “The assistant shall be easy to use.” | Define a user task, participant group, completion rate, error rate, or maximum interaction steps. |
| “The assistant shall be reliable.” | Define availability, defined fallback behavior, recovery expectations, and the measurement period. |
| “The assistant shall never hallucinate.” | Define evidence requirements, abstention behavior, a representative evaluation set, and an acceptable failure threshold. |
The “never hallucinate” example deserves care. It expresses a legitimate safety concern, but an absolute claim is rarely verifiable for an open-ended generative system. A stronger requirement focuses on controllable, observable behavior:
When sufficient approved evidence is unavailable, the system shall not present a procedural answer as approved internal guidance and shall use the configured escalation response.
That is both safer and testable.
A lightweight requirements package for an AI pilot
For a small pilot, you do not need a hundred-page specification. You do need enough structure that a customer, engineer, and QA reviewer can agree on what is being delivered.
A useful minimum package contains:
-
Problem statement
Who has which problem, in which workflow, and why it matters. -
User story and scope
The actor, capability, intended value, supported question types, and explicit non-goals. -
Functional requirements
Independent, observable system behaviors, including error and abstention paths. -
Non-functional requirements
Measurable targets for the risks that matter: quality, latency, access control, privacy, reliability, cost, and observability. -
Constraints and assumptions
Mandated systems, data locations, provider restrictions, existing identity systems, and decisions still awaiting confirmation. -
Acceptance and verification plan
The test, review, measurement, or demonstration that provides pass-or-fail evidence for each requirement.
The package should also preserve traceability. A reviewer should be able to follow the chain from a user need to a requirement, from the requirement to a design decision, and from the design decision to evidence that it works.
For example:
| Need | Requirement | Design may later choose | Evidence |
|---|---|---|---|
| Employees need self-service troubleshooting. | FR-1: submit question and receive answer or defined fallback. | A web chat endpoint and typed API response. | End-to-end acceptance test. |
| Employees must not receive restricted support material. | FR-4 and NFR-4: enforce and test document-level authorization. | Identity claims, metadata filters, access-control checks. | Permission-matrix integration test. |
| The feature must be useful during routine support work. | NFR-1 and NFR-3: latency and groundedness thresholds. | Retrieval configuration, prompt contract, model choice. | Load test and evaluation report. |
The design column is intentionally not the requirement. It is a place for engineering trade-offs once the required outcome is understood.
Requirements are revised through evidence
A pilot’s first requirements are hypotheses informed by discovery, not permanent truths. After initial testing, traffic analysis, and user feedback, teams refine the feature, its evaluation set, and its thresholds.
The diagram is useful because it counters a common AI-project mistake: declaring a feature “done” after a few impressive demonstrations. A system can pass the happy path yet fail on rare but consequential questions, a new document version, realistic concurrency, or an unauthorized-access attempt.
A disciplined revision loop asks:
- Did the feature meet the functional acceptance conditions?
- Did it meet the quality thresholds under the stated workload?
- Are failures concentrated in a particular user task, document set, or permission group?
- Is the target too weak to protect the workflow, or unnecessarily expensive for its value?
- Which requirement, assumption, test set, or architecture decision needs revision?
This is not an excuse to move the goalposts after every test. It is a way to make assumptions visible, gather evidence, and negotiate changes deliberately with stakeholders.
Key takeaways
A user-facing feature request becomes engineering-ready when you translate it into independent, verifiable obligations.
- A user story captures the actor, desired capability, and business value; it starts discovery but does not define delivery.
- Functional requirements state the system behaviors users and other systems can observe, including failure and abstention behavior.
- Non-functional requirements state measurable quality conditions such as latency, availability, security, privacy, grounding quality, cost, and observability.
- A requirement needs a measurement context: metric, scope, conditions, threshold, sample or time window, and verification method.
- Keep each requirement atomic. Split mixed statements so that each has unambiguous ownership and a clear pass-or-fail test.
- Treat specific technologies as constraints only when they are genuinely mandated; otherwise state the needed outcome and leave implementation choices open.
- For generative AI, replace vague claims such as “accurate” or “never hallucinates” with benchmarked evidence, citation, abstention, and escalation conditions.
Next, you will turn some of these requirements into validated request and response contracts using Python type hints and Pydantic. Those schemas will make the API boundary from the previous lesson explicit: what the client may send, what the backend guarantees to return, and what invalid data is rejected before it reaches a model.
Can't find a good explanation? Sign up and we'll make it for you
Sign up