That's not a bug in your code. It's baked into what a WebSocket is: a single TCP connection carrying one strictly-ordered stream of bytes. TCP's core promise — deliver everything, in order, no gaps — is exactly what makes it stall. WebTransport is the newer browser API that steps around that promise, and once you see the shape of the problem, you can't unsee how often WebSocket was quietly the wrong tool.

What a WebSocket actually is

A WebSocket feels like magic when you first meet it: new WebSocket(url), an onmessage handler, a send(), and you've got a live two-way channel. That simplicity is real and it's why WebSockets have run the real-time web for a decade — chat, notifications, live dashboards, collaborative editors.

But under that friendly surface, a WebSocket is one TCP connection, and it inherits everything TCP believes about the world. TCP treats your data as a single ordered stream of bytes and refuses to hand byte number 500 to your application until bytes 1 through 499 have all arrived. That guarantee is wonderful for a file download, where a gap would corrupt the result. It is a straitjacket for real-time data.

This gives a WebSocket two hard limits that no amount of clever application code can fully escape:

• Head-of-line blocking. Because everything shares one ordered stream, one lost packet stalls everything queued behind it — even logically unrelated messages — until that packet is retransmitted.
• One flavor of delivery. A WebSocket gives you exactly one channel, and it's always reliable and ordered. You have no way to tell it "this particular message is fine to drop if it's late." Everything gets the full retransmit-until-delivered treatment, whether it deserves it or not.

Enter WebTransport, riding on QUIC

WebTransport is built on HTTP/3, which runs on QUIC, which runs on UDP instead of TCP. That swap is the whole story. UDP doesn't insist on one ordered byte-stream, so QUIC gets to reinvent delivery on its own terms — and it does two things a TCP-bound WebSocket simply can't.

First: multiple independent streams over one connection. With WebTransport you open as many streams as you like inside a single QUIC connection, and QUIC keeps ordering per stream rather than across the whole connection. A lost packet on stream A only holds up stream A. Stream B, carrying completely different data, keeps flowing as if nothing happened. The head-of-line blocking that was unavoidable on TCP is now scoped to just the one stream that actually lost a packet.

Second: unreliable datagrams. Alongside those reliable streams, WebTransport gives you datagrams — fire-and-forget messages with no retransmission. Send one, and if it's lost, it's gone. No re-send, no waiting, no stalling. That sounds like a downgrade until you realize how much real-time data is worthless the moment it's stale. A player's position from 80 milliseconds ago is garbage; you already have a newer one. Re-sending the old one is worse than useless — it costs latency to deliver data you'd immediately throw away. Datagrams let you say "don't bother," which is exactly the right call for that data.

Streams or datagrams: pick per data type

The mental model that makes WebTransport click is that you now choose the delivery guarantee per piece of data, instead of accepting one guarantee for the whole connection.

The split is refreshingly intuitive:

• Reliable, ordered streams for anything that must arrive: a file or asset transfer, chat messages, a game action that changes state, any command where a gap would break correctness. This is the WebSocket-style guarantee — you just get many independent copies of it.
• Unreliable datagrams for anything that's worthless once stale: player position updates, live audio/video frames, cursor movements, high-frequency sensor telemetry. Miss one? The next one is already on its way and it's fresher anyway.

Notice that a single game connection wants both at once — reliable streams for "player fired a weapon," datagrams for "player is standing here now." WebSocket forces all of it down the one reliable pipe. WebTransport lets each kind of data travel the way it should.

The head-of-line blocking picture

It's worth making the stall concrete, because it's the single clearest reason to reach for WebTransport.

On the WebSocket side, packets 1 through 5 share one pipe. Packet 2 drops. Packets 3, 4, and 5 may have already physically arrived — but TCP won't release them to your app, because releasing them would mean delivering data out of order. So they sit in a buffer, waiting for a retransmit of packet 2, and your "live" connection is briefly frozen.

On the QUIC side, stream A loses a packet and has to wait for its retransmit — but stream B is a genuinely separate ordered sequence, so its packets sail straight through to the application. The loss is contained. On a lossy mobile network, where packet loss is routine, this is the difference between a connection that hitches constantly and one that glides.

Sending data: the code

WebTransport's API is lower-level than WebSocket's, and that's the honest tradeoff for the extra power. Here's a bidirectional stream plus a datagram over one connection:

// Open the connection (needs an HTTP/3 server on the other end).
const transport = new WebTransport("https://example.com:4433/game");
await transport.ready;

// A reliable, ordered stream — for must-arrive data.
const stream = await transport.createBidirectionalStream();
const writer = stream.writable.getWriter();
await writer.write(new TextEncoder().encode("player fired weapon"));

// Read whatever the server sends back on that stream.
const reader = stream.readable.getReader();
const { value } = await reader.read();
console.log("server said:", new TextDecoder().decode(value));

// A datagram — fire-and-forget, no retransmit. Perfect for position.
const dgram = transport.datagrams.writable.getWriter();
await dgram.write(new TextEncoder().encode(JSON.stringify({ x: 12, y: 30 })));

Compared with ws.send("...") and ws.onmessage, that's clearly more machinery — promises, readers, writers, byte encoding, explicit stream creation. But every extra line is buying you something a WebSocket can't offer: which stream this rides on, and whether it's reliable at all.

The honest caveats

WebTransport is genuinely newer, and "newer" comes with a bill.

• It needs HTTP/3 on the server. WebTransport can't run over your existing TCP stack; the server has to speak HTTP/3 over QUIC. That's a real infrastructure requirement, not a library import.
• Browser and tooling support is still maturing. It's shipping and usable, but it isn't the decade-hardened, works-literally-everywhere baseline that WebSocket has become.
• The API is lower-level. As the code above shows, you're managing streams and byte buffers yourself. For a simple "push me a notification" use case, that's overkill, and a WebSocket is still the right, boring choice.
• You'll often keep WebSocket as a fallback. A common pattern is WebTransport where it's available and beneficial, with a WebSocket path for clients or networks that can't do HTTP/3.

So this isn't "rip out every WebSocket this sprint." WebTransport earns its complexity specifically when latency and loss matter: real-time multiplayer games, low-latency live media, cloud gaming, high-frequency telemetry, anything where a stall or a stale packet is a felt problem.

The one-line takeaway

Here's the whole thing compressed: WebSocket gave you one ordered pipe. WebTransport gives you a bundle of independent pipes, plus a lossy express lane for data that's better dropped than delivered late. A WebSocket had to be reliable-and-ordered about everything, because TCP left it no choice. WebTransport lets you match each piece of data to the delivery it actually wants — and stops one unlucky packet from freezing the rest.

That contradiction is the root cause of basically every authentication disaster you've read about. Database dumps full of password hashes. Phishing pages that look exactly like the real login. People reusing hunter2 across forty sites so one breach unlocks their whole life. None of these are bugs in a specific app. They're all downstream of the same design flaw: the secret is shared, so it lives in too many places, and any of those places can leak or be tricked into giving it up.

