Prepare

In October I redesigned the homepage of AllWeb, a one-day conference in Tirana. Nobody asked me to. That one fact shapes the whole project, so it's the first thing to decide and write down.

A commissioned site is one a client asked for. The client answers your questions, confirms facts in writing, and decides when it goes live. A speculative site is one you make before anyone asks, to show what you'd do. There's nobody to ask, and nobody has approved it.

Being speculative changes four things. First, every page says who made it. The footer here reads: concept redesign by me, not affiliated with or commissioned by AllWeb. Second, facts come only from what the business has published, each with the date you read it. My brief lists every fact I used, all from their own site, read on the fifth of October. An earlier draft said they were founded in 2012. Their site never says that, so it stayed off the page. Third, it stays out of search. The page carries a noindex tag, and the server sends the same rule in its header. Both are checked here on the live site. Fourth, it lives at a preview address on my own account, and the page names that address as its own. It never goes on their domain, because launching is their decision, and they haven't made it.

Now write it where every AI session will read it: the first lines of the project's instruction file. What kind of project it is, who the client is, where facts may come from, the line every page carries, and the rules for search and the address. If a client had asked, the same lines would name them. They'd say who confirms the facts. And they'd say the site goes on the client's domain when the client approves it. Building a speculative demo safely has its own lesson, on spec work.

First decide whether anyone asked for the site. If nobody did, say who made it, use only dated public facts, keep it out of search, and never put it on their domain.

Before you build anything, write down your tools and accounts: what each one is for, whose account it is, and who can get in. It takes ten minutes now. It saves a hunt for logins at the end.

Start with the jobs, not the products. Something to think with and argue with. Something that edits the files. A history of every change. A host that serves the site, a way to count visitors, a way to send form email, and a domain. Products change every few months. The jobs don't. Then write what does each job on this project, one line each: the job, the tool, whose account it is. On my AllWeb redesign, an AI chat did the thinking and the critique. A coding agent edited the files, and the host serves a preview.

Check each line against the project, not your memory. The host's project name comes from the project's own link file. The visit counter is loaded by the site's script. And the site sends no form email at all: eighteen lines in the page are marked demo only. So two jobs have no tool, and the file says so: no form email, and no domain. A blank you wrote down is a decision. A blank you forgot turns up at launch.

This site is speculative, so every account is mine. When a client commissions a site, the host, the domain, the analytics and the form email are opened in the client's name, and you're invited in. If they sit on your account, the client's site depends on yours. Write down who holds each login, and the handover at the end is a list, not a hunt.

One rule for this file: no passwords and no keys. Keys live in a local file that never goes into history, and the project's ignore list already keeps it out. The lesson on secrets shows the rest.

Name the jobs, then the tools. Put every production account in the client's name, write down who holds each login, and never put a password in the file.

The bakery's order form now uses a key, a password that lets the site's server talk to the form service. Anyone who has it can send as the bakery. Keys and private notes get out four ways: AI chats, the repository and its history, the files you upload, and the settings on the live site.

Here's the first way. Orders are failing, and you're about to paste the whole settings file into an AI chat. Stop. A chat keeps what you send on someone else's servers, and you can't take it back. Send the error and the setting's name instead. The AI doesn't need the value to help. The same goes for screenshots, logs and the owner's emails.

In the project, the key lives in one file, dot env, and the server reads it by name. The code is clean, but Git will save that file with everything else. Git status lists it, with the notes folder, waiting to be added. Add both to the gitignore file before your first commit, and check again: they're gone, and check-ignore names the line that hides each. Commit a dot env example with the names and no values, so the next person knows what to set.

Now the one that catches people. Try it with a test key: one commit put it straight into the page script, and the next took it out. The file looks clean. But Git keeps every version: search the history for the key, and both commits come back, with the key still in the old file. Once that history is pushed, assume someone has a copy. You can rewrite history, but you can't recall copies, so treat the key as leaked and replace it.

The gitignore file protects the repository, not the upload. Deploy the whole project folder, and the host serves everything in it: the owner's emails, and the key. So deploy from a list. A short build step copies only the files named in site files into one folder, and only that folder goes online. A file you add later stays private until you list it. Ask for the notes and the dot env file again: four-oh-four, both.

