Build

An agent that starts coding from a one-line prompt fills every gap with the average website.

Here's what happens without a brief. You type: build the homepage for the bakery. The agent has never seen your brief, your manuscript or your tokens, so it guesses. You get a stock headline, three feature cards, a testimonial nobody gave and a blue button. Every one of those is a decision you didn't make.

A working brief has three parts, and you write all of them before any code exists. The context pack tells the agent what's already been decided. The do-not block names the mistakes you can predict. The spec is the agent's plan, written back to you, which you read and approve before it builds anything. The same three parts work in any AI builder, chat or coding tool.

The context pack is a list of documents, named exactly. Names, not summaries. If you paraphrase the brief into the prompt, the agent works from your paraphrase, and your paraphrase drops things. Give each document a few words on what it decides, so the agent knows the manuscript outranks its own copywriting. If your direction draws on a published style record, add that record's builder guide, which carries each rule with its evidence label. Then end on the line that matters most: nothing outside these files is a decision.

The do-not block comes from experience. Every line in it is a mistake you've watched an agent make, or one you can predict from this project. The bakery's founding year isn't known, so the agent will be tempted to make one up. Say no in writing. And say what to do when a fact is missing: mark it, don't fill it. Your project's standing instructions hold the rules for every session; the do-not block is for this build. Keep it short. The longer the list, the more of it gets skimmed past, by an agent as much as a person. Put the lines that would hurt the client first.

Now the spec. Ask the agent for a plan before any code, and tell it not to change any files yet. Many coding agents have a planning mode that does exactly this; if yours doesn't, say it in words. Ask it to write the plan against your context pack: which sections, which components, which tokens, which manuscript passage goes where. Then read it. This is the gate. If the plan says hero with tagline and your manuscript has no tagline, that's a guess, and you catch it here, where fixing it costs one sentence.

Here's the difference on the page. A plan you should send back uses words like compelling, key services and social proof. Those words name categories, and the agent will fill them with whatever's typical. A plan you can approve points back at your documents. Manuscript section one, headline as written. Today's bread, the four loaves the manuscript lists. And it says what's missing out loud: no founding year, because nobody has confirmed one. Send the vague steps back in writing. Approve the plan only when every step points at one of your documents.

When it's built, check the build against the same files you briefed it with. An agent stops when the work looks done to it, so give it a check it can run, and ask for evidence instead of a claim. Ask it to compare the page text with the manuscript and show you every difference. Ask for any color or size in the styles that isn't in the tokens. Then look yourself. The agent's report is evidence for you to read. The decision stays with you.

The agent builds from what's in the documents. Name them, say what it must never do, and approve a plan only when every step points at one of them.

Ask an agent for a card component and it'll give you one. Ask what goes in it and it'll make that up too. Start from the content instead.

Your content model already lists the slots each page type holds. For the bakery, every loaf has a name, a price, its allergens, and whether it's available today: available, few left or sold out. Each slot becomes one part of the loaf's entry, and nothing else goes on it. There's no star rating, because no slot holds one.

Another fictional client, a walking-holiday company called Fell and Tarn, has three optional slots: the next departure, a starting price and a photo. That's where the design work is, because each one is a case the component has to handle empty.

Variants follow the same rule: one exists only when the content differs and you can name how. A loaf that's running low gets a gold few left badge. A sold-out loaf says so, and loses its quantity buttons. A dark card for variety has no content reason, so it's cut.

Then the states. Here's the list with the head baker's real content. A list you've only seen like this isn't finished. Empty: before the day's list is in, Today's bread has nothing to show, so it says so and points to the hours. A loaf that's sold out says so too, and loses its quantity buttons. Loading: for the moment before the list arrives, each row keeps its full height, so nothing on the page jumps when the data lands. Broken: the list doesn't arrive, so the page says so and gives the shop's phone number. And when one price is missing from the data, the row shows a confirm marker for the review to catch. Never a price someone guessed. Longest: the longest allergen line on the real list, at the narrowest width, three hundred and twenty pixels. It wraps to two lines. Every name and price stays on one line, and nothing scrolls sideways. Five versions of one list. Each is a decision, and if you don't make it, the agent will.

Write the states down beside the component, in words, before an agent builds it. Here they are for Fell and Tarn's walk list. The error state offers a phone number, because an apology on its own is a dead end.