Passkeys are the fix, and the fix is almost aggressively simple: stop sending a secret. A passkey is a public/private key pair — the same asymmetric cryptography that's been securing HTTPS for decades — pointed at the problem of logging in. Your device generates the pair, keeps the private key locked away where even you can't easily extract it, and hands the server only the public key. The server files that public key next to your account and, from then on, never holds anything worth stealing.

The cast: FIDO2, WebAuthn, and where the key actually lives

Two names get thrown around and it's worth pinning them down once. WebAuthn is the browser API — navigator.credentials.create() and .get() — that web pages call to make and use passkeys. FIDO2 is the broader FIDO Alliance standard WebAuthn is part of, covering the protocol between the browser and the authenticator (the thing that actually holds the key). Together they define a system where the private key is generated and used inside hardware designed to never let it out.

That hardware is the important part. On your phone it's the secure enclave; on a laptop it's the TPM; on a hardware key like a YubiKey it's the key's own chip. The private key is created inside that chip and mathematically cannot be exported in the clear. When something needs signing, the data goes into the chip, a signature comes out, and the key itself never appears in your app's memory, your browser, or the network. That's the structural difference from a password manager, which stores a secret and then hands it back to you to transmit. A passkey's private key is never handed back to anyone.

Registration: the device makes a key, keeps half of it

Signing up with a passkey is a short conversation. The server (the "relying party," in spec-speak) sends the browser a challenge — a random blob — along with some info about itself, most importantly its relying party ID, which is basically its domain: paypal.com.

Your device then generates a brand-new key pair specifically for that site. The private key goes into the secure enclave and stays there, welded to that origin. The public key, plus a credential ID (a handle so the server knows which key to ask for later), goes back to the server. The server stores those two things against your account. That's it. There is no password to hash, no secret to guard, nothing in the database that helps an attacker who steals it.

Notice what the server database looks like now. If an attacker dumps it, they get a list of public keys. Public keys are, by design, safe to publish on a billboard — they can verify a signature but can't produce one. The breach that would have been catastrophic with password hashes is a shrug with passkeys, because there's nothing there to reuse.

Authentication: sign a random number, prove it's you

Logging back in is a challenge-response, and it's where the whole thing clicks. The server sends a fresh random challenge. Your browser asks the device to sign it — but the private key won't budge until you perform a user gesture: Face ID, a fingerprint, or a PIN. That gesture unlocks the key locally, on your hardware; the biometric never leaves your device and never touches the server.

The device signs the challenge with the private key and sends the signature back. The server takes the public key it stored during registration, verifies the signature, and — if the math checks out — logs you in. At no point did a secret cross the wire. What crossed the wire was a signature over a one-time random number, useless to anyone who intercepts it, because the next login uses a different challenge.

// Authentication, roughly, from the browser's side
const assertion = await navigator.credentials.get({
  publicKey: {
    challenge: serverRandomBytes,      // fresh every time
    rpId: "paypal.com",                // the origin the key is bound to
    allowCredentials: [{ id: credentialId, type: "public-key" }],
    userVerification: "required",      // forces the Face ID / PIN gesture
  },
});
// assertion.response.signature -> sent to the server, which verifies
// it against the stored public key. No secret is ever transmitted.

Two properties fall out of this for free. There's no shared secret in flight, so there's nothing to sniff. And because each challenge is random and single-use, a captured signature can't be replayed. Compare that to a password, which is the same string every single time — capture it once and you own it forever.

Why this actually kills phishing

This is the part worth tattooing on the inside of your eyelids, because it's the property passwords could never have.

Remember that the key was generated bound to a relying party ID — paypal.com. The browser enforces that binding. When a site asks for a passkey signature, the browser checks that the site's actual origin matches the rpId the key was created for. If you land on paypa1.com (that's a one, not an L) — a pixel-perfect phishing clone — and it tries to trigger your PayPal passkey, the browser looks at the origin, sees it doesn't match, and refuses to sign. Not "warns you." Refuses. There is no dialog for the user to click through, no signature produced, nothing for the fake site to steal.

Why is this impossible with passwords? A password is just a string; you decide which site to type it into, and humans are terrible at reading URLs under time pressure. The security depended on a tired person correctly parsing paypa1.com at 11pm. Passkeys move that check from your fallible eyeballs to the browser's origin comparison, which does not get tired and does not misread a 1 for an l. Phishing doesn't get harder. For passkey logins, it stops being a thing.

Platform passkeys vs. roaming keys

There are two flavors, and the difference is where the key lives and how it travels.

Platform passkeys are stored by your operating system and synced across your devices through a provider — iCloud Keychain for Apple, Google Password Manager for Android/Chrome, and others. Create a passkey on your phone and it's there on your laptop, encrypted end-to-end in transit. This is the mainstream experience, and it's the one that makes passkeys usable for normal humans: you're not tied to a single physical device.

Roaming authenticators are hardware keys like a YubiKey. The private key never leaves the physical fob; you carry it and tap or plug it in to authenticate. Nothing syncs anywhere. This is the high-assurance option — favored by people whose threat model includes "what if my cloud account itself is compromised" — at the cost of, well, having to carry a physical object and buy a backup.

The honest caveats

Passkeys are genuinely better, and I'm not going to pretend they're frictionless.

Account recovery is the hard problem. With passwords, "recovery" was a reset email — which, notice, was always a phishable backdoor that undercut your nice strong password anyway. Passkeys force the industry to build real recovery: a second passkey on another device, a hardware key in a drawer, or a provider-level recovery flow. Set up more than one credential from day one. A single passkey on a single device is a single point of failure.

