The network

A client asks and a server answers. A server is only a program on a computer somewhere, waiting to be asked. Your browser is a client. So is a phone app, or a script you run in a terminal.

Agents will happily put code on the wrong side of this line, and the result still runs. When you read what one built, the first question is which machine each piece runs on, because that decides who can see it and who can change it.

The program that turns an address into a page. It asks servers for files, draws what comes back, and runs the code that came with it. Chrome, Safari and Firefox are browsers.

An agent reading your code sees what should happen. The browser keeps a log of what did. When something looks broken, that log settles the argument, so ask for its contents instead of a theory about them.

The frontend is the code that runs in the user's browser. The backend is the code that runs on your server. Anyone can read the frontend and change what it sends. Nobody outside can read the backend.

Agents often put a rule where the button is, because that's where the feature is. A check in the frontend is only a courtesy to honest people, so anything that protects money or data has to be repeated on the backend.

The address of one thing on the web. https://shop.example.com:443/cart?coupon=SAVE#total has a scheme, a host, a port, a path, a query and a fragment. Each part is read by something different.

Naming the part gets you the right change. "Read the page number from the query string" and "put it in the path" are different pieces of work. Agents that build or compare URLs by gluing text together also produce a family of bugs that send people to the wrong place, and you can now spot them.

The internet's address book. It turns a name like shop.example.com into the numeric address of a computer. Answers get saved along the way, and each one says how long it may be kept, which is called its TTL.

Agents can edit a DNS record in seconds and then tell you it's done, while people keep arriving at the old server. The waiting is decided before the change, by the TTL already out there, so a move needs planning days ahead.

An IP address identifies a computer on a network, like 203.0.113.10. A port number picks out one program on that computer, because many can be listening at once. Together they say exactly where a message goes.

The errors an agent hits while running your app are often about this and nothing else. "Address already in use" means two programs want one port. "Connection refused" means nothing is listening there. Neither is a bug in the code you just changed.

A name that always means this same computer. A server on localhost:5173 answers you and nobody else, because for anyone else the same name means their own machine.

