What are non-functional requirements, and why can't you skip them when you vibe code?
Non-functional requirements are the quality bars your software has to clear while doing its job: how fast it responds, how often it stays up, how many users it can handle at once, how it protects data, who can access it without a screen reader struggling. You cannot skip them when you vibe code because an AI agent only builds what you tell it to build. It will happily ship a checkout page that works perfectly for one user and falls over at fifty, or a login flow with no rate limiting, unless you state a number it has to hit. Features describe what the app does. Non-functional requirements describe how well it has to do it, and they decide your architecture before a single feature exists.
I am Mahmoud Zalt, an independent senior AI systems architect. I have shipped production software since 2010, sixteen years now, and I founded Sista AI (sistava.com), where I run a fleet of autonomous AI agents in production, not in a demo video. I bring this up because non-functional requirements are exactly the kind of thing that separates a project that survives contact with real users from one that quietly falls apart the week it gets traffic. This is the part most vibe coding tutorials skip entirely.
Functional versus non-functional, in plain English
A functional requirement is a thing your software does. "A shopper can pay for a cart" is functional. "A user can upload a photo" is functional. These are the features you list when you describe your idea to an AI, and they are the easy part to state because you already think in terms of features.
A non-functional requirement is the standard that feature has to meet while it runs. Not what happens, but how well it happens.
| Functional (what it does) | Non-functional (how well it does it) |
|---|---|
| A shopper can pay for a cart | Checkout completes in under 3 seconds |
| A user uploads a photo | The app handles 500 people uploading at once |
| An admin views a report | The report is available 99.9% of the time |
Notice that both rows describe the same feature. The left column is the thing you would naturally type into a prompt. The right column is the thing almost nobody types into a prompt, and it is the part that decides whether the feature actually holds up once real people touch it.
This split is not new. It is standard software engineering vocabulary that predates AI coding tools by decades, and it exists because the two kinds of requirements get decided at different points and by different people. A product person or a founder usually drives the functional list: what the app should let a user do. A non-functional requirement is closer to an engineering decision, and it is the one vibe coding tends to skip, because describing a feature in plain language comes naturally, while stating a quality bar in plain language takes a bit more deliberate thought. That gap is exactly where this chapter of The Vibecoder's Handbook focuses.
Your AI will not infer these on its own
This is the part worth slowing down for. An AI coding agent is extremely good at building the feature you describe. It is not good at guessing the quality bar you had in your head but never wrote down. If you ask for "a fast checkout" without a number, the agent has no test to check itself against, so it builds something that feels reasonable to it and moves on. If you ask for "secure login" without specifics, you might get a login form with no rate limiting, no lockout, and passwords stored in a way that looks fine in a demo and falls apart in an audit.
This is not the AI being careless. It is doing exactly what you asked, and you asked for a feature, not a standard. "Fast" and "secure" are adjectives. An adjective cannot be tested, so nothing in your codebase or your agent's output is built to satisfy it. A number can be tested, and once you hand your AI a number, it has something concrete to design against from the very first line of code.
This is also why non-functional requirements belong at the planning stage, before your AI designs anything. A target like "handle 500 uploads at once" changes your database choice, your hosting setup, and how you queue background work, all from day one. Bolt that requirement on after launch, once the architecture already assumes ten concurrent users, and you are usually not adding a feature. You are rewriting the foundation.
Think about it from the agent's side for a second. Every time it writes code, it is making small architectural choices you never see: whether to store a session in memory or in a shared store, whether to run a job synchronously or queue it, whether to cache a response or hit the database every time. Each of those choices is fine for one target and wrong for another. Without a stated target, the agent picks whatever is simplest to generate, which is usually the version that works for one user on one machine. That is not a flaw in the tool. It is what happens when you leave a decision unmade and hand it to something that has to decide anyway.
Five categories to set a number for
Here are five categories that cover almost everything a solo builder or small team actually needs to pin down before building. For each one, the goal is the same: replace the adjective with a number.
| Category | Vague (does not count) | Measurable target (counts) |
|---|---|---|
| Performance | "Fast" | A page loads in under 2 seconds |
| Availability | "Reliable" | Up 99.9% of the time |
| Security | "Secure" | Passwords encrypted, login enforced on private data |
| Scale | "Handles growth" | 10,000 users and 1 GB of data in year one |
| Accessibility | "Usable by all" | Works by keyboard and screen reader, meets WCAG AA |
None of these targets need to be ambitious. A solo project serving a few hundred people does not need five nines of uptime or a system built for a million users. The point is not to aim high, it is to aim at something. "95% of pages load in under 2 seconds on a mobile connection, and the app is available 99.9% of the time" is a real target your agent can build toward and you can later test against. "Make it fast and reliable" is not.
The mistake almost every vibe coder makes
The most common mistake is assuming the AI will "just know" to make the app secure, fast, or ready to scale, because that seems like an obvious baseline any competent build should have. It is not an unreasonable assumption. It is also wrong, and it is the single biggest reason vibe-coded projects work perfectly in a demo and then leak data, time out, or fall over the first week real users show up.
- Assuming security is default. Rate limiting, input validation, and access control on private data are not automatic. If you never asked for them, they are probably missing.
- Discovering scale limits after launch. A database schema and hosting setup built for a demo with three test users does not casually become a setup for three thousand real ones. That is a rebuild, not a tweak.
- Treating accessibility as optional polish. Keyboard navigation and screen reader support are architectural decisions in how components are built, not a coat of paint you add at the end.
- Writing targets nobody can test. "Make it reliable" gives your agent, and you, nothing to check. If a target cannot fail a test, it is not really a target.
Every one of these mistakes traces back to the same root cause: an adjective where a number should have been. None of them show up in a quick demo, which is exactly why they slip through. A demo runs for one person, on one machine, on a good connection, with clean input, for five minutes. Every non-functional requirement you skipped is a bet that none of your real users will look, click, or type anything differently than you did while testing. That bet loses eventually, usually right after you start getting real traction, which is the worst possible time to discover it.
Do this now, before you build another feature
Open a plain text file, or a `specs` folder if you already have one for your project, and write one measurable target for each of the five categories: performance, availability, security, scale, and accessibility. Each one needs to be a number or a specific, checkable statement, not an adjective. This takes fifteen minutes and it is fifteen minutes that saves you from rebuilding your foundation later.
Then hand that file to your AI agent before it designs anything else. Reference it explicitly when you start a new feature: "build this so it meets the performance and security targets in specs/requirements.md." You are not asking the agent to implement all of it in one pass. You are giving it something to aim at from the first architectural decision onward, which is exactly what most vibe-coded projects never get.
Keep the targets honest and small at first. A weekend project does not need the same availability target as a payroll system, and writing "99.999% uptime" for a hobby app just because it sounds professional does not help anyone, it just adds pressure with nothing behind it. Pick numbers that match what you are actually building and who is actually going to use it. You can always raise the bar later, once real usage tells you where it actually needs to be. What matters right now is that every category has a number, not that the number is impressive.
Frequently Asked Questions
What is a non-functional requirement in simple terms?
It is a quality bar your software must clear while it does its job, rather than a feature it has to have. Speed, uptime, security, how many users it can handle, and accessibility are the common ones. If a functional requirement is "what," a non-functional requirement is "how well."
Why does an AI agent need non-functional requirements written down?
Because it builds what you describe, and "fast" or "secure" cannot be built against directly since there is nothing to test. A number, like "loads in under 2 seconds" or "handles 500 concurrent uploads," gives the agent something concrete to design around from the first line of code, instead of guessing and getting it wrong.
What happens if I skip non-functional requirements and add them later?
Usually you end up rebuilding, not adding. Your database, hosting, and data model get chosen based on the scale and performance targets you had in mind, even unstated ones. Discover a real target after launch, once the app already assumes a handful of casual users, and you are often replacing the foundation rather than extending it.
How many non-functional requirements does a small project actually need?
Five categories cover most solo and small-team projects: performance, availability, security, scale, and accessibility. One measurable target per category is enough to start. You do not need enterprise-grade numbers, a modest, honest target that fits your actual project is exactly right.
Where should I keep my non-functional requirements?
Somewhere your AI agent can reference before it builds, such as a `specs` folder in your project or a pinned planning document. The goal is to hand it to your agent before any architecture decisions get made, not to file it away as paperwork nobody reads again.
The short version, and where the full version lives
Non-functional requirements are not bureaucracy. They are the quiet decisions that shape your entire architecture, and setting them costs almost nothing if you do it before you build. Skip them, and your AI agent will build something that works today and buckles the moment it matters.
This article covers the short version. The full chapter in The Vibecoder's Handbook walks through setting your own measurable targets across all five categories, with the exact prompts and structure to hand your agent before it designs anything.
