The Spec — Part 1: What a Spec Is
maang.io AI-Native Builder Series
What is this?
Picture two pieces of paper sitting on a table next to an empty lot. The first is a glossy brochure: "A bright, modern family home with a big kitchen and a garden out back." It's exciting. It tells you what the house is for and why you'd want it. But you cannot build a house from it. The second piece of paper is a blueprint — exact dimensions, where every wall goes, which way the doors swing, where the pipes run. It's not exciting. Nobody frames a blueprint. But it is the thing a builder can actually pick up and turn into a real house, without having to guess.
A technical spec (short for specification) is the blueprint for your app. Your product brief and your user stories are the brochure — they say what you're building and why it matters. The spec is the document that says how it's put together: what data the app stores, what the pieces are, and how they fit. And here's the part that makes it matter more than ever in this course: the spec is the thing your AI partner builds from. Remember the head chef directing a brilliant-but-tasteless cook? The spec is the recipe card you hand that cook. A vague recipe gets a vague dish. A precise one gets exactly what you pictured.
The one-line idea: the technical spec is the bridge from what and why (the brief and stories) to how (the data, the pieces, the plan) — the blueprint your AI partner builds from, and the thing you verify it against.
The blueprint-versus-brochure image is the one we'll come back to all chapter. Let's earn it.
1. The bridge from "what" to "how"
By now you've built up real planning work. In Product Thinking you wrote the product brief — who StreakUp is for and why it should exist. In Requirements you separated must-haves from nice-to-haves and pinned down the MVP. In User Stories you turned all of that into small, testable stories and ordered them into a backlog. That's a lot of clarity about what and why.
But notice what's still missing. Not one of those documents says how the app is actually put together. "As a user, I can mark a habit done for today" is a perfect story — and it tells you nothing about where that "done" gets stored, or what message the app sends to save it. There's a gap between the story and the keyboard. The spec is what fills it.
Read it left to right. Everything you've made so far flows into the spec, and the spec flows out into the build. That's why this topic is the finale of 101: it's the last planning step, the one that collects all the thinking into a single buildable document. ⚠️ Skip it, and you walk into the build with a brochure where you needed a blueprint — and you'll discover the missing decisions one painful surprise at a time, mid-construction.
2. Why a spec exists at all
It's fair to ask: if the AI is so good, why not just hand it the brief and let it figure out the "how"? You can — and you'll get an answer. The problem is it'll be a house, not your house. The AI fills every gap you left with a guess, confidently, and its guesses won't match each other or your intent.
A spec exists to make the decisions on purpose, once, before they get made for you by accident. Here's the same fork we keep meeting, in spec form:
Three concrete things a spec buys you:
- It removes ambiguity before it becomes bugs. "See your streak" could mean calendar days, days-since-you-started, or longest-ever. Decide it in the spec and the AI builds one clear thing. Leave it vague and you'll find out which one it guessed only when the number looks wrong.
- It gives you something to verify against. This is the big one. "Trust, then verify" needs a trusted thing to verify against. The spec is that reference. When the AI hands back code, you check it against the spec — does it store what the spec says, expose the endpoints the spec lists? Without a spec, you're just hoping.
- It makes teamwork possible. You're building StreakUp in a small team. If two people imagine the data differently, their code won't fit together. The spec is the shared blueprint everyone builds from — the same role it plays for the AI.
💡 The spec is not bureaucracy you do instead of building. It's thinking you do so that building goes fast and straight. An hour on the spec saves a day of "wait, why doesn't this fit?"
3. Brief vs. stories vs. spec — three different documents
Beginners blur these three together. Keeping them distinct is a senior habit, because each answers a different question and each has a different audience. Here's the whole relationship in one picture:
A side-by-side makes the difference concrete:
| Document | Answers | Sounds like | Audience |
|---|---|---|---|
| Brief | Why are we building this, and for whom? | "Busy students forget their habits; StreakUp keeps them on track." | Anyone — a teammate, a parent, you in a month |
| User stories | What can a user do, and how do we know it works? | "As a user, I can mark a habit done; I see today's date checked off." | You + the AI, to know what to build |
| Technical spec | How is it built — data, pieces, plan? | "A Log row stores habit_id and a date; POST /habits/{id}/logs creates one." |
You + the AI, to actually build and verify it |
Notice the language shifts as you move down. The brief talks about people and value. The stories talk about actions and outcomes. The spec starts naming tables, endpoints, and fields — the concrete machinery. That shift from human language to buildable detail is the bridge this topic builds.
🚫 A common beginner mistake is to write a "spec" that's really just the brief reworded — lots of "the app should be fast and easy to use," no actual data model or endpoints. That's still a brochure. A real spec contains decisions a builder could disagree with, because they're specific enough to be wrong.
4. What's inside a technical spec
So what does the blueprint actually contain? For an app like StreakUp, a good first spec has a small, predictable set of sections. You don't need a hundred pages — you need the right few. Here's the shape of the document you'll assemble across this topic:
- Overview — a short paragraph: what the app does and what's in scope for the MVP. This is where your brief gets compressed into a sentence or two so the spec stands on its own.
- Data Model — the tables of data the app stores and how they connect. For StreakUp that's three tables — users, habits, and the daily log. This is the heart of the spec, and it's all of Part 2.
- API — the list of endpoints: the specific messages the web and mobile apps send to the backend to get things done. Also Part 2. (An endpoint is one named action the backend can perform, like "create a habit" — we'll define it properly there.)
- Task Breakdown — the build split into small tasks, roughly sized, in an order that respects what-depends-on-what. That's Part 3.
- Open Questions — an honest list of what you haven't decided yet. Mature specs include this. It's far better to write "we haven't decided how time zones work" than to pretend the question doesn't exist and let the AI guess.
You don't write these top to bottom in one sitting. You'll build the data model and API in Part 2, the tasks in Part 3, and then in Part 4 use AI to draft, critique, and assemble the whole thing into your Spec Package — Milestone 1.
5. The spec is a living draft, not a contract carved in stone
One more mindset shift before we start drawing blueprints. A real-building blueprint is mostly fixed before the first wall goes up. A software spec is not — and pretending otherwise is a classic beginner trap.
Here's the truth: you will learn things during the build that change the spec. You'll start building an endpoint and realize you forgot a field. That's normal and good. The spec's job isn't to be perfect on the first try — it's to be clear enough to start, and easy to update when reality teaches you something.
This is the Build Loop wearing planning clothes — the same understand → design → prompt → verify → test → commit rhythm you'll run all course, here applied to the document instead of the code. The spec evolves with the build, not frozen before it. ⚠️ The trap is the opposite extreme too: treating the spec as so sacred that you'd rather build the wrong thing than change the document. The spec serves the app, never the other way around.
💡 Keep your spec in the same repo as your code (you'll set up Git in 201). When the spec lives next to what it describes, updating it becomes a habit instead of a chore — and a spec that matches the code is the only kind worth having.
Key takeaways
- A technical spec is your app's blueprint — the bridge from what and why (brief + stories) to how (data, pieces, plan). It's the document your AI partner actually builds from.
- A spec exists to make design decisions on purpose, once — removing ambiguity before it becomes bugs, giving you something to verify AI output against, and giving a team a shared plan.
- Brief, stories, and spec are three different documents: why, what, and how. The spec is the one that names tables, endpoints, and fields — specific enough to be wrong.
- A StreakUp spec has a small, predictable shape: overview, data model, API, task breakdown, and open questions. You'll assemble these across this topic.
- The spec is a living draft, not a frozen contract. It runs on the Build Loop: draft → build → learn → update. Keep it next to your code so it stays true.
Your turn
Open your build journal and start your StreakUp technical spec — even just the skeleton:
- Write the Overview paragraph. In two or three sentences, compress your StreakUp brief into "what the app does and what's in scope for the MVP." Pull the must-haves straight from your Requirements work.
- Add the five empty section headings — Overview, Data Model, API, Task Breakdown, Open Questions. You'll fill the rest in over the next three chapters; today you're framing the blueprint.
- Seed the Open Questions list with one real thing you're genuinely unsure how to handle (a great candidate: "How does a streak handle time zones / what counts as 'today'?"). Naming the unknown is a senior habit.
In Part 2, we draw the most important pages of the blueprint: StreakUp's data model — the exact tables that store your users and habits — and the API the apps use to talk to it. This is the technical heart of the whole tier.