Clay Tercek

My Clearest Briefs Go to a Robot

hello@tercek.me (Clay Tercek) — Mon, 10 Aug 2026 00:00:00 GMT

The clearest briefs I've ever written have all been addressed to a robot.

When I hand a task to Claude, I explain the background, spell out the constraints, define what done looks like, and call out the edge cases I'm worried about. I'll even list the things I don't want it to do. It's some of the best technical writing I produce all week.

Nobody I actually work with gets that treatment. Humans get "hey, can you take a look at this when you get a chance?"

The robot is a brutal audience

Why does the robot get the good version? Because it punishes vague writing instantly. Hand a colleague an underspecified task and they'll nod, fill in the gaps from shared context, maybe ask a clarifying question a day later. Hand a model an underspecified task and it confidently does the wrong thing, right in front of you, in about thirty seconds.

That's the tightest feedback loop on unclear communication anyone has ever had. "Prompt engineering" gets dressed up as a new technical discipline, but strip away the mystique and it's just briefing: context, goal, constraints, examples of what good looks like. The stuff we always owed each other and mostly skipped, because a human recipient absorbs the ambiguity for free and the cost stays invisible.

I ran into this same pattern with agent config files: people who never got around to writing a README will happily fill an AGENTS.md with build steps, conventions, and architecture notes. The robot asked, so the docs finally got written. Turns out that wasn't just about docs.

And yet the inbox got worse

Here's the part that gets me. Everyone leveled up at written communication at the same moment, and the messages showing up in my inbox got worse. Longer, rounder, padded with headers and bullet points nobody chose.

Because the good writing stays private. You write a tight three-sentence brief, hand it to the model, and the model inflates it into four polite paragraphs. Then you send the four paragraphs and keep the three sentences.

Andrew Gelman was complaining about exactly this on his blog just yesterday: "Instead of sending me the chatbot output, just send me your goddamn prompt." He's right, and the reason he's right is simple: everything you wanted to say was already in the prompt. The model didn't add information, it spread the same information across more words. So now I have to read your four paragraphs trying to reconstruct the three sentences you started from. Plenty of people don't even do that anymore, they paste the message into an LLM and ask for a summary. Inflate on your end, deflate on mine, lossy in both directions. We've invented the world's slowest way to send three sentences.

Niklas Gruhn has a name for the person doing the forwarding: a meat proxy. If all you did was carry the model's output to my inbox, you added nothing but latency. And as he points out, if I wanted a chatbot's take, "I can talk to Claude myself. It's going to be faster and I get to control the context."

The rule

Before you hit send, ask which artifact carries more information per word: the output, or the prompt that produced it? If it's the prompt, send the prompt. Not as a transcript with an apology attached. Just send the message you typed, because that was the actual message all along.

The corollary is less comfortable. If you'd be embarrassed to send the prompt ("make this sound professional," "write an update saying things are on track"), the polished version has nothing to say either. The polish is laundering.

When the output is the message

To be fair, sometimes the model genuinely adds information: it researched something you didn't know and you verified it, it wrote code that runs, it boiled ten documents down to a real decision. In those cases the output carries more than the prompt did, so send the output. The sin was never using AI. The sin is sending text that contains less information than the prompt that produced it.

Aim it at people

You already know how to write. The proof is sitting in your prompt history: context up front, constraints named, done defined. You've been doing it every day, for an audience that gives you nothing back but compliance.

Next time, skip the middleman. Send the brief.

References

Andrew Gelman, "People keep sending me AI slop that they want me to post on the blog"
Niklas Gruhn, "Don't be a meat proxy"
AGENTS.md Is Not a README — the docs version of this same argument

A Field Guide to Zig Allocators

hello@tercek.me (Clay Tercek) — Mon, 20 Jul 2026 00:00:00 GMT

I've been learning Zig, and the thing that stuck with me isn't comptime or the syntax everyone posts about. It's that the language flat out refuses to allocate memory behind your back.

In most languages, memory just appears. You write new Thing() or malloc(64), or you let the garbage collector sort it out, and where those bytes actually came from is somebody else's problem. Zig makes a different call: any function that needs to allocate takes an Allocator as a parameter. If a function doesn't take one, it can't allocate. You can tell what a function does to memory from its signature alone.

Sounds like a chore. In practice it's the most interesting decision in the language, because it means the strategy for handing out memory is just a value you pass around. Swap the value, swap the behavior, and the code in between never changes.