You'll recognize generated components quickly: every card exactly three lines long, icons that illustrate nothing, ratings nobody supplied. If a component only looks right with invented text, it was built for the invented text.

Then check it with the client's real content, and break it on purpose. Blank each slot that could arrive empty. Slow the connection, then cut it off. Paste in the longest real value at your narrowest width. Expect one of these to catch something you missed.

Components come from slots. Variants come from real differences in the content. And nothing's finished until you've seen it empty, loading, broken and at its longest.

An agent changed the bakery's site and says it's done. You can't read the code it wrote, and you shouldn't have to. You can check its work with things that don't take its word for it: tests that hold your decisions, an accessibility scan, and screenshots you've approved.

Before the agent starts, write down the decisions the site must keep, in plain sentences. Home has one button, and it says Order ahead. Pickup only: no page offers delivery. Every page says the bakery is fictional. Then ask the agent to turn each sentence into a test, with the sentence as its name. You don't need to read the code inside. Check that each name says your decision, word for word.

Add an accessibility scan of one page of each type. It finds one thing already: the sold-out loaf, gray at three point six six to one, logged before with its reason. That stays listed as known, and anything new fails. Then screenshots of Home and the order page, at three seventy-five and twelve eighty. Run everything once. Nine checks pass. The four screenshots fail, because there's nothing to compare them with yet, so each one is saved. Open each one and look at it the way the owner would. If it's right, commit it. That's approving it: from now on, that picture is what the page should look like.

Now the change from the start: make the Order ahead button on Home stand out more. For this lesson, I wrote the agent's change so the checks have something to catch. The checks and their results are real. Run the same command. Eight of thirteen checks fail, and you didn't read a line of code to find that out.

The pinned test says the button no longer says Order ahead. That was a decision, so it's not the agent's to change. The scan says white text on the new green is four point two four to one, under the four point five that text this size needs. And it's on three pages, not one. The screenshots show what moved, in red. On Home, that's the button you asked about. On the order page, Place order changed too, because both buttons share one style. You didn't ask for that.

So send it back. Throw away its first try, and say exactly what has to stay: the label, the green, and the order page as it is. Run the checks again. Eleven pass. Only the two Home screenshots differ, and the order page hasn't moved. That difference is the change you asked for. Look at the new picture, and if it's right, approve it as the new screenshot and commit. The next change gets checked against this one.

These checks catch what you pinned, what a scanner can measure, and what moved. They can't tell whether new words are true, or whether the page still makes sense. So keep looking at the page yourself, and add each new decision as you make it.

Pin your decisions as tests, scan each kind of page, and approve the screenshots you've looked at. Then an agent's change is checked by something other than the agent.

On my speculative AllWeb redesign, the first thing a keyboard reaches is a link most visitors never see: Skip to content. It's built into the first page, because accessibility costs little to build in and a lot to add later. Here are the parts to build in, and a quick way to check each one as you go.

Start with landmarks. A header, the main navigation with a name, one main, and a footer with its own named navigation. A screen reader lists them, so someone can jump straight to the part they want. Controls get names in words, too: the menu button shows three bars, so it also carries the word Menu for screen readers. Then the headings. One H1, and an H2 for each section, in the order they appear on the page. Read alone, the outline should work like a table of contents. One H2 is hidden on screen: the quotes have no visible title, so a screen reader still gets one. Now put the mouse away and press the Tab key. The skip link appears first, then the logo, then the menu, each with a clear ring around it. Keep going until you've been round the whole page once. Press Enter on the skip link, and the next Tab lands on the ticket button inside the main content. That ring is one rule for everything you can focus: a two pixel cream outline with a dark edge around it. It shows on the light sections and the dark ones alike.

Motion gets the same care. When someone has asked their device for less motion, the stylesheet turns off every transition and hides the moving bands. The script reads the same setting too.

Write these into the builder brief, so every page the builder makes starts with them. Then check the first page before you build the next: tab through it, and read its heading outline. The test phase checks the whole site later, with a screen reader.

Build landmarks, headings, a skip link and focus into the first page, then check it.

The homepage got all your attention. The other five pages got an agent and a deadline. That's where sites drift.

