DEV Community: Takafumi Endo

Why Athena/Iceberg Tends to Make Code the Spec

Takafumi Endo — Tue, 21 Jul 2026 03:45:35 +0000

Every time this comes up, someone credits the same setup: Athena on Iceberg is where "the code is the spec" — where you open Git and read the whole system, catalog to transforms to schema, without logging into anything. In my experience they're not wrong.

What I want to argue is that they're right for mostly the wrong reason.

The reason people reach for is the engine — serverless, open format, nothing to provision. But the thing that actually keeps code as the spec, when it does, is something you could have applied to almost any engine. And the thing that breaks it, when it breaks, has nothing to do with Iceberg at all.

So here's the split I've landed on, for now: whether "code is the spec" holds is about 90% discipline and 10% engine. Athena/Iceberg earns that 10% honestly — but 10% is all it earns, and I keep watching people mistake it for the whole thing. (Just where my own tinkering has led — not advice.)

I should say up front that I'm still in the middle of this. What the best declarative setup for an agent actually looks like — how you turn a system into a spec it can read and act on without guessing — is something I'm actively testing, not something I've settled. Read what follows as a working idea at a particular moment, written down partly so I can find out where it's wrong.

To see where the 10% actually lives, it helps to notice that a stateful system always keeps two copies of itself.

The spec has two copies

One copy is declared: the code you wrote, the schema you committed, the transforms in dbt, the catalog in Terraform. The other is realized: the state the engine accumulates while running — statistics, physical layout, caches, maintenance history, tuning knobs someone set at 2am.

"Code is the spec" is really a claim about the distance between those two. When the declared copy explains almost everything about the realized one, you can reason about the system by reading Git. When it doesn't, you can't.

Some of that state is declarable — you can pin a distribution or sort strategy in DDL, dbt, or Terraform. But plenty of it isn't, or drifts away from what you declared: which strategy the engine is actually using once automatic optimization kicks in, when the last vacuum finished, whether statistics are fresh, which materialized view is stale, whether that partition is really being pruned. To answer those you log in and ask the running system. Now your spec is half in the repo and half in someone's head.

So the real question isn't "is my code readable." It's: how much of the truth escaped the code into runtime state I can't see? I've started calling that the hidden-state surface area. Shrink it and the code stays the spec. Let it grow and the code becomes a hopeful sketch.

I argued a while back that rigor compresses — the more precisely you can state a fact, the fewer tokens it takes to hand over. This is the same idea pointed at a platform instead of a function: the smaller the hidden-state surface, the shorter and truer the account of the system you can hand to anyone, human or agent.

Why this is mostly discipline

Here's the part I want to be honest about first, because it's the 90%: the engine doesn't make your system legible. Declarative rigor does.

A catalog expressed as data contracts, transforms as a single dbt DAG, infra as Terraform — that's what makes design intent followable in code. And it's almost entirely engine-agnostic. You can point all of it at Redshift and get something a newcomer can read top to bottom. You can also build an Iceberg-on-Athena setup that's an undocumented swamp of hand-run ALTERs and orphaned partitions nobody dares touch.

I've done both. The readable one wasn't readable because of the storage format. It was readable because the rules were declared, in one place, and enforced. "Iceberg, therefore legible" is a claim I'd push back on if someone else made it — so I should hold myself to the same standard.

If you do nothing else, do this part. It's where the leverage is.

But the engine sets the difficulty

Now the 10% — small, but not nothing. Given equal discipline, engines differ in how much state they insist on keeping inside themselves versus how much they externalize where you can see it. That doesn't decide whether you can make code the spec; it decides how much discipline it costs to keep it that way.

Athena on Iceberg externalizes an unusual amount. The stuff that's normally locked inside a proprietary engine — snapshot history, the manifest of what files exist, the current schema, the partition spec — lives as open metadata that isn't confined to one vendor's internal system tables. You can read it through standard metadata tables ($snapshots, $manifests, $history), through the catalog, or straight from object storage. It's still state, and it still changes at runtime — but the format is open and portable, so the same facts stay reachable from more than one tool.

Redshift keeps more of that truth behind its own interfaces. Materialized-view freshness, VACUUM/ANALYZE history, statistics, workload-management tuning, and — with automatic table optimization or AUTO distribution — the effective physical layout, which can shift with data volume regardless of what you declared. It's all observable; you just query the system views for it.

	Athena / Iceberg	Redshift
Visible in Git / code	Terraform, dbt, contracts, SQL/YAML	Terraform, dbt, DDL, contracts
Runtime state lives...	open metadata (snapshots, manifests, schema, partition spec)	engine-internal: MV freshness, vacuum/analyze history, stats, effective dist/sort under `AUTO`, tuning
To inspect it you...	read open metadata tables, the catalog, or object storage	query the engine's system views
Compute infra to manage?	no dedicated warehouse compute	provisioned: yes · serverless: mostly abstracted
Hidden-state surface	typically smaller, more externalized	typically larger, more engine-bound

The honest framing: it's not that one is readable and one isn't. Both expose their state — the difference is how. One hands you facts in an open format that multiple compatible tools can inspect; the other hands them back through its own interfaces. Same level of legibility, less engine-specific discipline required to preserve it — not necessarily less operational work overall. That's the whole 10%. (This is for the batch-oriented, per-tenant workload I keep describing; a giant, high-churn Iceberg estate grows its own large state surface — manifests, small files, snapshot sprawl, catalog commits, cross-engine compatibility — and the gap narrows.)

Why I actually care: the guesser downstream

Here's where it stops being an aesthetics argument for me.

The real line isn't S3 versus a database. It's this: a fact exposed through an inspectable interface the agent can actually reach is verified; a fact outside its observable context must be estimated. A Redshift VACUUM history the agent is allowed to query is verified; an Iceberg snapshot it has no catalog access or tooling for is a guess. The engine doesn't decide it — reachable evidence does. What Iceberg tends to do is make that evidence easier to expose safely and portably: open metadata is simple to grant read access to without also handing over the keys to a live warehouse.

And the consumer of those facts, more and more, is an agent. These days I'm rarely the one reading the schema first — Claude Code or Codex is, running in the repo, editing a migration, rewriting a transform. What it can see is the declared copy plus whatever interfaces I've wired it into; everything else it infers. The larger the hidden-state surface — or the harder its evidence is to reach — the more of my system the agent is quietly guessing about, and the more defensive lines I tack onto prompts: "check the effective sort strategy first," "don't assume the MV is fresh," "verify before you migrate." When the fact is reachable, it can state it flatly and move on; when it isn't, the best it can do is hedge — and hedging costs tokens and trust.

And this isn't OLAP-only. The agent touches both tiers — on OLTP it edits schema, writes migrations, reasons about a tenant_id guard; on OLAP it changes a dbt model, reads a partition spec, checks whether a snapshot rolled forward. The same question decides it either way: can it reach the evidence for what it's about to do? Legibility-for-agents is one property spanning the whole platform, not a warehouse feature.

It's the same move I make everywhere else

Once I saw "shrink the hidden-state surface" as the goal, I noticed I was already doing it at the architecture level, not just the table level.

The platform I work on keeps three kinds of state deliberately apart — durable relational truth in Postgres, hot disposable state in DynamoDB, private local work in per-user SQLite — and the thing I'm most careful about isn't any one store. It's the crossings between them.

OLTP  (write / update)                 OLAP  (read / aggregate)
┌───────────────────────────┐          ┌──────────────────────┐
│ control-db (Postgres)      │          │ Athena / Iceberg      │
│   durable, relational      │          │   S3 Tables (open     │
│ operational_state (Dynamo) │  ==3==>  │   metadata mart)      │
│   hot, TTL'd               │  bridges │ DuckDB (local)        │
│ metadata.db (SQLite)       │          │                       │
│   local, private           │          │                       │
└───────────────────────────┘          └──────────────────────┘
     the only sanctioned OLTP→OLAP paths are three named bridges,
     and Postgres reaches the lake through exactly one VPC Lambda.

The point of narrowing the crossings to a countable few — and letting Postgres reach the analytics lake through a single path — is the same point as preferring open metadata. Every uncounted pathway is hidden state: a way the system can be true in production in a shape the code never described. Three named bridges I can hold in my head. Twenty accidental ones I cannot, and neither can an agent.

Same principle at two scales: make the crossings and the state legible, so the code keeps describing the system. That the pattern reappears from a single table up to the whole control-plane-to-lake boundary is, honestly, most of why I trust it — though that's a hunch I hold loosely, not a thesis I'd defend to the death.

And this is where I've started spending real budget on purpose. Making OLTP and OLAP legible to an agent — declared schemas, reachable metadata, counted crossings, a system view the agent is actually allowed to query — used to read as tidiness, a nice-to-have for when you had time. With Claude Code and Codex doing more of the actual editing, it's stopped feeling like tidiness and started feeling like the interface I hand the most productive worker on the team. An hour spent making a fact reachable is an hour I don't spend, over and over, writing "be careful, verify this" into prompts — and the payoff compounds every time the agent runs. So I treat agent-legibility as infrastructure worth building, the way you'd invest in tests or types, not polish applied at the end. Whether it fully pencils out depends on how much of your work the agents are really doing; for the amount they're doing in mine, it already has.

Objections I'd raise myself

"So you're saying Iceberg is more readable than Redshift." No — I'm saying it externalizes more state, which lowers the discipline cost of legibility. A disciplined Redshift shop beats a sloppy Iceberg one every time. The 90% dominates; the engine only sets the exchange rate.
"Open metadata isn't zero hidden state." Correct. Compaction, small-file cleanup, maintenance jobs — Iceberg has operational state too. It's smaller and observable-from-outside, not absent. If I implied "no hidden state," that's overreach.
"Athena/Iceberg has its own tax." It does — and it's not about S3 consistency (object storage is strongly consistent now). It's concurrent-write conflicts, catalog commit semantics, small files, compaction, snapshot expiration, and orphan-file cleanup. Athena needs OPTIMIZE/VACUUM against Iceberg tables too. Legibility isn't free; I'm trading one set of runtime concerns for another, and I want that trade stated plainly, not smuggled in.
"This is just a warehouse-vs-lakehouse take in disguise." Partly. But the axis I care about isn't performance or cost — it's the size of the gap between declared and realized. Two separate arguments; I don't want to lean on the popular one to prop up mine.

Where this leaves me

The design goal I keep circling back to is small: shrink the distance between what the code says and what's true at runtime — because that distance is precisely where humans and agents are forced to guess.

Most of the shrinking is discipline: declare the rules, put them in one place, enforce them — the 90%, and no engine does it for you. The last 10% is picking tools that don't quietly hoard state inside themselves, but hand you their truth as metadata you can read, crossings you can count, facts you can verify. Do the 90% and almost any engine can be the spec; do the 10% too and the code stays the spec with less of you holding it together by hand. That's the honest version of what people reach for when they credit Athena/Iceberg — not that the engine makes code the spec, but that it asks less of you to keep it that way.

I want to be honest about how provisional this still is. I don't think anyone, me least of all, has settled what declarative management and code-as-spec should look like once the primary reader is an agent rather than a person. I'm running my own small experiments — which facts to externalize, which interfaces to expose, where the verified/estimated line should sit — and expect to be revising this for a while. The 90/10 is a heuristic I find useful today, not a law I'd stand behind tomorrow.

That, for now, is the shape I'm designing toward — a little more on purpose, a little less out of habit, and still figuring out the edges.

The Agent Runtime Got Heavy: Rethinking Sandboxes with Codex App Server

Takafumi Endo — Wed, 15 Jul 2026 03:06:18 +0000

Once an AI agent moves past being a chat box — reading and writing files, installing dependencies, running tests, watching them fail and retrying — the model alone stops being a product. The agent needs a place to work:

a filesystem
a shell and process execution
language runtimes and libraries
dev tools like Git
long-running processes
execution logs and diffs
permissions and an approval UI
state that survives between sessions

On the web, the usual way to provide this is to spin up an isolated container or microVM per user. AWS, Cloudflare, and Vercel all offer good services for exactly this. But should every agent product own a cloud sandbox?

I wrote before, in The Wrapper Got Heavy, that the thing we used to dismiss as a thin "wrapper" has become a heavy runtime — a sandbox plus an agent loop plus state gravity. This post is something like the sequel. If the runtime got heavy, the next question is where you run it — in the cloud, or on the user's own machine.

Lately I've been recommending a different shape more often. For a single-user agent, I first consider running Codex or Claude Code inside a desktop app. This isn't just "local is cheaper." Moving execution onto the user's PC changes more than infra — it changes how you design file access, state, latency, and the permission UI. Treat what follows as a working thesis, not a final verdict.

TL;DR

For single-user AI agents, a desktop app can be a more natural runtime than a cloud sandbox.

You can use the user's existing environment and compute instead of provisioning a second one in the cloud, and Codex App Server lets you reuse a serious agent loop rather than rebuilding it.

But Codex isn't an SDK — treat it as an embedded runtime that needs version pinning and compatibility management.

Cloud sandboxes have already come a long way

Let me say it up front: cloud sandboxes aren't bad. For public services that must safely run code from many untrusted users, a strong isolation boundary in the cloud is essential.

AWS AgentCore Runtime assigns a dedicated microVM per session. Each session has its own kernel, memory, and filesystem, and on completion the microVM is destroyed and its memory sanitized. The underlying Firecracker is a KVM-based lightweight microVM with under 5 MiB of overhead per VM (AWS's Tools writeup).

Cloudflare Sandbox SDK exposes command execution, file operations, background processes, and port forwarding as an API. You do need to understand its lifecycle: by default it stops after 10 minutes of inactivity and starts fresh next time, so ordinary local disk state is lost — you push durable state out to something like R2.

Vercel Sandbox gives you an isolated Linux microVM (Firecracker) with streaming, file management, network policy, and snapshots in the SDK. Persistent sandboxes are the default: on stop the filesystem is snapshotted, and it's restored on resume.

The hard part isn't "starting a VM"

When you build a sandbox in the cloud, the hard part isn't the boot API. In a real product you also have to solve:

Area	What you have to design
Lifecycle	start, sleep, resume, destroy, timeout
State	persistence, snapshots, caching
Transport	WebSocket, SSE, reconnect, output streaming
Security	network limits, secrets, privilege escalation
Placement	region, cold start, session affinity
Ops	logs, metrics, audit, crash recovery
Cost	CPU, memory, storage, egress, idle time
UX	approvals, progress, diffs, interruption, retries

For example, Cloudflare Containers can take a while to start from a stopped state, and you have to account for routing follow-up requests to the right instance — and for it possibly restarting in a different location. Even AgentCore sessions require carrying a session ID so requests reach the same microVM; lose it and you hit a cold start (microVM stickiness).

None of this is a flaw of the cloud. It's the complexity required to let many untrusted users share one fleet of servers. The question is whether a single-user desktop product actually needs that complexity.

On the desktop, the user's PC is already a finished runtime

A developer's machine already has the working repo, Git history and credentials, language runtimes and dependency caches, Docker and local databases, SSH config, an IDE, and plenty of storage, memory, and sometimes a GPU.

The cloud approach has to recreate all of that in a separate environment, keep it in sync, and persist/restore it as needed (clone, install deps, inject secrets, hand results back). Granted, there are options like Vercel Sandbox where persistence is the default, or Cloudflare's R2-based backup/restore — but the shape of "stand up a separate environment and sync it" remains. On the desktop, you just launch the agent in that directory. No network file sync, no upload to remote storage, no image build required. CPU, memory, and storage aren't metered and billed by a cloud provider to the app vendor — they're resources the user already owns.

One important caveat: even though the Codex or Claude Code process runs locally, LLM inference does not run on a local GPU. File and command operations are local; the model conversation goes over the network. A local GPU can help with workloads the agent kicks off — builds, ML, image processing — but for a single-user agent that's rarely the main draw. The bigger, more mundane wins are fast operations over large local files (parsing, indexing, searching, embedding) on the local SSD, and the user's existing toolchain working as-is.

So what a desktop setup lets the provider avoid, or greatly reduce, is the ongoing cost of sandbox CPU/memory/disk, durable storage, egress, orchestration, and monitoring infra. In return you take on distribution, updates, per-OS support, and the security design of local execution. So this isn't "local is always cheaper" — it's that the cost of compute and the burden of complexity shift from the provider to the user's machine. Even so, not having to run a per-user execution platform is a big deal, I think.

PTY brings interactive local execution into the app

When you embed a tool like Claude Code or Codex CLI in an app, calling child_process.exec() isn't always enough. These CLIs do interactive things: streaming progress, waiting for input, adapting to terminal width, ANSI control sequences, signals like Ctrl+C, and keeping long-lived processes alive.

That's where you need a PTY (pseudo-terminal). Microsoft's node-pty uses forkpty on macOS/Linux and ConPTY on Windows to make a child process believe it's attached to a real terminal. For display you can use xterm.js (the same one VS Code's integrated terminal uses). The overall shape looks roughly like this:

┌────────────────────────────────────────────┐
│ Desktop UI  (Chat / Diff / Approval / Term) │
└──────────────────┬─────────────────────────┘
                   │ restricted IPC