That's the part I want to dig into here. Not "how do I allocate in Zig," but the handful of strategies you'd actually pass in: what each one is good at, and where each one bites you. There's a little interactive strip in each section. Tap a size to allocate, tap a block to free it, or drag a block's right edge to resize it, and watch how the same requests play out differently depending on who's handing out the memory.

One interface, many strategies

The whole thing hangs on one small type. Simplified a little, std.mem.Allocator is a pointer plus a table of function pointers:

pub const Allocator = struct {
    ptr: *anyopaque,
    vtable: *const VTable,

    pub const VTable = struct {
        alloc: *const fn (ctx: *anyopaque, len: usize, alignment: Alignment, ret_addr: usize) ?[*]u8,
        resize: *const fn (ctx: *anyopaque, memory: []u8, alignment: Alignment, new_len: usize, ret_addr: usize) bool,
        remap: *const fn (ctx: *anyopaque, memory: []u8, alignment: Alignment, new_len: usize, ret_addr: usize) ?[*]u8,
        free: *const fn (ctx: *anyopaque, memory: []u8, alignment: Alignment, ret_addr: usize) void,
    };
};

Four functions. alloc hands you bytes, free gives them back, resize and remap try to grow or shrink in place. Every allocator in the standard library, and every one you write yourself, is just a different implementation of those four.

So a function that needs memory doesn't care which one it got:

fn readLines(allocator: std.mem.Allocator, path: []const u8) ![][]u8 {
    // ... uses allocator.alloc, allocator.free, and friends
}

Call it with an arena and every line lives until you drop the arena. Call it with a general purpose allocator and you free each line yourself. Same function. The caller picks the memory strategy, not the library. That inversion is the whole point, and once it clicks you start seeing the plain Allocator as a slot you drop a strategy into.

Here's the lineup.

The bump allocator: fast, and it never gives anything back

Start with the simplest thing that could possibly work. You have a block of memory and a pointer to the next free spot. Every allocation hands back the pointer and shoves it forward by the requested size. That's it. That's the whole allocator.

🎛️ Interactive demo — view this post on tercek.me for the playground.

Allocate a few blocks and you can watch the region fill from the left. Now tap one to free it. Nothing happens, and the demo tells you why: a bump allocator has no idea how to reclaim one allocation out of the middle. There's a single pointer and it only goes forward. You can drag the top block's edge to grow it, since that's just nudging the pointer a little further, but the blocks behind it don't even have a handle to grab, and the only way to get memory back is to reset the whole thing, which frees everything at once.

That sounds broken until you notice how often it's exactly what you want. Zig calls this an arena:

var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena.deinit();
const allocator = arena.allocator();

const a = try allocator.alloc(u8, 64);
const b = try allocator.alloc(u8, 128);
// no free() anywhere. deinit() drops all of it in one shot.

Think about handling a single web request. You allocate a pile of temporary junk, parse some JSON, build a response, and the second the request is done, all of it is garbage. You don't want to free thirty things in the right order. You want to wipe the slate. An arena turns thirty frees into one, and every allocation in between costs about as much as bumping a pointer.

The tradeoff is right there in the demo: you can't free just one thing. If some allocations in an arena are short lived and others need to stick around, the long lived ones pin the whole region, and your "temporary" memory quietly becomes permanent until the reset. Arenas are for phases with a clear end, not for objects with their own individual lifetimes.