Cross-ecosystem syncing is still awkward. Apple's sync doesn't natively flow into Google's, and vice versa. It's improving, and QR-code cross-device sign-in (use your phone to log in on someone else's laptop) papers over a lot, but if you live half in Apple's world and half in Google's, you'll feel the seams.

"What if I lose my device?" is the question everyone asks, and the honest answer is: if it was a synced platform passkey, it's already on your other devices and in your provider's encrypted backup — losing the phone doesn't lose the key. If it was a lone hardware key with no backup, you're locked out, the same way you'd be locked out of a safe whose only key you dropped in the ocean. The mitigation is the same either way: register more than one authenticator.

The through-line is this: passwords weren't a good idea that got poorly implemented. They were the wrong primitive from the start — a secret you're required to share, then somehow keep secret from everyone you shared it with. Passkeys don't patch that; they retire it. The server holds something public, your device holds something that never moves, and the only "secret" left in the system is a fingerprint that never travels anywhere. Once you've logged in with a glance at your phone and no password at all, the old way starts to look less like security and more like a thirty-year-long game of hoping nobody was listening.

That's the pitch of the built-in AI APIs. Chrome (and, increasingly, other browsers) ships a small language model — Google's Gemini Nano — down to the device, and exposes it through a set of JavaScript APIs. When your code calls one, the inference happens locally. The prompt never leaves the laptop. The response comes back without a single packet crossing the network.

Once you internalize that, a lot of features you'd previously have dismissed as "too expensive to run on every keystroke" or "can't, privacy" suddenly become a few lines of JavaScript. Let's look at why local inference changes the math, what the API family actually looks like, and — the part everyone skips — where it falls flat on its face.

Why "on the device" is the whole story

Every time you call a cloud LLM, the same chain of events plays out. Your user's text leaves their machine, travels to a server you don't own, gets run through a model, and the answer travels back. That chain buys you a genuinely powerful model. But it also buys you four bills you might not want to pay.

Run the model on the device and all four bills go to zero at once:

• Privacy. The data never leaves. For a "summarize this private note" or "clean up this half-written email" feature, that's not a nice-to-have — it's the difference between shippable and a compliance meeting.
• Cost. There's no per-token meter. You can run inference on every keystroke, on every item in a list, on background tabs, and your invoice doesn't move.
• Offline. A subway, a plane, a dead conference-center Wi-Fi — the model still works, because it's already there.
• Latency. No round trip. For small tasks the answer starts appearing almost immediately, because you skipped the slowest part: the network.

None of this is magic. It's just where the computation happens. Move it from a datacenter to the navigator and the entire cost structure of the feature flips.

The API family: one model, many doors

You don't talk to Gemini Nano directly. The browser wraps it in a family of APIs, and picking the right one is most of the skill.

At the bottom is the general Prompt API — free-form, you send text (and, increasingly, images or audio) and get text back. It's the "I'll do whatever you describe" door:

// Always check first — availability is not guaranteed.
const availability = await LanguageModel.availability();

if (availability !== "unavailable") {
  const session = await LanguageModel.create({
    initialPrompts: [
      { role: "system", content: "You are a terse, friendly assistant." },
    ],
  });

  const reply = await session.prompt("Give me three name ideas for a coffee app.");
  console.log(reply);
}

On top of that sit the task-specific APIs, each a purpose-built door for one common job:

• Summarizer — turn long text into a headline, a tl;dr, or bullet points.
• Translator — translate between languages, on-device.
• Language Detector — figure out what language a chunk of text is (the natural partner to Translator).
• Writer / Rewriter — draft new text from a prompt, or rework existing text to be shorter, longer, or more formal.

The Summarizer is a good example of how little code these take:

const summarizer = await Summarizer.create({
  type: "tl;dr",
  format: "plain-text",
  length: "short",
});

const summary = await summarizer.summarize(longArticleText);

Why bother with the narrow APIs when the Prompt API can technically do all of it? Because they're tuned for their job, their options are structured instead of buried in prompt phrasing, and they give the browser room to optimize a known task. Rule of thumb: reach for the specific API when one fits, and drop to the Prompt API only when nothing else does.

The honest part: it's small, and it's not always there

Now the caveats, because a post that only lists upsides is marketing, not engineering.

The model is small. Gemini Nano is measured in a couple of gigabytes, not the hundreds you'd need for a frontier model. It is nowhere near GPT-class on reasoning, nuance, world knowledge, or long, multi-step problems. Ask it to summarize a paragraph and it shines. Ask it to debug a subtle race condition across five files, reason through a legal argument, or write a novel chapter that holds together, and you'll feel the ceiling immediately. This is a small model doing small-model things well — not a pocket-sized genius.

There's a one-time download. The model isn't shipped with the browser binary; it's fetched on demand, and it's big enough that you cannot pretend the download is instant. The very first time a user hits your feature, the model may still be arriving. Which leads to the caveat that actually shows up in your code:

Availability is gated, experimental, and must be feature-detected. These APIs are new, partly behind origin trials or flags, and only present on capable hardware. So you never assume they exist. You check — and you specifically handle the "still downloading" state, because it's a real state a real user will land in:

const availability = await LanguageModel.availability();

switch (availability) {
  case "unavailable":
    // No model on this device — fall back to a cloud call or hide the feature.
    useCloudFallback();
    break;
  case "downloadable":
  case "downloading":
    // Model isn't ready yet. Show progress; don't block the UI on it.
    const session = await LanguageModel.create({
      monitor(m) {
        m.addEventListener("downloadprogress", (e) => {
          console.log(`Downloading model: ${Math.round(e.loaded * 100)}%`);
        });
      },
    });
    break;
  case "available":
    // Ready to go right now.
    break;
}

Feature-detect, handle "unavailable," handle "downloading." If you skip that, your feature works beautifully on your machine and throws on a stranger's. That's not a footnote; it's the difference between a demo and a product.

So when do you actually use it?

The framing that makes all of this click: on-device AI is not a replacement for cloud AI. It's a new tier. You don't pick one forever — you route each task to the tier that fits it.

Reach for on-device when the task is:

• Private or sensitive — the data shouldn't leave the machine.
• Offline-capable — it has to keep working with no connection.
• High-volume — you're running it constantly and a per-token bill would hurt.
• Simple and bounded — classify, tag, detect language, summarize a paragraph, tidy a sentence.

Reach for the cloud when you need what a small model can't give you: deep reasoning, a large context window, genuinely high-quality long-form output, or anything complex and novel. An agent that plans across many steps, an analysis that has to be right, a code-generation task — that's still cloud territory, and pretending otherwise just ships a worse feature.

The best designs use both. On-device handles the constant, cheap, private stuff — instant language detection, an offline "summarize this page" button, a rewrite-my-sentence helper that fires on every edit — while a cloud call is reserved for the moments the user explicitly asks for heavy lifting. You get the responsiveness and privacy of local inference for the 90% of tasks that are easy, and the raw capability of a big model for the 10% that aren't.

The browser as an AI runtime

Step back and the trend line is hard to miss. The browser used to be a client: it rendered your UI and forwarded requests to servers that did the real work. Then it got a GPU (WebGPU), real threads, a filesystem, and now a language model baked into the platform, callable from plain JavaScript.

That last one is a quiet turning point. Inference — the thing we've spent two years assuming lives in someone else's datacenter behind an API key — is becoming a local capability, as ordinary to reach for as localStorage or fetch. It won't be the tier you use for everything, and it shouldn't be. But for the enormous class of small, private, high-frequency tasks, the model is now sitting right there on the device, free and offline and instant.

The browser is quietly becoming an AI runtime, not just a client. Worth building for.

This isn't a bug in your code. It's a thirty-year-old gap in HTTP itself, and you've been papering over it your whole career without noticing. The method that should carry a search — GET — isn't allowed to have a request body. And the method that's allowed to have a body — POST — carries all the wrong semantics. So we pick POST, shrug, and give up caching and idempotency as the price of being able to send a real query.

QUERY is the proposed HTTP method that closes the gap. It's the one you'd have designed if you were building HTTP today: safe and idempotent like GET, but with a request body like POST. It is currently an IETF Internet-Draft adopted by the HTTP working group — not yet a finished RFC, but far enough along that it's worth understanding now, because it renames a problem you already have.

Why GET can't do the job

The instinct is: "just put the query in the URL." And for simple cases, GET /search?q=cats&sort=new is perfect. That's exactly what GET is for. The trouble starts the moment your query stops being a couple of key-value pairs.

Real search is structured. A faceted product search, a GraphQL-style selection, an Elasticsearch bool query with nested filters, a geospatial polygon — these are JSON objects with arrays and nesting, sometimes kilobytes of them. You have three bad options for cramming that into a URL:

• Query string. URL-encode a whole JSON blob into ?filter=%7B%22.... It works until it hits the wall — and there is a wall. Browsers, proxies, and servers all cap URL length somewhere around 2,000–8,000 characters, and none of them agree on where. Cross that invisible line and you get a 414 URI Too Long, sometimes only from one proxy in the chain, sometimes only in production.
• The URL leaks. Everything in the URL gets logged. Access logs, proxy logs, browser history, the Referer header sent to the next site, analytics. Put a customer's search terms — or worse, an auth token someone stuffed in a query param — in the URL and you've quietly written it to a dozen places you don't control.
• Encoding pain. Deeply nested state doesn't map cleanly to flat key=value pairs. You end up inventing a bracket convention (filter[price][gte]=10) that every client and server has to agree on and parse by hand.

The obvious fix — "let GET have a body" — is a dead end, and not for a good reason, just an old one. RFC 9110 technically permits a body on a GET, but immediately warns that doing so has no defined meaning and will break things: caches, proxies, and libraries throughout the ecosystem were built assuming GET bodies don't exist, and many silently drop them. So a GET body is a trap. Which is how everyone ends up at POST.

What POST actually costs you

POST works. The body goes through. That's the whole appeal, and it's also where the honesty ends.

The word "safe" in HTTP is a technical term with teeth. A safe method is one the spec promises has no side effects the client is responsible for — a read, essentially. GET, HEAD, and OPTIONS are safe. A crawler will happily fire safe requests all day because it knows it isn't changing anything. Idempotent means making the same request twice has the same effect as making it once — so a client, proxy, or load balancer can safely retry it after a timeout without fear of doing the thing twice.

POST is neither. It's the method that specifically means "this might change something, and repeating it might change something again." So the entire infrastructure that speaks HTTP treats your POST /search accordingly:

• Caches refuse it. A POST response is essentially uncacheable by default. Your identical search from a thousand users can't be served from a shared cache, because the cache has no way to know the request was harmless.
• Retries are dangerous. A proxy or client library will retry a timed-out GET automatically. It won't retry a POST, because it can't tell your safe search from an unsafe "charge the card." So a blip becomes a user-facing error instead of a transparent retry.
• The semantics lie. Anyone reading your access logs, your API, or your traces sees POST /search and has to know, out of band, that it's actually a read. The protocol is no longer telling the truth about your system.

You didn't choose any of that. You chose it by elimination, because POST was the only method left standing that could carry the body.

What QUERY changes

QUERY is deliberately boring, and that's the point. Take everything good about GET and add the one thing it lacks.

A QUERY request is safe and idempotent — the spec says so, the same way it says GET is. So every retry policy, every crawler, every cache that special-cases safe methods can treat QUERY exactly like a read, because it is one. And a QUERY request carries a body, with a Content-Type that describes it. Your query is application/json, or a GraphQL document, or an SQL-ish DSL — whatever you want — sent as content, not smuggled into a URL.

QUERY /products HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "filter": {
    "category": "keyboards",
    "price": { "gte": 40, "lte": 150 },
    "tags": { "any": ["mechanical", "wireless"] }
  },
  "sort": [{ "field": "price", "order": "asc" }],
  "limit": 50
}

