Why the AI needs a spec: every gap becomes a guess

In What AI coding tools can and cannot do you saw that these tools are good at screens and at CRUD, and weak at unwritten rules, security and exact data. The reason is how they work. A coding tool is built on a large language model. It writes the code that is most likely to fit your request, based on the millions of programs it learned from. When your request is silent on a point, the tool does not stop and ask. It picks the most common answer it has seen.

For screens, the most common answer is usually fine. A list with a button, a form with a Save button, a menu at the top. If the AI guesses wrong, you see it at once and say "make the button bigger". That guess cost you ten seconds.

For rules and data, the most common answer is often wrong for your business, and you cannot see it on the screen. Most example apps the model learned from are demos with one user, so they do not limit who sees what. Many store prices as text or as decimal numbers. Almost none know your delivery cut-off. These guesses look fine in a demo and fail with real shops, real money and real deadlines. By then other code is built on top of them, so the fix is slow.

So a spec for an AI has a different job from a spec for a team. In Writing specs people read you learned to write for engineers and designers who share your context and can ask you in the corridor. The AI shares none of your context. It does not know Mangrove Market, partner shops or what a sales rep is. It will not ask unless you tell it to. So your spec spends little space on what screens look like and most of its space on the things the AI would guess wrong: who can see what, what the data is, and the rules.

The one-page spec: users, screens, data and rules

A spec the AI can follow fits on one page and has four core parts. Each answers a question the AI would otherwise guess.

1. Users and roles: who uses the app, and what may each of them see and do? A role is a kind of user with its own permissions. Ravi's app has three. A shop owner like Ravi sees and orders only for his own shop. A sales rep sees the shops in their own area (Mangrove has about 40 reps for about 1,800 partner shops, so roughly 45 shops each) and, in the first version, only reads. An admin on Imran's team manages products, prices and users. If you write only "shop owners order stock", the AI builds one kind of user who can see everything.

2. Screens and flows: what does each person see, in what order? List the screens by name with one line each, then write the main path. For Ravi: sign in, My usual order (last week's items with today's prices), edit quantities on that same screen, Confirm (total and delivery day), and Order history. The main path is three taps: open the app, tap Review, tap Send. You do not need drawings. The AI is good at layout, and you will adjust it by looking.

3. Data: what is stored, and in what form? Apps keep their data in a database, as tables of rows and columns, and you met them properly in Modeling data in tables. You can describe them in plain words. Ravi's app needs five: shops, products, usual order lines (what each shop normally orders), orders, and order lines (what is in each order). For each table, list its fields and mark which are required. Then state the formats the AI gets wrong:

• Money is whole cents. $6.40 is stored as the number 640. Text cannot be added up safely, and decimal numbers in most programming languages are slightly inexact (in JavaScript, 0.1 + 0.2 gives 0.30000000000000004). Whole cents add up exactly.
• Quantities are whole numbers. Ravi orders 10 bags of rice, never 9.5. Give a range, such as 1 to 999.
• Each order line keeps the price at the time of the order. If the price of rice changes next week, last week's order must still show what Ravi paid.
• Times have a time zone. "4 pm" means 4 pm in the shop's local time. Say so.

4. Rules: what must always or never happen? These are the business rules the AI cannot know. Number them, so you and the AI can point at them later (R1, R2…). For Ravi's app:

• R1 A shop sees only its own orders. A rep sees only the shops in their area. This is checked on the server, never only by hiding buttons.
• R2 The minimum order is $50.00. Below it, Send is disabled and the screen says how much is missing.
• R3 Orders sent before 4:00 pm shop time are delivered the next day; at 4:00 pm or later, the day after.
• R4 Products that are out of stock, or no longer sold, cannot be added or sent.
• R5 A shop can cancel an order only before the distribution centre starts packing it.

Write each rule so that someone could check it with a yes or no. "Orders should be on time" cannot be checked. "Orders sent before 4:00 pm shop time are delivered the next day" can.

Acceptance checks, edge cases and what is out