That's also why a form works on your computer and fails live. The dot env file never left your machine, so the live server starts without the key. Put it in the host's settings, where the server reads it when it starts, and the same order goes through. Build-time settings are different again. Some build steps write any setting marked public into the files they make, so it ships to every visitor. Fine for a site address, never for a key. Search the built folder for the key: after a clean build, nothing.

When a key has been in a chat, a commit or a public file, don't guess who saw it. Replace it. Make a new key at the service, put it in the host's settings, then turn the old one off. Here the service is a local stand-in. Then prove it. The old key is refused, the new one is accepted, and a test order goes through. Then write down which key, where it was exposed, when you replaced it, and how you checked. Checking the finished page for keys is in the review build and pre-send gate lessons.

A key is safe in one place: the settings of the server that uses it. Keep it out of chats, history and uploads, and replace any key that gets out.

Ask an AI what a client's homepage should lead with, and you'll have a fluent answer in seconds. Once you've seen it, it's hard to think past it.

So before I ask the AI anything that needs judgment, I write my own answer down. What the homepage is for. Which photo leads. A few lines, in a file, with a date on it. It can be wrong, and it usually needs adjusting. But it exists before the machine's version does, and that changes how I read the machine's version.

The order matters. First you, with your position written down. Then the evidence: what the client sent, what a search turns up. Then the AI. Then you again. Put the two answers side by side and decide. Where you agree, move on. Where you differ, one of you knows something the other doesn't, and your job is to find out which.

This is one for a fictional bakery. Regulars come for bread, not cakes, so the position is the morning queue photo. Then the evidence, and what I'm unsure about. Don't skip that line. It tells you where the AI might actually help. Below it, after the AI has answered, what it said and what I did. It wanted to lead with cakes because they carry a higher margin. Maybe they do. But nobody gave it any margins. It made up a reason that sounded commercial, so my answer stood, and the file says why.

Look at the two habits side by side. Ask first, and you're editing its draft. You argue with its headings and its order, and you rarely step outside them. Decide first, and you're comparing two drafts, one of them yours, and every disagreement turns into a question you can check. Make a save point with the position file before you open the chat, and your version history shows you decided first. When a client asks how much of the work the AI did, you can show them.

Sometimes the AI will be right and you'll be wrong. That's part of why you asked. Change your mind, and add a line to the position file saying what changed it. Sounding confident doesn't count as a reason. The other half of the habit is a log, one file, where every time the AI is wrong or sure about something it couldn't know, you write down what it said and how you caught it. After a few weeks you'll see patterns. Maybe it keeps inventing dates, or reaches for the same layout every time. Each pattern becomes a rule in the project file it reads at the start of every session.

An entry looks like this. The AI wrote family-run since 1998 into the bakery's homepage copy. Nothing the client sent mentions 1998. It sounded right, and that's how a line like this gets through. I caught it because I check every fact against a source, and this one had none. So it became a placeholder and a question for the client.

Write your answer down first. Then ask.

Here's my AllWeb project as it sat on my computer: the site, a component lab, the photos, two long documents, and three screenshots with machine-made names. It works while you're in the middle of it. Now ask where the next person would find the facts, or the decisions, and there's no clear answer.

Give each kind of file one place, and make the folders first: research, with every fact's source, a plan folder for what you decide to build, decisions, one short dated note each, and a log of what the AI got wrong. Then the files that sit at the top: the instruction file and the accounts list from the last two lessons, and the brief. Now copy the real files in, without rewriting anything or adding a fact. The audit and the three dated screenshots go into research. The manuscript goes into plan. The site goes in whole, except the secrets file and the host's link folder.

Now list it. Brief, research, plan, decisions, log and site, plus the instruction file and the accounts list. The decisions folder is empty, and that's honest: the first note goes in with the first call you make. And no secrets file came along. The same layout works as folders on your computer, as a shared document with these headings, or as a builder's project space. What matters is that someone else could open it and find the facts, the decisions and the site without asking you.

One place for each kind of file: the brief, research, plan, decisions, the AI log and the site. Copy the real files in, add nothing, and leave secrets out.