Build one page first and get it approved. Usually that's the homepage, because it carries the most decisions: type, spacing, components, how sections open and close, how images sit. Until you and the client have signed it off, every other page copies decisions that might still change. Once it's approved, freeze it, so nobody improves it while the rest gets built. An unapproved homepage copied across six pages means every later change gets made six times, and some of them get missed.

The approved homepage is now your reference for how this site handles things. Copy its decisions, and leave its layout where it is. In the fictional bakery, the Today's bread page lists loaves with the same list the homepage already proved. The Order ahead page needs a form, which the homepage never used, so the form gets built as a new component from its slot and held to the homepage's colors, type and spacing. Give your coding agent the homepage file and the manuscript, the approved words, every time.

Here's what drift looks like. The agent tidies a sentence because it read awkwardly. It adds a heading, Our story, because about pages usually have one. It moves a section up because the layout looked better that way. It drops in a stock photo because the page looked bare. Each change is small and each one is plausible, which is why nobody catches them. The manuscript holds the approved words. If a sentence needs changing, that goes back to whoever approved it.

Then check every page against the manuscript. By eye it's tedious and you'll miss things, so have the agent do the comparison and report back without fixing anything. Ask for added, missing and changed text, with both versions quoted, and for any spacing value that isn't in the tokens. Then you decide what to do with each one, and read the report with care. A line the agent cut because it looked repeated may have been repeated on purpose.

The last check is rhythm across the whole site. You planned each page's rhythm in the wireframes: where it's dense, where it rests, where it peaks. Assembly is where every page quietly turns into the same page. A hero, three cards, a quote, a call to action.

So lay the built pages side by side, zoomed right out, and read their shapes. Each bakery page has a different job, so each should have a different shape. The homepage leads with the queue photo, Today's bread is a list of loaves, and Visit is the address and the hours. If two pages with different jobs come out with the same silhouette, one of them is wrong. Check this every couple of pages, before one pattern sets across the site. Show the client pages in small batches, too. Three pages get read properly. A whole site at once gets a thumbs up and no reading.

Sometimes the build shows that the manuscript has a problem. A heading is too long for any sensible layout, or two pages say the same thing. Don't fix it in the HTML. Mark it, send it to whoever owns the copy, and rebuild from the corrected manuscript. Otherwise the manuscript and the site disagree, and the next agent session puts the old words back.

Approve one page properly and build the rest from it. Then check every page against its approved words, before anyone else reads it.

Before anyone visits a page, they meet it somewhere else: as a search result, or as a link pasted into a chat. Both are built from a few lines at the top of the page. These are those lines on my speculative AllWeb redesign, and each one has a job.

The title is written for the person searching. It says what the event is, where and when: AllWeb 2026, in the capital of Albania, on 6 November, a marketing, business and innovation conference. The description helps them decide whether to click: who it's for, the day, the city, and what they'll find there. The share card is a picture of the page itself. A script opens the page, crops the hero to twelve hundred by six hundred and thirty pixels, and saves it. Run it again whenever the hero changes. On a review build, every one of these tags points at the review address. A card that points at the client's own domain would look as if they had published it.

Structured data describes the page to search engines and AI answers, in a fixed vocabulary. Here it gives the event's name, its dates, that it happens in person, and its city. Every one of those facts needs a row on the claims list. The name, the date and the city come from the brief's facts list, copied from AllWeb's own site. Describe only what's on the page. This page has no questions section, so it has no FAQ data. Then read it back. A checker, or a short script like this one, should parse it and repeat what the page says.

Record it for each page: the title, the description, the share card, and every structured fact with its row on the claims list.

Write titles for searchers, make cards from the page, and mark up only verified facts.

This is a speculative redesign I made for AllWeb, a conference in the capital of Albania. They didn't commission it. It runs here, on my own computer, at a local address, and nobody else can open that. To show it to anyone, it needs a place on the web, and the first place should always be a preview.

Start with what gets uploaded. The project folder holds more than the site. There's the written brief, the tools that made the images, and the original photos. An ignore file lists what stays home. The host reads it before it uploads anything. Settings files, which can hold private keys, are on it too. The lesson on secret keys explains why those never leave.

This folder is already linked to a project at my host, so one command deploys it. I leave off the production flag. The host uploads the files and prints two addresses: one to inspect the deployment, and the preview itself. Further down, the target is null and there's no production address. This deployment is a preview and nothing else. That's the difference that matters. Each preview gets a new address of its own. Production is the one address you give people, and it changes only when you promote a deployment to it. Checked a minute after the deploy, the production address still shows its last change from before the preview. The preview didn't touch it.