(A stack allocator is the close cousin here: same bump pointer, but it lets you free the most recent allocation and roll the pointer back, as long as you free in reverse order. You'll see exactly that behavior in the next section.)

The fixed buffer allocator: same idea, no heap at all

Take that bump allocator and hand it a buffer that lives on the stack. No malloc, no OS, no heap. Just an array and an offset.

var buf: [1024]u8 = undefined;
var fba = std.heap.FixedBufferAllocator.init(&buf);
const allocator = fba.allocator();

Everything about the bump behavior carries over, with one hard new rule: the buffer is a fixed size and it never grows. Fill it up and the next allocation returns error.OutOfMemory. The demo below is deliberately tiny so you can hit the wall fast.

🎛️ Interactive demo — view this post on tercek.me for the playground.

Keep allocating and you'll run out of room, and the allocator says so instead of quietly grabbing more from somewhere. That failure is a feature. On an embedded target with no heap, or in a hot path where you refuse to touch the OS allocator, a fixed buffer gives you a hard, visible ceiling. You know at compile time exactly how much memory this code can use, because you're the one who declared it.

One nuance the demo shows: a FixedBufferAllocator can free, but only the most recent allocation, because that's the only one it can prove sits right at the top of the buffer. Free the last thing and the offset rolls back. Try to free something in the middle and it can't, for the same reason the arena couldn't. That "free the top" move is the stack allocator I mentioned, hiding in plain sight. Growing works the same way: drag the top block's edge and the offset slides up, right until it would run off the end of the buffer, where you hit the wall again.

The pool allocator: one size, no fragmentation, ever

Everything so far allocates arbitrary sizes and can only free from the end. The pool goes the other direction. It commits to exactly one size up front, and in exchange it lets you free anything, in any order, for basically free.

The trick is that if every slot is identical, freeing one just puts it back on a list of empty slots. Allocating grabs the first one off that list. No searching, no measuring, no leftover gaps that don't fit anything. Both operations are O(1), and the memory can never fragment, because there's nothing to fragment: every hole is exactly the right size for the next request, by construction.

🎛️ Interactive demo — view this post on tercek.me for the playground.

Allocate and free in whatever order you like. Slots light up and go dark, and the layout never gets messy, because it can't. In Zig this is MemoryPool, parameterized by the type it hands out:

const Node = struct { value: i32, next: ?*Node };

var pool = std.heap.MemoryPool(Node).init(std.heap.page_allocator);
defer pool.deinit();

const n1 = try pool.create();
const n2 = try pool.create();
pool.destroy(n1); // n1's slot goes straight back on the free list

This is the allocator you reach for when you're churning through a lot of one thing: nodes in a linked list or a graph, entities in a game, particles, connection structs. The catch is right in the name. A pool of Node holds nodes and nothing else. The moment you need two sizes, you need two pools, and the "one size fits all" superpower is also the whole limitation. That's also why the pool slots in the demo have no resize handle at all: there's only the one size, so there's nothing to drag.

The general purpose allocator: does everything, and now you have to think

Sooner or later you need the real thing: arbitrary sizes, freed individually, in any order, memory actually reused. This is what malloc has always done, and it's the default mental model most of us drag in from other languages. In Zig it's the DebugAllocator, though most people still call it the GPA out of habit:

var gpa = std.heap.DebugAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();

const a = try allocator.alloc(u8, 64);
defer allocator.free(a);

To pull off "any size, freed in any order," it keeps a list of free holes and, on each request, goes hunting for one big enough. Which is where it gets interesting, and where it can bite you. Play with the demo: allocate a few blocks of different sizes, then free a couple out of the middle.

🎛️ Interactive demo — view this post on tercek.me for the playground.

Watch the "largest hole" number. You can have plenty of total free space and still fail to allocate, because that free space is chopped into pieces too small to use. The demo will happily tell you that you've got, say, 9 bytes free but the biggest run is only 3, so a request for 4 fails anyway. That's fragmentation, and it's the price of admission for a general purpose allocator. It's the exact failure mode the arena and the pool are built to dodge.

Freeing next to another free block helps: the demo coalesces adjacent holes back into one bigger hole, which is what a real allocator does to fight fragmentation. But it can't fix everything, and no general purpose allocator can. That's the deal. In return for handling every case, it makes you pay in bookkeeping, in the occasional slow request while it hunts for a hole, and in the fragmentation you just watched happen.

Resize is where the free list really shows off. Drag a block's right edge to grow it: if the hole right after it is big enough, the allocator just extends in place and nothing moves. If it isn't, let go, and watch the block jump somewhere else on the strip entirely. That's a remap, the allocator finding a bigger hole, moving your bytes there, and handing back a new pointer. It's the same thing that happens under the hood when you grow a dynamic array and it suddenly lives at a new address.

The Zig flavored bonus: the DebugAllocator is packed with safety checks. Double frees, leaks, use after free, it catches them and points at the exact line. You run it in development, and when it's time to ship you swap in a faster backing allocator by changing one line, because everything downstream only ever knew about the Allocator interface.

The ring buffer: run in a circle and overwrite the past

Every allocator so far treats running out of room as an error. The ring buffer treats it as the normal case. You lay your memory out in a circle: allocations march forward like a bump allocator, but when the write pointer hits the end, it wraps back to the start and writes straight over the oldest data.

🎛️ Interactive demo — view this post on tercek.me for the playground.

Keep allocating past the end and watch the writes wrap back around to the start. The oldest blocks just get stomped, no error, no freeing, no bookkeeping. That's the whole point, and it's exactly what you want when you only ever care about the most recent slice of a stream: the last few seconds of audio, incoming network packets you handle and forget, the tail of a log, a history buffer for undo. The data structure is the eviction policy.

The tradeoff is that you don't get to keep anything. A ring buffer will happily overwrite data you were still using if you let the pointer lap you, so it only fits when "old enough" reliably means "safe to throw away." It doesn't really resize either, because the entire idea is a fixed window that recycles itself. Zig's std.RingBuffer is a byte-oriented take on this, and the pattern shows up all over streaming and I/O code.

The buddy allocator: split in halves, merge in pairs

The free list fought fragmentation by searching and coalescing. The buddy allocator fights it with structure instead. Every block is a power of two, and the whole region starts life as one big block. To allocate, you round the request up to the nearest power of two, then split a block in half, and half again, until you land on one the right size. Each split makes two "buddies," and that pairing is the trick: when you free a block, if its buddy is also free, the two snap back into the bigger block they came from. Merge all the way up and you're back to one clean region.

🎛️ Interactive demo — view this post on tercek.me for the playground.

Allocate a few odd sizes and you can watch the region divide into neat power-of-two pieces (the demo draws each free block separately so the structure is visible). Free two buddies and they merge. This is what a lot of kernels and GPU or DMA drivers reach for, because merging is O(1) and cheap: you don't scan a free list, you check one buddy and you're done.

Two tradeoffs fall out of the power-of-two rule, and the demo shows both. Ask for 3 bytes and you get 4, so a byte is wasted inside the block. That's internal fragmentation, the cost of rounding. And two free blocks sitting right next to each other won't always merge, because they have to be actual buddies, the specific pair some split created, so you can still strand free space you can't recombine.

All six, one strip

Here's all six in one place. Same buffer, same buttons, and a set of tabs to swap the strategy underneath. Try running the same sequence of allocs, resizes, and frees through each one and watch where they split: the arena that won't free, the fixed buffer that hits a wall, the pool that never makes a mess, the free list that fragments and remaps, the ring that laps itself, the buddy that halves and merges.

🎛️ Interactive demo — view this post on tercek.me for the playground.

That divergence is the entire argument for doing it Zig's way. In a language where allocation is baked in, "use an arena for this request" is a rewrite. Here it's a different value passed to the same function. The code that reads the file, parses the input, builds the tree, none of it knows or cares. It asked for memory through an interface, and you got to decide what was behind the interface.

So which one

There's no universal answer, which is sort of the point, but here's the rough map I've landed on:

Arena when a batch of allocations share a lifetime and die together: a request, a frame, a parse pass. Free everything at once, never free anything on its own.
Fixed buffer when you want a hard memory ceiling and no heap at all: embedded, hot paths, anywhere a clean error.OutOfMemory beats a surprise.
Pool when you're churning through many of the exact same thing and want O(1) alloc and free with zero fragmentation.
General purpose when you genuinely need arbitrary sizes and independent lifetimes and you're willing to pay for it. In Zig, also your safety net while developing.
Ring buffer when you only care about the most recent slice of a stream and old data is safe to overwrite: audio, packets, logs, undo history.
Buddy when you want arbitrary-ish sizes with fast, cheap coalescing and can eat a little rounding waste: kernels, GPU and DMA memory.

Most real programs use several at once: a GPA at the root, an arena per request hanging off it, a pool for the hot inner loop. Zig doesn't make that composition clever, it makes it boring. Everything speaks the same four function interface, so you stack them like Lego.

I came to Zig for the comptime stuff. The allocator design is what made me want to stay. Passing memory strategy around as a plain value sounds like a small thing, right up until you realize most of the memory bugs you've ever chased were really just the language deciding this for you, out of sight.

Caching Is Portable. Invalidation Isn’t.

hello@tercek.me (Clay Tercek) — Fri, 10 Jul 2026 00:00:00 GMT

A couple months ago I wrote about why we should cache the HTML too. The basic argument was pretty simple: the fastest request is the one your server never sees. We cache images, CSS, and JavaScript without thinking twice, then render the exact same HTML again for every visitor.

Astro 7 just shipped with a bunch of performance work, but one feature stood out to me: route caching. It takes that argument and fixes the most annoying part of actually putting it into practice.

Fast enough, until it isn't

I feel like caching has been largely ignored in the headless world because most sites are fast and cheap enough. A serverless function renders the page in a few hundred milliseconds, the hosting bill stays tiny, and nobody has a reason to care that the same work happens on every request.

Then the site gets a giant audience and both problems become urgent at the same time.

Serverless hosting can make this stranger. A platform might run your function near the visitor, which cuts down the round trip, but moving the server closer doesn't remove any work. The function still runs. The CMS still gets queried. The HTML still gets rendered. Edge execution and edge caching sound similar, but they're solving different problems.

In a lot of setups the CDN sits in front of the serverless function but doesn't cache its HTML by default. Every request passes straight through to compute. You can add an application cache behind the CDN, but by then the request has already invoked your function, which is exactly the work I want to avoid.

Cloudflare just shipped Workers Cache to fix exactly this problem. Workers originally ran in front of an origin and its cache. Once frameworks started deploying the entire application as a Worker, the Worker became the origin, so there was nothing left behind it to cache. Workers Cache flips that architecture around: on a hit, the cache responds and the Worker never runs.

Headers only got us halfway there

To be fair, we already have a portable interface for telling a CDN how to cache a response: the Cache-Control header. Set s-maxage, maybe add stale-while-revalidate, and any CDN that understands standard HTTP caching has enough information to save the response.

That works great until the content changes.

Say a product is cached for an hour, then someone updates its price in the CMS. You could wait out the hour, but serving a knowingly wrong price for 59 minutes isn't a particularly good caching strategy. You want the CMS to fire a webhook and purge that product immediately.

There isn't a standard HTTP header for that. Cloudflare, Netlify, Vercel, and every other CDN have their own purge APIs, authentication, tag formats, and limitations. At that point your otherwise portable application grows a little bundle of infrastructure-specific code.

This is where Astro's route caching gets interesting. A page can describe how it should be cached:

cache.set({
  maxAge: 300,
  swr: 60,
  tags: [`products:${Astro.params.id}`],
});

Then a webhook can invalidate the same tag when the product changes:

await cache.invalidate({ tags: [`products:${slug}`] });

The application owns the caching intent. The adapter translates it into whatever the host actually needs. Astro 7 currently has experimental CDN cache providers for Cloudflare, Netlify, and Vercel, and the same Astro.cache and cache.invalidate() calls work across all three.

That's the abstraction I want. Cache lifetimes were already mostly portable. Invalidation was the part gluing an application to its CDN.

You can also define cache behavior for groups of routes in astro.config.mjs, which is probably where I'd put the boring defaults:

routeRules: {
  '/blog/[...path]': { maxAge: 300, swr: 60 },
}

Then route code only needs to get involved when it has useful tags or needs to opt out.

Next.js got close first

Next.js has had full-route caching and on-demand revalidation for a while. On Vercel, the whole thing is integrated: Next.js knows how the response was rendered, Vercel knows how it was cached, and revalidatePath() or revalidateTag() connects the two.

Self-hosted caching works too, but on-demand revalidation stops at the Next.js server cache. An arbitrary CDN will keep serving its copy until the TTL expires unless you also call its purge API. That's the gap. Astro's adapters make the host-specific purge part of the cache provider, while the application keeps the same interface.

Portable doesn't mean automatic

There are tradeoffs here. The CDN providers are still experimental, and right now "CDN agnostic" really means the three supported platforms. If you host somewhere else, someone still has to write the provider.

You also still have to decide what is safe to cache. A personalized dashboard is not made cacheable just because the API is pleasant. Cache the public product page, not the logged-in account sitting next to it. Invalidation webhooks need authentication. Tags need enough thought that updating one product doesn't purge the entire catalog (unless that's actually what you want).