An agent saying "it's running on localhost" has only told you about its own machine. If it runs in a container (a sealed-off environment on your machine) or in the cloud (on someone else's computer), its localhost isn't yours and you won't see a thing. Working on localhost also says little about production, where there's real distance, real encryption and a different server.

A reliable conversation between two programs across a network. Before any data moves, the two sides exchange messages to open the connection, and that costs one full trip there and back.

Opening a connection is expensive, and you pay for it per connection, which agents rarely think about. Code that opens a new database connection for every request can look perfectly clean and still fall over when many people use it at once.

The agreed format browsers and servers use to talk. One side sends a request, the other sends back a response. It remembers nothing between requests, so each one has to carry everything the server needs to know.

Almost everything your agent builds on the web goes through it, including the agent's own calls to its model. Reading one raw exchange is the fastest way to find out which side is wrong, and it replaces a lot of guessing by either of you.

A request is a method (a verb such as GET), a path, some headers (labelled lines of extra information) and maybe a body (the content). A response is a status code (a number saying how it went), some headers and maybe a body. Every feature on the web is built from those two shapes.

Saying "it's broken" gives an agent nothing to hold. Splitting the bug in two does: if the request was wrong, the problem is in the frontend, and if the response was wrong, it's in the backend. That cuts the search in half before anyone reads a line of code.

A command that sends one HTTP request from the terminal and prints what comes back. It takes the browser out of the question, so it tells you whether the server itself works.

It gives an agent a cheap way to prove a claim, and it gives you output you can read. One trap: curl exits 0 even when the server answers with an error, because the transfer itself worked. Use it in a script without --fail and your check can never fail.

The verb at the start of a request. GET reads, POST creates or submits, PUT replaces, DELETE removes. The method also tells everything between you and the server whether it's safe to send the same request again.

Requests get repeated, by double taps, flaky networks and helpful retry code. An agent that uses GET for an action can have it fired by a link preview, and one that writes a plain POST checkout can charge someone twice. Neither shows up in a test where everything goes right.

A three-digit number at the top of every response. 2xx means it worked, 3xx means look elsewhere, 4xx means the request was wrong, and 5xx means the server failed. It works like an exit code for the web.

This is the word that sharpens your instructions most. Left alone, agents often catch an error and return 200 with an error message inside, which reads as success to every client, cache and graph. Asking for the exact code fixes all of them at once.

A labelled line of extra information on a request or response, such as Content-Type: application/json. Names ignore upper and lower case. Many travel with every request, and you never see them unless you look.

One header is often the whole fix, and it can save an agent writing a page of code: caching, content type, a redirect, a login challenge. Ask for it by name. Code running in the page can't set them all either, so some header bugs can't be fixed in the frontend at all.

A plain text format for data: named values in curly braces (called objects), lists in square brackets, text in double quotes, plus numbers, true, false and null, which means nothing. Most programs on the web send it. Nothing else is allowed, including comments.

Your agent reads and writes JSON all day, including when it asks to use its tools, and its output can be almost right. The strictness is useful: one stray comma fails loudly. Numbers are the quiet exception, because a big id can come back changed with no error.

The set of requests a program agrees to answer, and the answers it promises to give. It's a contract between two pieces of software, so that neither side has to read the other's code.

Two ways this goes wrong with agents. They invent endpoints (the separate addresses an API answers at) and fields that sound right but don't exist, so point them at real docs. And they rename a field on your server without knowing who else reads it, and nothing fails until a client shows nonsense.

A style of designing web APIs around things rather than actions: GET /orders/42, not POST /getOrder. The word comes from Roy Fielding's 2000 dissertation, and most APIs called REST follow only part of it.

It's a convention an agent already knows, so naming it gets you predictable addresses. Don't stop there, though. "Make it RESTful" leaves plenty open, so spell out the addresses and the status codes you want, and argue about the design before the code exists.

A program whose whole job is keeping data safe on disk and finding it again quickly. Your server sends it questions over a connection. When your server restarts, its memory is gone, and the database still has everything.

Agents building a quick demo often keep data in a variable, because it runs first time and every check passes. Then a deploy wipes it, or a second copy of the server gives different answers. The "Data and failure" chapter goes much deeper.

A small piece of text a server asks the browser to keep. The browser then attaches it to later requests to that site, by itself. It's how HTTP, which has no memory, comes to know you.

The security of a login rests on a few words after the value, and they're easy to leave out, because a cookie without them works fine in every test. Asking for them by name gets them. They also explain "works on localhost, not in production".

The server's memory of a signed-in user. At login it creates a record and gives the browser a long random id in a cookie. Each later request carries the id, so the server can look up who it belongs to.

An agent asked for "login" will produce something that lets the right person in, and you won't see the gaps by logging in. The questions to ask are whether logging out really ends it, and what happens to a stolen copy.

HTTPS is HTTP sent through TLS, an encrypted tunnel. TLS proves you reached the real site, hides what you send, and detects any change on the way. A padlock means the line is private, and says nothing about whether the site is honest.

A certificate is a site's proof of who it is. When a certificate error blocks an agent, the quick way past is to turn checking off, and it may just do that. The app then works and is open to anyone on the path. Treat a disabled check as a failed task, however many other checks pass.

One click travels through a DNS lookup, a connection, encryption, your server, your database and back. Each step takes time, and they add up. A latency budget says how long the whole trip may take, so you can see which step broke it.

Told to "make it faster", an agent will optimise what it can see, which is the code. The time may well be somewhere else: distance, a new connection for every request, or sixty database queries. Measure first and point it at the step that matters.

A saved copy of a response, kept by the browser or by something between you and the server, so the same request needn't travel again. The Cache-Control header sets the rules. It makes sites fast, and it's why people see old versions.

Agents add caching when asked to speed things up, and rarely work out how the new version will reach people, which is the harder half. "I deployed and nothing changed" is often this. So is a private page served to the wrong person.

A network of servers around the world that keep copies of your files close to users. Requests go to the nearest one, and only a miss has to travel on to your real server, which is called the origin.

It's the only real fix for distance, and it takes load off your server. It also means a mistake in your cache headers is now served to the world. Personal pages must never be shared, so have the agent prove it with the response headers.

A server that stands in front of your real server, takes requests from outside and passes them on. It can handle encryption, share load between copies and cut off slow replies, so "the server" is usually several programs.

When an agent looks for an error in your app's logs and finds nothing, it may be looking in the wrong program. A 502 or 504 often comes from the proxy, and your code may never have seen the request. Naming the layer sends it to the right place.

A connection that stays open, so either side can send at any moment. It starts as an ordinary HTTP request, and then both sides agree to switch. Plain HTTP can't do this, because there the server only ever answers.

Agents reach for this whenever they hear "real time", and it's a lot to run: connections to hold open, reconnection, and proxies that drop them. Asking again every ten seconds, or a one-way stream, is often all you need, so ask which one it chose and why.

A request another company's server sends to yours when something happens, such as a payment clearing. It's an API call the other way round: you give them a URL and wait. Anyone who finds that URL can send to it too.

An agent's first version usually trusts the request, handles it once and does all the work before replying. All three are wrong: anyone can send to that URL, real senders repeat themselves, and they give up if you are slow. A demo sends one honest event, so spell out what you need.

A large body of code that makes most of the structural decisions for you, such as how a URL finds its code and where files go. You fill in the gaps. Next.js, Rails, Django and Laravel are frameworks.

A framework is why an agent can build quickly, and also a place it goes wrong. Models learned conventions from older versions, so it may write the old way with full confidence. Make it check the installed version and read those docs.

The three languages a browser understands. HTML says what's on the page, CSS says how it looks, and JavaScript says what it does. Whatever tools an agent uses, these are what finally reach the browser.

Naming the layer narrows the change. "This is a CSS problem" stops an agent rewriting working logic to fix a margin. It also tells you what a screenshot can prove: it shows HTML and CSS, and says nothing about whether JavaScript is working.

Rendering means turning data into a page. Server rendering does it before sending, so the HTML arrives ready to read. Client rendering sends JavaScript that builds the page in the browser. Static rendering does it once, when the site is built.

Your agent will pick one or inherit one from the framework, and the choice decides what breaks: a blank screen, a page that looks ready and isn't, or data that's as old as the last build. Decide on purpose, page by page, and ask how to tell which you got.

A limit on how long to wait for something before giving up and reporting failure. Without one, a program waiting on a server that never replies can wait for ever, holding on to everything it was using.

Agents rarely add timeouts unless asked, because the code works without them, right up to the day a service you depend on goes slow. Then requests pile up waiting, and pages that never touch that service go down too. Asking is one sentence.