No length ceiling. Nothing sensitive in the URL, so nothing sensitive in your access logs or browser history. No bracket-encoding convention to invent. And the method itself announces, to every piece of software on the path, that this is a safe, repeatable read.

The clever part: caching a request that has a body

Here's the piece that makes QUERY more than "POST with better manners," and it's the detail worth remembering.

A normal cache keys on the method and the URL. That's why GET is cacheable and POST isn't — a GET's full input lives in the URL, so the URL is a complete cache key. But a QUERY's input is in the body. Two QUERY requests to the same /products URL can ask completely different questions. So a cache that ignored the body would be catastrophically wrong: it'd serve one user's search results to another user's totally different search.

QUERY's answer is that the request body becomes part of the cache key. A cache stores the response against the combination of method, URI, and the query content. Fire the identical QUERY again — same URL, same body — and a shared cache can return the stored result without ever touching your database. Change one filter and it's a different key, so you get a fresh result. You get GET-style caching for requests whose input was far too big and complex to ever fit in a GET.

The draft also lets the server point at the results with a Content-Location response header — effectively saying "the answer to that query also lives at this stable URL" — so a follow-up plain GET can fetch the same result the normal, fully-cacheable way. It's the bridge back to classic HTTP caching for the results themselves.

Will it replace POST? No — and that's the right question

QUERY replaces exactly one thing: the POST you use when you aren't posting. Search, filtered list endpoints, complex reporting reads, GraphQL-over-HTTP queries, any "give me data based on this complicated criteria" call. Everywhere your POST is a read wearing a write's coat, QUERY is the honest version.

It does not touch the POST that actually creates and mutates. Placing an order, sending a message, uploading a file — those have side effects, they're not idempotent, and POST is exactly right for them. Nothing about QUERY changes that. The line is simple: is this request a read? If yes, QUERY is what you were reaching for. If it changes state, it stays POST.

The honest caveat: it's a draft. Client libraries, server frameworks, proxies, and CDNs are only starting to grow first-class support, and until the whole path understands the method, an intermediary that doesn't recognize QUERY may reject or mishandle it. So this isn't "rewrite your search endpoints this sprint." It's "understand the shape of the fix, watch the draft, and know exactly which of your POSTs are lying." Because once you see it, you can't unsee it: half the POSTs in your codebase were always secretly a GET that just needed somewhere to put its body.

Neither is a bug. Both are features you opted into. The mistake is leaving them standing open to the internet because they were open on your laptop and nothing ever yelled at you to close them.

Let's look at what's actually behind each door, then lock them properly — not with one flag, but in layers.

What you're actually exposing

Swagger / OpenAPI. springdoc serves /swagger-ui/index.html for humans and /v3/api-docs as raw JSON for machines. That JSON is the whole thing: every route, every method, every parameter, every request and response schema. For a legitimate consumer it's documentation. For an attacker it's reconnaissance they didn't have to do — your undocumented internal endpoints, your admin routes, your "we'll secure that later" controller, all neatly listed.

Actuator. This one's worse, because some of its endpoints don't just describe the app, they operate it. A quick tour of the sharp ones:

• /actuator/env and /configprops — your configuration, including a lot of things that were never meant to leave the server.
• /actuator/beans and /mappings — your whole bean graph and URL map, i.e. the internal architecture.
• /actuator/heapdump — downloads a full heap dump. Whatever secrets were sitting in memory are now a file on the attacker's disk.
• /actuator/loggers — lets you change log levels at runtime via POST. Crank a package to DEBUG and watch the secrets scroll.
• /actuator/shutdown — exactly what it says. Disabled by default, but people enable it and forget.