The API removes platform plumbing. It can't remove the need to understand your own data.

Still, this feels like exactly the right direction. My hope is that the provider interface eventually escapes Astro and becomes something more framework agnostic, maybe as a Vite plugin or a small standard that Vite frameworks can share. Every server-rendered framework needs to express the same handful of ideas: cache this response, serve it stale while refreshing, and purge it by path or tag.

We already have standard language for the first two. Astro is taking a real swing at the third.

Agents Saved React (Unfortunately)

hello@tercek.me (Clay Tercek) — Fri, 29 May 2026 00:00:00 GMT

There's an article making the rounds about AI causing a repeat of frontend's "lost decade." The central claim is that agentic coding tools are "deskilling" developers the way JavaScript frameworks did before them.

Half of that is right.

The deskilling argument actually lands for agentic coding. When an AI writes your code and you accept it without reading it, you don't need to understand what it's doing to ship something. That's a real concern.

But applying "deskilling" to React and the framework era? That's where I disagree. The article's own list of lost skills is worth reading back: semantic HTML, CSS, browser differences, accessibility, progressive enhancement, network performance. That's exactly the list of things a good React developer still has to know. React didn't remove those requirements. It repackaged them into a component model that's more portable and easier to reason about at scale. The skills didn't disappear. The syntax changed. That reads more like "old school dev mad at change" than a real critique.