Rules say what must be true. Acceptance checks show it with real numbers, so both you and the AI can test it. You learned the given / when / then format in User stories and acceptance criteria: given a starting situation, when someone does one thing, then you can see a result. For an AI, these examples do two jobs. The AI can turn each one into an automatic test, and you can tap through each one by hand in a minute. A check you can tap through is your proof that the app does what the spec says, whatever the AI tells you.

A2 Cut-off
  Given Ravi's usual order totals $156.70 and the shop's time is 4:00 pm
  When he taps Send
  Then one order is saved with delivery the day after tomorrow
  And the Sent screen shows that date

Write checks for the boundaries, because that is where guesses hide. If the cut-off is 4:00 pm, write one check at 3:59 pm and one at exactly 4:00 pm. If the minimum is $50.00, write one at $49.99 or below and one at exactly $50.00. Use real values ("$42.00", "3:59 pm"), never "a small order" or "late in the day". Aim for five to ten checks for a first version, at least one for every rule.

Edge cases are the unusual situations that break a happy path. Ask "what if?" about each screen. For Ravi's app, four matter:

• No usual order yet. A new shop has no last week. The spec says: show the product list so the owner can build a first order, and save it as the usual order.
• Product no longer sold. Mangrove stops selling a brand of tea. The line shows greyed out with "no longer sold" and is left out of the total.
• Price changed since last week. Rice went from $6.40 to $6.60. The app shows today's price and marks the line "price changed", so the total on the Confirm screen does not surprise Ravi.
• Signal lost while sending. Ravi taps Send, the shop's mobile data drops, the app retries, and the request reaches the server twice. Without a rule, that is two orders and two deliveries. The fix has a name: an idempotency key. The phone creates one unique code when Ravi taps Send and sends it with every retry. The server saves the code with the order, and if the same code arrives again it returns the order it already has. You do not need to build this yourself. You need to write the rule ("one tap on Send creates at most one order, even if the request is repeated") so the AI builds it.

Out of scope is the list of things the first version will not do. It matters more for an AI than for a team, because AI tools tend to add features nobody asked for, such as a payment page "to make the app complete". For Ravi's prototype: no payments (invoices stay as they are today), no delivery tracking, no promotions, one shop per owner. When the AI's plan includes one of these, you point at the list.

Handing it over: SPEC.md, instruction files and a plan first

Write the spec in Markdown. It is plain text with a few marks: # starts a heading and - starts a list item. Every AI coding tool reads it well, and it shows nicely on GitHub.

Save it as a file named SPEC.md in the project folder, next to the code. A spec pasted into a chat is lost when the chat ends, and most tools start each new session with no memory of the last one. A file stays. You point the tool at it ("read SPEC.md first"), you change it when you decide something, and the history of your decisions lives with the code. When you and the AI disagree about what the app should do, the file wins.

Many tools also read a project instruction file automatically at the start of every session. The names differ by tool and change over time, so check your tool's documentation. At the time of writing, Claude Code reads CLAUDE.md; AGENTS.md is an open format read by many tools, including Cursor and GitHub Copilot's coding agent; Cursor also has project rules in a .cursor/rules folder. Browser app builders such as Lovable or Bolt usually keep project instructions in a settings or knowledge area instead of a file. You saw these files from a developer's side in Working with AI coding assistants.

Keep the two apart. The instruction file says how to work in this project, in a few lines that are true for every feature: read SPEC.md before changing anything, money is whole cents, access rules live in the database, plan before building. The spec says what the app does, and it grows with each feature. And remember that both are advice the tool usually follows, never a lock. A rule like "a shop sees only its own orders" must also be enforced by the database itself, which you will set up in Data and security basics.

Then give your first prompt, and make it ask for two things before any code:

• Questions. "List everything in SPEC.md that is unclear, missing or contradictory." The AI is good at spotting gaps in someone else's text. Each question it asks is a guess it would otherwise have made silently.
• A plan, not code. "Propose a plan of small steps, and wait." Some tools have a planning mode that reads and plans without changing files; in others you say it in the prompt. A wrong step in a plan costs you one sentence to fix. The same mistake in code costs an hour. You will steer the plan one step at a time in Building in small steps.

When the questions come back, write your answers into SPEC.md, not only into the chat. Then ask for the plan again, or approve it.