Good news first: by default Boot only exposes health over HTTP, and env sanitizes obvious keys. The danger is the line that's in half the tutorials on the internet:

management:
  endpoints:
    web:
      exposure:
        include: "*"   # <- exposes every actuator endpoint. great in a demo, a gift in prod.

Ship that, leave it unauthenticated, and every endpoint above is one curl away.

Lock it in layers, not with one switch

The instinct is to find the single "secure it" setting. There isn't one, and that's fine — defense in depth means each layer assumes the one above it failed.

Layer 1 — expose less

The cheapest fix is the one you skip: don't publish what you don't need. Pin the actuator exposure list to the endpoints you actually use, and never * in production.

management:
  endpoints:
    web:
      exposure:
        include: health,info     # not "*"
  endpoint:
    health:
      show-details: when-authorized   # full health only after login; anonymous sees just UP/DOWN

And Swagger genuinely does not need to exist in production for most apps. Turn it off per profile:

# application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

If you do keep it in prod — internal tools, a partner API — then it has to get the same auth as everything else below. An endpoint that doesn't exist can't be attacked; that's always the strongest version of "secured."

Layers 2 and 3 — authenticate, then authorize

Add spring-boot-starter-security, and the framework gives you a login out of the box. But "logged in" is not the bar for these endpoints — admin is. The distinction matters: a regular user account that gets phished shouldn't come with a heap dump button.

Spring Security's EndpointRequest matchers know about actuator, so you don't hand-write the paths:

@Bean
SecurityFilterChain security(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            // health + info stay open for load balancers and uptime checks
            .requestMatchers(EndpointRequest.to(HealthEndpoint.class, InfoEndpoint.class)).permitAll()
            // every OTHER actuator endpoint: admins only
            .requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("ADMIN")
            // Swagger UI + the raw OpenAPI doc: admins only
            .requestMatchers("/swagger-ui/**", "/swagger-ui.html", "/v3/api-docs/**").hasRole("ADMIN")
            // your real application rules
            .anyRequest().authenticated()
        )
        .httpBasic(Customizer.withDefaults())   // or formLogin for a browser UI
        // actuator POSTs (e.g. /loggers) are not browser forms — exempt them from CSRF
        .csrf(csrf -> csrf.ignoringRequestMatchers(EndpointRequest.toAnyEndpoint()));
    return http.build();
}

One thing the diagram is quietly insisting on: order matters. Spring Security takes the first matcher that matches, so the narrow health rule has to come before the broad toAnyEndpoint() — flip them and toAnyEndpoint() swallows health and your load balancer starts getting 401s. Most-specific first, every time.

And the credentials behind ROLE_ADMIN have to be real. Not the random password Boot prints to the console on startup, not user / password in a properties file. A proper user — from your database or directory — with a BCrypt-hashed secret:

@Bean
PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

Layer 4 — isolate the port

The last layer is network, not code. Move actuator off your public application port entirely:

management:
  server:
    port: 9001          # actuator lives here...
    address: 127.0.0.1  # ...and only answers on loopback / your internal net

Now even a misconfigured rule upstream doesn't help an outside attacker, because the port they can reach doesn't serve actuator at all. Your monitoring, which lives on the same box or inside the same network, still gets in. This pairs naturally with a firewall or security group that simply never routes 9001 to the outside world.

The short version

Swagger and Actuator aren't dangerous because they're insecure. They're dangerous because they're useful, which is exactly why you turned them on and then stopped seeing them. Treat them like any other privileged surface:

• Expose less — pin the actuator list, and turn Swagger off in prod unless you have a reason not to.
• Authenticate — put Spring Security in front of both.
• Authorize — hasRole("ADMIN"), not merely "logged in," with real BCrypt-backed credentials.
• Isolate — separate management port, bound to the internal network.

No single one of these is the answer. Stacked, they mean that the day one layer is misconfigured — and someday one will be — the other three are still standing between a stranger and a copy of your app's memory.

There are two halves to this, and most people only ever think about one. Response headers are orders you give the browser. Request headers are claims the client makes about itself — and the client can lie about every single one. Get that trust direction backwards and you end up building an auth check on top of a field anyone can forge with a one-line curl.

Here's the whole picture, then the specifics.

Two kinds of header, two levels of trust

A request header is set by whoever made the request. Your frontend, a browser, curl, a scraper, an attacker with a terminal — all equal, all anonymous. User-Agent, Host, Origin, X-Forwarded-For: every one of them is free text the sender chose to type. Treat them as evidence to verify, never as proof of anything.

A response header is set by you, the server. The interesting ones are instructions the browser is more or less contractually obliged to follow: only ever talk to me over HTTPS, refuse to run inline script, don't let this page be put in a frame. You write one line; the browser enforces it for every user who visits.

So the rule has two sides and they're mirror images. Outbound: send the headers that switch on the browser's built-in defenses. Inbound: assume every header is hostile until you've checked the thing it claims.

The defensive set

These are the response headers worth attaching to basically everything. None of them cost you anything at runtime, and you set them in one place, not per route.

Strict-Transport-Security. HSTS. max-age=63072000; includeSubDomains; preload. It tells the browser "for the next two years, only ever reach me over HTTPS" — so the downgrade trick, where someone on the network quietly answers your first plain-HTTP request before the redirect kicks in, stops working. It's only honored over HTTPS in the first place. The preload flag opts you into a list baked straight into browsers, but it's sticky and a pain to back out of, so don't add it until you mean it.

Content-Security-Policy. The big one, and the fiddly one. CSP tells the browser which sources of script, style, images and so on it's allowed to load and run — so even if an attacker manages to inject a <script> into your page, the browser simply refuses to execute it. default-src 'self' is the strict starting point. Roll it out with Content-Security-Policy-Report-Only first, so you get reports of what it would block without actually breaking your own app. This is the header that neuters most XSS, which is why it's worth the tuning it asks for.

X-Content-Type-Options: nosniff. One value, no options. It stops the browser second-guessing your Content-Type and "helpfully" deciding that the thing you served as plain text is actually executable script. Cheap to set, closes a whole class of MIME-confusion bugs.

X-Frame-Options / frame-ancestors. Clickjacking defense — it stops other sites loading your page inside an invisible iframe and tricking your logged-in users into clicking things they can't see. X-Frame-Options: DENY is the old header; CSP's frame-ancestors 'none' is the modern replacement. Set both for now — old browsers only understand the first.