┌──────────────────▼─────────────────────────┐
│ Privileged Host Process                    │
│  Project / Permission / PTY / Audit        │
│  Codex App Server Client                    │
└──────────────┬─────────────────┬───────────┘
               │ stdio JSONL     │ PTY
        ┌──────▼──────┐   ┌──────▼──────────┐
        │ codex       │   │ shell / tools   │
        │ app-server  │   │ tests / servers │
        └──────┬──────┘   └─────────────────┘
               │
        OS-level sandbox → Local filesystem

Note that talking to Codex App Server itself does not require a PTY. App Server connects over ordinary stdio (JSONL); the PTY is for user-facing terminals and interactive child processes (shells, dev servers, progress-drawing CLIs). App Server does have its own PTY-backed command-execution API, but that's separate from the connection transport.

Codex is well suited to embedding in a desktop app

The specific reason I reach for Codex is Codex App Server. It's a local server process for driving Codex's agent machinery from a custom client — not just a prompt-sending API. It handles thread creation/resume/fork/persistence, turn start/interrupt/mid-turn input, approval requests for commands and file changes, streaming of execution events and diffs, config, ChatGPT login, and integration with MCP and Skills.

App Server holds threads as a long-running child process and connects over bidirectional JSON-RPC. A single input produces many events, and when approval is needed the server asks the client and pauses the turn until it answers. The integration pattern is clean: bundle the per-OS Codex binary, pin a verified version, launch it as a child process, and exchange JSONL over stdin/stdout. Codex's own desktop app and VS Code extension use the same shape.