Anyway. The bigger thing I've been chewing on is React itself.

DX rules, UX drools

I've spent years quietly hoping the frontend world would move on. Not because React is broken. It's not. The developer experience is genuinely excellent. Component model, unidirectional data flow, a massive library ecosystem. You can build anything with it. Slowly, on a bad connection, but anything.

But "you can build anything" and "you should build this" aren't the same claim. The answer to the second one is almost never React.

The performance story has been bad since the beginning. Shipping a runtime to the browser to reconcile a virtual DOM with the actual one is a strange thing to make the default, especially once browsers got good at the exact job React was hired to do. The virtual DOM was always a tradeoff, not a free win. And the framework made that tradeoff on the user's behalf, not the developer's. Bundle sizes ballooned. Time to interactive got worse. Developer experience kept improving while user experience slid in the other direction.

We were so close

Here's what's annoying: fine-grained reactivity has existed for years. Svelte figured this out. You write components, the compiler produces lean output, there's no virtual DOM to reconcile. It's faster. The bundles are smaller. The expensive work happens at build time instead of in the user's browser. Svelte is excellent, and I genuinely enjoy working with it.

Solid went further and asked: what if you got Svelte-level performance but kept React's mental model? Signals, composable primitives, JSX. Turns out you can have both. Solid routinely lands near the top of the framework benchmarks, right next to vanilla JavaScript. Solid is a great framework. Nobody uses it.

