Spec-driven development: how to write TK so that the AI agent does not think up

**Spec-driven development (SDD) is an approach in which you write the exact specification first, and the code generates the AI agent strictly according to it. The specification becomes the source of truth, and the code becomes the derivative artifact. This order removes the main pain of vibcoding: the agent stops coming up with what you forgot or were too lazy to describe.

• ** What decides: * Predictability of the result instead of guessed / misguided.
• **How it works:**Speak → plan → tasks → code, with verification at every step.
• What to Write: GitHub Spec Kit, Amazon Kiro or your process on regular .md files.
• **Who needs: * Everyone who does not make a one-time script, but a feature that is then maintained.

## What is spec-driven development

Classic vibcoding looks like this: you open a chat with an agent, write “make a registration form” and see what happened. If the result is past – specify, the agent reworks, you look again. It works on a small task. On the serious - turns into an endless correspondence, where no one remembers what exactly decided three messages ago.

Spec-driven development turns the order. First, you write a specification—a document that unambiguously describes what the system should do, under what conditions, and what is considered correct behavior. And then the agent on this speck writes the code.

The SDD’s key message is that specification is the source of truth, and code is just its implementation. If the code is broken, the code is wrong. If the speck is incomplete, it is the sin of the speck, not the “stupid agent.” This shifts the focus from “scolding the neural network” to “describe the requirements”, which is where the real work lies.

The approach has several names that you will come across: spec-driven development, SDD, development through specification, spec-first. It's about the same thing.

## Why Vibcoding Breaks Down on Serious Tasks

An AI agent doesn’t read your mind. It fills in the gaps in the TK with the most likely variant of the training data – and that is why it “thinks up”. The problem is not that the model is stupid. The problem is, you gave her an incomplete contract and you're hoping for telepathy.

Typical places where vibcoding falls apart:

• Border cases. You said login form. The agent made a happy path. That with the wrong password, the empty field, the account lockdown, the third failed attempt, he figured it out, and usually not the way you want it to.
• Implicit business rules. Discount for new users - who is considered new? The first 30 days? No orders? This is a decision, not a layout, and the agent will take it for you.
• **Consistency between sessions. In a new chat, the agent does not remember yesterday’s arrangements and reinvents them, often differently.
• Silent scope creep. Just in case, the agent adds error handling, flags, abstractions you didn’t ask for, and the code grows sideways.

According to 2026, teams that switched to spec-driven workflow reported a 3-10-fold increase in the proportion of tasks solved by the agent the first time on non-trivial features. The reason is simple: the less ambiguity remains, the less the agent guesses.

## How SDD Works: Spec → Plan → Tasks → Code

Developing through a specification is not “write one big document and throw it to an agent.” It's a four-step cycle where every transition is a human test.

1. Specification (what and why). Describe the requirements: what the system should do, for whom, under what conditions, what is considered a success. There is no word about technology, only behavior.
2. **Plan (how).**According to the approved speck, the agent (or you) prepares the technical plan: architecture, stack, data structure, module boundaries. Here, the speck turns into engineering solutions.
3. Tasks (by steps). The plan is broken down into small atomic tasks, each of which can be performed and verified separately. Do not “authenticate”, but “add the User model with X fields”, “add endpoint login”, “add the processing of the wrong password”.
4. Implementation (code). The agent takes tasks one at a time and writes code. Each task is traced back to the point of speck - so you can see that nothing was lost and nothing extra was added.

The important principle is that man approves every transition. Speka approved, we're making a plan. The plan is approved to cut to tasks. This is not bureaucracy: it is at these joints that mistakes are the cheapest to catch. Catch an incorrect requirement in the sinter is one edit of the paragraph. To catch it in the finished code - rewrite half the feature.

## What makes a good speck

The well-established format (it is used by Amazon Kiro, and many homemade processes) is three files per feature:

• requirements.md - Requirements. What should be happening from a user and business perspective? No code or technology.
• design.md - design/architecture. How to implement it: data models, APIs, threads, dependencies, error handling.
• tasks.md - tasks. Numbered list of atomic steps with references to requirements.

