How to write a build prompt that stops your AI coding tool going off the rails

Most bad AI builds start with a vague brief. Here is what to put in a build prompt for Claude Code, Cursor or Codex so the first version uses your real stack.

Why builds go wrong

Ask a coding tool to "build a SaaS for dog walkers with payments" and it will. It will also choose a database you did not want, invent a payment flow, name its own environment variables and style everything in a way you will spend tomorrow undoing. None of that is the model being bad. It filled every gap you left with a reasonable guess.

A build prompt is the document that closes those gaps. The goal is not length. It is to state every fact the model would otherwise have to guess.

Start with what already exists

The most useful section says what is already set up and must be used as it is: the host, the database, the email provider, the payment provider, the storage. Name them. An assistant that knows the database is Postgres on your host will not add a second database from a tutorial it remembers.

Name the environment variables

List the exact names of the variables the app can read, with one line on what each is for. Never include the values. This single list prevents the most common failure, where the tool invents a name such as DB_URL while your host provides DATABASE_URL, and the app fails only after it is deployed.

State the conventions

Describe the product in one paragraph

Say who it is for and the one thing it does, the way you would tell a friend. Then list the first screens. Resist adding the second and third feature. A tool given one clear job produces a working first version, and a working first version is much easier to extend than a broad half-finished one.

Set the rules it must not break

Give it a look and feel

Without direction, generated interfaces all look the same. A short design section fixes that: one accent colour, a type scale, spacing rules, how buttons and forms behave, and what the page should look like on a phone. You do not need a designer for this, only decisions written down.

Put it where every tool reads it

Save the prompt in the repository under the file names coding tools look for, such as CLAUDE.md and AGENTS.md. Then every session starts with the same facts, and you stop repeating yourself.

Generated from the real thing

The weakness of a hand-written prompt is that it drifts from reality. At the end of a launch, Shipyard writes the build prompt from what it just created: the actual host, the real variable names, the webhook path, the sending address, plus a design system derived from the colour you picked. It commits the prompt to the repository, so your coding tool starts from facts.

Launch in an hour, not a weekend

Shipyard connects your accounts once, then sets up the domain, hosting, database, email and payments for every new product.

See how it works

Read next

How to write a build prompt that stops your AI coding tool going off the rails – Shipyard