# Spec-Driven Development with Tessl

Spec-driven development is a workflow where your AI coding [agent](/reference/custom-agent-setup.md) gathers requirements and writes specifications *before* writing any code. You review and approve the specs, then the agent implements them.

## The Problem with Vibecoding

When you prompt an agent without structure, you get vibecoded output:

* The agent assumes what you want instead of asking
* It hallucinates APIs from stale training data
* There's no way to verify the result matches your intent
* When you restart the session, the agent has no easy way to regain context

This creates an **intent-to-code chasm** — a gap between what you meant and what you got. The agent produced *something*, but you have no systematic way to check if it's the right thing.

{% hint style="info" %}
Vibecoding is fine for throwaway prototypes. For anything you actually care about, you need a process that bridges that gap.
{% endhint %}

## Quick Start

Assuming Tessl is already [set up and ready to go in your terminal](broken://pages/nGU0rz0uGSZv5cYBrzwd), install the spec-driven development tile:

```bash
tessl init
tessl install tessl-labs/spec-driven-development
```

Then include "use spec-driven development" in your prompt:

```
Build a REST API for managing team projects. Use spec-driven development.
```

That's it. The agent now follows a structured workflow instead of diving straight into code.

## What Happens Next

{% stepper %}
{% step %}

#### The agent asks questions first

Instead of making assumptions, the agent interviews you:

* What endpoints do you need?
* How should authentication work?
* What happens when a resource isn't found?
* Should deleted items be soft-deleted or permanently removed?

One question at a time, until requirements are clear.
{% endstep %}

{% step %}

#### The agent writes specs before code

The agent creates specification documents in a `specs/` folder. These are markdown files that capture:

* Functional requirements
* API contracts
* Edge cases and error handling
* Links to tests that verify each requirement
  {% endstep %}

{% step %}

#### You approve before implementation begins

The agent pauses while you (and all the stakeholders) review the specs. This is your checkpoint — if something's wrong or missing, you catch it *before* any code is written.
{% endstep %}

{% step %}

#### Implementation follows the specs

Once you approve, the agent builds against the documented requirements. When it's done, it verifies that all requirements are satisfied and updates specs with anything discovered during development.
{% endstep %}
{% endstepper %}

## Combining with Documentation Tiles

The spec-driven development tile teaches your agent *how to work*. Tiles with documentation from the [Tessl Registry](https://tessl.io/registry) teach it *what tools to use correctly*.

Together, they're powerful:

```bash
tessl install tessl-labs/spec-driven-development
tessl install tessl/npm-express
tessl install tessl/npm-langchain
```

Now your agent:

* Follows a structured workflow (spec-driven tile)
* Uses Express APIs correctly without hallucinating (Express tile)
* Implements LangChain patterns properly (LangChain tile)

Process without library context gives you well-organized hallucinations. Documentation and code samples without process yield correctly spelled chaos. You need both.

## Learn More

For details on the spec format, the `[@test]` linking syntax, and what's inside the tile: see the [tile documentation on GitHub](https://github.com/tesslio/spec-driven-development-tile).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tessl.io/use/spec-driven-development-with-tessl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.