Referrer-Policy. Controls how much of your URL leaks in the Referer header when a user clicks a link out to another site. strict-origin-when-cross-origin is a sane default; reach for no-referrer if your URLs carry anything sensitive (tokens in query strings — which you shouldn't have, but here we all are).

Permissions-Policy. Switches off browser features you don't use. geolocation=(), camera=(), microphone=() says "nothing on this origin may even ask for these" — so an injected script can't quietly try, either.

And one in reverse: stop advertising your stack. Drop Server and X-Powered-By. They won't get you owned on their own, but they hand any passing scanner your framework and version for free, which is the first step of every "find a known CVE for this exact version" script. In Express it's one line: app.disable("x-powered-by").

You don't hand-set all of this on every route. Put it in one place — middleware, or better, the reverse proxy / CDN at the edge — so it's on by default and can't be forgotten. In Express, Helmet does most of the set for you:

import helmet from "helmet";
app.use(helmet());        // HSTS, nosniff, frame, referrer, a baseline CSP, and more
app.disable("x-powered-by");

Then check your work from the outside. Point securityheaders.com or Mozilla Observatory at a live URL and it'll grade the lot in seconds and tell you what's missing.

The headers you must never trust

Now the inbound side, where the bugs are quieter and a lot meaner. Every item here is a request header someone can set to whatever they like.

X-Forwarded-For. The classic. Behind a proxy, the client's real IP gets put here, so people reach for it to rate-limit, geo-block, or allowlist. The problem: the client can simply send their own X-Forwarded-For, and now your "trusted IP" is whatever string they pasted in. The only value you can trust is the one your own proxy appended — which means telling your framework exactly how many proxies sit in front of you and reading only that hop.

// You run exactly one proxy you control (your load balancer).
// Trust that one hop — no more, no less.
app.set("trust proxy", 1);
// Now req.ip is the value your proxy vouched for, not whatever the client claimed.

Trust the whole header blindly and your IP allowlist becomes a polite suggestion.

Host. A real browser sets it honestly; an attacker is under no such obligation. If you build absolute URLs out of the Host header — password-reset links are the textbook case — someone can send a forged Host, and the reset email you generate now points your victim at the attacker's server. Validate Host against an allowlist of domains you actually serve, and never splice it straight into a link.

Origin and Referer. Useful signals, not authentication. They tell you where a browser thinks a request came from, which is handy as one input to a CSRF check — but they can be absent, and outside a browser they're whatever the sender wants. Use them as a hint, never as the lock.

Content-Type. A claim about the body, not a guarantee about it. Don't let it decide how far you trust the payload, and don't lean on it as CSRF protection — "we only accept application/json" falls over the second someone sends text/plain with a JSON body in it.

The thread through all of these: a request header is the sender describing themselves. Verify the thing it claims — the token's signature, the IP your proxy vouched for, the domain on your allowlist — and never trust the claim on its own.

The two CORS lines that quietly open the door

CORS gets its own section, because it's the one people most often "fix" straight into a hole. The setup: a browser won't let evil.com's JavaScript read a response from your-api.com unless your API explicitly says it's allowed, via Access-Control-Allow-Origin.

Here's the bug nearly everyone ships at least once:

Access-Control-Allow-Origin: <reflects whatever Origin the request sent>
Access-Control-Allow-Credentials: true

Reflecting the request's Origin straight back means every site is allowed. Add Allow-Credentials: true on top and you've also told the browser to send cookies — so any malicious page your logged-in user happens to visit can now make authenticated calls to your API and read the answers. You didn't open a door; you took down the wall.

The fix is an explicit allowlist, and only ever echoing an origin that's on it:

const ALLOWED = new Set(["https://app.example.com"]);

app.use((req, res, next) => {
  const origin = req.headers.origin;
  if (ALLOWED.has(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Access-Control-Allow-Credentials", "true");
    res.setHeader("Vary", "Origin"); // so a cache can't serve one origin's header to another
  }
  next();
});

And the thing CORS is not: it is not server-side access control. All it governs is whether a browser hands the response back to the page's script. The request still arrived, your handler still ran, your database was still queried — curl ignores CORS entirely. So CORS protects your users' browsers from leaking data cross-origin; it does nothing to stop a direct attacker hitting your endpoint. Your real authorization has to live in the handler, every time.

"But mine's a pure JSON API"

Fair, and worth being honest about. A couple of these — CSP, X-Frame-Options — really only bite when a browser renders your response as a page. If your API exclusively returns JSON to server-side clients that no browser ever touches, those two are belt-and-suspenders.

But HSTS still matters the moment anyone reaches you over HTTP. nosniff still matters. CORS absolutely still matters as soon as any browser talks to you. And every request-header trap above applies no matter who's calling, browser or not. So the inbound rules aren't optional just because you skipped the HTML — those are the ones that quietly cost you the most.

Ship it

Put the response set in one place — middleware or the edge — so it's on by default and can't be dropped per route. Send HSTS, nosniff, a real CSP (report-only first), frame protection, Referrer-Policy and Permissions-Policy, and strip the stack-advertising headers. On the way in: pick a trusted-proxy count and read only that hop, validate Host, treat Origin and Content-Type as hints, and verify tokens instead of just decoding them. Then run the live URL through a header scanner and fix whatever it grades you down for.

The whole thing is maybe twenty lines and one afternoon. It's the cheapest security you'll ever ship — which is precisely why it's the most often skipped.

So here's the tour: what Fable 5 actually is, the facts that'll trip you up the first time, what genuinely got better, and the part nobody puts in the launch post: when you should not reach for it.

What it even is

Fable 5 is Anthropic's most capable widely released model, and it's built for the hard end of the work. Overnight agent runs. First-shot builds of a system you've specified well. The kind of debugging that used to need a human babysitting the loop. It carries a 1M token context window (that's the default, not just a ceiling you can opt into) and can write up to 128K tokens back.

The part most people get wrong on day one: it's not a drop-in upgrade for everything. If your whole ask is "give me the latest and greatest," the sensible move is Opus 4.8. Fable 5 is the model you reach for on purpose, for the jobs that were genuinely out of reach before. Think of it as the specialist you call in, not the one who sits at the front desk.

The facts that'll trip you up first

This is the fun part, because every one of these has quietly broken someone's afternoon.

Thinking is always on. On older models you flipped thinking on, set a token budget, or switched it off. On Fable 5 you do none of that. The reasoning is always running, and trying to disable it is a flat 400. The old budget_tokens knob is gone too. What you get instead is one dial: effort.

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

// Thinking is always on. You don't request it, and you can't turn it off.
// Steer how deep it goes with effort, not a token budget.
const res = await client.messages.create({
  model: "claude-fable-5",
  max_tokens: 16000,
  output_config: { effort: "high" }, // low | medium | high | xhigh | max
  messages: [{ role: "user", content: "..." }],
});
// Sending thinking: { type: "disabled" } here? That's a 400.

You never see the raw reasoning. Fable 5 thinks in full behind the scenes and hands you a summary, or nothing at all. The unfiltered chain of thought is sealed and never returned. Ask for the summarized view if you want the gist; otherwise the thinking field comes back empty while the model still thought (and still billed) for the work. One sharp edge: if you're continuing a conversation on the same model, pass those thinking blocks back exactly as you got them. Edit them and the API rejects the turn. Hand them to a different model and they're quietly dropped, no charge, no error.

The token math you memorized is wrong now. Fable 5 ships a new tokenizer. The paragraph that was 1,000 tokens on Opus lands closer to 1,300 here. Nothing you wrote changed; the ruler did. So every max_tokens you hand-tuned, every cost estimate sitting in a spreadsheet, every "this fits in the window" assumption needs a fresh measurement. Run count_tokens with model: "claude-fable-5" and it'll hand you the count under both tokenizers, so you can see the gap before it shows up on the invoice.

A refusal is a 200, not a crash. This one gets everybody once. Fable 5 runs safety classifiers on the way in, mostly around biology and cybersecurity, and benign-adjacent work can trip them too. When one declines, you don't get an exception. You get a cheerful HTTP 200 with stop_reason set to "refusal" and, often, an empty content array. Code that grabs content[0] without looking will throw on thin air.

const res = await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 16000,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }], // refusals retry here, same request
  messages: [{ role: "user", content: "..." }],
});

