Writing a spec

How to turn an idea or something you built into a spec anyone can copy and adapt.

What is a spec on Specbin?

A spec is a plain-text or Markdown description of something to build, essentially a self-contained prompt you can copy and give to an AI builder to make your own version.

How do I write my first spec without overcomplicating it?

Start with one small, self-contained thing and describe only what matters. You do not need a formal requirements document, diagrams, or a list of every edge case.

Cover four basics in plain language:

  • What it is: one sentence naming the thing and where it runs (for example, a single-page offline browser tool).
  • What it looks like: rough layout, key elements, and visual states that matter.
  • What it does: the main actions a user can take and how it responds.
  • What to leave out: no accounts, no backend, or sample data instead of a live API.

To check your draft, paste it into a fresh chat with an AI builder. If the build misses something important, add one concrete line and try again. Stop as soon as a fresh run lands close to what you meant.

How should I format a spec?

Use plain text or simple Markdown. Because the public spec box copies the body exactly, write it so someone can paste it straight into an AI builder without editing out filler.

A few habits help both readers and AI builders:

  • Lead with a one-sentence summary so the overall goal is clear up front.
  • Group details with short headings or bullet lists (Layout, Behavior, Sample data, Constraints).
  • Be concrete instead of vague. Write "highlight delayed rows in amber" instead of "make delays stand out", and "single HTML file with no external libraries" instead of "keep it lightweight".
  • Include starting data when the layout depends on realistic content.

A compact spec can be as short as this:

Build a single-page cooking multi-timer that runs offline in the browser.

## Layout
- Serif typography on a plain light background in a centered column.
- Top bar with a timer label input, minutes and seconds fields, and an Add button.
- Stacked list of timers showing label, remaining time in monospace digits, and Pause, Reset, and Remove buttons.

## Behavior
- Multiple timers run independently at the same time.
- When a timer reaches 00:00, highlight its row in amber and play a soft chime once.
- Store active timers in localStorage so refreshing the page keeps them.

## Constraints
- No accounts, backend, or external libraries.
- Start with two sample timers on first load ("Pasta", 9:00 and "Garlic bread", 4:00) so the layout is visible right away.

Plain prose works fine for very short specs too: only add headings when they make the text easier to scan.

What belongs in the spec vs. the description and screenshots?

A Specbin post separates builder instructions from notes for humans:

  • Title (required): A short, literal name for what the spec builds.
  • Spec body (required): Only the instructions needed to build it. Because Specbin copies the body verbatim, keep backstory, commentary, and links for readers out of it.
  • Description (optional): Rendered separately as Markdown. Use it to explain what you made and why, note what worked well or needed tweaking, or suggest variations.
  • Screenshots or GIFs (optional): Helpful for communicating what a finished result looks like or how an interaction feels, but not required.

How do I turn several prompts into one reusable spec?

Most builds take a trail of follow-up prompts: adjusting layout, undoing an idea, fixing a bug. Do not paste that whole chat into a spec. A transcript keeps dead ends and contradictions that confuse the next run.

Write for the version you ended up with. While the finished build is still in context, ask the AI to draft one clean spec from scratch, then cut anything vague or bloated. Try this prompt:

Write a single, self-contained Markdown spec that another AI builder could use to recreate the final version of what we just built from scratch.
Include layout, behavior, sample data, and technical constraints.
Leave out dead ends, bug fixes, and intermediate changes.
Keep it concise and concrete.

Test the resulting spec in a brand-new chat. Anything the fresh build misses points to a detail your original thread only assumed.

How do I reverse-engineer a spec if I lost the chat?

If you lost the original chat or have a vibe-coded app, page, or script you already own or can inspect, you can extract a spec from the artifact itself. Work from the most direct source you have:

  • Source files you own: Point an AI coding tool at the files and ask for a plain-language spec of what the project looks like and does, rather than copying code line by line.
  • A running app or page you can inspect: Click through every screen, control, empty state, and error state and note how each behaves. Inspecting the markup and styles in browser DevTools helps capture layout and typography accurately.
  • Screenshots or a short recording only: Treat them as visual reference, nothing more. A screenshot shows visible layout, text, and one static state: it does not reveal hidden logic, validation rules, data formats, keyboard shortcuts, backend behavior, or secrets. Use the image for visual details, then write the interactive behavior and sample data yourself from memory and direct testing.

When working from source files you own, a prompt like this works well:

Read the files in this project and write a concise, self-contained Markdown spec that another AI builder could use to recreate it from scratch.
Describe visible layout, user flows, edge states, data shape, and constraints (such as running offline or using sample data) in plain language instead of pasting implementation code.
Flag anything ambiguous you had to infer.

Before sharing an extracted spec, remove private URLs, API keys, and personal data, and swap real records or feeds for small sample values. Then test the spec in a fresh chat and compare the rebuild to your original: extraction gives you a starting draft, not a guarantee that every behavior carried over.

Can I post a spec right now?

Yes. Open Post a spec, sign in with GitHub, and pick a username if it’s your first time. Add a title and paste the spec or load a text file. The Markdown description is optional. Preview the draft, then choose Publish spec.

How will public posts and forks work?

Publishing gives your spec a shareable link. Readers don’t need an account to read or copy it. You can edit or delete your own post and add optional screenshots or GIFs. People can star a spec, leave a review, or start a fork from the version they read. A fork keeps credit while at least half its wording matches its pinned source.