The connection itself is light. You launch the bundled (version-pinned) Codex binary with the app-server subcommand as a child process and connect over standard I/O — stdio is the default transport, so you don't open a network port. Then you read the child's stdout line by line as JSONL: send an initialize request once per connection, and after you get its response, send the initialized notification (it's sent by the client, not returned by the server). Then call thread/start with the working directory (cwd), a sandbox mode (e.g. workspace-write), and an approval policy (e.g. on-request). That brings up one thread, and from there events — model output, diffs, approval requests — flow back on stdout.

In practice you add request-ID-to-Promise mapping, crash handling and restarts, event ordering, backpressure, and handling turns that are suspended for approval. That last set is where the "light" first impression ends — a restart racing an in-flight turn, or the initialization flow itself, is where the real work (and the surprise I hit below) lives. You can generate types matching your bundled binary with codex app-server generate-ts, which makes it easy to pin the binary/client combination. There's also a WebSocket transport, but it's officially experimental/unsupported; inside an app, keeping ports closed and using stdio is simpler and safer.

You get Codex's own local sandbox

Running the agent locally is not the same as letting the model do anything it wants with the user's privileges. Even locally, Codex combines an OS-enforced sandbox and approval policy:

macOS: Seatbelt
Linux / WSL2: bubblewrap (bwrap) + seccomp (falling back to a bundled helper that relies on user namespaces if bwrap isn't present)
Windows: a native sandbox using a dedicated low-privilege user, filesystem boundaries, and the firewall when run in PowerShell; the Linux sandbox when run in WSL2

In the standard workspace-write + on-request setup, going outside the working directory or reaching the internet requires approval. Sandbox and approvals are two separate dials: the former controls what's technically possible, the latter controls when to stop and ask. You don't have to build per-OS sandboxes from scratch — the execution side rides existing boundaries. App Server also returns approval events as structured data, so instead of making users type y at a raw log, you can build a product-native approval dialog.

Even so, embedding Codex isn't simple

Having written up the upsides, I should be honest that embedding it carries a real cost of keeping up.

When I recently upgraded Codex to the 0.144 line, an implementation that had been working stopped working, and recovery took real effort. I can't be sure the cause was only a specific change on Codex's side. Around the same time, users reported cases like app-server crashing right after launch in an environment bundling 0.144.0-alpha.4, and — after a desktop-app update — trouble with in-app browser control and with how running services were handled on restart. These are user reports, not a confirmed root cause or a documented spec change, but they point at the same thing: not just the agent's protocol but its updates and process lifecycle now need verifying.

This is exactly why the earlier "pin the binary version and generate schemas from it" matters. One distinction worth drawing: backward compatibility of the JSON-RPC protocol and compatibility of the whole runtime including process management are not the same thing. Even with a stable message contract, lifecycle-level incompatibilities can bite — binary replacement mid-update, a running turn racing a restart, stale runtimes lingering, missing helper binaries.

In our own case, the root cause wasn't the JSON-RPC protocol at all — it was the initialization flow. After initializing, App Server tried to connect to Remote Control, but our embedding context had no ChatGPT auth, so it retried forever and hung — presenting as won't start / freeze / a flood of errors. And the trap: setting -c features.remote_control=false did nothing — it's treated as an unknown key, silently a no-op. The switch that actually worked was an internal environment variable, CODEX_INTERNAL_APP_SERVER_REMOTE_CONTROL_DISABLED=1. The config surface and the runtime's real behavior had diverged, and the only working knob was undocumented and internal — which is precisely the kind of failure you don't get from an SDK, and do get from a runtime you embed.

What I took from this: don't treat Codex App Server like an ordinary SDK. Codex is a runtime you embed in your app. You want to pin, test, and be able to roll back the binary, schema, config, launch method, and process lifecycle as a single compatibility unit. In fact OpenAI itself describes bundling per-platform binaries and pinning to a tested version in its VS Code extension and desktop app. An upgrade is something to verify and then switch to, not something to follow unconditionally — that's my current operating stance.

Separate the UI process from the execution process

"Local" doesn't mean "safe." The agent's process sits close to the user's files, credentials, SSH config, and browser data — so the app's own privilege separation matters.

With Electron, don't let the renderer touch Node.js or the PTY directly. Enable the renderer sandbox and context isolation, and keep privileged operations in the main process or a narrow preload API. Expose to the renderer only vetted operations — start a thread, approve, interrupt, subscribe — and never a way to run arbitrary shell commands or read/write arbitrary paths. Manage the PTY and App Server on the privileged side. Tauri is the same idea: define per-command permissions and capabilities and minimize what the WebView is granted.

The UX advantages of the desktop shape

More than the infra savings, I think the UX difference is what really matters.

The files are already there. No waiting on upload or sync; you work directly against the current tree, including uncommitted diffs and local-only config.
You reproduce in the same environment. A problem that only happens on the user's machine can be investigated with the same OS, deps, and local services.
Big file operations are fast. Search and Git-history walks finish on the local SSD, without one HTTP call per operation.
Existing tools just work. The user's already-configured linters, test runners, Docker, Xcode, Android SDK, and so on are all available.
Approvals are easier to make meaningful. You can tie an approval for a write target, a network destination, or a command to the OS file picker and notifications.

The desktop shape has clear weaknesses too

It isn't always the right shape. Objections I'd raise myself:

If the machine stops, the agent stops. Sleep, power loss, and disconnects all hit it. Claude Code's Remote Control lets you steer from another device while execution stays local, but that's different from a cloud environment that keeps running while your machine is off. For long-running work you can combine SSH or a managed remote environment and split UI from execution.
Environment variance is large. Shell, paths, permissions, PTY, and package management differ per OS. "You can leverage the user's environment" and "you can't reproduce it" are two sides of the same coin.
Distribution and updates become a compatibility problem of their own. A cloud sandbox lets the provider update the runtime centrally, in one place. On the desktop you need a delivery pipeline that pins — and can roll back — the binary, schema, config, and launch method as one compatibility unit, and threads that unit through auto-update, not just development. (We track Codex versions with a weekly workflow and a lockfile-pinned version.)
You're close to secrets. A local agent can reach more sensitive data than a disposable cloud environment. Don't skip the working-directory boundary, network limits, approvals, and audit logs.
Not for running anonymous users' code. Playgrounds, online IDEs, coding tests, generated-UI previews and the like still need a cloud sandbox.

Which should you choose

Roughly, I'd think about it like this:

Requirement	Better fit
A single user operating their own files	Desktop
Leverage an existing local dev environment	Desktop
Handle lots of local files fast	Desktop
Investigate a problem specific to the user's machine	Desktop
Keep running while the machine is off	Cloud
Run anonymous users' code	Cloud
Guarantee an identical environment for everyone	Cloud
Update the runtime centrally, without per-client compatibility work	Cloud
Use centrally managed secrets	Cloud / managed remote env
Concentrate high-end GPU usage	Cloud / dedicated remote env

In a real product, a hybrid is natural: everyday work on Desktop + Local Codex, long or heavy jobs on a remote environment or Cloud Sandbox, untrusted code in a Cloud Sandbox, review and approval in the Desktop UI.

There's another axis worth using: the client form factor. Even within one product, I'd lean the desktop app toward a serious runtime — the side that embeds the heavy local work environment — and lean the web browser toward lightweight features — pushing heavy execution to a cloud sandbox and keeping the browser to viewing, approvals, and light tasks. The point is to separate where the heavy runtime lives from where you keep only a light surface.

This continues the argument from The Wrapper Got Heavy. Now that the runtime is heavy, the design question isn't "which client calls the model" but "where does that heavy runtime live, and where does the state gather?" By state gravity I mean the pull that draws the runtime toward wherever the state — the repo, dependencies, auth, caches, running processes — already collects. Seen that way, heavy execution belongs where the hardware and state naturally gather — the desktop app — while the browser stays a light window onto it.

Wrapping up

A capable agent needs a runtime with files, a shell, libraries, processes, and state. Providing that on the web means a large substrate — microVMs or containers, durable storage, network controls, lifecycle management — and AWS, Cloudflare, and Vercel provide it powerfully.

For a single-user desktop app, though, the user's PC is already a high-performance, persistent agent environment. Launch Codex or Claude Code from a desktop app with PTY support and you reuse the existing files, tools, caches, and compute. And Codex App Server exposes threads, events, diffs, approvals, auth, and config over bidirectional JSON-RPC, with embedding into local apps and IDEs officially in scope. That Codex carries its own OS-level sandbox is another implementation win.

Before building a cloud sandbox, it's worth asking once: does this agent really need to run on the provider's servers? If it operates the user's own files and tools, the first candidate might not be a web app plus a microVM. Desktop × PTY × Codex is becoming a practical default for this class of agent — at least, that's my current view.

Service and Codex App Server specifics reference the official docs as of July 2026; this area moves fast, so check the latest before relying on any detail.

Designing Schema Boundaries for AI Agents

Takafumi Endo — Wed, 08 Jul 2026 10:48:44 +0000

An agent can now change your whole persistence stack in one pass.

Ask Claude Code or Codex to "add a plan_tier to accounts and wire it through," and it will read the repo, edit the Drizzle schema, generate a SQL migration, update the dbt source, touch a model, regenerate the TypeScript types, add a test, run the build, read the failure, and fix it. Multi-file, coherent, green. A year ago that was an afternoon; now, in a well-shaped repo, it's a prompt.

For a while I read that as pure upside — schema changes stopped being bottlenecked on how fast a human can hand-write a migration. Now I think the upside came with a quieter inversion: the same speed that makes good changes cheap makes unsafe changes cheap too. And the unsafe ones are exactly the kind that pass review, because they look consistent.

I've written before about handing agents short, verified facts instead of asking them to be careful. This is the same argument aimed at the database — the place where a confident wrong move is most expensive. It's a working theory, not a universal rule.

Where I've landed for now (and expect to keep revising):

Agents making schema changes cheap is good. It's not the problem.

The problem is that the change is cheap while the verification boundary is still shaped for the human-migration era.

The dangerous change isn't the one that fails to build — it's the one that builds fine and quietly breaks a contract downstream.

What's missing isn't a better prompt or a stricter reviewer. It's a compiler that lowers every declaration onto one contract graph and judges the change against it.

One definition up front, so the rest reads cleanly: by contract compiler I mean a tool that reads every declaration of persistence shape — ORM schema, SQL DDL, dbt artifacts, object manifests, SDK types — lowers them into one graph, and evaluates a change against it as a set of operational hazards. Not a migration runner, not a codegen step. A judge.

The new reality: the agent writes the schema

It's worth being concrete about how wide the blast radius of a single "small" schema change already is. When an agent touches one column, the coherent version of that change spans:

Drizzle / Prisma / SQL DDL  →  migration plan     →  dbt source
        ↓                            ↓                    ↓
   app types / SDK          backward compat?         dbt models
        ↓                            ↓                    ↓
   API contract             RLS / tenant guard      Parquet export → S3/R2

(I write migration plan rather than migration on purpose: whether you're SQL-first or ORM-first, the migration is a derivative of a desired state, and it's the desired state the graph should be built from.)

An agent will happily update all of those in one commit, and it will make them look mutually consistent. That's the impressive part. It's also the trap: internal consistency across the files it edited says nothing about consistency with the things it didn't — the live database, last week's published artifact, the SDK a client already pinned, the PII policy that lives outside the repo.

So the interesting question stopped being "can the agent implement the change?" It obviously can. The question is: who verifies the contract graph the change lives in?

The hazard is the green build

Here's the shape of the risk, because it's not the one people reach for first. The scary agent change isn't the one that throws a compiler error — you'll catch that. It's the one where everything is green and the damage is semantic:

nullable quietly tightened, so old rows now violate a constraint that only bites on the next write.
a type narrowed — text → varchar(32) — that truncates in production and nowhere else.
an enum or code value removed or remapped, so historical rows decode or compare differently.
a rename modeled as drop-plus-add, which reads to every downstream consumer as data loss.
a PII column newly exposed to an analytics model and, three hops later, sitting in a Parquet export.
the dbt source left stale, so the model builds against a schema that no longer exists.
a dataset's Parquet schema changed without a version bump, over-writing current so yesterday's reader silently gets today's shape.

Many of these slip straight through a CI that only asks whether the SQL parses and the build passes. Wire in dbt contracts, source tests, migration lint, Atlas, or integration tests and some of them get caught — but the default "does it build" pipeline doesn't ask whether the change is destructive, backward-incompatible, or contract-breaking. In the human era that gap was survivable — changes were slow, and a reviewer's eye covered a lot of it. Speed removes the slack. When agents can produce these changes repeatedly, "a human will notice" stops being a control.

The failure I most want to avoid is the one that reads as safety. A green build on a breaking change is exactly that.

The lightweight stack is great — and it doesn't close the loop

I want to be fair to the tools this sits on, because I like them a lot.

dbt is genuinely good at the analytics side of this. Model contracts let you declare the shape a model must return — the column names and types — and at least the build fails when the logic drifts from that shape. (How far the constraints are actually enforced depends on the data platform, but as an analytics-output contract it's strong.) dbt-duckdb lets you run the whole DAG against an in-memory DuckDB inside a CI job, and its external materialization exports CSV/JSON/Parquet straight to a location you choose. Pair that with S3/R2 and you get a lightweight publish layer: compile the transformation, test it locally, publish the result, no long-running warehouse required.

The important detail isn't that the file lands in a bucket. It's that the artifact becomes another contract surface: a schema hash, a versioned path, a manifest, and a current pointer that consumers may already be reading. Overwrite that pointer with a new shape and you haven't "updated a file" — you've changed a contract other systems depend on, silently. Hold that thought; it's where a hazard I'll later call UNTRACKED_LATEST_OVERWRITE comes from — a name from this article's own vocabulary, not a standard.

But dbt's contract is an analytics-output contract. dbt can declare sources, test them, and watch their freshness — but that isn't ownership of the ops database's lifecycle. Indexes, constraints, RLS, triggers, extensions, tenant boundaries, PII classification, the app's ORM types — all of that lives upstream of the source block, managed by Drizzle, Prisma, Atlas, or hand-written DDL. dbt sees a projection of it and trusts the projection.

So the loop isn't closed. The analytics contract depends on an ops contract that nothing verifies it against — and the agent is now editing both ends at once.

What's missing is a harness

We already accepted this idea on the agent side. Nobody runs a raw model against a shell; you wrap it in a harness — the loop that orchestrates tools, prompts, permissions, and execution. OpenAI has used the language of an agent loop and harness around Codex CLI.

My claim is small: schema changes need a harness for the same reason agent loops do — an untrusted author producing fast, plausible actions against a system where mistakes are expensive. The author being a model rather than a human doesn't change the requirement; it sharpens it.

The shape I keep arriving at is four roles:

Author     human or agent writes desired state
           SQL DDL · Drizzle · Prisma · Atlas HCL · dbt SQL + YAML
              │
Observer   reads live state
           DB introspection · dbt artifacts · S3/R2 manifests · registry · pointers
              │
Compiler   lowers everything into one IR
           table · column · constraint · source · model · artifact · policy
              │
Evaluator  turns diffs into decisions
           safe · warning · blocked · requires-human

The Author is deliberately untrusted. I don't care whether a person or a model wrote the migration — I care what the Compiler and Evaluator say about it. That single stance is what makes the whole thing agent-ready: you don't have to trust the writer if you can judge the write.

Which is exactly why the Observer matters as much as the Author. The live database and the authored declaration have to be independent inputs. If the compiler only reads the migration the agent produced, it's grading the agent's story about the world — not the world. The whole point is to check the write against a state the writer didn't get to narrate.

Lower to an IR, don't diff strings

The declarations are all different renderings — SQL DDL, TypeScript, a Prisma schema, HCL, dbt's SQL + YAML + manifest.json, a DuckDB catalog, a Parquet schema, an object key. Compare any two as text and it breaks on the first reformat. So the Compiler lowers each into a common intermediate representation and compares that:

// illustrative, not a real schema — the point is which fields exist, not the format
type Column = {
  name: string
  type: string
  nullable: boolean
  semantic?: string      // 'email' | 'money' | 'tenant_id' | …
  sensitivity?: string   // 'public' … 'restricted'
  pii?: boolean
  lineage?: Ref[]        // where it came from, where it flows
}

A table carries analogous facts (keys, constraints, indexes, access policies); an analytics model carries its dependencies, its output columns, and how it materializes. The exact shape isn't the interesting part — what matters is that ops objects, dbt models, and published artifacts all land in one vocabulary the evaluator can reason over.

The point that took me a while: the IR is a unit of judgment, not an output. Types, validators, SDK clients, sources.yml, Parquet schemas, policy bundles — those are all derived from it. dbt's manifest.json is, in effect, the analytics-side IR you already have; the missing half is lowering the ops side into the same shape so the two can be compared at all. Whatever the agent writes, in whatever format, ends up flowing through one evaluator.

Hazards, not diffs

A diff tells you what changed. It can't tell you whether that's safe — and safe/unsafe is the only thing a gate actually needs. So the Evaluator turns a diff into a classified hazard with its blast radius attached, and emits it as structured data, because the readers are CI and an agent as much as a person. Something along these lines — the exact fields matter less than the idea:

{
  "status": "blocked",
  "hazards": [
    {
      "type": "COLUMN_DROP",
      "severity": "critical",
      "object": "ops.users.email",
      "affected": [
        "dbt.source.raw_users",
        "dbt.model.mart_users",
        "sdk.User.email",
        "artifact.customer_segments.v1"
      ],
      "reason": "column is still consumed by downstream models"
    }
  ],
  "nextAction": {
    "kind": "expand_contract",
    "requiresHumanDecision": true
  }
}

CI's question stops being "is there a diff" and becomes "what's the highest severity, and does anything here need a human." The vocabulary of hazards is finite and worth naming, though I won't try to enumerate it here — a column drop that's still consumed downstream, a type narrowing, an enum remapped, PII that reaches an export without a policy, a published artifact whose schema changed under a live pointer. They group loosely by where they originate: the ops schema, the analytics models, or the published artifacts. (The names I give them across this post are my own shorthand, a design vocabulary for the argument, not a standard.) Let the agent implement. Don't let it past the Evaluator.

Make the Boundary Machine-Readable

Everything above works with a human author too. Here's what changes when the author is a model — and it's the part I find most underrated. Give the agent the contract, not vibes.

If the harness can judge a change, it can also tell the agent the rules before the change. Instead of a paragraph of "please be careful, watch for breaking changes," you give it something machine-readable: which classes of change are pre-approved (adding a nullable column, an index, a test), which are off-limits without a deprecation path (dropping a column, exposing PII without a policy, overwriting a live pointer), and what the migration policy is (breaking changes go through expand–contract; a dataset shape change forces a version bump). The specific encoding doesn't matter much; treating the boundary as data the agent can read does.

Now the instruction isn't "fix it nicely." It's: change this so no hazard exceeds warning; if a critical is unavoidable, don't implement — return a plan. The agent iterates against structured feedback (a hazard verdict) instead of against a green checkmark that means nothing. Breaking changes come back as expand–contract plans, not as a DROP COLUMN that happened to compile.

This is the same thing I keep chasing in every one of these posts. The reason I stopped tacking "don't guess, verify, watch for false negatives" onto every prompt isn't that I started trusting the agent more. It's that the facts I hand it — and now the actions I allow it — carry their own guarantees. When "you may not expose PII without a policy" is a blocked action and a blocking hazard, I don't have to ask the agent to respect it.

Which points at the shift underneath all of this. The scarce skill is no longer writing the migration — an agent will write ten before lunch. The scarce skill is defining the contract that decides whether a migration is safe. That's the part that doesn't get cheaper when the model gets better; if anything it gets more valuable.

A few patterns fall out of this once the boundary is a compiler rather than a reviewer's attention — which is the point where "what does this look like in practice" deserves its own section.

What I would put in CI

None of this is real until it's a gate. What I want is for the harness to run like any other CI check — except that the question it asks is a different one. The loop, end to end:

AI agent
  │ proposes change
  ▼
Author files
  Drizzle · Prisma · SQL · dbt · SDK
  │
  ▼
Contract Compiler
  ops IR · analytics IR · artifact IR
  │
  ▼
Hazard Evaluator
  safe · warning · blocked · requires-human
  │
  ├── safe ──────────────▶ merge
  ├── warning ───────────▶ review
  └── blocked ───────────▶ agent gets structured feedback,
                            returns a plan instead of a change

The principle, not a spec: the gate compiles the proposed state and the live state into the same IR — independently — joins the dbt and artifact sides onto that graph, and returns a hazard verdict rather than a build result. It blocks on critical, routes the ambiguous cases to a human, and lets the safe majority through untouched. The mechanics of how you introspect the database or where you read the last published manifest are the boring, swappable part; the load-bearing idea is that CI evaluates a graph, not a syntax tree.

A few principles keep the gate calm to live with rather than something people route around: begin from a plan, not a diff; don't let the analytics source definitions and the ops schema drift into two hand-maintained copies of the same truth; and treat a published artifact as versioned and its live pointer as a deliberate move, not an overwrite. How you implement each is a taste question; that you don't skip them isn't.

The shift in one line: CI stops asking whether the migration builds, and starts asking whether the contract graph is still safe.

Objections I'd raise myself

"This is just linting / dbt contracts / Atlas." Those exist and they're good — Atlas flags destructive ops changes, dbt contracts pin analytics output. What none of them does alone is carry a pii label from an ops column to a Parquet export, or block a publish on that basis. The gap is the edge between the tools, which is precisely where an agent editing both ends creates trouble.
"Why not just give the agent more context?" Because the missing thing isn't context volume, it's a decision boundary. More repo text doesn't tell the agent whether a column drop is safe — the answer isn't in the files it's reading; it's in the graph across them. A contract graph can decide it; a bigger window just lets the agent read more of the question.
"You're just distrusting the model." The opposite. Distrust would be forbidding agents from touching schema. This lets them touch everything — and makes the boundary a compiler instead of my nerves. I'd apply the same harness to myself.
"Over-engineering for a three-table app." Yes. Below some size, a human reading the diff is the right control. The harness earns its keep exactly when change volume outruns human attention — which is the situation agents create.
"Hazard rules will have false positives." They will, and a conservative gate that occasionally blocks a safe change is a trade I'll take over one that occasionally ships a silent breaking one. But "tune toward missing fewer real hazards" isn't enough on its own — a gate that cries wolf gets muted, and a muted gate is worse than none. So the real requirement is that false positives be explicit, suppressible with evidence, and tracked as policy exceptions rather than quietly tolerated. An override should leave a record, not a shrug.

Where this is going

I came in through "agents make schema changes cheap" and walked out at something more structural: SQL DDL, an ORM schema, a dbt model, a Parquet schema, an S3 manifest, and an SDK type are all renderings of one contract — and in the agent era, the author of every one of those can be a model moving fast. Manage them as separate files reviewed by tiring humans and the speed becomes a liability. Lower them to one IR, judge changes as hazards, and hand the agent the boundary as context — and the speed goes back to being the gift it was supposed to be.

I hold the strong version loosely. The four-layer split and the IR-first stance feel more right the more I sit with them; the exact hazard taxonomy and how far to automate the boundary versus leave it to review are edges I'm still finding. And maybe for an analytics-first shop the honest answer is still a warehouse and shared Postgres with a careful reviewer, and this is a monorepo-shaped preference more than a law.

But the direction feels clear enough to design toward. Let the agents write the schema — the migrations, the models, the types, all of it. Just don't let the safety of it rest on how the diff happens to look on a given afternoon.

Agents should write schema changes. Whether a schema change is safe should be decided by a contract compiler — not by vibes, and not by whoever happens to be reviewing at 6pm.

AWS Is Not Simpler. Agents Just Got Better at Reading It.

Takafumi Endo — Tue, 07 Jul 2026 09:46:03 +0000

I optimized my architecture for the wrong model.

I used to think black-box infrastructure was the right abstraction for AI-driven development.

Vercel, Supabase, Cloudflare Workers — a sharp contract in front, a managed backend behind — felt like the obvious fit. The less an agent had to reason about, the fewer places it could get lost. Give it a clean interface, hide the messy backend, move fast.

I still think that was right for the agents we had last year. I don't think it's right for the agents we're starting to use now.

The shift is not that AWS got simpler. It didn't. Setup still takes longer, CI/CD takes more work to wire, and cost control has real limits. The shift is that agents got better at reading complexity — and once an agent can actually use a large structured context, the things I treated as overhead (resources, provider schemas, IAM policies, explicit queues, explicit alarms, explicit networks) become the highest-signal context I can hand it.

To keep this concrete, I'm holding the tool constant. This is HCL/Terraform on AWS vs HCL/Terraform on Cloudflare — same language, same workflow, two providers.

The inversion

Agents are…	Best served by…
Context-poor (last year's loops)	Black boxes — shrink the surface, hide the backend
Context-rich (now)	Inspectable systems — describe everything as code

The one-line version:

The better agents get at reading, the more valuable explicit infrastructure becomes.

I didn't become more pro-AWS because AWS got easier. I became more pro-AWS because agents got better at reading it.

Same Terraform, two providers

The interesting comparison isn't AWS-elegance vs Cloudflare-elegance. It's how much of the infrastructure topology and operational contract an agent can reconstruct from the HCL plus the provider schema alone.

	Terraform × AWS	Terraform × Cloudflare
Provider maturity	AWS provider is about as battle-tested as IaC gets; enormous public corpus of modules/examples	v5 is a ground-up, OpenAPI-generated rewrite — improving fast, but breaking and still stabilizing on a short cadence
Schema faithfulness	AWSCC is auto-generated from the CloudFormation resource schema, so it tracks CloudFormation coverage closely and picks up new services fast	Generated from OpenAPI; solid for resources, but Workers abstractions sit above what HCL expresses
What's visible in HCL + schema	Most of the infra topology and operational contract — queues, roles, permissions, schedules, alarms, networks, data-plane wiring	That a binding exists — but its behavior lives in `wrangler.json`, Worker code, D1 migrations, `package.json`, framework conventions
Infra shape reconstructable from HCL?	Infra shape: largely yes. App semantics: no.	Infra shape: only partially. App semantics live elsewhere.
Terse-prompt tolerance	High — common patterns are well-represented	High for small stacks; drops once Workers + D1/R2/KV/DO/Queues/bindings interact

The Cloudflare row isn't a knock — it's the crux. A Terraform file can tell an agent that a binding exists. It can't, by itself, explain how that binding is used, where responsibility sits between Worker code and storage, how migrations relate to runtime behavior, or which framework conventions are doing invisible work. With AWS-via-Terraform, far more of the infrastructure topology and operational contract is visible through the same artifact: queues, permissions, schedules, alarms, networks, roles, policies, data-plane wiring. The application still matters — Lambda code, migrations, and API specs are not in the HCL either — but the infra shape is less hidden from the agent. That's not because AWS is simpler; it's because AWS puts more of the operational contract into the same inspectable artifact.

Cloudflare is a different bet, not the wrong one

Workers, D1, R2, KV, Durable Objects, Queues, and framework-native deploy form a genuinely coherent platform. For cost, speed, and operational lightness it's one of the best balances available, and I reach for it happily.

It just isn't optimized around the same kind of explicitness. Cloudflare is improving Terraform — v5 is a real, OpenAPI-generated step up in coverage and API alignment — but its more interesting strategic move is elsewhere: intent-based, framework-native provisioning (VoidZero/Vite, Astro), where you read intent from the framework and provision the infra. In its VoidZero acquisition framing, Cloudflare describes a future where a single Vite deploy command detects an app's need for a database or object store and provisions resources like D1 or R2 with no manual dashboard step. That's a coherent future. It's simply a different bet from "everything explicit as code," and it's why HCL-on-Cloudflare underdetermines the system today. Evaluate Cloudflare as framework-native infra, not as Terraform that happens to target the edge.

The safety boundary (this is not "walk away")

Inspectable substrate is half the story. The other half is a loop that closes correctness with plan, policy, and tests — not with the model's confidence. Two Terraform-specific studies make the same point: surface success is not the same as being correct.

Looks like success	What actually happened	Study
Structured schema knowledge made the model a much better coder	Baseline overall success was 27.1%; with injection, technical validation reached 75.3% and overall success 62.6% — but intent alignment plateaued, the "Correctness–Congruence Gap." Valid HCL ≠ the infra you asked for.	Nekrasov et al., 2025
One-shot security "fixes" made the flagged issue disappear 83% of the time	Only 10% were actually clean, and 57–71% were deceptive fixes — the scanner went green, the hole stayed open.	TerraProbe — Alsaid et al., 2026

TerraProbe in particular was run the way you shouldn't ship: first-pass, minimally-prompted repairs, not a high-context, closed-loop workflow. That's the point — it's evidence for the loop, not against agents. Nekrasov et al. make the complementary case: even when structured knowledge improves validity, valid HCL still isn't the same as the infra you intended. A green check is not proof. So the substrate feeds a closed loop:

#	Stage	On failure
1	NL request	—
2	Pull provider schema + module docs (via MCP)	—
3	Generate HCL	—
4	`fmt` / `validate` / `plan`	plan diff → back to 3
5	Policy scan — Checkov / tfsec / OPA / Conftest	violation → back to 3
6	Cost estimate	—
7	Smoke test in an ephemeral env	—
8	Apply — with human review	—

The loop is the point: a plan diff or a failed policy check routes back to regeneration, never forward to apply.

Pulumi is the interesting exception here: it keeps most of the AWS schema substrate (its providers are bridged from the same Terraform providers) but swaps HCL for a real language — so the agent gets the compiler and type system as an extra oracle. The risk is the mirror image of the power: real languages also let agents get clever, so you lean harder on preview, policy-as-code, and tests to keep it declarative in spirit.

Why this isn't an AWS victory lap

I'm not returning to AWS because it's lighter. It isn't. Environment setup takes longer, CI/CD takes more work, cost control is harder than on a tightly scoped platform, and there's more surface area — more IAM, more policy, more wiring, more ways to be wrong.

But that surface area is also more explicit. For human-only development, the explicitness often felt like drag. For AI-driven development, it increasingly feels like leverage. The infrastructure I used to hide from the model is becoming the infrastructure the model needs to read.

That's the real shift.

Cloudflare may still win the intent-native path. Vercel and Supabase may still be the right answer when the contract is small and the backend should stay out of sight. But for enterprise requirements, complex systems, and agents that need to make grounded changes across infra and application code, HCL-on-AWS is hard to beat — not because it's elegant, but because it leaves more of the system inspectable as code.

Opaque platforms were useful when agents were context-bound. Explicit infrastructure becomes useful when agents are context-rich. We're crossing that line now.

If you've made the opposite call — betting on intent-native, framework-first infra for agentic dev — I'd like to hear how it's holding up. That's the fork I'm least sure about.

You Can't Review an Agent. You Can Review a Plan.

Takafumi Endo — Mon, 06 Jul 2026 09:45:05 +0000

A harness for AI-era Terraform.

I'm building one. For a while now I've been developing a harness for infrastructure-as-code as a private SDK and compiler — the layer that sits between whoever proposes a change (a person, an agent, CI) and whatever actually reaches production. This post isn't the tool. It's the thinking underneath it, and the few pieces I've become most convinced by while building it. (Notes from inside the work — where I've landed so far, not advice.)

The problem that sent me down this road is easy to state and easy to underrate.

A version of it happened recently. An agent fixed some Terraform; the PR read clean — tidy diff, sensible resource names, a plan output that looked exactly like what I'd asked for. It got approved. And then, at apply time, a different plan ran than the one that was reviewed: apply had re-planned against state that moved in between, and the diff that touched production wasn't quite the diff anyone had read.

Nothing broke, that time. But that near-miss is the whole reason the harness exists.

Because the danger was never "the agent writes bad HCL." Agents write perfectly good HCL; I let them. The danger is the distance between the plan a human reviewed and the plan that actually runs — and once agents are the ones proposing changes at volume, that distance is the thing I most want to nail shut.

Where I've landed for now (and expect to keep revising):

What AI-era IaC needs isn't AI that can apply. It's a structure where every change — human or agent — is evaluated at the same boundary, and only a reviewed plan ships.

The unit of trust isn't the agent. It's a specific, reviewed plan, bound byte for byte.

You can't review an agent. You can only review a plan.

Instructions to an agent can be broken. A CI gate can't be talked out of it. Put guidance in the prompt; put the guarantee in the gate.

Terraform/OpenTofu don't go away. You wrap them in a harness; you don't replace them.

Your repo has non-human authors now

For years IaC had a comfortable shape: a human writes HCL, a human reads the plan, the same human or a teammate runs apply. The author and the applier were the same kind of thing — a person: slow, few, accountable. Reviewing the author and reviewing the change were nearly the same act.

That assumption is quietly breaking, and it's breaking because of who's holding the keyboard. GitHub's Copilot coding agent, OpenAI's Codex, Claude Code in GitHub Actions — agents now open issues, push branches, and answer review comments in the repo, and standards like MCP and AGENTS.md are there so they can read your docs, state, and conventions and act on them. The detail that matters isn't any one of those tools; it's the implication: the IaC repo stopped being a place only humans edit. It's a place agents propose changes too.

And here's the part you can't review your way out of: you can read one agent's PR carefully, but you cannot review the agent. It isn't a colleague who earns standing over quarters; it's a process that opens the next PR just as confidently whether or not the last one was sound. Confidence is flat. Correctness isn't.

Reviewed and applied are two different facts

So "get the agent to write Terraform" solves the easy half. The half that matters is: what evaluates the change, and is it the same thing for everyone?

terraform plan reads remote state and produces a diff against your config. Save that plan and apply it, and Terraform runs exactly those actions with no further prompts. Don't save it — re-plan at apply time — and the gap reopens: state may have drifted, a variable may have moved, and the diff that runs is no longer the diff that was read. That's the near-miss from the top, in one sentence.

So the thing worth binding isn't the PR. It's the plan. Call it a plan fingerprint — an identifier over the saved plan, bound together with the findings it was reviewed against and a signature, so apply can refuse anything whose fingerprint doesn't match an approval record. That core — plan, findings, signature — is the part I lean on today. What I want folded into the identifier is wider: the plan JSON, the variables, the policy bundle, the workspace, the provider lock, and the toolchain (Terraform/OpenTofu version, provider versions, runner image, state version), because a plan is only as reproducible as the environment that produced it. I'm still widening what goes in; the honest state is a solid core and a growing edge.

One caveat worth stating early: the fingerprint can be public, but the artifact behind it probably shouldn't be. Saved plans and plan JSON can carry sensitive values, so treat them as sensitive build artifacts, not something to paste into a PR comment.

The fact I want the gate to be able to state flatly looks less like a paragraph and more like this:

IAC.PLAN_DRIFT   approval=#4821   severity=high   quality=verified
  claim:   applied plan ≠ approved plan
  cause:   apply re-planned against state changed after approval
  bind:    plan_hash + findings + signature   (+ vars/policy/toolchain: target)
  next:    reject apply | re-request approval on new fingerprint

A pattern-match can only hedge — "this might not be the reviewed plan, please double-check." A fingerprint comparison states one thing flatly: this is not the plan you approved. The rigorous check is the shorter one.

The harness, in four boxes

I keep drawing the same four boxes, so I've stopped pretending they're incidental.

Author      what do we want / why       (humans and agents write here)
Compiler    how is it implemented       (HCL today: Terraform / OpenTofu)
Observer    what is true right now       (state, drift, DB, audit, cost, history)
Evaluator   are we allowed to do it      (policy, fingerprint, approval, signature)

Author — intent. What do we want, and why. Both humans and agents write here, freely.
Compiler — translation. Intent into whichever engine you run — swappable by design, though today that's the HCL engines (Terraform/OpenTofu).
Observer — reality. More on this below; it's the layer most people under-build.
Evaluator — judgment. The only layer that can say no.

The load-bearing idea: Author and Compiler can be as smart or as sloppy as they like, because nothing they produce reaches production without clearing the Evaluator. You move safety out of "trust the writer" and into "verify the plan" — which is precisely the move that survives the writer becoming an agent. Most of what I'm building lives in the Compiler and Evaluator boxes; the other two are where it plugs into the world.

And to be clear about the engines underneath: Terraform, OpenTofu, and Pulumi are genuinely excellent — I reach for them daily, and the harness wraps them rather than replacing them. But none of them was designed AI-first; each still assumes a human author, a human reviewer, and a human at the apply prompt. That's not a criticism so much as headroom. The engines are great, and there's still real room for the layer above them — and, eventually, the engines themselves — to evolve into something an agent can be trusted to drive.

Observer isn't monitoring

The layer I see skipped most is Observer, usually collapsed into "we have some dashboards." But in an AI-era harness it's doing something specific: giving every actor — human or agent — a grounded picture of the world before they propose against it. Drift was already a problem when only humans touched the cloud; once agents and external tools change things through the API, an out-of-band change the Observer can't see is a blind spot the whole harness inherits. (Recent research is even throwing LLM agents at reconciling out-of-band changes back into code, which tells you it isn't solved.)

What I want Observer to actually gather:

Terraform/OpenTofu state, and cloud provider inventory
drift detection, and CloudTrail / audit logs
DB schema state
cost data, and security posture
policy-violation history, and incident / change history

With that, an agent references not just "the current code" but "the real environment," "the intent," and "what went wrong last time."

One gate, no side doors

A harness only works if there's no side door. The same boundary has to apply to the human on their laptop, the agent in the repo, the local CLI, and the CI runner — identically.

Concretely, three disciplines carry most of it:

One policy bundle, everywhere. The rules that run in pre-commit on a laptop are the same rules, same version, that gate the plan in CI. If local and CI can disagree, the local path becomes the bypass.
Approve a fingerprint, not a PR. Save the plan, hash it, and let apply consume only a plan whose fingerprint carries a signed approval. A PR can be approved and then have its plan change underneath it; a fingerprint can't.
Split the plan role from the apply role. The job that plans can propose; the job that applies accepts nothing but an approved fingerprint. HCP Terraform already leans this way — run stages, policy checks, run tasks, separable plan/apply permissions. The harness isn't new primitives; it's refusing to let anyone route around them.

BEFORE — raw AI x Terraform

  AI Agent --HCL--> terraform apply --> production
  (review, policy, plan-binding, role split: all fuzzy)


AFTER — through the harness

  AI Agent / Human
     | intent
     v
  Author --> Compiler --> terraform plan / tofu plan
                              |
                              v
                         Evaluator (policy + fingerprint)
                              |
                              v
                 Signed approval + plan fingerprint
                              |
                              v
                        Apply role --------> production

A rule in a prompt is only a wish

The failure mode I most want to avoid is safety that lives in a sentence.

"Please don't create a public S3 bucket" in an AGENTS.md is a wish. OPA turning the plan JSON into a decision that fails CI is a fact. Same intent, completely different load-bearing capacity. AGENTS.md and MCP make the Author and Compiler layers stronger — better context, fewer dumb diffs — but they don't make anything safe; they make it more likely to be good, which is not the same claim. Instructions can be broken — by a prompt injection, a confused tool call, a model that just… doesn't. So: put the guidance in AGENTS.md, and the guarantee in the Evaluator.

The Evaluator rules I reach for:

diffs containing delete / replace / drop → no auto-apply
public ingress → denied without an explicit, logged exception
high DB sensitivity → encryption, audit log, backup, private network required, or the plan fails
plan fingerprint ≠ approval record → apply refused
missing / expired / under-privileged approval → apply refused

One rule I want but haven't shipped: a stricter policy profile for agent-authored changes than for human ones — routing by author type mechanically, rather than trusting anyone less by vibe.

And once agents sit inside CI, the attack surface grows (OWASP keeps an Agentic-AI risk list for exactly this). Four minimums I wouldn't ship without:

Separate read-only tools from mutating tools. Let the agent read provider docs and state; don't hand it apply-class operations directly.
Separate plan from apply. The agent proposes up to a plan. Apply goes through signed approval and a CI gate.
Separate CI job permissions. Plan jobs get the plan role; apply jobs get the apply role and accept nothing but an approved plan.
Put policy in code, not the prompt. Don't ask for no public S3 — detect it in the plan and fail.

The through-line: stop asking whether to trust the agent, and make its output mechanically evaluable instead.

A `destroy` is the `DROP COLUMN` of infrastructure

This is where it stops being a generic "AI + Terraform" post, because the database people already solved a version of it.

A DROP COLUMN is a destructive change: irreversible, backward-incompatible, exactly what you don't ship in one move. Atlas detects destructive changes and fails CI over them; the expand-contract pattern — add the new shape, migrate, and only then, separately, remove the old — exists so the dangerous half never rides along with the safe half. Tools like Bytebase wrap the whole thing in review, approval, rollout, and audit rather than letting anyone touch prod directly.

Infrastructure has the same hazards and mostly none of the discipline. A destroy, a forced replace, a deleted stateful resource — these are the DROP COLUMN of infra. So here's the rule I borrow: destructive infra changes shouldn't be one-shot. Today the harness enforces that as a hard stop — a destructive change is a critical hazard that can't clear the gate without explicit human approval. The direction I'm pushing toward is the database's fuller two-phase discipline: expand, migrate, then contract, each step approved on its own. The stop exists now; the mechanical two-step is where I'm headed.

Make it concrete. These three simplified plan entries are not equal, even if a shallow policy sees them as the same category of destructive change:

replace   aws_db_instance.main
delete    aws_s3_bucket.logs
destroy   aws_kms_key.customer_data

A generic "no destructive changes" rule treats them as one category. But the Evaluator shouldn't reason about the verb — it should reason about what the resource means. Here's the reading I'm building the Evaluator toward — polished more than it currently is, but the direction is the point:

destroy aws_kms_key.customer_data
  classification = confidential
  stateful       = true
  recovery       = hard          # key loss = data loss
  blast_radius   = production
  => DENY. expand-contract required: new key -> re-encrypt -> retire old, each approved

delete aws_s3_bucket.logs
  classification = internal
  stateful       = true
  recovery       = medium        # lifecycle-archived elsewhere
  blast_radius   = production
  => HOLD. require explicit retention check + second approval

Now the gate isn't guessing from a keyword; it's deciding from the resource's meaning — at least, that's the target. I want to be honest about where the line falls in what I've actually built: the database-side version of this is real — a schema's sensitivity already propagates into required controls — while deriving infra-side labels like recovery and blast_radius to the precision shown above is still partly ahead of me, not fully behind. The move I like even more is where those labels come from: propagate intent across the boundary. If a schema is labeled confidential, deletion-protected, RPO-strict, that intent shouldn't stop at the database —

DB schema intent
  classification = confidential
  rpo            = 5min
  deletion       = protected
        | propagate
        v
Infra requirement
  KMS encryption . PITR backup . deletion protection
  private endpoint . audit logging
        | enforce
        v
Policy gate
  any of these unset  ->  plan fails

Put plainly: the same way you don't let a DROP COLUMN through on a whim, you don't let a destroy through on an agent's confidence. Most "AI IaC" writing stops at "the agent can write HCL." The interesting seam is one layer down — where application semantics, DB constraints, and infra safety turn out to be the same dependency seen from different angles.

Sign the plan, not the checkmark

Software supply chains already made this move — SLSA provenance, artifact attestations, signed build provenance: verifiable claims about who made what, under whose authority. If a build artifact deserves that, an infra change deserves it at least as much, and an AI-involved one most of all.

So an approval isn't a green checkmark. It's a signed statement — the same core-vs-target split as the fingerprint above: the load-bearing fields today are the plan, its findings, and the signature; the fuller record below is the shape I'm building toward:

Field	Meaning
commit SHA	which source change
plan hash	which plan was approved
plan JSON hash	the exact diff evaluated
policy bundle hash	which rules judged it
workspace / env	dev / stg / prod
actor	AI, human, CI job, service account
reviewer identity	who approved
approval reason	why it was allowed
expiry	how long the approval is valid
signature	tamper-evidence, non-repudiation

Now "who approved this change, against which plan, having seen which policy result" has an answer you can verify months later — not reconstruct from memory and Slack scrollback. Call it non-repudiation for the AI era.

Objections I'd raise myself

"This is just CI/CD with extra steps." Partly. The step that carries the weight is binding approval to a fingerprint, not a PR. That one substitution is most of the value.
"Agents can be trusted more than this implies." Maybe, eventually. But the harness costs about the same whether the agent is excellent or awful, and it fails safe either way. I'd rather not stake the blast radius on the model being good this week.
"plan/apply roles and policy gates already exist." They do. I'm not claiming new primitives — I'm claiming one boundary for everyone, human and agent, CLI and CI, with no privileged bypass.
"Expand-contract for infra is over-engineering." For a weekend project, yes. For anything with a stateful resource you'd grieve losing, the DB people already learned this the expensive way, and I'd rather borrow the scar than earn my own.

Where the harness leaks

Three honest edges. The Compiler layer fragments — OpenTofu is going its own way as a CNCF project, and Pulumi and CDKTF aren't HCL at all; the harness only helps if the Evaluator can read every engine's plan format. Drift is a genuinely open Observer problem — an Observer that can't see out-of-band change is a harness with a blind spot. And every gate is a place a rushed team adds a bypass; an "emergency skip" used weekly is theater. If the escape hatch isn't itself logged, signed, and rare, none of the above holds.

Self-driving isn't unattended

The last decade of IaC went hand-crafted → declared. The next one is going declared → self-driving — and "self-driving" is going to get read as "unattended apply." I think that's the wrong reading. Self-driving infrastructure isn't an agent holding the apply button. It's an agent proposing freely into a harness where only a reviewed, fingerprinted, signed plan reaches production.

What matters in AI-era IaC was never that the agent can write HCL. It's that whatever it writes passes through intent, implementation, observation, and evaluation — Author, Compiler, Observer, Evaluator — and that only a reviewed plan lands in prod.

Don't put the caution in the prompt. Put it in the gate.

That's the shape I keep building toward — still wrong in places I haven't found yet.

AI Agents Don't Need a Monorepo. They Need a Readable Codebase

Takafumi Endo — Thu, 02 Jul 2026 01:56:10 +0000

For an AI, a monorepo is good — concentrated context is more efficient, everything in one place. But lately I've stopped asking whether a project is monorepo or multirepo. The repo boundary is no longer the unit I care about most. The coordination boundary is — and underneath even that, one plainer thing: whether the codebase is readable to the agent at all.

By readable I mean something concrete: the agent can infer responsibility from names, find the right files fast, see where boundaries are, and verify a change with predictable commands. That holds in a monorepo and a multirepo alike — and it decides more than the repo shape does.

The situation I'm writing about is the solo-or-small-team case: one person orchestrating many agents, with little time spent negotiating boundaries with other humans. So the question I ask first is — can I run several agents on this codebase at once without them, or me, becoming the thing everyone waits on?

I once wrote that the writer moved back to the edge — agents living inside the work environment, pulling state toward them. This is the sequel. The writer didn't just relocate. It multiplied. When writers multiply, the constraint that matters in a design changes too.

Not advice, and not "monorepo is over." One person's notes, written mostly to find where they're wrong.

Where I've landed for now (and expect to revise):

monorepo is still good for AI — concentrated context is more efficient.

But the real question isn't monorepo vs multirepo. It's how little your structure obstructs human + agent parallelism.

On a team, human coordination is the bottleneck, and it caps how many agents any one person can actually run.

Solo, with clear responsibilities and in/out contracts, multirepo works just as well — clone into a parent directory and implement across it.

Before any of that: directory layout, naming, and feature names have to be AI-readable. That precondition matters more than the repo shape — in a monorepo and a multirepo.

monorepo helps — when "same place" is machine-readable

monorepo genuinely helps agents. Code, types, tests, dependencies, design decisions in one place; change an API and its downstream app in one commit; reason across boundaries. That's real.

But Nx keeps warning that repos merely dumped into one directory aren't a monorepo — they're code collocation: no boundaries, unstructured tooling, irrelevant tests running. What turns collocation into a benefit is the layer on top — affected-only build/test, a dependency graph, CODEOWNERS, enforced API boundaries.

So the value isn't "same place." It's same place, made machine-readable. That distinction runs through everything below.

The bottleneck is coordination, not the repo

When several people share one repo, their work collides. To avoid that, tasks, responsibilities, and review units get carved to fit human collaboration. That's correct — because the human is the bottleneck. But it also caps how many agents one developer can run. If you can drive ten agents but review-and-consensus only clears three, your effective parallelism is three.

When one person owns the whole repo, that ceiling lifts. You dispatch agents on your own judgment, across features, with no review queue in the way. You spend the parallelism directly. A concrete afternoon looks like this:

Agent A — update the API contract
Agent B — fix the frontend calls to match
Agent C — write the migration and seed data
Agent D — chase the failing tests and typecheck

Four changes moving at once, all mine to reconcile — no one to sync with first. That's the shape of work this whole post is about.

	Team, shared repo	Solo, many agents
Bottleneck	Human coordination (review, consensus)	Attention, verification, tooling
What sets the repo boundary	Coordination units	Whatever the agent reads well
Effective parallelism	Capped by review throughput	Capped by your attention, machine, and tooling
Right shape leans toward	Boundaries that fit people	Boundaries that fit agents

That gap is why the monorepo-vs-multirepo axis stopped feeling central to me. The center is the coordination boundary — and it doesn't have to line up with the repo boundary. Teams cut repos to match coordination. Solo-with-many-agents, coordination nearly vanishes, so you can draw repo lines however you like. The only constraint left is: can the agent explore, change, and verify without getting lost?

Claude Code and Codex already assume this — worktrees running a feature and a bugfix as separate checkouts at once, tasks executing in independent sandboxes. One human orchestrating many agents, treated as a first-class workflow.

At scale, "sees everything" backfires

Counterintuitively, seeing everything in a big monorepo often hurts. Anthropic's large-codebase guidance notes that a giant root CLAUDE.md and stray file reads fill the context window and degrade cost and performance; the fix is per-directory CLAUDE.md, read-deny rules, code intelligence, sparse worktrees. Research points the same way — agents don't solve more just by reading more, because broad context doesn't automatically become useful structure, and can even drop performance.

What agents need isn't full visibility. It's fast paths to the structure that matters — true in monorepo and multirepo alike. The problem was never size by itself. It's undirected size. Large is fine when the map is good; large without a map is just noise.

Before any of this: the structure has to be readable

Here's the part I actually care about most, and it sits underneath everything above. Whether you land on monorepo or multirepo, none of it works if the directory layout, the naming conventions, and even the feature names aren't legible to the agent. That precondition is more fundamental than the repo shape — it's what makes a monorepo worth its concentration and a multirepo worth stitching together.

Repo structure is itself a fact you hand the agent — rigor compresses. Vague structure burns tokens on guesses; machine-readable structure lands in a line. Reports back this up — LLM-friendly structure maps improving accuracy and cutting completion time, text+structure hybrids trimming input tokens, AGENTS.md alone reducing runtime and token spend. The numbers are workload-dependent, so I don't take them literally, but the direction is consistent.

So the order of operations is the opposite of how the debate usually runs. Pick the repo shape last. Make the structure readable first.

The repo is physical. The workspace is operational.

Readable first — then the question becomes how to keep it readable when the code is split across repos. The unit shifts from repo to workspace. Claude Code's --add-dir pulls sibling repos into one session; Nx points at "synthetic monorepo" infrastructure to view across repos. The idea: repos can be split, but the agent sees one meaningful workspace.

My old line — clone several repos locally, open the parent directory, implement across them in one context — fits here. But the parent directory alone is weak. What earns its keep is the thin layer above it:

Layer	What it is	Why the agent needs it
`AGENTS.md` / `CLAUDE.md`	Instructions at root + per directory	Tells the agent where to look, not just what the project is
Workspace manifest	Which repos exist, how they connect	Turns a folder of clones into one workspace
Cross-repo dependency map	What depends on what	Lets the agent trace impact across repos
Unified verify commands	`test` / `lint` / `typecheck` / `build` / `dev`	One way to check work, everywhere
Contracts	API schema, event schema, migrations	Makes boundaries machine-checkable, not assumed

With that layer, multirepo behaves like a synthetic monorepo. Without it, even a clean monorepo wastes context.

Objections I'd raise myself

"multirepo is just heavier ops." Half true — migration fan-out, cross-repo visibility, dependency tracking. My claim is conditional: when the coordination boundary disappears, multirepo + parent workspace beats a team-shaped monorepo more often. Not always.
"contracts rot." The load-bearing objection. The moment a contract drifts from the code, the synthetic workspace is a fiction. So contracts have to be enforced in CI, not kept as a promise humans remember.
"don't generalize solo to teams." I don't. Teams need coordination; carving repos to fit it is correct. My one point: the right shape moves with coordination cost. Fewer people, more agents per person → the scale tips toward workspace + contracts.
"synthetic monorepo is fragile." It is. Clones under a parent directory collapse fast without a manifest and a dependency map. Tooling is still thin here, and I'm feeling my way.

A checklist that earns its place

Not exhaustive — roughly the order I've found things matter.

Area	Do this
Structure	`apps/` `packages/` `services/` `libs/` `contracts/` — responsibility legible from the name
Agent instructions	`AGENTS.md` / `CLAUDE.md` at root and per directory
Contracts	API / event schema, DB migrations, input/output contracts, made explicit
Verify	Standard `test` / `lint` / `typecheck` / `build` / `dev` commands everywhere
Boundaries	CODEOWNERS, public API, import boundaries, dependency rules
Parallelism	Assume worktree / sandbox / branch-naming from the start
Multirepo	Parent workspace manifest + cross-repo dependency map
AI readability	A separate "where to look" doc for agents, apart from the human README

The shape, in one line

monorepo is still a good way to colocate context — for an AI, concentration is efficiency. But the win isn't the monorepo. On a team, split responsibilities so humans don't block each other. Solo with many agents, clear contracts let a multirepo do the same job. And underneath both, the thing that actually decides whether an agent thrives is the same: is the structure readable?

The writer moved to the edge, then multiplied. What paces the multiplied writer is no longer where the code lives. It is how far humans and agents can move without waiting on each other — and how quickly an agent can find its way around before it moves at all.

Repo design in the AI era isn't about where you put the code. It's about how readable the structure is, and how little you obstruct the parallelism between humans and agents. Held loosely — a view I plan to keep testing as I design against it.

Let Aurora Sleep: Multi-Tenant SaaS Cost, Reconsidered with AI IaC

Takafumi Endo — Tue, 30 Jun 2026 10:21:48 +0000

For most multi-tenant SaaS, the default still rhymes: PostgreSQL on Aurora, behind an API, in a private subnet. Stable, well-understood, the shape you'd draw on a whiteboard.

But I keep feeling a mismatch between what that shape costs and what it actually does while a product is small or bursty. A lot of the time, Vercel + Cloudflare + Supabase or Neon would give me similar real-world performance for less. And yet I get pulled back to AWS and Aurora — not for raw performance, but for enterprise requirements: VPC isolation, audit posture, "it has to live in our AWS org."

What changed for me is the third option in that fork. It used to be "cheap edge stack or heavy AWS stack." Now there's a middle path: keep the AWS/Aurora skeleton the enterprise wants, but redesign it so it stops costing like it's always on — and reach that redesign by sparring with an AI against a real dev deployment, instead of needing to already be an infra specialist.

Here's the whole idea in one picture:

BEFORE — everything flows through Aurora
  Client ── API ── VPC App ── Aurora (always warm)
                      │
                      └── NAT ── OpenAI        (NAT always provisioned)

AFTER — Aurora only for control/commit
  Client ── CloudFront / S3            viewer & artifacts (no DB)
         └─ Hot Lambda ── DynamoDB     hot path / cache / counters (no DB)

  Control actions ── VPC Lambda ── Aurora        (wakes on purpose)
  LLM calls ──────── non-VPC Lambda ── OpenAI     (no NAT, no DB)

One scoping note up front: this is primarily for dev, internal tools, bursty early-stage SaaS, and low-frequency enterprise environments — not a blanket "let your production database sleep" recommendation for steady, high-traffic workloads. It's an optimization for a specific shape of usage, not a rejection of the proven production default.

Not a "Postgres is over" piece, and not a best-practice writeup either. This is something I'm still validating — a design space I mostly reached by sparring with Claude Code and Codex while keeping one eye on cost-performance, then deploying to dev to see what actually held. Notes on where my thinking has drifted, written down mostly so I can find out where it's wrong. If anything here is useful, take it as "you can stumble into shapes like this too," not "do it this way."

Where I've landed for now:

The cost pain usually isn't Aurora. It's making Aurora the center of every request.

Demote Aurora to a thin control plane — canonical state, commit, approval, audit — and let it sleep.

Push viewing, LLM hot paths, and ephemeral state to S3 / CloudFront / DynamoDB / non-VPC Lambda.

What makes this reachable for non-specialists is declarative schema + IaC + AI, validated agilely in dev.

The default bills like it's always on

The textbook shape — CloudFront → ALB/API Gateway → app → Aurora, pool model with tenant_id everywhere and RLS for isolation — is fine. The problem is what accretes around it to make it reliable: always-on Aurora, RDS Proxy, NAT Gateway, readers, VPC endpoints, logs.

For dev or a 1–30 person workload, the fixed cost of reliability is wildly out of proportion to the traffic. You're paying ledger-grade rent to store scratch work deleted in an hour.

The mismatch isn't "Aurora is expensive." It's "Aurora is expensive when it can never go idle."

Here's the cost shape the redesign is chasing — not exact dollars, but where the fixed costs go:

BEFORE                              AFTER
- Aurora always warm               - Aurora wakes only for control/commit
- NAT always provisioned           - No NAT for LLM egress
- RDS Proxy holding connections    - No Proxy in the sleep path
- DB hit on health/viewer/LLM      - Viewer/LLM/health paths stay DB-free

The reframe: Aurora as a thin control plane

Don't put Aurora in the path of every request.
Make it a thin control plane: canonical state, approval, audit, commit.
Move viewing, LLM execution, short-lived state, and delivery
to S3 / CloudFront / DynamoDB / non-VPC Lambda.

There's a system of work — high-churn, disposable, fine to lose — and a system of record — money, contracts, audit, singular and strict. The mistake is paying record-grade prices for work-grade state. So split by job:

Layer	Job
S3	artifacts, reports, raw payloads (cheap bulk)
CloudFront	viewer delivery — keeps reads off Aurora
DynamoDB	projections, cache, locks, progress, counters (hot path)
Aurora	tenant, RBAC, manifest, lineage, approval, audit, rollups
non-VPC Lambda	outbound LLM calls — no NAT, never touches the DB

Once viewing and the LLM hot path stop touching Aurora, it stops waking for trivia. That, more than any price knob, moves the bill.

One discipline keeps DynamoDB from quietly becoming a second source of truth: anything stored there should be either TTL-bound, recomputable from Aurora/S3, or an explicit live counter with a reconciliation path. If a value is none of those, it probably wants to be in Aurora.

Sleep-first only works if the app lets Aurora sleep

Aurora Serverless v2 can scale to zero in supported configurations (min_acu = 0), and while paused, compute charge goes to zero (storage still bills). The flag is the easy part; the discipline is not poking it awake.

Bad:  set min=0, but login/health/LLM/viewer all read Aurora -> never sleeps
Good: only login, admin, manifest commit, rollups, audit wake it on purpose

Two silent traps: in this sleep-first setup, RDS Proxy works against you — it keeps database connections around, which prevents pause — and any open user-initiated connection does the same. So sleep-first wants no Proxy, a small pool, short idle timeouts. (None of this is a knock on RDS Proxy in general; it's doing exactly its job, which happens to be the opposite of what you want here.)

The goal isn't to make Aurora cheap by configuration; it's to make the application structurally capable of not needing Aurora most of the time. The min_acu = 0 flag only pays off once the app no longer reaches for the DB on every request.

No NAT: separate "can reach data" from "can reach the internet"

Dropping NAT is usually pitched as savings (it bills per hour and per GB). The better reason is blast radius:

A Lambda that can touch the data cannot go out.
A Lambda that can go out cannot touch the data.

One function with both powers, if compromised, can read and exfiltrate. Split it: a VPC control Lambda reaches RDS but can't egress; a non-VPC egress Lambda calls the external LLM but has no line to the DB. Cheaper and smaller blast radius at once. (Caveat: an /ask flow hands tenant context to the egress function, so minimize the payload, forbid logging it, keep a request_id audit trail.)

The point isn't that non-VPC is magically safe. The egress Lambda still touches the OpenAI key and whatever prompt/context you pass it, so it still deserves a narrow IAM role, a single-purpose secret, no broad Secrets Manager or S3 read permissions, and strict logging rules. The win is narrower and more durable: it cannot both read the database and ship it somewhere.

And the boundary only holds if the network isn't the only thing keeping the egress Lambda away from the DB. Aurora has to be private, its security group must not allow the egress path, and the egress Lambda must have no Data API access or broad Secrets Manager permissions that would quietly recreate a database path through IAM. "Not in the VPC" is necessary, not sufficient.

The part that makes this AI-friendly: declarative schema

This design means making the same placement call constantly: canonical Aurora? DynamoDB cache? S3 artifact? hot path? allowed to wake the DB?

Migration-history schema fights you here — to know what is, you replay what happened (001_create… 006_revert…). Declarative schema flips it: you describe the desired current state and let the tool diff it. Both you and the AI read one artifact that says what should be true now.

It doesn't abolish prod migrations — the loop is declarative -> plan -> reviewed migration -> apply -> drift check. You think in declarative state; you apply via migration. That's what fits AI-assisted work: the AI reasons over a stable description, not a changelog.

You don't have to be an infra specialist up front

This is the claim I most want to make — and hold most loosely.

A sleep-first, no-NAT, projection-driven design used to need someone who lived in AWS networking. The wall wasn't the idea; it was getting VPC routing, IAM boundaries, and serverless wiring all correct. Most of this design, honestly, isn't something I knew up front — it's where I drifted by sparring with Claude Code and Codex against a real dev deployment: "does this Lambda actually have egress?", "what wakes Aurora here?", "where's the tenant boundary?" With IaC describing the whole thing as code, the feedback is a deployed stack you can poke, not a whiteboard argument — and that's what let me reach a shape like this at all.

It costs more than a managed edge platform and burns dev cycles. But infra design became something you validate agilely rather than get right up front from expertise alone.

To be precise about the claim: AI doesn't remove the need for infrastructure expertise. It changes the iteration loop — from "know the answer upfront" to "generate, deploy, inspect, and correct faster." You still need the judgment to know what to inspect; you just acquire it by iterating instead of having to bring all of it to the whiteboard.

The honest caveat: the AI will confidently produce wiring that's "plausible but subtly wrong" — a security group more open than you think, a function you believe is sandboxed but isn't. So the loop must include verification you can eyeball: probe the egress, confirm what wakes the DB, read the plan diff. And be clear-eyed that demoting Aurora is really distributed-systems-ification — you trade fixed cost for consistency, projections, and sync. It's a tradeoff, not a free win.

When this stops being the right call

Aurora awake < ~100h/mo:  min_acu=0 + wake-ahead — keep going
~100–250h/mo:             compare against RDS db.t4g.micro/small
> ~250h/mo:               always-on RDS, or Aurora min_acu=0.5
prod-like / heavy validation: Aurora min_acu=0.5

Judge total cost (ACU + NAT + Proxy + endpoints + DynamoDB + S3 + Lambda + CloudWatch), not Aurora alone. For bursty dev, killing Aurora compute and NAT usually wins; for steady production, often it won't. These aren't universal thresholds — they're decision triggers for my environment, and they move with region, log volume, and DynamoDB/S3 usage.

What I'd actually measure

Numbers beat vibes here. If I were deciding whether this is paying off, these are the signals I'd watch:

Aurora awake hours per month (the headline number)
which endpoints wake Aurora — and whether any are supposed to be DB-free
NAT hourly cost avoided by moving egress out of the VPC
DynamoDB counter / reconciliation lag — how stale the cheap layer gets
p95 login latency right after a cold resume (the resume-tax you're accepting)
count of unexpected DB calls from hot paths (this should trend to zero)

Objections I'd raise myself

"You've rebuilt a distributed system to avoid a DB bill." Sometimes, yes. The boundary I try to hold is: only move work-grade state out of Aurora. If a flow needs cross-store transactions, strict read-after-write semantics everywhere, or complex reconciliation, it probably belongs back in the path. The moment you're reaching for distributed consistency to keep the cheap layer correct, you've moved the boundary too far.
"Stale auth will bite you." The sharp edge. JWT + DynamoDB cache is fine for low-risk reads, but role/budget changes, manifest commits, approvals, and any tenant-data-injecting /ask must consult canonical Aurora. "Fast but stale permissions" is how you ship an authz incident.
"The warmup endpoint is a footgun." A public /warmup doing select 1 leaks almost nothing — but it's a button that wakes Aurora, and a public one can be hammered until sleep-first is meaningless. Behind WAF/rate-limit, single-flight, no-op when recently warm.

A checklist before you try this

If you want to see whether your workload fits, run down these before touching anything:

Is your workload bursty / intermittent (not steady high traffic)?
Can viewer reads be served without touching Aurora (CloudFront/S3/DynamoDB)?
Can LLM calls run outside the VPC, with no DB access?
Can the DynamoDB state be TTL-bound, recomputable, or reconciled?
Can you tolerate resume latency on the paths that do wake Aurora?
Do you have metrics for what wakes Aurora, so you can catch leaks?
Is your schema declarative, so you (and the AI) reason over current state, not history?

If most boxes are unchecked, the boring always-on RDS/Aurora is probably still the right call — and that's fine.

Still figuring out the edges

The shift isn't any one AWS feature. It's that the boundary between "only an infra specialist could safely build this" and "a product engineer can reach it by sparring with an AI against a dev deployment" has moved a lot.

Enterprise gravity toward AWS and Aurora is real and isn't leaving. But it no longer forces the always-on, NAT-heavy, everything-through-the-DB default. Keep Aurora as the vault — strict, singular — let it sleep, and run the workbench at the edge, with explicit events carrying workbench changes back into the control plane. Whether this particular shape survives more validation, I don't know yet. What I'm fairly sure of is that the path to trying designs like it is now something you can iterate into — with AI and IaC, deploying and inspecting — instead of having to know it cold beforehand.

If you've run something like this in production — or watched it fall apart — I'd like to hear where it broke for you.

The Wrapper Got Heavy: Why ChatGPT Clones Are Runtime Problems Now

Takafumi Endo — Fri, 26 Jun 2026 03:00:39 +0000

A year ago, "it's just a ChatGPT wrapper" was a dismissal. You'd hear it about a startup and know what it meant: an LLM API call, a little RAG, file upload, a chat box on top. Thin. Replaceable. Probably dead the next time the base model shipped a feature.

I keep coming back to that phrase, because it stopped being true in a way I didn't notice happening. The thing you'd be wrapping is no longer a model with a chat UI. It's a fast, stateful web application with its own agent loop, its own sandbox, its own artifact system. The wrapper didn't get easier to build as the models got better. It got heavier.

The simple interface hides the hard part. A ChatGPT-shaped product is not just an API call with a chat box around it; it's the accumulation of many product and infrastructure decisions that make execution feel safe, stateful, and immediate. The model is the part you can buy. The surrounding runtime is the part people had to design.

What gets me is the timescale. It's been roughly a year, and the question actually worth arguing about has moved out from under us — from "is this just a wrapper?" to "where does the sandbox even run?" The pace is faster than I can comfortably track. And the part I keep finding fun is that it all bends toward the practical, not away from it: every one of these shifts makes the tools more usable, more real, closer to something you'd actually ship. Surprising and, honestly, a good time to be building.

This isn't a "wrappers are over" argument, and it isn't advice. It's me writing down where my thinking has drifted while trying to build these things myself — partly so I can find out where it's wrong. Read it as one person's notes.

What "wrapper" used to mean

The old shape was honestly small. Roughly:

prompt → LLM API → (RAG retrieval) → response
        + file parsing on the side

The whole game was prompt design, a retrieval index, and some glue. You could stand it up in a weekend. The reason "wrapper" was an insult is that the surface area was tiny — the model did the hard part, and you did the part anyone could redo.

The leverage point was the prompt and the context you stuffed into it. I've written before that token spend only becomes an asset when you redesign the work around it. Back then, "the work" was mostly the prompt. There wasn't much else in the box.

Two things that are easy to blur

Before going further, it's worth separating two things, because the rest of this post depends on not mixing them up.

The first is the consumer surface: ChatGPT's Data Analysis, Canvas, and Agent mode; Claude's artifacts and browser agents. These are managed sandboxes the platform owns end to end. You can't bring your own; you can only observe their shape.

The second is the developer engine: Codex's CLI / app-server / SDK, and Claude Code's headless mode and Agent SDK. These expose the agent loop as something you can drive from your own code.

They're the same product family seen from two sides. The lesson you take from each is different:

The consumer products reveal the shape of the architecture — sandboxed analysis, artifact surfaces, browser/terminal agents.
The developer tools reveal the build strategy — don't rebuild the agent loop; drive the existing engine and own the boundary, the policy, and the domain compiler around it.

Keep those two lines in mind. The first half of what follows is about the shape. The second half is about the strategy.

The sandbox is the actual product surface

The clearest way I've found to see the shape is to stop looking at ChatGPT as "a model" and look at it as a set of execution environments, each with a network boundary around it. Strip the marketing and the consumer surface decomposes into tiers:

Surface	What it really is	Network	Closest analogy
Plain chat	inference + retrieval, no shell	n/a	the old "wrapper"
Data analysis	stateful Python/Jupyter-like sandbox on uploaded files	no direct external web/API calls	short-lived compute sandbox
Canvas	code edit + render/preview sandbox	policy-gated (workspace/admin)	preview environment
Agent mode	remote browser + code interpreter + limited terminal + connectors	restricted + confirmations	a managed virtual computer

What strikes me, laid out like this: none of these is only a model feature. Each is a product/runtime feature that depends on model behavior but is mostly a managed sandbox with a deliberate trust boundary — what can run, what it can reach, when a human has to confirm. The design center isn't "a better prompt." It's managed sandbox + network boundary + user confirmation + tool isolation.

And notably, it is not "trust a user-supplied container as your production sandbox." There's no devcontainer.json you hand in and have it boot as your runtime. The isolation is the point, and the isolation is theirs, hand-built per surface. That's the part a thin wrapper can't fake — and the part that's now the bulk of the work.

So the leverage point moved. It used to be the prompt. The model call used to be the product; now it's the commodity-shaped component inside a much heavier runtime.

Runtime choice is really a state-gravity decision

The moment you decide your wrapper needs to run something — execute the code it wrote, render the component, hold work state between turns — you've inherited an infrastructure decision you can't shortcut. And the heart of it isn't "which platform is fastest." It's where the state lives.

It helps to notice that "state" here isn't one thing. An agentic product juggles at least four, with different gravity:

1. conversation state        — turns, plan, tool-call history
2. workspace filesystem state — the repo/files the agent edits
3. artifact / render state    — the live canvas, the preview
4. connector / auth state     — credentials, permissions, approvals

The real design question is which of these lives inside the sandbox, close to the actor, and which gets pushed back to a durable store (a DB, object storage, Git). This is the same state gravity model I keep running into: high-churn work state wants to be close to whatever reads and writes it most; the durable record stays central. (It's telling that Codex exposes SQLite-backed state for agent jobs and exported results via sqlite_home — the workbench is local, the ledger is elsewhere. The pattern keeps reappearing.)

Choosing a platform is choosing that gravity, and none of the options hands it to you for free:

Vercel — Fluid Compute killed the "too short-lived for agents" complaint (300s default, up to 800s, 30-min beta), but it still isn't a stateful repo-workspace sandbox out of the box, so a code-running agent needs extra design on top.
Cloudflare — Durable Objects are great for per-entity conversation state (SQLite-backed, one writer each); less of a fit, alone, as an arbitrary-code sandbox or a cloned repo.
AWS — Fargate gives real per-task isolation. Beyond that you're assembling: the pattern I'd reach for is a session-scoped, disposable VM per agent run — something you build on the primitives rather than buy off the shelf. Maximum control, maximum assembly.
Roll your own — gVisor / Firecracker, your own warm pools and snapshots. The most control, the deepest hole.

Whichever you pick, you spend real days on cold-start latency, warm pools, and the network policy before a single user-visible feature ships. The wrapper used to be the prompt. Now part of the wrapper is a sandbox you have to operate — and the network boundary is not a checkbox. A good concrete example: Codex cloud runs a two-phase model — the setup phase has network access to install dependencies, then the agent phase runs offline by default, and secrets are removed before the agent phase even starts. That separation of setup egress from agent egress, with secrets scoped to setup, is exactly the kind of boundary you end up rebuilding yourself if you roll your own runtime.

Don't rebuild Codex or Claude Code — drive them

Chat-with-a-sandbox is heavy but reachable. The coding agents — Claude Code, Codex — are a different tier, and this is where the build strategy from earlier pays off. The honest move is to stand on the engines that already exist rather than reimplement the loop.

Codex is the clear example because the engine is exposed. codex exec runs the agent non-interactively — single session to completion, events streamed as JSONL via --json, a built-in sandbox (read-only by default, workspace-write when you opt in), approval gating you can set to never for unattended runs. codex app-server runs the same core as a server over stdio / WebSocket / Unix socket, which is how IDEs and SDK clients drive it — the Python SDK, for instance, controls the local app-server over JSON-RPC, while codex exec --json is the simpler non-interactive path. Claude Code has its own headless mode (claude -p) and Agent SDK in the same spirit.

One caveat I'd flag honestly: you can speak the app-server protocol, but treat it as a fast-moving integration surface, not yet a boring, stable production ABI — the docs mark it as primarily for development/debugging, and the WebSocket transport is still hardening. Build on it, but expect it to move.

The lesson I take from this: the agent loop, the tool orchestration, the apply-patch system, the sandbox enforcement — that's a frontier-grade engine, and the leverage is in driving it, not rebuilding it. Trying to hand-roll the equivalent loop is the new version of trying to hand-roll dominators in a static analyzer: technically possible, almost always the wrong place to spend your rigor.

The part worth owning — and how thin the moat really is

So where's the defensible work, if the model is a commodity and the agent loop is borrowed?

Honestly, I'm not sure "defensible" is the right word, and I want to resist making my own work sound safer than it is. Here's the most honest version I have.

The durable idea — more durable, I think, than any tooling that implements it — is an epistemology: typing the facts you hand an agent by how you know them. Is a claim verified (it follows from a model you built, with evidence) or estimated (a pattern guessed it)? What's its provenance? I care about this because an agent handed grounded, labeled facts has to guess less, and a fact that carries its own confidence is worth more than a longer context window.

The tooling I've built around that — an SDK and compiler aimed at Codex and Claude Code, turning messy domain data into typed, sourced facts — is just my current implementation of the idea, not a moat. And I should take my own earlier objection seriously: if platforms absorb the commodity layer, why wouldn't they absorb this too? They might — a generic facts-grounding layer is exactly the kind of thing that gets commoditized next. There's a second pressure cutting the same way: as models get better at deriving global facts unaided, the need for hand-built verified/estimated scaffolding could shrink, not grow.

So I won't claim a moat. The narrower thing I will claim — more defensible for being narrow — is that the facts that matter most are tied to your domain: your invariants, your private data, the specific thing that's dangerous in your system. That's the part a general platform doesn't have and a smarter model can't infer from nothing. Owning the pipeline that produces those facts buys trustworthy agent output now, on your actual problem. Whether that's a lasting edge or a temporary one, I don't know. The honest reason to build it isn't defensibility — it's that it makes the agent's answers true today.

Objections I'd raise myself

"Wrappers are still easy — most apps don't need a sandbox." True, and plenty of good products are still a chat box over an API. My claim only covers the frontier-shaped slice — runs code, renders artifacts, holds work state, feels instant. Outside it, "just wrap it" is still accurate, and I don't want to inflate the rest into something heavier than it is just to dignify the work.
"This is build-vs-buy, nothing new." Partly. What's new is that the buy side moved. You used to buy the model and build the app. Now you also buy the agent engine and the sandbox platform, and the build is the orchestration, the boundary, and the facts pipeline between them.
"Won't the platforms just absorb all of this?" Probably some of it. Managed agent sandboxes will get boring the way managed Postgres did, and a generic facts-grounding layer is a plausible next thing to be commoditized. I don't have a clean rebuttal — only that the specific facts tied to your domain and private data are the slowest part to absorb. That's a thinner claim than "I have a moat," and I'd rather state the thin true one.
"You're building on a borrowed engine and a rented sandbox." Yes, and it makes the strategy less stable than I'd like. The app-server isn't a frozen ABI; the platform sets the gravity, not me. I'm not standing on bedrock — I'm standing on a fast-moving layer and trying to stay close to it. The wager is that staying close beats trying to own the whole stack. It's a wager, not a fortress.

Where this is going

The best developers at OpenAI and Anthropic are improving the consumer product relentlessly, and you can't out-ship them on their own surface — the chat, the sandbox, the artifacts, the latency move every few weeks. Matching that head-on is a losing race.

So the move is two-handed, and I'll admit it isn't a stable one. One hand keeps up: drive codex exec and app-server, Claude Code's headless mode, whichever sandbox platform's gravity fits — ride the improvements instead of fighting them. The other hand grounds the facts your agent runs on. Neither hand is holding bedrock; both sit on layers that move, one rented and one possibly temporary. The wager is only that staying close to the frontier while owning your domain's facts beats the alternatives — not that it's safe.

The phrase aged in an interesting direction. "Just a wrapper" used to mean thin, replaceable, not really engineering. For the frontier-shaped slice, it now means a state-gravity decision and an orchestration layer over a borrowed engine. (For everything else, "just wrap it" is still true, and that's fine.) The model call used to be the product. Now it's the commodity inside the product — and the easy part is the part you no longer build.

That's the pull I keep feeling: stop trying to reproduce the giants, stay close to the layer that keeps moving, and stay honest about how much of the advantage is real versus borrowed.

Your Fuzzer Is Only as Smart as Its Oracle

Takafumi Endo — Wed, 24 Jun 2026 14:07:23 +0000

A migration my schema tool generated passed every check I had. The final schema matched the target exactly — convergence, green. Then I looked at the plan it took to get there: DROP TABLE; CREATE TABLE. On a table with data. The destination was right; the path would have erased a production database.

The test was green because I was checking the wrong thing. I had an oracle for where it ended up and none for how it got there.

That gap is most of what this post is about. I build developer tools — SDKs, a compiler, a declarative schema-management system — the kind of software where one wrong edge case ships to everyone downstream. And I spent a long time trying to get coding agents to test this stuff for me. Claude Code, Codex — with enough prompting and the right skills you can get something that looks like a test suite. What I could never get was coverage that followed the real dev flow without quietly skipping the case that mattered. It's convincing right up until you check whether it checked anything.

What finally worked better was semantic fuzzing: constrained, deterministic random generation, run against properties instead of a reference output, with the agent writing the generators and domain rules rather than playing tester. It catches a lot. And the more I run the harness, the more it improves.

But the interesting part isn't the fuzzing. AI made the building of the harness cheap — generators, adapters, the long tail of domain rules. It did not make the harness run itself correctly, and it did not write the part that decides what "correct" means when you have no second implementation to diff against. That part was always the real work, and it still is.

So this is a post about oracles wearing a fuzzing costume. As usual: notes on where my thinking has drifted, not advice.

Where I've landed for now (and expect to revise):

Randomness doesn't find bugs. The oracle does; randomness just walks it there.

So the value isn't the generator. It's the law you check.

The laws worth having need no reference implementation — they're algebraic relations the tool must satisfy by its own logic.

AI dropped the cost of the harness. The scarce skill moved from headcount to seeing what the law is.

"Semantic" needs pinning down

"I fuzz it" says almost nothing on its own. At one end of the dial is crash fuzzing — uniform noise at a parser, asking only "did it fall over?" At the other is reference-model testing — diffing every output against a full second implementation you now have to build and trust. Semantic fuzzing sits in between, and the whole game is what you do with the middle.

Three properties make it work. Generation is distribution-constrained (biased toward inputs with real structure — schemas and migration sequences that could plausibly exist — not uniform noise), deterministic (every case carries a seed, so a failure replays exactly), and shrinkable (a failing case minimizes itself to the smallest thing that still breaks).

That's property-based testing's family tree, and I'd rather say so than pretend it's new. The goal isn't maximum randomness — it's productive randomness: reproducible, minimizable, aimed where bugs live. The one thing it refuses to do is what reference-model testing does — build a second implementation to check the answer. It checks relations the answer must obey instead, which is the move the rest of this post turns on.

The oracle is the whole game

A fuzzer is never smarter than its oracle.

The generator is just search. It produces inputs; it has no idea what's wrong with any of them. The thing that decides this is a bug is the oracle — and whatever the oracle can't recognize, the fuzzer cannot find, however many cases you burn.

Point a billion inputs at a crash oracle and you get crashes. You won't get a migration that converges to the right state via a catastrophic path, or a rollback that silently drops a constraint. Those don't crash. They're wrong semantically, and a crash oracle is blind to exactly that.

The trap here is reaching for a reference implementation — "I'll build a correct model and diff against it." But a full reference model of a schema engine is a second schema engine, with its own bugs to maintain. You doubled the work and got a thing you also can't trust.

The way out: stop asking for a reference, ask for laws — relations the tool must satisfy regardless of the "right answer."

Law	Relation checked	Reference needed?	Axis
convergence	`apply(spec)` → introspect → residual drift `== 0`	no	correctness
idempotency	`apply(spec)` twice → 2nd run is a no-op	no	correctness
rollback	`base → target → base` → back to base, exactly	no	correctness
safety	destructive change → must surface hazard / require approval	no	safety

None needs the correct schema in advance — each is true by the meaning of the operation. convergence doesn't ask "is this schema right?", it asks "did you reach the state you claimed?" That's the metamorphic move: don't verify the answer, verify a relation the answer must obey.

Note safety as a peer, not a footnote. "Reached the right state" and "took a safe path" are different axes — the DROP TABLE; CREATE TABLE from the opening satisfies convergence and still erases your data. The oracle must check the path, not just the destination. This is the law that would have caught my green-but-catastrophic migration.

A worked example: schemas, extensions, a Docker loop

One generator feeds a pipeline; every stage is a place to hang a law.

 generate schema + mutation sequence
            │
            ▼
   IR / shadow DB                ── convergence, idempotency  (in-process)
            │
            ▼
   diff + online-migration plan  ── safety, plan honesty      (in-process)
            │
            ▼
   apply to Docker Postgres/MySQL── locks, extensions, races  (Docker)
            │
            ▼
   introspect + review           ── drift == 0

Run that across thousands of seeds and you're not testing "does ADD COLUMN work." You're hitting combinations a human suite never reaches — especially extension combinations. Base PostgreSQL/MySQL is the easy part; bugs hide where citext meets a generated column meets a partial index meets an old trigger. Enumerating those by hand used to need a team. Generated, it's a distribution you tune.

But be honest about which layer answers:

Layer	Runtime	Answers	Can't answer
In-process	PGlite / `node:sqlite`	convergence, idempotency, real SQL exec	multi-connection, lock fidelity, full extension catalog
Docker	real Postgres / MySQL	locks, isolation, extensions, version matrix	provider parity, hosted-backend quirks
Live	real cloud / hosted	IAM/KMS enforcement, audit immutability	(bulk testing — too slow/expensive)

The same generated case fans out: cheap laws run in-process by the thousand; expensive laws that need a real engine run in Docker, sampled. The layer is chosen per property, not per pipeline. Putting a lock-contention law in the in-process tier wouldn't make it fast — it would make it lie.

The flywheel is real, but it has a catch

"Run it more, it gets better" is true — but not because green accumulates. A suite at 100% pass proves nothing about whether it can catch anything. The flywheel only turns toward value if, on every failure:

The failure minimizes and re-enters as a regression case. Every real bug becomes a permanent, tiny, deterministic test. The corpus grows in the shape of your mistakes.
You periodically test the oracle itself. Inject a known fault — delete a hazard rule, invert a guard, drop a constraint in the introspector — and confirm some law kills it.

fault injected ──▶ does a law fail?
                     ├─ yes → oracle bites. trust the green.
                     └─ no  → green is decorative. fix the oracle.

That second step is the one I see skipped most, and the one that keeps the whole thing from becoming theater. An oracle you never test is a claim, not a check. Honest flywheel: minimize failures into the corpus, and verify the verifier. Do that and it genuinely compounds.

What got cheap (and what didn't)

A few years ago this pipeline was a staffing decision: generators, shadow DB, migration planner, Docker orchestration, per-dialect adapters — a team and a quarter. The barrier wasn't ideas; it was implementation labor, and that priced most people out of serious simulation testing.

That wall came down, and I can point to where. A per-dialect adapter — the layer that maps my IR onto one database's quirks — used to be a multi-day slog of reading docs and discovering edge cases by getting burned. The last one I added came out in an afternoon: I described the IR and the target's introspection format, the agent drafted the adapter and a first pass of its quirk-rules, and I spent my time reviewing rather than typing. Parsing is a commodity, local execution is cheap, and the long tail of boilerplate writes itself faster than I can spec it.

But notice exactly what got cheap. Building the harness did. Knowing which relations are actually invariant did not. Routing each law to a layer that can honestly answer it did not. Checking that the checker still bites did not. The agent wrote the adapter; it could not tell me whether safety belonged on the same axis as convergence, or whether my green meant anything. The scarce skill went from "can you build the harness" to "can you see what the law is." The implementation got democratized. The judgment didn't.

Where it breaks

Local simulation kills a startling fraction of bugs for almost no money. It does not replace a remote environment:

Provider parity — the real cloud API does things no emulator reproduces.
Real enforcement — IAM denies, KMS policies, VPC isolation, audit-log immutability: only provable against the real thing.
Hosted-backend quirks — managed Postgres, pooler modes, hosted auth schemas. My local Docker Postgres happily ran a migration that deadlocked on a managed instance behind a transaction-mode pooler, because the pooler changes how sessions and locks interleave — behavior the local container simply doesn't have.
Genuine concurrency at scale — race probes catch a lot; they don't certify production load.

These live on a rare live tier, used as calibration anchors, not bulk testing. Local says the logic is right; only live says the platform agrees.

Objections I'd raise myself

"This is just property-based testing." The generation and shrinking, largely yes. The contribution is the framing: the oracle is the artifact, the laws need no reference, and safety is a first-class axis.
"Why not just have the agent write and run the tests?" I tried, hard. The agent will produce a plausible suite, but it tends to test the happy path it just wrote and skip the case that actually bites — and you can't tell from the green. A fuzz harness inverts that: the agent supplies generators and laws (things I can review), and generation finds the cases neither of us thought of. The agent is good at proposing rules, unreliable at being exhaustive.
"AI-written oracles are subtly unsound." The failure mode I fear most — a hole in the oracle reads as safety. So: borrow battle-tested algorithm cores, keep the bespoke part to domain rules I can eyeball in review, never let the harness downgrade a real bug to "expected." The verifier is the last thing you let the AI write unsupervised.
"Green still lies." Until you mutation-test the oracle. That's not polish; it's what makes green mean anything.
"This grows into an unmaintainable matrix." Only if every law runs on every layer. Counter-discipline: route each property to the cheapest honest layer, retire laws that stop catching anything.

Where this is going

I came in through a practical door — semantic fuzzing catches a lot of bugs cheaply — and walked out somewhere narrower: the random part was never the point. The oracle was, and AI made everything except the oracle cheap enough to finally see that.

In the AI era, rigor is what pays off: it compresses a vague situation into a few hard facts an agent can act on. Here that takes its sharpest form. Rigor is what turns blind randomness into a bug-finding machine: the law does the finding; the noise just does the walking.

The implementation barrier is down. Knowing what "correct" even means for the thing you built is the whole job now.

Which brings me back to that green migration with DROP TABLE hiding in its path. The fuzzer didn't miss it because the randomness was weak. It missed it because I hadn't yet written the law that calls erasing your data a bug. The day I did, generation found the case in minutes — it had been walking past it the whole time, waiting for me to say it mattered. That's the job now: not running more cases, but learning to name the failures worth catching, one law at a time.

Every API Will Be Rebuilt for Agents

Takafumi Endo — Tue, 23 Jun 2026 11:15:18 +0000

MCP solves the plug. It doesn't solve the verb gap.

Hand a coding agent a beautifully documented REST API — versioned, OpenAPI'd, the kind a human developer would happily build against — wrap it in MCP in an afternoon, and watch it still fumble. It picks the wrong endpoint. It calls three when one would do. It does a destructive write it should have asked about. The API isn't bad. It's built for the wrong consumer.

MCP is winning the part that was always going to be solved — the plug. And winning is what exposes the uncomfortable part: almost every API we have is built for a consumer that's no longer the only primary consumer. For twenty years that consumer was a human developer who showed up with intent and a mental model. Now it's an agent that has neither and has to reconstruct both from your surface. When the primary consumer of an interface changes that completely, the interface gets rebuilt. It always has.

So, here's the claim I'll commit to: the serious product surfaces agents operate against will be rebuilt around agent-native operations. Not wrapped. Rebuilt. These are still one person's notes, not advice — and intentionally directional, not a migration plan. The direction isn't what I'm unsure about. Only the timeline is.

When I say every API, I don't mean every endpoint gets replaced or every protocol disappears. I mean the product-level operations an agent is trusted to execute move from resource-shaped APIs to intent-shaped contracts — redesigned around goals, state, side-effects, approval, and recovery.

MCP standardizes the plug, not the operations

Give MCP its due: it's now a genuine cross-client standard — Claude, ChatGPT, VS Code, Cursor, Codex, Copilot. Connection, auth, transport, human-in-the-loop, long-running Tasks: all getting standardized, steadily.

But in the spec, a tool is just a function — a name, a description, a schema. MCP deliberately doesn't decide what state transitions your domain has, what order tools go in, which operations are dangerous, or which need approval. That's the right scope for a protocol. It also means MCP gives you a clean way to expose whatever your API already is — and what it already is, is a thing designed for a developer who brings the plan.

Call the failure the verb gap: APIs hand agents nouns and CRUD; agents need verbs that carry intent. No protocol closes that gap, because the gap is in the API, not the wire. MCP solves the plug. It does not solve the verb gap.

The wrapper ceiling is already visible

The tell is that the most API-mature companies are walking the wrapper back, in public.

GitHub's official MCP server is excellent — and GitHub is narrowing its default toolset and consolidating PR tools into fewer, more capable ones, explicitly to cut tool bloat and improve agent reasoning. The implication is hard to miss: even one of the best API companies on the planet is learning that a 1:1 mapping from product API to agent tools isn't the right shape.

Research points the same way. AutoMCP generated MCP servers from OpenAPI specs: across 50 real APIs and ~5,000 endpoints, tool-call success went from 76.5% to 99.9% — but only after fixing the underlying spec. A 2026 study on agent-ready OpenAPI docs found agents failing systematically at planning and tool selection, with defects in essentially every operation. Their line is the one to underline: an API can be structurally valid and still not be semantically ready for an agent.

Every "just wrap it" path ends at the same wall — the contract is wrong for the new consumer, and you can't wrapper your way to a different contract. Wrapping buys a demo. Rebuilding buys a product.

What "rebuilt for agents" looks like

An agent-native API isn't an API an agent can call. It's an API whose operations carry enough intent, state, and safety for an agent to know what it's doing.

Not a few coarse endpoints bolted on. A different default shape for every operation — one that answers more than "what do I return." It answers: what's the goal, what state am I in, what are the side-effects, do I need approval, how do I recover.

inspect_pull_request        → state + what's relevant, not the raw blob
find_merge_blockers         → the global fact, computed, not re-derived
preview_write_action        → dry-run: here's what WOULD happen
commit_approved_action      → the write, gated behind explicit approval
explain_missing_permissions → why it can't, in actionable terms
rollback_last_action        → recovery as a first-class verb

Agent-native doesn't just mean coarse-grained. A coarse endpoint can still be unsafe, opaque, and impossible to undo. The difference is that an agent-native operation exposes its preconditions, expected effects, uncertainty, required approvals, and recovery path as part of the contract. preview / commit split intent from effect, so a dangerous write becomes a two-step you can reason about. rollback makes recovery part of the surface, not an afterthought.

There's a hint here about how these get built. Today we usually grow REST outward from the database — tables become resources, columns become fields, CRUD becomes the default. But an operation that knows its preconditions and its legal next moves is really a state machine wearing an API. It's not a stretch to imagine the mainstream flipping: generating the surface from an explicit state model — transitions, guards, and valid next-actions as the source of truth — with storage downstream, instead of the other way around. That's the version of this I'd most want to build.

And here's why it's one API, not two: developers want all of this too. Preview-before-commit, blast radius, clear permission errors, rollback — that's not an "agent edition," it's just a better API whose main consumer happens to be an agent. You don't want to maintain a human API plus an agent API forever. Over time, the agent-native design should subsume the human one.

This connects to the last post: a good operation collapses a risky multi-step workflow into one confident verb, the way a rigorous fact collapses a hedge into a flat statement. Rigor compresses; so does a good operation.

It's not just APIs — CLIs are the same surface

This was never really about REST. It's about any surface an agent operates against, and the CLI is the other big one. A coding agent lives in a terminal — it runs git, kubectl, your build and deploy scripts — and hits the same verb gap: tools that assume a human who already knows the flags.

CLIs add a second problem the API case hides: output. Most CLIs print for a human — colors, progress bars, free-form logs, a summary line you're meant to eyeball. The agent has to scrape that, which is the verb gap again, moved to the return path. So an agent-native CLI prioritizes machine-readable output — --json, structured logs, stable exit codes, errors that name the next action — over pretty terminal formatting. When you can't have both, the default flips: readable for the agent beats readable for the eye.

That's the same coin as the verb gap, both sides of it. Calling side: verbs that carry intent. Return side: state the agent can parse, not prose it has to interpret. And the shift is bigger than APIs: every interface we built assuming a human on the other end — APIs, CLIs, logs, output formats — is up for reconsideration once the other end is an agent.

Security is what makes it "must," not "nice"

MCP clients put tool name, description, and schema straight into the model's context — so a malicious description can steer the model (tool poisoning, confused-deputy, over-broad scopes). And agents use configured tools autonomously; GitHub's own docs recommend allowlisting read-only tools for exactly this reason.

You can't allowlist your way to safe writes on a human-shaped API. You rebuild writes as preview → approve → commit, with permission errors that explain themselves. Safety isn't a wrapper you add; it's a property you design into the operations.

Three layers now, one contract later

This won't happen overnight. Near term, three things coexist — but only one is the endgame.

Layer	What it is	Status
Direct API / SDK / CLI	local detour — files, shell, git, tests	persists where proximity beats protocol
Wrapper MCP over legacy API	the human-shaped API, exposed as tools	a bridge — scaffolding, not a destination
Agent-native API	goal-shaped operations with state, approval, recovery	where everything converges

The wrapper is useful as a transition — it connects what exists today — but it carries the legacy contract underneath, and that contract is the problem. Over time the core gets rebuilt and the wrapper dissolves, the same way mobile BFFs gave way to redesigned APIs instead of living forever as shims.

Practically: greenfield should start agent-native now — no reason to ship a human-only contract you'll rewrite. Brownfield wraps as a bridge, then rebuilds the operations that matter most first. Either way the arrow points one direction.

Objections I'd raise myself

"You can't rewrite every API; legacy is forever." Legacy persists — but "persists" isn't "is what you'd build." SOAP still runs; nobody starts there. Human-shaped APIs become the thing you wrap and migrate off, not the thing you design.
"This is just BFFs rebranded." The technique isn't new; the consumer is. A BFF serves a fixed UI flow a human designed. An agent-native operation has to surface its own preconditions, danger, and recovery, because the agent is forming the plan — and it applies to the whole surface, not one frontend.
"Models will get good enough to use raw APIs." Maybe for reads. But capability makes the security case worse — a more capable agent doing an unguarded destructive write is the nightmare, not the fix.
"Rebuilding every domain doesn't scale." The load-bearing worry. The bet is that AI dropped the cost of domain-specific implementation enough that it finally pencils out. If that's wrong, the timeline stretches. The direction doesn't change.

Where this is going

The contract at the center of interface design is flipping. Old: the human holds the intent; the API returns materials. New: the agent holds the goal; the API returns state, constraints, the next safe action, and a way back. The competitive axis stops being endpoint count and becomes whether an agent can safely accomplish a goal against your surface.

We probably don't have the right format for this yet. I doubt it's REST or GraphQL; both were shaped for consumers that aren't the agent. For now, OpenAPI and Zod are still the right place to stand: precise schemas reduce mistakes, and AutoMCP's jump from 76.5% to 99.9% is evidence of that. But implementer correctness and agent operability are different axes, and the second one will likely grow its own format. That part I'm looking forward to.

These days I keep tacking defensive lines onto prompts: "preview before you write," "ask before anything destructive," "explain why you can't." It's not that I distrust the agent — it's that the operations I hand it are the vague part, so reminders are the only patch I have. Rebuild the operations to carry their own preview, approval, and rollback, and those lines stop being necessary.

If the operation is safe by design, you don't have to ask the agent to be careful with it.

The Repo Is the Context: Why Agents Don’t Need History

Takafumi Endo — Fri, 19 Jun 2026 10:46:54 +0000

History still matters. I just don't want it to be the default context for agents editing the present system.

A coding agent will read whatever you put in front of it.

That sounds like a strength. Most of the time it is the problem.

For a while my answer was "more Markdown" — CLAUDE.md, AGENTS.md, specs, ADRs, planning docs. It felt responsible: agents need context, so give them context.

Then I watched an agent do something confidently wrong because it had faithfully trusted a document that described a system we stopped having months ago. It wasn't a hallucination. It was obedience to history.

That's when the question shifted for me. Not "what prompt should I write?" but the quieter one underneath it: what should the agent read? I wrote recently that token efficiency is really a "what do you hand over" problem — each token should buy a verified fact, not a guess. This post is the same idea, pointed at the repo itself.

History is for humans. The present source of truth is for agents.

This is not an argument against keeping history.

I still think ADRs, migration logs, old specs, and planning docs are valuable. They explain why the system took its current shape — the tradeoffs, the constraints, the abandoned paths, the organizational memory. Humans need that. When you're reviewing a decision, onboarding to a domain, debugging a strange constraint, or trying to understand why an obvious-looking change was deliberately avoided, history is exactly the right thing to read.

But Claude Code, Codex, and similar coding agents are usually doing something different. They're about to edit the present system.

For that task, historical prose shouldn't be the primary context. The agent needs the current source of truth: current schema, current module boundaries, current public APIs, current tests, current state machines, current configuration, current dependency rules.

A human may read migration history to understand how the database evolved. But I don't want Claude Code to learn the current database by replaying every migration — I want it to read the current schema. A human may read ADRs to follow the reasoning behind a decision. But I don't want an editing agent to infer the current architecture by replaying every ADR — I want it to read the current module graph.

History explains why the system became this shape. The current source of truth explains what shape it has now. Both matter. They just serve different readers.

Reader	What they should read
Human — trying to understand why	ADRs, old specs, migration history, design notes
Coding agent — trying to change what exists now	current schema, tests, types, module graph, config, public APIs

So the rule was never "delete history." It's:

Keep history for humans.
Give agents the present source of truth.

A well-shaped repository should let an agent understand the current system without replaying its past. And the larger the system gets, the more this matters — not because history becomes useless, but because in prose it gets mixed in with obsolete truth, and the two become indistinguishable. The danger isn't the old fact. It's the old fact wearing the same clothes as the current one.

Drift is the failure mode, and agents are loyal to it

Here's the chain I keep tripping over:

duplication → drift → context pollution

The moment a fact lives in two places — once in the code, once in a Markdown description of the code — they begin to diverge. Code changes under pressure; prose changes when someone remembers. So the doc quietly goes stale, and now you have two answers to the same question with no marker for which is current.

A human reading a slightly-wrong doc squints and cross-checks. An agent doesn't squint. It's very good at trusting polluted context and acting on it decisively. The thing that makes agents fast — taking the given facts at face value — is exactly what makes drift dangerous.

So the most useful move isn't writing better docs. It's having fewer places where a fact can rot.

A boundary in CLAUDE.md is advice. A boundary in the build is architecture.

This is the line I keep coming back to.

If CLAUDE.md says "the billing module must not import from checkout," that's a polite request. Nothing enforces it; the next edit can ignore it and nobody — human or agent — gets stopped.

If that same boundary lives in ESLint config, in package.json exports, or in TypeScript project references, it's no longer advice. It's a wall. The agent doesn't have to remember the rule, because the rule is a property of the system it's editing.

That reframes "AI readability" for me. It was never about writing longer instructions. It's about making the repository itself say the true thing — structurally, where it can't drift:

directory structure carries the architecture
naming carries intent
package exports carry the public API surface
lint rules carry dependency boundaries
schemas carry data contracts
state machines carry workflows
tests carry expected behavior
config files carry the actual stack
generated-file markers carry "do not touch by hand"

Each of these is closer to the system than any sentence about the system can be. That proximity is the whole point — the closer a fact sits to the thing it describes, the less room there is for it to lie.

Markdown should be a map, not the territory

I haven't thrown out CLAUDE.md and AGENTS.md. I've shrunk them.

Their job isn't to restate the architecture. It's to point at where the current architecture actually lives.

## Sources of truth

- Database schema:     packages/database/schema
- API contract:        packages/api/openapi.yaml
- Checkout workflow:   src/features/checkout/checkout.machine.ts
- Public package APIs: package.json "exports"
- Module boundaries:   eslint.config.js
- Commands:            package.json scripts

That's a map. It survives change, because it points at the territory instead of copying it.

The trap is the opposite: a section in CLAUDE.md that restates the behavior — the checkout states, what billing depends on, what the API accepts. The day the code moves, that paragraph becomes a confident lie. And the agent will read it with exactly the same trust it gives the truth.

Specs are scaffolding — give them an exit strategy

I still like a short spec at the start of a feature. It gives Claude Code or Codex a sharper target than vague intent, and it helps me think. That part is genuinely useful.

The mistake is letting the spec stay as a second source of truth after the code exists. Once the feature ships, the durable parts of the spec should migrate into the repo's present tense. This is where the repo starts becoming readable without being explained:

The spec captured…	…so move it into
screen states	state machine / Storybook stories
API behavior	OpenAPI / GraphQL / typed router
validation rules	Zod / Valibot / JSON Schema
domain states	discriminated unions / domain model
permissions	policy code / authorization tests
database rules	schema / constraints
done-ness	tests
infrastructure	Terraform / OpenTofu / Pulumi

The spec was scaffolding around the building. You don't leave scaffolding up and then ask people to trust it over the walls.

Naming is prompt engineering, run inside the repo

This is the part I find quietly fun. Agents infer intent from names — which means names aren't only for humans anymore.

createUser()
updateUser()
deleteUser()

tells an agent almost nothing about the domain. This:

registerMember()
inviteMember()
deactivateMember()
transferWorkspaceOwnership()

tells it where it is. The same goes for structure — a layout an agent can read as a map of where behavior belongs:

Path	What lives there
`domains/billing/commands/`	state-changing operations
`domains/billing/queries/`	reads
`domains/billing/policies/`	authorization rules
`domains/billing/repositories/`	data access

A layout like that answers "where does this change belong?" before the agent has to guess. And it will guess — if the repo doesn't tell an agent where a thing lives, it'll happily invent a home for it, somewhere plausible and wrong.

So naming and layout are a kind of standing prompt: written once, into the structure, read on every single run.

The same "what do you hand over" question, one layer up

In the graphs post, the facts I wanted to hand an agent were computed — dominance, reachability, ordering — and the discipline was labeling each one verified or estimated by where it came from.

This is the same question, just earlier in the pipeline. A current schema is a verified fact about the data. A migration log you have to replay is, at best, estimated truth about the present. A lint-enforced boundary is verified; a sentence in CLAUDE.md is a hope. The repo, when it's shaped well, is a source of facts that carry their own freshness — because they are the system, not a description trailing behind it.

Present schema over migration history. Current module graph over ADRs. Live tests over old acceptance criteria. Real config over README prose. State machines over paragraphs about workflows.

None of that throws the history away. It just stops asking the editing agent to reconstruct the present from it.

Last year I tuned the instructions. This year I shaped the repo.

I want to be honest about where this comes from, because it's experience, not a benchmark.

A year ago I was fixated on the instruction layer — .claude/, .codex/, AGENTS.md, CLAUDE.md. I tuned rules, wrote skills, kept the files growing, treating the prompt around the repo as the thing to perfect.

Somewhere along the way the obsession moved. Instead of tuning the instructions, I started tuning the repo itself: pulling facts into a single source of truth, refactoring toward structure an agent could read, writing new code the same way from the start.

What I notice now is that the instruction files matter less than I expected. On a repo in the hundreds of thousands of lines, with a short AGENTS.md and rules and skills that are nowhere near perfectly tuned, I rarely feel Claude Code drift from what I intended, or stall when it's time to actually implement. The friction I used to paper over with longer instructions mostly just isn't there.

The honest caveat: the models and the agents themselves got dramatically better over the same stretch, and I can't cleanly separate "my repo got more legible" from "the tools got smarter."

But the direction of the feeling has been consistent: the more the present lived in the repo instead of in prose wrapped around it, the less I had to say to get good work out of the agent.

Where this is going

These days I keep adding defensive lines to prompts: "don't trust stale docs," "check the actual schema," "don't guess where this goes."

The better answer is not to write better warnings.

It is to shape a repo where those warnings are unnecessary.

Keep history for people. Shape the present for agents.

Human-readable history explains why the system became this way.
AI-readable repositories expose what the system is now.

Don't make agents reconstruct the present from the past.
Make the current source of truth impossible to misunderstand.

Rigor Compresses: Why AI Agents Need Graphs, Not More Context

Takafumi Endo — Thu, 18 Jun 2026 01:53:21 +0000

A coding agent can edit one function beautifully.

But ask it a global question — "what breaks if I change this?", "can this write run without the tenant check?", "is this migration destructive?" — and it often starts guessing.

For a while, I thought the answer was better token efficiency. Now I think the deeper question is: what facts do you hand the agent in the first place?

I recently wrote on Medium that token spend only becomes an asset when you redesign the work around it — verification, context, workflow — rather than just buying more of it.

This post is the engineering side of that argument. Since then I've been hunting for token-efficient tooling, and writing my own when nothing fits. What follows is the piece I find most leverageable: making each token buy a verified fact instead of a guess. (Just where my own tinkering has led — not advice.)

Token efficiency is really a "what do you hand over" problem

"Saving tokens" sounds like a story about compression and caching — or, lately, about giving the agent more context: bigger windows, more retrieval. But in my own work, what moved the needle most wasn't more context; it was the quality of the few facts I hand the agent.

Coding agents are strong locally. Within one function, one diff, they write beautifully. But the global facts — what calls this, what breaks if I change it, whether this write can run without the tenant check, whether this migration is destructive — they tend to guess at, fairly confidently, and sometimes get wrong.

So what helps, I think, isn't a long analysis log or a full-repo grep — it's handing over those global facts short, accurate, and with evidence. The heart of token efficiency is not saving but maximum signal per token.

The global facts you want are mostly graphs

What's interesting is that most of the global facts agents struggle with look like graph questions.

Impact — who depends on this? → reachability over a call/reference graph
Ordering & cycles — can these migrations apply in a valid order? → topological sort + cycle detection (DAG)
"X before Y" — does the required guard run before the dangerous op? → dominance in a control/call graph
Flow — can untrusted input reach this sink? → reachability over a dataflow graph

depends-on, calls, flows-to, must-precede are all relations, and a set of relations is a graph. Facts an agent has trouble deriving on its own often come out cleanly once you turn them into a graph.

Put differently: every one of these facts can be written in a single language — a dependency graph. Impact, ordering, guard dominance, flow. It's the common language for handing facts to an agent.

And the toolkit you need is smaller than you'd think: traversal, topological sort + cycle detection, strongly connected components (SCC), reachability, dominators, occasionally shortest path or max-flow. Past that, an eye for spotting when a problem is a graph covers most of it, I'd say.

A fact I want to hand an agent looks less like a paragraph and more like this:

DB.GUARD_BYPASS  repo.rs:142  severity=high  quality=verified
  claim:   delete reachable without tenant guard
  missing: assert_tenant() does not dominate this sink
  path:    handler → repo.raw_delete
  next:    use repo.delete() (scoped) | read(repo.rs:120)

The hard part isn't formatting the fact. It's producing it cheaply, with enough evidence to trust it.

Graph theory has always been practical — but it feels like it's accelerating

Graph theory, DAGs first among them, has long been put to practical use in software. Build systems, dependency resolution, scheduling, compilers, plan/apply-style orchestration — open any of them up and it's a graph. None of this is new.

But it does feel like it's accelerating now, and I think the reason is AI coding. Implementing these algorithms used to sit behind a wall of cost and specialization. That wall has come down, and algorithms feel like they're being democratized in a practical sense.

The framing I personally find useful is that an algorithm is two layers: a base theory, and on top of it, optimization for a specific domain. The theory is shared; the optimization is domain-specific. What AI dropped most is the latter — the cost of implementing it for your own domain.

So I've drifted from generic OSS toward small, homegrown detectors

This shift quietly changed how I pick tools. Generic analysis OSS gives you the commodity — algorithms, parsers, a query language — and does it well. But the valuable layer, your own domain, is something you end up filling in yourself. A generic taint engine doesn't carry the assumption that assert_tenant() is a required guard, or which calls are dangerous sinks, or the invariants of your declarative schema layer. The algorithms are interchangeable; the domain model on top is harder to swap.

Parsing is a commodity (tree-sitter), the algorithms are a small known core, and an agent can help you write the domain rules quickly. So the bar for "worth building" drops, and a long tail of small, domain-specific detectors — never worth it before — starts to pencil out. That long tail, I suspect, is where a good chunk of the practical value lives. And the agent both builds them and consumes them: a generate ⇄ verify flywheel starts turning.

The substrate these homegrown detectors build their facts on is two layers: tree-sitter and LSP. tree-sitter is an incremental, error-tolerant parser — it can pull structure cheaply even out of a half-written, broken buffer — but it doesn't resolve names, so I treat facts from it as estimated. LSP actually resolves types and references, so those can be verified, at the cost of being stateful, with cold starts and lag. What I find interesting is that the layer you pick maps straight onto the quality label — and that freshness tends to invert: synchronous, local tree-sitter is closest to the dirty buffer, while precise LSP can lag behind as its index catches up. So I've been doing an "until LSP catches up, fall back to tree-sitter and label it estimated" kind of switch. Right now I'm implementing and testing exactly this — driving the LSP client headless (keeping the buffer in sync via didChange, juggling servers across languages) — and it's the kind of thing that gets more interesting the more you actually build it.

The division of labor, roughly:

	tree-sitter	LSP (language server)
Gives you	syntax / structure (CST)	resolved types & references
Resolves names?	no	yes
Quality label	`estimated`	`verified`
Cost / state	fast, local, synchronous	stateful, cold starts, lag
Half-written buffer	works (error-tolerant)	often bails
Freshness vs the edit	closest to the dirty buffer	can lag while re-indexing

There's one discipline I try to keep: where to draw the trust boundary. Dominator computations and dataflow fixpoints, written with AI help, tend to come out "plausible but subtly unsound" — and in hazard detection, unsoundness means a miss that reads as safety, which is the failure I most want to avoid. So, for myself, here's what I do:

borrow battle-tested algorithm cores (don't hand-roll dominators)
keep the bespoke part to the domain rules I can actually eyeball in review
label every fact verified (graph-derived) or estimated (pattern-derived)

Where you put the "verification of the verifier" feels like what decides whether the flywheel turns toward value or toward error.

A concrete example: detecting dangerous DB operations

Take the DB.GUARD_BYPASS fact from earlier — here's how it gets computed. In a declarative schema-management tool, a hazard like "a dangerous write is reachable without passing the guard" turns into a fairly clean graph question: the required guard should dominate the dangerous sink, and if it doesn't, the sink is reachable without the guard. I compute this over read-models I already have (a symbol index, dependency edges), cheaply, and it's close enough to sound that I can emit it as verified.

By verified I don't mean globally true in the formal-methods sense — I mean something narrower: the claim follows from the graph model I built, with evidence, rather than from the agent's guess. The model itself can still be incomplete, so the label is about the source of a fact, not absolute truth.

What's doing the work here is that rigor produces compression. A pattern match can only hedge — "possibly an unscoped delete, please verify" — and hedging costs tokens. A dominator result can state one fact flatly: this guard does not dominate this sink. The more rigorous the analysis, the shorter the fact. "Doing it properly" and "handing it over in few tokens" might, it turns out, be the same investment.

Personally, the database side is where it gets most interesting

The same dependency question keeps reappearing at larger scales — first inside a function, then across a repository, then across storage systems: what depends on what, what must happen before what, and what changes when this node moves?

The two-layer structure shows up most sharply, I find, around databases. Even just "storing data," the design changes with PostgreSQL vs SQLite. It changes again depending on whether you ship schema via migrations or express it declaratively. And OLTP vs OLAP are, infrastructurally, almost different worlds.

But — and this is the part I find interesting — look at them through the lens of "how do you define the dependencies," and things that are scattered at the infrastructure level start to connect into a single graph. Transactions and analytics, writes and aggregations, mutable state and immutable snapshots. Physically separate worlds, yet contiguous on the abstraction of how dependencies are defined. Even an architecture where an event log links a control plane (Postgres) to a data plane (object storage + columnar) ends up looking, to me, like one dependency graph.

Could you bind even heterogeneous infrastructure together in the same dependency-graph language you use to hand an agent facts? I feel like there's quite a bit of potential in that view.

Where this is going

I came in through the practical doorway of token efficiency and ended up at "deterministic facts to hand an agent," the graphs underneath them, the democratization of algorithms that makes them buildable, and the abstraction of dependency. The theory is mature, the implementation barrier has dropped, and per-domain craftsmanship is becoming the center of value, it feels like — and the area still feels wide open.

I plan to dig into it for a while. As a start, I'll jot down the themes I'm interested in, a bit at a time.

One last thing — a hope. These days, working with Claude Code or Codex, I keep tacking defensive lines onto my prompts: "watch for false positives," "don't miss false negatives," "don't guess, verify." It isn't that I distrust the agent. It's that the facts I'm handing it are the vague part, so reminders are the only way I can paper over the worry.

My hope is that, as I keep practicing this graph stuff — as I get better at handing over grounded facts that carry their own verified / estimated labels — I'll need to write those "please be careful" lines a little less often.

If the fact itself is sound, you don't have to ask the agent to be careful about it.

This is the practical reason I care about the shape of facts, not just the size of context. Instead of telling the agent to be cautious, you bake the caution into the facts.

That, maybe, is the view I most want to reach at the end of this detour.

DEV Community: Takafumi Endo

Why Athena/Iceberg Tends to Make Code the Spec

The spec has two copies

Why this is mostly discipline

But the engine sets the difficulty

Why I actually care: the guesser downstream

It's the same move I make everywhere else

Objections I'd raise myself

Where this leaves me

The Agent Runtime Got Heavy: Rethinking Sandboxes with Codex App Server

Cloud sandboxes have already come a long way

The hard part isn't "starting a VM"

On the desktop, the user's PC is already a finished runtime

PTY brings interactive local execution into the app

Codex is well suited to embedding in a desktop app

You get Codex's own local sandbox

Even so, embedding Codex isn't simple

Separate the UI process from the execution process

The UX advantages of the desktop shape

The desktop shape has clear weaknesses too

Which should you choose

Wrapping up

Designing Schema Boundaries for AI Agents

The new reality: the agent writes the schema

The hazard is the green build

The lightweight stack is great — and it doesn't close the loop

What's missing is a harness

Lower to an IR, don't diff strings

Hazards, not diffs

Make the Boundary Machine-Readable

What I would put in CI

Objections I'd raise myself

Where this is going

AWS Is Not Simpler. Agents Just Got Better at Reading It.

The inversion

Same Terraform, two providers

Cloudflare is a different bet, not the wrong one

The safety boundary (this is not "walk away")

Why this isn't an AWS victory lap

You Can't Review an Agent. You Can Review a Plan.

Your repo has non-human authors now

Reviewed and applied are two different facts

The harness, in four boxes

Observer isn't monitoring

One gate, no side doors

A rule in a prompt is only a wish

A destroy is the DROP COLUMN of infrastructure

Sign the plan, not the checkmark

Objections I'd raise myself

Where the harness leaks

Self-driving isn't unattended

AI Agents Don't Need a Monorepo. They Need a Readable Codebase

monorepo helps — when "same place" is machine-readable

The bottleneck is coordination, not the repo

At scale, "sees everything" backfires

Before any of this: the structure has to be readable

The repo is physical. The workspace is operational.

Objections I'd raise myself

A checklist that earns its place

The shape, in one line

Let Aurora Sleep: Multi-Tenant SaaS Cost, Reconsidered with AI IaC

The default bills like it's always on

The reframe: Aurora as a thin control plane

Sleep-first only works if the app lets Aurora sleep

No NAT: separate "can reach data" from "can reach the internet"

The part that makes this AI-friendly: declarative schema

You don't have to be an infra specialist up front

When this stops being the right call

What I'd actually measure

Objections I'd raise myself

A checklist before you try this

Still figuring out the edges

The Wrapper Got Heavy: Why ChatGPT Clones Are Runtime Problems Now

What "wrapper" used to mean

Two things that are easy to blur

The sandbox is the actual product surface

Runtime choice is really a state-gravity decision

Don't rebuild Codex or Claude Code — drive them

The part worth owning — and how thin the moat really is

Objections I'd raise myself

A `destroy` is the `DROP COLUMN` of infrastructure