This version is in plain language. For the engineering detail, read the technical version.
A coding agent is an AI tool that writes software from what you describe in ordinary language. It creates the files, changes them, and tries to run them. Popular ones include Claude Code, OpenAI Codex, and Cursor.
“Build me a webpage that shows the catalog, with sections for pricing, stories, and a signup.”
That is a fair first sentence. A lot of people treat it as the whole request. They paste it into a coding agent and wait for an app.
Inside every coding agent is a model, the part that turns your words into a plan and then into code.
Here is the part most people do not expect. Whether you are building a small tool for one team or a large system for a whole company, there is more than one reasonable way to build it. The model picks one of those ways, and it does not always pick the same one. Ask it the same thing twice and you can get two working apps that look different, behave differently, and keep their information differently. That variation is built into how these models work. A clearer request narrows it. It does not remove it.
So the useful habit is to look before the agent picks. Make it show you the choices it could make, and make the important ones yourself while they are still sentences on a page. You are taking part in the outcome, instead of discovering it afterward.
The example
One app runs through this whole piece, so the choices have something concrete to attach to.
A small shop in New Jersey sells a dozen products online, to customers in the United States and in London. A visitor looks through the products and prices, reads what three customers said about the shop, and buys one. Buying means giving a name, an email, and a phone number, then paying. The shop also wants to recognize a customer who comes back.
That is a small app. A large company system has the same three layers described below, with more screens, more rules, more records, and more people affected by each decision. The questions stay the same. The cost of skipping them grows.
Three layers, three sets of choices
Almost every app has three layers, and the agent makes decisions for you in each.
- The front end. What a person sees and taps: the screens and the pieces they are built from.
- The middle. The rules of the business, and which part of the app is allowed to carry each rule out.
- The back end. Where the information is kept: the customers, the prices, the orders.
There is also a question about where the app will run. It comes at the end, because it follows from the middle layer.
First, ask for options
At every layer, the agent’s first proposal is one possibility out of several. If you accept it right away, you never see the others, and your real preferences usually show up in the difference between them.
Ask for three. Three ways to lay out the screen. Three ways to organize the work. Three ways to keep the records. Then ask about the one it recommends. Why this one? What gets harder in six months if we choose it? What did you assume about the people using it?
You are not trying to catch the agent out. You are looking at the decisions while they are still a paragraph. A paragraph is cheap to change. A set of records with a year of real customers in it is not.
Before any of this, let the agent interview you. What is the app for? Who uses it? What can they do when it works? Answer those. If the honest answer is “I have not decided,” say that, and ask it for options. Then turn the interview around and ask the agent what it is about to build.
Layer 1: the front end
In the shop, the front end is the catalog page, the customer quotes, and the checkout form.
Sketches before the real thing. A wireframe is a plain sketch of a screen: boxes, labels, and the order things appear in. No colors, no fonts, no polish. Think of the pencil layout a magazine editor marks up before anyone designs the page. Ask for sketches of the screens that matter, and ask for more than one of each.
The catalog shows why. One option is a single long page: products, then quotes, then checkout. Another is a grid of products, with checkout on its own page. A third gives each product its own page. All three match “a page with sections.” A shop with a dozen products probably wants the grid. A business that sells one service would want the long page. You only see the difference when the options sit side by side. Pick one, and say what you turned down, so the next round does not drift back to it.
Loose words get the same treatment. You said “stories” and meant three short customer quotes. The agent might build a blog, with an author, a date, and a page for every story. Both are reasonable. Only one is what you had in mind. Say which.
A kit of parts. A component is a piece of the screen used more than once: a button, a product card, a form field, a section with a heading. A component library is the agreed set of those pieces, settled before anyone assembles a full page. It works like a house style for a publication: one way to set a headline, one way to set a caption, used every time.
Software teams build these pieces with a toolkit, usually called a framework. Next.js, SvelteKit, and Astro are three common ones. Whichever one your app will use, ask the agent to build the kit of parts in that toolkit first, and then build the screens out of the kit. The sketch and the finished screen are then made of the same parts, so they have little room to disagree.
Skip the kit and the agent invents a new button every time it needs one. The catalog button says Buy. The checkout button says Pay and looks slightly different. A page added next month says Request a demo and looks different again, because nobody said those were one button with three labels.
A request that works:
By stories I mean three customer quotes, not a blog. Show me three sketches of the catalog: one long page, a grid of products with a separate checkout, and a page for each product. Recommend one. Then build one set of reusable parts, including a single button style, before you build any page.
Layer 2: the middle
In the shop, the middle decides what happens when someone buys, and which part of the app is allowed to do it.
The rules
This is the layer people describe most loosely and the agent fills in most freely. “Let people sign up and pay” can mean several things. Pay first, and create the account afterward. Create the account first, and pay later. Create an account quietly during checkout, without asking. Each is a reasonable way to build it, and each is a different customer experience.
Ask the agent to write the steps out in order before it builds them. For the shop:
- The visitor picks a product.
- The visitor gives a name, an email, and a phone number. Check them here, before moving on.
- If the email belongs to a returning customer, attach the order to that customer. Otherwise create a new customer.
- Take payment last.
- Mark the order as paid only after the payment company confirms it.
Step 5 hides a rule that is easy to miss. Payment companies sometimes send the same confirmation twice, in case the first message was lost. If the app is not built to expect that, one purchase can be recorded as two. Ask the agent how it makes sure one payment produces one order.
Who carries them out
Once the rules are clear, decide which part of the app is allowed to carry out each one.
One arrangement worth asking for by name is a modular monolith. Monolith means one application, instead of a crowd of small programs that have to send messages to each other. Modular means that inside that one application, the work is divided into rooms with doors. Each room looks after its own information. No room reaches into another room’s drawers.
For the shop, the rooms might be the catalog, customer accounts, orders, and payment. When someone pays, the payment room may ask the accounts room, through its door, whether this person is already a customer. The payment room may not open the accounts room and change a customer’s details. So when someone later changes how payment works, the signup still works, because the only connection between them is a door you can point to.
Two other arrangements show up when you do not ask. One is a single big tangle, where any part can change any other part. It feels quick on the first day and becomes painful within a few months, because a change to the prices quietly breaks the checkout, and nobody knew those two were connected. The other is a set of separate programs from the very start. That adds more ways to fail and more things to update and watch. Large companies sometimes need that. A shop with a dozen products does not.
The same thinking applies to where the files go, which is the filing system for the work. Ask the agent for two ways to organize the folders, with one sentence for what belongs in each folder and one for what does not. A filing system that uses the same words as the business, such as catalog, accounts, orders, and payment, is easier to follow than one organized by technical category. It also helps the agent: with a clear filing system, it puts the next feature in the right room. Without one, it puts it wherever it happened to be working.
A request that works:
Before you build checkout, write the steps out in order, including what is checked at each step and what happens if the payment company confirms the same payment twice. Organize the app as one application with four rooms: catalog, accounts, orders, and payment. Payment may ask accounts whether someone is a customer. Payment may not change account details. Show me the rooms and the folders before you build them.
If the agent cannot name the rooms and the doors between them, there is no real structure yet, only folders with good intentions.
Layer 3: the back end
In the shop, the back end keeps the customers, the products and their prices, and each order.
This is where a casual request does the most lasting damage. The information is kept in a database, which you can think of as a set of spreadsheets. Each list is a table. Each entry in a list is a row. Each fact about an entry is a column. The agent will invent lists that look fine and columns that are slightly wrong. Slightly wrong is the dangerous kind, because by the time you notice, the list is full of real customers and fixing it is a project.
Say what one entry means. Before any list exists, ask for one sentence a person could say out loud about each. “One row is one customer.” “One row is one price, in one currency, for one product.” “One row is one order, placed by one customer.” If nobody can say the sentence, the list is muddled. Split it or rename it until the sentence is easy.
Then look at the individual columns. People skip this because it sounds like paperwork. It decides whether the information is still trustworthy next year.
Labels for each entry. Every customer and every order needs a label that belongs to it and nothing else. When an order needs to say which customer placed it, it stores that customer’s label. The agent will often choose a counting number, 1 then 2 then 3, or a long random code.
A counting number is easy to read. It also tells anyone who sees it how many customers or orders you have. Order 18421 is a count as well as a label. A random code hides the count, and it also makes the database work harder as it grows, because each new entry gets filed in a random place instead of at the end.
There is a middle option called UUID version 7. It is a code that is unique, so no two customers share one, and it also lines up by time, so new entries are filed at the end, the way new pages go at the back of a notebook. If that is what you want, say “UUID v7.” Otherwise you get whatever the agent picked.
Money has to be exact. Computers have a kind of number meant for “close enough,” which is fine for a chart and wrong for money. A price of 19.99 stored that way can come back as 19.989999, and across a thousand orders the totals no longer match what the bank says. Ask for one of two safe options and make the agent say which: a number that always keeps exactly two digits after the point, so 19.99 stays 19.99, or a whole number of cents, 1999. The shop also sells in London, so every price needs a currency code next to it, such as USD or GBP, because the dollar sign alone is used by more than one country.
A phone number is not a number you do math on. It can start with 0 or a plus sign. A New Jersey number is ten digits. A London number starts with 0 when you dial it locally and with +44 when you dial it from abroad. If the agent stores phone numbers the way a spreadsheet stores amounts, it drops the leading zero and has nowhere to put the plus, and the London customer’s number becomes a different number. Store phone numbers as text. If you want one consistent shape, the standard one is a plus, the country code, and the digits, with no spaces or dashes. Then say which countries you actually serve. “The United States and the United Kingdom” is a clear promise, and it is the one this shop needs.
Dates and names. An order placed at 11 p.m. in New Jersey is already the next morning in London. Unless you decide how times are recorded, people will disagree about which day an order happened. A name is not “first and last” everywhere, and some people have only one name. You do not have to solve every country in the world. You do have to name the cases you care about, and ask the agent to show you how it will store them.
A request that works:
Before you create any lists, give me one sentence for what a single entry means in each. Label entries with UUID v7. Store prices as whole cents, with a currency code. Store phone numbers as text in the international format, for US and UK customers. Record times in one standard time zone. Show me the lists and their columns before you create them.
Where it will run
The last question is where the running app lives, and how a change gets from the agent’s work to the live site. One application you update in one step, or several separate programs that each update on their own schedule. The records kept with the app, or by a company that runs databases for a living.
Some of this can wait. The part tied to the middle layer cannot. One application means one thing to update and one set of records. A crowd of separate programs means a crowd of updates, and someone to watch each one. Ask the agent what it assumed, in a short paragraph. If that paragraph describes a setup you do not have and do not want to run, say so while it is still a paragraph. The shop needs one site and one place to keep its customers.
The order, layer by layer
This is the sequence I want before the agent writes the app.
- The outcome. Say it in a few sentences: who it is for, and what they can do when it works.
- The interview. Let the agent ask you questions. Answer them. Where you have not decided, ask for options.
- The front end. Ask for several sketches. Pick one. Have the agent build the kit of parts in the toolkit you will use, then build the screens from it.
- The middle. Write the business rules as numbered steps. Ask for two ways to organize the rooms and the folders. Name the rooms and the doors between them.
- The back end. Ask for the lists, with one sentence for what each entry means. Decide how labels, money, phone numbers, and times are stored.
- Where it runs. Ask where it will live and what a normal update looks like.
- The review. Read all of it. Ask questions about what it proposed. Then let it write the app.
The last step is the one people skip, because the agent is fast and the idea is exciting. That speed is the reason to pause. The agent will happily build a whole product from one sentence, and you will spend the next month undoing decisions you never made.
Let the agent interview you. That part is real. Then interview it back, one layer at a time: the screens and their parts, the rules and the rooms that carry them out, and the records down to the smallest column. That is your intent. If you cannot point at it, you do not have a request yet. You have a wish, and the agent will build something close to it.