Preact shipped signals for the same reason back in 2022. And the React Compiler that Meta shipped in late 2024 is trying to automate, at build time, the memoization that compiler-first frameworks made unnecessary half a decade earlier. It doesn't touch the core issue: the runtime and the reconciler still ship to the browser, and the compiler just re-renders less of the tree. It's a stopgap with good marketing.

Around 2023 and into 2024, there was real momentum behind the idea that React would stop being the default. Not die. Just become one tool among several, chosen when it's actually the right fit. SvelteKit was getting attention. Solid was maturing. The conversation felt like it was actually happening.

Then agents happened

When an AI is writing your code, it writes what it knows best. Models have more React training data than anything else in the frontend space, the patterns are exhaustively documented, and the community is enormous. Ask an agent to scaffold a component and you're getting React, a useEffect that fires twice in development, and a package.json with thirty dependencies. That's not a criticism, it's just how it works.

It's not even subtle. Someone asked eight different models and tools to build a frontend: Claude, GPT, Gemini, DeepSeek, Qwen, v0, Lovable, Bolt. They all landed on nearly the same answer. React, Next.js, TypeScript, Tailwind, shadcn/ui. The stack is a property of the training corpus, not a choice. And because the next model trains on the code this one generates, the corpus skews further toward React every cycle. The default reinforces itself.

So instead of the frontend world diversifying, it consolidated. React got a massive tailwind. Not the CSS kind.

Svelte and Solid are still out there and still measurably faster. They're just not what the agent defaults to.

What bothers me most is the timing. Svelte 5 shipped with runes in October 2024. SolidStart hit 1.0 that May. Real alternatives existed with real communities. The moment when developers might have started making deliberate, performance-conscious framework choices arrived right as the era of developers writing code by hand started winding down.

AI coding tools get marketed as accelerators of innovation. But if you're generating the same patterns from three years ago at ten times the speed, that's not innovation. It's just more of the same, faster.

The lost decade is here. It just comes with better autocomplete.

AGENTS.md Is Not a README

hello@tercek.me (Clay Tercek) — Wed, 27 May 2026 00:00:00 GMT