Now ask for the preview as someone who isn't signed in to my account. The host answers with a redirect to its sign-in page. On this project, previews are protected. That's a sensible default for unfinished work, and it also means a client can't open this link yet. The host adds a noindex header to the redirect, too. When a version is ready to show, use your host's own way of sharing that preview, or send the review address. For this redesign, the review address is the project's production address, kept out of search.

Then check what that address really serves. The header says noindex, and so does the page. The robots file allows crawling, so a search engine can read that noindex. The brief and the image tool answer not found, so only the site went up. Last, open it on a phone. At three hundred seventy-five pixels wide, the date, the city and the ticket button all sit on the first screen.

Write it down in the project notes: the preview's address, that it's a preview, who can open it, and what you checked. The next lesson keeps that address out of search for as long as it's a review.

Deploy a preview first, open it as a stranger, and check what it serves.

The client needs to see the site on their own phone, so it goes online, at a review address. The moment it has one, it's on the public web. Anyone with the link can open it, and so can a crawler that finds the link.

This happened. A demo of a photographer's site, built as a pitch, went up on a public address with nothing telling search engines to stay away. It started appearing in search above his own website. Nobody wanted that, least of all him. On a different project, a live client page went out with the words legal entity name still sitting in square brackets.

Most hosts give you two kinds of address. A preview is made for one version of the site, so you can check it and send it round. Production is the address the site launches on. Hosts treat them differently. Some add a noindex signal to previews and nothing to production, and that can include the free address the host gives a new project before it has a real domain. So find out which kind your review link is, and read your host's own page on what it adds. Don't assume. Whatever the host does, your review build carries its own noindex.

Noindex is the instruction that keeps a page out of the index. Google documents two ways to give it: a robots meta tag in the head of each page, or an X-Robots-Tag header on the response. Do both. The meta tag travels with the page if someone copies the build to another host. The header covers files that have no head, and Google's page names PDFs, images and video. Your host's settings can usually add the header for every file.

Three assumptions to drop. The host first: as you've seen, what it adds depends on the host and on the kind of address. Then robots.txt. Never block a review build there. Google is explicit: if robots.txt blocks a page, the crawler never sees the noindex on it, and the address can still show up if something links to it. Last, noindex is a request to search engines. Anyone with the link can still open the page. If it has to be private, use your host's access protection, a password or a login in front of the whole build.

Some sites need keys: long secret strings that let the site use a map, a form service or a database. A key written into the code that reaches the browser can be read by anyone with View Source, review build or not, and someone else's bill can land on your client. Secret keys live in your host's settings, as environment variables, where the server uses them and the page never shows them. A few services issue a public key that's meant to sit in the page, and their docs say so. Everything else stays out of the code.

Then check it, every time, in a browser, on the exact link you're about to send. Open the link. View the page source and search for robots: the meta tag should be there, saying noindex. Then check the header. Your browser's developer tools show it in the network panel, and one command in a terminal shows the same. X-Robots-Tag should say noindex. While the source is open, search it for key. If either noindex signal is missing, or a secret key turns up, the link doesn't go out.

Next, the link preview. When the client pastes your link into a chat, many apps read the page's Open Graph tags to build a card. If those tags point at the client's real domain, with their real logo as the image, the draft presents itself as their live site wherever the link travels. On a review build, leave the preview image off, or point it at an image hosted on the review build itself.

Then placeholders. Brackets survive when you only check the pages you expect to see. Search what actually ships for square brackets and for your CONFIRM marker. Include pages nothing links to yet, because they're still reachable by address. If a fact isn't confirmed, the sentence comes out. A missing line reads as unfinished. A bracket where the company's legal name should be reads as careless.

None of this stops the client seeing it. Send them the exact link. You're done when that link opens, you've seen both noindex signals on it, and no key is in its page source. Then put the removal on your launch checklist, because the same mistake runs the other way too: a noindex tag that ships with the real site keeps the client's new homepage out of search until somebody notices.

A review build is public as soon as it has an address. Know whether it's a preview or production, put noindex in the page and the header, keep every key out of the page, and check all of it in a browser on the exact link before it goes out.