// Check stop_reason BEFORE you read content.
if (res.stop_reason === "refusal") {
  // a classifier declined; content is empty (pre-output) or partial (mid-stream)
}

The nice part: wire up that fallback and a refusal quietly retries on Opus 4.8 in the same round trip, and you only pay for the answer that actually comes back.

It wants your data for 30 days. Fable 5 isn't available under zero data retention. If your org is set to ZDR, every request 400s no matter how clean the payload is. Worth knowing before you burn an afternoon debugging a request that was fine all along.

A single call can run for minutes. On a genuinely hard task at high effort, one request can chew for several minutes. A fifteen-minute call isn't a hang; it's the model gathering context, building, and checking its own work. Plan for it. Stream the response, show progress, and let people wander off and come back instead of staring at a spinner that looks frozen.

What actually got better

The headline is long-horizon work. Fable 5 is built to run far without a hand on its shoulder: big refactors, multi-step builds, the overnight kind of task. The trick to getting the most out of it is boring but real. Give it the whole spec up front in one clear turn, set effort high, and let it go. It plans more before it acts, and that front-loaded thinking usually means fewer wrong turns, not more.

The surprising win is at the cheap end of the dial.

You'd expect a premium model to shine at max effort, and it does. But the bigger story is that Fable 5 at low or medium often beats older models running flat out. So "worth the premium" doesn't have to mean "crank everything to max and eat the bill." A lot of work runs fine on a low setting and still comes out ahead.

Debugging got noticeably sharper. It finds real bugs instead of plausible-looking ones, and it's better at the worst kind: the intermittent flake, where weaker models run the test once, see green, and declare victory. (Fair warning, that bug-finding strength doesn't stretch into security analysis, where those same classifiers tend to step in.)

It's a better delegator, too. Where older models would spawn a sub-agent and then sit there blocked until it finished, Fable 5 keeps long-running sub-agents alive and talks to them while it works on something else. If your harness fans work out across agents, that changes how much you can keep in flight at once.

It can also read a bad photo. Flipped, blurry, low-light, noisy. It's trained to reach for crop and zoom tools instead of squinting and guessing, which helps a lot on the screenshot-and-document side of vision.

And here's the twist that catches careful prompt engineers off guard: your hard-won scaffolding can hurt. All those "FIRST do X, THEN do Y, ALWAYS verify Z" prompts you tuned for older models tend to over-constrain Fable 5 and drag its output quality down. The better move is to state the goal and the constraints, then get out of the way. Years of prompt-wrangling instinct, and the new advice is mostly "say less."

The catch

None of this is free, and I mean that literally. Fable 5 runs \(10 per million input tokens and \)50 per million output, against Opus 4.8's \(5 and \)25. Stack the higher rate on top of a tokenizer that counts more tokens for the same text, and an unchanged workload can cost a good bit more than your gut expects. It can also refuse work that's perfectly legitimate but happens to sit near a sensitive area. And it won't run at all under zero retention.

This is a specialist. For everyday traffic, Opus 4.8 is still the one to reach for. Fable 5 earns its keep on the problems that were actually out of reach before, not the ones you've already solved twice.