Open source projects are getting plagued by agent files. AGENTS.md, CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, committed skills, the works. The convention, pushed hard by the people who make these tools, is to commit them. The agents.md spec frames the file as "a README for agents," project infrastructure that belongs in source control next to your CI config. GitHub has written up lessons from 2,500+ repos treating it as shared documentation.

I think this is mostly a mistake.

These files are inherently personal. The way I drive an agent is not the way you drive an agent, and committing my workflow into a shared repo quietly assumes the whole team should converge on one. I don't think that's true, and I don't think it's desirable. Your agent workflow can and should be bespoke. It's closer to your editor config or your shell aliases than to your test suite. Nobody commits their .vimrc to the project repo and expects everyone to adopt it.

The usual argument for committing the file is that it documents the architecture, the repo layout, the build and release process, the conventions a new collaborator needs. All of that should be shared. But none of it is agent information. It's documentation, and documentation belongs in the README, where humans will actually read it. Putting it in AGENTS.md just hides your project docs somewhere only the robots look. As spawarotti put it on Hacker News:

"At this point AGENTS.md is a README.md with enough hype behind it to actually motivate people to populate it with contents. People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots."

The shareable content was never agent content. It's the docs we should have been writing for each other all along.

This instinct isn't fringe, but it's a minority position. You can watch the debate play out in real time: a Hacker News commenter says flatly, "I would .gitignore all of those files. Is this not what is done in industry?" and gets mostly disagreement. The split is always the same: shared rules enforce consistency, but they also flatten everyone into one person's setup.

So why does everyone commit them anyway?

Because the alternative is genuinely worse right now.

The reason to colocate agent instructions with the code is that git gives you branch-awareness for free. Say you're on a feature branch and you tweak AGENTS.md to describe a module that only exists on that branch. Then you switch back to main. Because the file is tracked, your changes travel with the branch, so main's agent never sees references to code that doesn't exist yet. Anyone who has tried git-ignoring their agent files knows the opposite feeling: a single global instruction file that's perpetually slightly wrong for whatever branch you're actually on.

So you're stuck between two bad options. Commit the file and impose your workflow on the team, or ignore it and lose the branch-awareness that made it useful.

What we have today

The tools do offer escape hatches, they're just incomplete.

Claude Code, for instance, has a real hierarchy (documented here): a user-level ~/.claude/CLAUDE.md that applies across all projects and never gets committed, a team-shared project ./CLAUDE.md, and a personal ./CLAUDE.local.md that you're meant to add to .gitignore. AGENTS.md has an open proposal to standardize a global ~/.config/agents/AGENTS.md, explicitly modeled on how git handles ~/.gitconfig versus a repo's .git/config.

That git analogy is the right one. Git solved exactly this problem decades ago: global defaults in ~/.gitconfig, repo overrides in .git/config, and personal per-repo ignores in .git/info/exclude that never touch the shared .gitignore. The local layer is never committed. We just haven't fully ported that model to agent memory.

The gap is branch-awareness. CLAUDE.local.md is per-worktree, not per-branch. None of the personal-config options track your branches the way a committed file does.

That gap is what pushed me to build offstage, a small Go CLI that keeps personal files colocated with a project without committing them to the project's repo. It's backed by a separate private git repo, and it's branch-aware: files are stored under <project-id>/<git-branch>, so each branch gets its own notes, synced across machines via git hooks. It's been working for me, but I'm floating it as one option, not a recommendation, and your mileage may vary. It's a partial fix at best: if a branch gets merged via a PR, offstage has no way to know, so you have to manually run offstage merge to reconcile. The branch lifecycle and the file lifecycle drift apart the moment the merge happens somewhere offstage can't see.

A better solution

The real fix is more foundational than a sync tool. A few directions I think are worth exploring:

Native per-branch personal memory in the agent itself. The agent already knows what branch you're on. It could keep personal instructions keyed by branch, stored outside the repo, and reconcile on branch events (merge, delete, rebase) by hooking into git the way it already hooks into everything else. This is offstage's job, done by something that can actually observe the merge.
A standardized local layer, universally honored. If every agent agreed on a ~/.config/agents/ global file plus a gitignored local override, and actually merged them at runtime, most of the "personal vs. shared" tension disappears. The committed AGENTS.md becomes a genuine team README; everything bespoke lives in your local layer.
Treat the shared file as the floor, not the ceiling. Commit only the truly project-wide facts (build commands, test runner, deploy steps) and socially discourage stuffing personal workflow into it. Keep the file boring and uncontroversial on purpose.

