# How to write a good spec

> A good spec (`SPEC.md`) is a short, plain-language agreement inside your project that defines what you are building, who it helps, what is included or left out, how you will verify it works, and which technical pieces your coding agent needs before writing any code.

## Analogy

Think of an architect's sketch and room list before anyone pours concrete. Moving a wall on paper takes thirty seconds with an eraser; moving a brick wall after the roof is on takes a sledgehammer. Your spec is that sketch.

## How it works

In sdd, every project and every major feature starts with a spec saved in a file called `SPEC.md` at the root of your project folder. Instead of asking you to write a long document from scratch, your coding-agent uses its `interview-me` skill to ask you one question at a time, offering a sensible suggested answer for each.

Those questions are about people, problems and goals, never about code. Together you agree on five plain-language sections: **what** you are building, **who** it is for, the **must-haves** for the first version, what is **out of scope** for now, and **how we will know it works** when you test it yourself.

Below your plain-language summary, the agent adds the technical notes it needs: which stack pieces the app actually requires. Each app gets only what it needs: if nothing is saved between visits, there is no database; if there are no accounts, there are no logins; if there are no AI features, there are no AI providers.

Your spec is a living document, not a contract carved in stone. Whenever you change your mind or discover a better idea while testing, tell your agent to update `SPEC.md` and the plan first, and only then change the code. That keeps your project coherent from start to finish.

## In your project

When you start a project or ask for a new feature, your agent won't jump straight into generating files. It will ask its first question, wait for your reply, and after a few turns write `SPEC.md` in your language and show it to you for your OK before making a plan.

## Copy for your agent

```text
I want to define what we're building in SPEC.md. Interview me one question at a time, with a suggested answer for each, about who it's for, must-haves, what's out of scope, and how we'll know it works.
```

---
Source: [Agentic Makers](https://agenticmakers.app/en/learn/how-to-write-a-good-spec) · License: CC BY 4.0