How to turn an app idea into a specification an AI can build from

Your agent is a brilliant builder and a terrible mind reader. Most bad AI builds are not model failures, they are briefing failures. Here is what to write down before you ask for code.

Why the one line prompt keeps failing you

"Build me an app that generates guitar tabs" is not a small version of a specification. It is a different kind of object. It contains a subject and a verb, and every other decision is left to the model: who this is for, what happens on the first screen, what the data looks like, what counts as done.

The model will make all of those decisions anyway. It has to. It just makes them invisibly, in one pass, optimising for a plausible looking result rather than the one you had in mind. Then you spend the next two hours steering it back, one correction at a time, which is exactly the work you were trying to skip.

A specification from one sentence is a guess. One earned from votes, comments, and feature requests is evidence.

The fix is not a longer prompt. It is moving the thinking to the front, into a document that survives between sessions and that you can hand to a different agent tomorrow and get the same build.

What a build-ready specification actually contains

A specification your agent can execute answers questions in a predictable order. If you write nothing else, write these:

Purpose

One paragraph on what this product is for, aimed at a person rather than a compiler. Not the feature list. The reason the feature list exists. If you cannot write this without listing features, the idea is not ready yet.

Target audience

Who specifically. "Guitarists" is not an audience, it is a category. "Intermediate players stuck in a creative rut who already know three chord shapes and want something new to practise" tells the model what to assume about onboarding, vocabulary, and default settings.

Features, split into core and enhanced

This split matters more than the features themselves. It tells your agent what to build first and what to leave stubbed. Each feature gets three things:

• A name. Short, so you can point at it in conversation.
• A user story. One sentence in the user's voice. This is the only human voice in an otherwise machine readable document, and it is what stops a feature drifting into something technically correct and useless.
• A description. What it does, concretely enough to implement.

Data structure

Entities and the relationships between them. Agents are good at inventing schemas and bad at inventing the same schema twice. Writing this down is what lets you resume a build a week later without a migration.

Constraints

The decisions you have already made and do not want relitigated. Platform, stack, budget, things that are explicitly out of scope. Be specific: "React 19 with TypeScript and Vite" rather than "a React project". Every constraint you omit is a decision the model makes for you.

Acceptance criteria

What "done" means, in checkable statements. This is the section people skip and the one that most changes the output, because it converts a vague build into a list your agent can verify itself against.

The structure, in practice

Put together, a specification for a real idea looks like this:

{
  "name": "AI Guitar Tabs",
  "purpose": "To democratize music creation by allowing guitarists of all
              skill levels to generate custom tabs and lyrics inspired by
              their favorite artists.",
  "target_audience": "...",
  "features": {
    "core": [
      {
        "name": "Style transfer generation",
        "user_story": "As a guitarist in a rut, I want a new piece in a
                       style I love so I have something fresh to play.",
        "description": "..."
      }
    ],
    "enhanced": [ ... ]
  },
  "use_cases": [ ... ],
  "constraints": [ ... ],
  "data_structure": { "entities": [ ... ], "relationships": [ ... ] },
  "acceptance_criteria": [ ... ]
}

Structured rather than prose, because your agent parses it rather than reads it, and because a schema makes gaps obvious. An empty acceptance_criteria array is a visible hole. A paragraph that quietly forgot to mention what done means is not.

Where the content comes from

Everything above assumes you know the answers. Usually you do not, not on day one. This is the part most advice skips: a specification written alone on a Tuesday night is still a guess, just a longer one.

Three things worth doing before you write it:

• Capture the idea while it is still hot, with a title, a description, and a home. Most ideas die because they were never written down, not because they were bad.
• Show it to people who will tell you the truth. Not "would you use this", which everyone answers yes to. Something that measures how strongly they want it, so casual interest and real conviction do not look identical in your notes.
• Collect the feature requests that come back. The ones other people propose are the ones you were never going to think of, and they are the difference between a specification that describes your assumptions and one that describes a product.

Then write the specification from that material. The sections stay the same. What changes is that the answers are evidence rather than invention.

Handing it over

Once the document exists, the build step gets boring, which is the goal. You point your agent at the specification rather than describing the idea again, and it plans against a fixed target:

> Use idz mcp to fetch my latest AI Guitar Tabs specification and build the idea

  Found 2 specifications. Let me use the latest one to build the idea.
  Ready. 3 phases, 12 tasks.

Phases and tasks rather than a wall of code, because a specification with acceptance criteria can be broken into pieces that are each checkable on their own.

The short version

• Write purpose and audience before features. If you cannot, the idea is not ready.
• Split features into core and enhanced. That split is the build order.
• Give every feature a user story in the user's voice.
• Name your constraints, or the model picks them for you.
• Write acceptance criteria. It is the section that changes the output most.
• Gather real signal first, so the document is evidence rather than a longer guess.