This separation is not accidental. It forces you to separate what from how—namely, the mixing of these two things often creates a junk code. When the requirements and implementation are piled into a single industrial unit, the agent begins to make product decisions on the go.

## How to write requirements without water

The main problem of conventional TK is the vague formulation: “the system should conveniently handle errors.” For an agent, "comfortable" is nothing. To make the requirements unambiguous, use the notation EARS (Easy Approach to Requirements Syntax). The idea is to write each requirement according to a template with a trigger and mandatory behavior.

Basic EARS templates:

• When <событие>, the system must <поведение>.
• If <условие>, that system should <поведение>.
• While <состояние>, the system should <поведение>.
• Where <функция включена>, the system should <поведение>.

Compare. Bad: Login form with validation. Good on EARS:

• When a user submits a form with the correct email and password, the system should create a session and redirect to /dashboard.
• If the password is incorrect, the system *should show the error "Incorrect email or password" without specifying what is wrong.
• If there were 5 failed attempts in 15 minutes, the system must temporarily block the entrance for 15 minutes.
• While there is a request to the server, the system ** should * block the button and show the boot indicator.

The difference is obvious: in the second case, the agent has nothing to think about. Each behavior is given a trigger and result, and then a test is written on it.

## How to formalize TK so that the agent does not invent

There are several techniques that work regardless of the instrument.

Describe behavior, not wishes. Quick search is a wish. “Search returns results ≤300ms in a sample of up to 10,000 records” — behavior that can be verified.

Explicitly list boundary cases. Empty input, maximum length, duplicates, no rights, network loss, parallel requests. Anything that is not described, the agent will close by accident.

Secret what NOT to do. A separate "outside" section saves a wagon of time: "do not add a role model", "do not touch payments", "no caching at this stage". This is the direct antidote to scope creep.

**Set decisions, not just requirements. ** If you chose JWT over sessions, write this down and why. Otherwise, in the next session, the agent will reinvent the choice.

Give examples of input and output. One specific example of a JSON response is worth three paragraphs of description. The agent works perfectly on the model.

Definition of terms. Active user, order, new client - give precise definitions. An indefinite term is a hole in which an agent inserts his guess.

## Example: Was and Became

So that the difference is not abstract, here is the same query in two versions.

** Was (wibcoding):**

Export orders to CSV.

The agent issues a button that unloads all orders, all fields, without pagination, without rights, with dates in an incomprehensible format. For 100,000 orders, the page falls by timeout.

Steel (steak):

Requirement. When the manager presses Export, the system must form a CSV with orders for the selected period. ** Fields:** id, date (ISO 8601), amount (in kopecks), status, email client. No other fields. Rights: Export is only available for manager and higher. Otherwise, 403. ** Volume: ** Up to 50,000 lines per export. More – generate a file in the background and send a link. **Border cases:**Empty period → file with headers only; client without email → empty cell, do not fall. Outside: Export to Excel, column selection, scheduler - not in this task.

The second option is longer, but it saves time: the agent collects what you need the first time, and you do not catch bugs in the sale after a week.

## Spec-driven development tools in 2026

The SDD can be conducted in a notebook, but in 2026 special tools appeared under it.

GitHub Spec Kit is an open tulkit that adds to the command agent /specify, /plan, /tasks, /implement and guides you through the process. It works on top of any agent (Claude Code, Copilot, Gemini CLI and others). By mid-2026, the repository had surpassed 111,000 stars, a measure of how much the theme had shot. A good choice if you want a ready-made process rather than inventing your own.

Amazon Kiro is an IDE built around specks. At your request, it generates requirements.md (including in EARS format), design.md and tasks.md, and then performs tasks one at a time. Suitable for those who want the tool itself to lead the structure of the sinter.

Your process on .md files. There is no magic in the tolkit: you can keep the specs/ folder with the same three files and the rule "agent does not write code until the spectacle is approved." This goes hand in hand with AGENTS.md, where you once describe how an agent should handle the specks in your project.