Before an AI changes anything in your project, save a version you can go back to. Then let it work, look at the result, and keep it or go back. Here's that habit on the AllWeb project folder from the last lesson.

The simplest save point works with any tool: a dated copy of the whole folder, named for what works. To go back, you open the copy. The build phase uses version control, so start it here. Keep secrets out from the very first save. Then make the folder a repository and save every file, with a message that says what works right now. Now a change. Here it stands in for an AI's edit: the hero headline swapped for an earlier line I'd considered, ideas worth leaving your screen for. Git status shows the one file that changed. Look at it in the preview before you decide. It works. But I chose the current line over this one in October, and seeing it again doesn't change my mind. So go back. Going back takes one command, and it undoes only what changed since the save. Git status is clean, and the reloaded page matches the saved version exactly.

Do that once on purpose, now, so you know it works before you need it. And name every save point for what works, not update. Three changes later, homepage works tells you where to go back to. The lesson on Git checkpoints shows the full routine when an agent saves its own work.

Save a version before every AI change, and name it for what works. Look at the result, keep it or go back, and go back once on purpose so you know you can.

Every new AI session starts with no memory of your project. What carries over is a short file it reads first. Here's the one for the AllWeb project, written from its brief.

Start from the brief, but don't paste it in. It's a hundred lines on type, color and photos. Take only what the AI needs every time, and point to the rest. So, the job in two lines, and where the full brief is. Then the fact source, and the rule for a missing fact: leave it out, or mark it to confirm and say so. Name the claim you've already refused, so it can't sneak back. Decisions already made, so nobody reverses them quietly: the headline, the two typefaces, one display size, the photo rules. Then the checks before it says done: look at the preview at three widths, and check the credit and the noindex are still there. Last, a never list, short and specific.

Now test it. Start a fresh session, say nothing first, and ask what the project is. It answers from the file: speculative, the fact source, the refused claim, the never list. If it gets something wrong, fix the file, not the chat. Each builder reads this from its own place. A terminal agent reads a file like this one in the project folder. A chat builder has a project instructions box. The words are the same. The lesson on project files covers two agents in detail.

Write the file every session reads first: the job, the fact source, decisions, checks and the never list. Keep it short, point to files, and test it on a fresh session.

The AI that built a page will tell you it's good. It wrote it, it remembers why, and it grades its own reasons. So split the work: one AI to research and argue, one to build, and one to critique cold.

On the AllWeb redesign I split it like this. An AI chat did the research, argued strategy with me, and came back later as the critic. A coding agent did the building. Write that into the instruction file, so each session knows its job, and what isn't its job. The researcher brings a source for every claim. The builder edits files and doesn't grade its own work. The critic is a fresh session with the brief and the result, nothing else.

The critic is the one people skip. Give it the brief and the live page, and nothing from the build: no chat history, no list of what the builder meant to do. If it has the builder's reasons, it agrees with them. Ask where the page fails the brief, line by line, and tell it to say when it can't check something. Save it in the project, beside the instructions. You'll use it in the Test phase, on the finished site.

Three AIs don't make a decision. When the critic and the builder disagree, you settle it, and you write your own answer before you ask either of them.

Give each AI one job: research, build or critique. The critic sees the brief and the result, never the builder's reasons, and you decide between them.

An agent that can edit your files and run commands will happily do both for twenty minutes in the wrong direction. Keep the decisions yours.

Start every session by checking whether your agent asks before it acts, or acts and tells you afterward. Most agents have a setting for this, and some don't ask by default. Know which one you're in before you hand it anything big.

When should you ask for a plan first? If you could describe the change in one sentence, just ask. Fix this typo. Rename this heading. But if it touches several pages, or you aren't sure how it should be done, or anything might be deleted or moved, ask for the plan first, and read it before anything changes.

Here's a plan for the bakery site, from the day the agent drafted the order page. Read it as a list of decisions, because that's what it is. Steps one, two and five are what I asked for. Step three replaces the contact form, and I never asked for that. Step four deletes the wholesale page, because the agent thinks nobody uses it. Those two lines are decisions dressed up as tasks, and they aren't the agent's to make. So send the plan back, and say exactly what to leave alone. The revised plan has three steps, and every one of them is yours.