None of these fully exist yet. For now I commit a deliberately minimal AGENTS.md and keep everything bespoke in offstage. But I think the long-term answer is for agents to treat memory the way git treats config: layered, with the personal layer kept firmly off the shared record.

References

agents.md — the open spec, now under the Linux Foundation's Agentic AI Foundation
Claude Code memory docs — the user / project / local hierarchy
agents.md issue #91 — proposal for a global user-level AGENTS.md
HN: "I would .gitignore all of those files"
HN: spawarotti, "AGENTS.md is a README.md with enough hype"
git-scm.com/docs/gitignore — .git/info/exclude and core.excludesFile
offstage — my attempt at the branch-aware personal layer

Cache the HTML Too

hello@tercek.me (Clay Tercek) — Tue, 26 May 2026 00:00:00 GMT

A lot of web frameworks and platforms bury the single easiest way to make a site faster and cheaper: CDN caching. We spend enormous effort shaving milliseconds off server-side rendering, picking the fastest meta-framework, optimizing database queries, and then skip past the one move that beats all of it. Just save the result. There's no reason to repeat the same work on every single request.

The fastest request is the one your server never sees.

HTML is cacheable too

Most CDNs make this trivial, but the default trips people up. Cloudflare, Fastly, CloudFront, Vercel's edge: they all cache your static assets (CSS, JS, images, fonts) out of the box. What they do not cache by default is HTML. As Cloudflare's docs put it plainly: "The Cloudflare CDN does not cache HTML by default."

That's the part people miss. Caching media feels obvious, but caching pages feels dangerous. Yet a huge fraction of the HTML you serve is identical for every visitor, and there's no reason to render it fresh each time.

Turning it on is mostly a one-liner. The mechanism across every CDN is the Cache-Control header: s-maxage controls how long the CDN holds the response, and stale-while-revalidate lets it serve the stale copy instantly while refreshing in the background. On Cloudflare you can also do it without touching your app, via a Cache Rule that marks matching URLs as eligible for cache.

One real caveat: "cache everything" means everything. If you blanket-cache HTML, you can hand one user's logged-in page to the next visitor. So scope it: exclude anything with an auth cookie, exclude your dashboard, cache the public pages. Anything that sets Set-Cookie, private, or no-store is skipped automatically, but you should still be deliberate about it.

How much of your site actually needs to be fresh?

This is the question worth asking before you reach for anything fancier. Your blog, your marketing pages, your docs, your product listings... how often do they really change? Sure, modern frameworks render pages fast. But "fast to render on every request" will always lose to "already rendered, sitting at an edge node 20ms from the user." Static beats dynamic, and a cache turns dynamic into static for the 99% of requests where nothing changed.

A note on framework caching

Frameworks have their own caching layers, and it's easy to conflate them with CDN caching. Next.js is the instructive case because its caching model is famously confusing.

Next.js has several distinct caches: Request Memoization (dedupes calls within a single render), the Data Cache (persists fetch results across requests), the Full Route Cache (server-side), and the Router Cache (client-side). The Full Route Cache serves fully rendered static pages straight from cache: at build time Next.js renders static routes to HTML plus the RSC payload, and serves that cached output instead of re-rendering per request. That's exactly the static-serving behavior you want.

Server Actions are not cached. They use POST and are mutations by design; Next.js only ever memoized GET-style data fetches. Actions can trigger invalidation via revalidatePath / revalidateTag, but they're never served from cache.

Worth knowing too: Next.js 15 flipped the defaults toward less implicit caching: fetch is no-store by default now, and GET route handlers aren't cached by default. The framework is leaning away from caching-by-magic, which makes the case for owning your caching at the CDN layer even stronger.

None of this means Next.js is bad at caching. The point is that framework caches and CDN caches solve overlapping but different problems, and the CDN layer is the portable one. It works the same no matter what you build with, and it's hard to beat for the effort it takes. Reach for it first.

References

Cloudflare: default cache behavior — what gets cached out of the box, and what doesn't
Cloudflare: "Cache Everything" via Cache Rules
Next.js caching guide — the four cache layers, explained
Next.js 15 release notes — the caching default changes
MDN: Cache-Control — s-maxage, stale-while-revalidate, and friends