The choice between them is a matter of taste and scale. It is easiest to start with your process on files, and switch to Tulkit when you feel that manual conducting becomes a lot.

## Frequent Errors and Anti-Patterns

• A 20-page document that no one reads and is out of date on the second day. Speck should be exactly as detailed as necessary to remove ambiguity, and not longer.
• Technology in Requirements. "Use Redis" in requirements.md is an error. The requirement says what (caching the result for 5 minutes), the solution about Redis lives in design.md.
• **Speak that is not updated. ** If the code is broken and you only edit the code, the steak is dead. Then the whole approach loses its meaning: the source of truth no longer exists.
• Atomic tasks that are not atomic. "Backend" is not a task. If a step cannot be tested with a single test or a single look at diff, it must be crushed further.
• **Missing the crossover review. ** Allowing an agent to immediately generate speculate, plan, tasks, and code without stopping is the same vibcoding, only with extra files. The value lies in the affirmation at every junction.
• SDD for disposable scripts. Write three sinter files for a one-time parser - overengineering. The tool should be on the scale of the task.

## Preparedness checklist

Before you let the agent into the code, go through the list:

• Each requirement describes behavior through trigger and outcome (EARS style).
• Boundary cases are listed: empty data, limits, errors, access rights.
• There is a section “outside the box” – what not to do.
• All ambiguous terms are defined.
• There is at least one example of entry and exit.
• The technical decisions taken and their reasons are recorded.
• The tasks are atomic and each refers to a requirement clause.
• It is clear what counts as "done": what tests or checks must pass.

If everything is green on the checklist, the agent will hardly think. If there are gaps, that is where he will go wrong.

## When spec-driven development is redundant

Honestly, SDD is not always needed. For a one-off script, an ejection experiment, a tiny edit, or a prototype that you throw out tomorrow, a full-blown speck is an unnecessary move. Here, vibcoding is faster and more appropriate.

SDD pays off where the cost of error is high and the code will be supported: product features, teamwork, complex business rules, integrations, everything related to money, access and user data. The rule is simple: the longer the code lives and the more people touch it, the sooner you should switch to speculation

## Frequent questions

**How is spec-driven development different from vibcoding? ** Vibcoding - first code, then clarification in the chat. SDD is the specification first, then the code. In vibcoding, the source of truth is smeared through correspondence, in SDD it lies in separate files.

**Isn't that the same as good old TK? ** In spirit, yes, but with two differences. Specta is written in machine-readable, unambiguous form (EARS, examples, atomic tasks) specifically for an AI agent, and it lives next to the code, not in a forgotten document. This is the TK from which the code is directly generated.

Is it slower than just asking for an agent? ** On small tasks, yes, slower. On medium and large – faster, because you do not spend cycles on “remove, misunderstood” and do not fix bugs in the product. Savings occur where the cost of error increases.

Where to start without special tools? ** Open the folder specs/, for each feature - files requirements.md, design.md, tasks.md. Write a rule in AGENTS.md: The agent does not write code until the speck is approved. This is enough to feel the effect.

**Do I need to update the speculation after the changes? ** I will. Once you control behavior only in code, the speck ceases to be the source of truth and the whole approach collapses. You change the behavior, first the sinter, then the code.

## Conclusion

Spec-driven development is not about bureaucracy or more documents. It's about moving decision-making from the middle of code generation to the beginning, where it's cheap to change those decisions. Once you honestly answer the questions “what should happen, under what conditions and what is considered a success” – and the agent simply does not have room to think for you.

Start small: take the following non-trivial feature, write a short EARS speculation on it, add an “out-of-frame” section and an example of input and output. Compare the result with the usual. Most likely, the agent will hit the target the first time - and you will understand that the "dumb neural network" all this time just performed your incomplete TK.

## What to read next

• AGENTS.md: единый источник истины для ИИ-агентовXX
• Memory Bank: хранение контекста для ИИ в разработке проектовXX
• Как писать тесты через ИИXX
• Подготовка проекта с помощью ИИ: от идеи до документацииXX