When it asks permission to run something, read the request the same way. What's the command? Which path does it touch? Is that path inside this project? Did I ask for this? This one deletes a folder outside the project, and nothing you asked for needs that. Say no, and ask for a plan instead.

If you can see it heading the wrong way, stop it, mid-turn, and redirect it. But stopping isn't undoing. The three files it changed before you stopped it are still changed. Undoing is what your save point is for, and that's the next lesson.

The last decision is when to throw the session away. Every session carries everything said in it, including the wrong turns. Start fresh when you move to an unrelated task. Start fresh when you've corrected it twice on the same thing and it's still wrong, because by then the conversation is full of failed attempts. And once a plan is agreed and saved to a file, a fresh session can build from the file with nothing else in its way.

Know which mode you're in, and read the plan before you approve it.

The most dangerous sentence on a draft site is the one that sounds right. Over two thousand happy customers. Where did that come from?

Start by knowing what counts as a fact on a website. Numbers. Reviews and testimonials. Prices. Credentials, awards and certifications. Founding dates, names, addresses, opening hours. If a reader would trust the business or act because of it, it's a fact, and it has to come from somewhere you can point to: the client, or something the client sent you. The AI writes these easily, because sites like this usually have them. That's why they turn up in drafts nobody asked for.

When you don't have the fact, you have two options and only one of them is honest. A guess reads well, and nobody notices it's wrong until a customer does. A placeholder is ugly on purpose. Square brackets, the word confirm, and what you need. It looks unfinished because it is. Reviews are different. No placeholder makes a made-up quote acceptable, so leave the section out until real ones arrive.

Every placeholder takes the same route. You write it into the page. You add it to the client checklist, with the page it sits on. The client answers, and you note where the answer came from. Then you swap the placeholder for the real fact. The checklist is also the list of what's blocking launch, and you can send it to the client as it stands. Always use the same brackets and the same word, so one search finds every one of them.

Here's the checklist for a fictional bakery. Open items, closed items, and where each answer came from. Look at the head baker's training. Two sources gave different accounts. When sources disagree, don't pick the one that sounds better. Picking one is still a guess, just a guess with a link next to it. Leave it out and ask. When the evidence runs out, say less.

Your coding agent can help you find them, as long as it isn't the one deciding. Give it a prompt like this. List every fact on the homepage, and for each one give the line in claims dot md it came from, or write none. Then you go through every claim marked none. Each one gets a source from the client, becomes a placeholder, or comes out. Don't let it fix them on the same pass. You want the list first, so you can see what it was about to invent.

A placeholder only works if it never reaches a page people can visit. I've seen a live client site go out with unfilled brackets where the legal entity name should have been. In one way that's worse than a guess, because everyone can see it. So the last check before any send or launch is a search of the whole build. Zero results, or it doesn't go.

Here's that search, on the fictional bakery build. The first one looks for the confirm format and finds nothing. Good. The second looks for any lowercase words inside square brackets, because a placeholder someone typed their own way slips past the first search. It can also catch code that happens to use brackets, so read each hit. This one is real: the legal name on the About page. That page doesn't ship until it's filled.

If you can't trace it, it doesn't go on the page.

Everything you decide from here on, you'll judge in a preview: the site running on your own computer. So start one now, and give it a port of its own.

The AllWeb project has three previews, and each has its own port, written in the project's launch file: the site on 4637, a photo grading review on 4641, and a component lab on 5612. Start the site's preview with one command. It answers at localhost, on port 4637. Here's why the port is written down. Start a second preview on the same port, and this tool quietly takes a random one instead. With two projects open, your bookmark shows whichever one got there first.

Now open it and look at three widths. 1280, a laptop. 768, a tablet. 375, a phone. At each one, check that the headline, the date and the ticket button are on the first screen. Three widths are for looking, not testing. The Test phase sweeps every width in between. The lesson on browser tools shows the responsive view used here.

Run the site on your own computer, on a port of its own, and look at 1280, 768 and 375 every time you change something.