(One footnote for completeness: if you're in Anthropic's Project Glasswing, you'll meet the same model wearing the name Claude Mythos 5. Same capabilities, same price, different label.)

So when do you actually use it

Hand it the problem you haven't been able to crack. Give it the full picture in one go, not a trickle of follow-ups. Set the effort to match how much the answer matters, wire a fallback for the occasional refusal, and let it run while you go do something else.

Just don't ask it to stop thinking. That's the one thing it won't do for you.

You've seen the videos. Someone types one sentence, an app appears, the crowd claps. What's never on camera is the next six months: the part where somebody has to read that code, change it, and explain to a customer why it did something nobody intended. Generating code was never the hard part of this job. Living with it is.

I lean on AI every day. Claude Code, Cursor, the usual suspects. But I use it the way you'd use a strong, fast junior engineer who started this morning, has read nothing, remembers nothing tomorrow, and will confidently do exactly the wrong thing if you let them. Handled like that, it's a huge multiplier. Handled like a senior you can hand the keys to, it quietly rots your codebase while everyone's impressed by the velocity.

Here's how I actually run it.

The vibe-coding trap

"Vibe coding" is fun right up to the moment it isn't. You prompt, it produces, it runs, you ship. Speed feels incredible. Then a bug shows up in code you didn't write and don't understand, and now you're debugging a stranger's work with none of the context that would've come from writing it yourself.

That's the trap. The code looking plausible is not the same as the code being correct, and AI is extremely good at plausible. It writes things that pass the eye test and fail the edge case. Confident, well-formatted, subtly wrong. The worst kind of pull request, basically, except it arrives every ninety seconds.

The fix is the same one that works for AI-assisted writing, and honestly the same one that works for junior engineers: you don't hand over a blank canvas and hope. You hand over a rulebook and a leash.

The rulebook lives in the repo

For code, the rulebook isn't a prompt you retype. It's a file that sits in the repository and the agent reads automatically every time it starts: CLAUDE.md, or AGENTS.md, or your editor's rules file. Same idea whatever the tool calls it.

Think of it as the onboarding doc you wish every new hire actually read, except this one does, every single session, without complaint.

Without it, the agent guesses. It puts files wherever, invents a naming scheme, picks a library you'd never approve, and writes business logic into a controller because nothing told it not to. With it, the guessing stops. Here's the shape of mine:

# CLAUDE.md

## Project map
- HTTP controllers live in `src/api`, thin. Business logic in `src/services`.
- Persistence in `src/repositories`. No SQL outside that folder.

## Conventions
- Constructor injection only. No field @Autowired.
- DTOs in/out at the boundary. Never leak entities to the API.

## Commands (run these, don't claim "done" until they pass)
- Build:  ./mvnw -q compile
- Test:   ./mvnw -q test
- Lint:   ./mvnw -q spotless:check

## Do NOT
- Add a dependency without asking.
- Touch the `payments` module.
- Commit anything under `secrets/` or any `.env`.

That last block is the most valuable part. Every "do not" is a class of disaster the agent now can't wander into. You write it once and you stop re-explaining it forever.

Tests are the leash

The rulebook keeps the agent pointed in the right direction. Tests are what stop it from lying to you about whether it got there.

This is the single thing that makes AI coding safe past toy size: you don't trust the code, you trust the test that proves the code. So the agent doesn't get to declare victory because the diff looks reasonable. It declares victory when the suite is green, and not one second before.

In practice I either write the failing test first, or I make the agent write it before the implementation and I check that the test is actually testing the real thing (they love a test that asserts true == true and calls it a day). Then the loop is simple: red, write code, green, or back to the agent. The test is the leash. It's exactly as long as your coverage is honest.

// The contract, written before the code:
@Test
void rejectsTransferWhenBalanceTooLow() {
    var account = new Account(money("10.00"));
    assertThrows(InsufficientFundsException.class,
        () -> account.transfer(money("25.00")));
}
// Now the agent can write transfer(). It isn't "done" until this is green.

No test, no trust. If a change can't be pinned down by a test, that's usually a sign it's the kind of change I shouldn't be handing off in the first place. Which brings up the real question.

Know what to hand over

Not everything is safe to give away, and pretending otherwise is how the velocity demos turn into incident reports.

The left column is where AI earns its keep: boilerplate, CRUD endpoints, the fifteenth mapper between two nearly identical shapes, unit tests for code that already exists, mechanical renames across forty files, "explain what this legacy function does." Work that's tedious, fast to generate, and easy to verify. Hand it over and don't feel a thing.

The right column is where I keep my hands on the wheel. System and data architecture. Anything touching auth, security, or money. Concurrency, locking, ordering, the stuff that works fine until it's 2am and a race condition is eating your weekend. And the one thing the model fundamentally can't do for you: figuring out what the actual problem is. The agent can build the thing. It can't tell you you're building the wrong thing.

The boundary isn't fixed, by the way. As your tests and your rulebook get stronger, more work safely slides left. But it slides because you earned the safety, not because you got tired of reviewing.

What the agent can't do

It can't hold your whole system in its head. It sees the files in front of it and a summary, not the four years of context about why that weird workaround exists and what breaks if you "clean it up."

It can't own the consequences. When the thing it wrote goes sideways in production, it's not on the call. You are. No skin in the game means no judgment about risk, just confident output either way.

And it doesn't know what "good" means for your domain. Good code for a banking ledger and good code for a throwaway internal dashboard are different in ways the model will flatten into the same tidy average unless you tell it otherwise.

So the senior skill in all this isn't writing code anymore. It's reading a diff quickly, smelling what's off, and saying "no, not like that" with a reason. The job shifted from typing to reviewing, and reviewing well is harder than it looks. You're the editor. The agent is a very fast, very forgetful typist.

The honest version

This makes me genuinely faster, and I'm not going to pretend it doesn't. On the 70% of the work that's mechanical, it's a different speed of working entirely. That's real, and it frees up attention for the 30% that's actually judgment, which is the part that was always worth my time.

But it is not hands-off, and the people selling it as hands-off are describing a codebase I wouldn't want to inherit. I read every diff. I write the tests, or I check the ones it wrote like I don't trust them, because I don't. The rulebook and the leash aren't bureaucracy. They're the only reason the speed doesn't turn into a slow-motion mess six months out.

The tool will change. It's Claude Code today, something better next year, and your CLAUDE.md and your test suite move over almost untouched, because they're about your codebase, not the model. That's the asset. The model is just the engine you bolt it to.

So: scope it small, write down the rules, make the tests the gate, and review like it's a junior's PR, because that's precisely what it is. Then merge it under your name and mean it.

I've spent six and a half years building production systems across telecom, fintech, govtech and edtech. The languages changed. The frameworks changed. The cloud providers changed. Five patterns kept showing up.

1. The boundary between services is a contract, not a suggestion

Every microservice migration I've seen go badly started with the same mistake: treating service boundaries as code-organization, not contract-organization.

The test is simple. If a downstream team can ship a breaking change without your service knowing about it, you don't have a contract. You have an internal call masquerading as a network call — the worst of both worlds. You pay the latency cost of HTTP and the coupling cost of a shared module.

What it looks like when it's right:

• Schemas live in a versioned, language-agnostic format (OpenAPI, protobuf)
• Breaking changes get a /v2, never a same-version mutation
• Consumers can pin a version; producers can't yank one out from under them
• A test suite proves you serialize what you say you serialize

This is boring. It's also the reason your platform doesn't catch fire on a Friday.

2. Idempotency is a feature, not a hope

Networks fail. Retries happen. The question isn't whether your service will see the same request twice. The question is whether the second time hurts.

The cheapest implementation is a request-id header that the caller generates and the server caches the result against. If the same id arrives twice, the server returns the cached response and skips the side effect. Costs you a Redis key and a hash check. Saves you a duplicate charge or a duplicate row.

I've watched teams without this build elaborate compensation flows to undo what the second request did. They never work as well as not doing the work twice in the first place.

3. Retries are a contract too

Retries between services without a budget are how cascading failures start. Service A retries B three times, B retries C three times — that's nine attempts on C from one logical call. C is already struggling; now it's seeing 9× load.

Two rules I won't break:

• Bound the retry budget end-to-end, not per-hop. Pass a deadline header. Each hop checks it before retrying.
• Circuit-break aggressively. After N failures in a window, stop calling. Surface a 503 fast. The system recovers faster from a clean failure than from slow degradation.

Spring Cloud's circuit breaker (Resilience4j under the hood) does this in three lines of config. Most Node teams hand-roll something with a global counter and call it a day. Both work; the question is whether you're explicit about the budget or just hoping.

4. Observability before incidents, not during

The single biggest predictor of how a system survives an incident is whether the operator can see what's happening right now. Not yesterday's logs. Now.

The minimum viable trio:

• Structured logs with a request-id propagated through every service touched
• One latency dashboard with p50 / p95 / p99 per route, refreshed in seconds
• Error rate per dependency, not just per service — so you know which downstream is the problem before users do

Add this before you have the incident. The pattern I've seen kill teams: rolling out fancy distributed tracing two weeks after a P0, while the lessons are still in postmortem format.

5. If it doesn't move a metric, don't ship it

Every system I've owned shipped with a number attached — throughput lifts, manual-effort reductions, faster cycle times, integrations going live across enterprise systems.

Not because metrics make engineers feel important. Because the discipline of choosing a metric before you start coding forces you to know what "done" means. Every one of those numbers existed in a spec before the first line of code did. The code was the cheap part. The agreement on the metric was the expensive part.

The corollary: if you can't articulate the metric, you don't understand the work yet. Go back and ask.

Six years compresses to this: code is the easy part. The hard part is the discipline you build around the code — boundaries, idempotency, retries, observability, metrics — that lets the code keep working when the world gets noisy.

Everything else is a tool to serve that.