Blog · 16 November 2026 · 7 minute read
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
- The framework and its version, and the language.
- How pages, routes and data access are organised.
- How authentication works: sessions, where they are stored, which routes are protected.
- How email is sent, and from which address.
- How payments work: the checkout flow, the webhook path, and that signatures must be verified.
- How to run it locally and how it deploys.
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
- Never print or commit a secret. Read every key from its variable.
- Do not add a new service or dependency without saying why.
- Do not change infrastructure. Build on what exists.
- Write a test for anything that handles money or sign-in.
- When something is unclear, ask instead of guessing.
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