DEV Community: Takafumi Endo

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.

Why AI Agents Make Me Reach for SQLite

Takafumi Endo — Wed, 17 Jun 2026 03:34:20 +0000

Lately I keep reaching for SQLite where, before, I'd have reached for Postgres without thinking.

It started with small services, then a bigger question: could a multi-tenant SaaS actually run on SQLite? And for AI agents specifically, isn't a local, embedded database the more natural home for their state?

Turso is the version of this stack I've found most compelling so far, especially when paired with Cloudflare. I wish D1 would reach embedded-replica parity with Turso, and that AWS offered a managed SQLite-style service the way it offers RDS for Postgres.

This isn't a "Postgres is over" argument. I still use Postgres more often than SQLite. And it isn't advice. It's just where my thinking has drifted recently — written down mostly so I can find out where it's wrong. Read it as one person's notes, not a recommendation.

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

SQLite isn't replacing Postgres.

For work state, it's increasingly my first reach, not my last.

AI agents push this harder: their state is high-churn, local, and mostly private.

The answer isn't all-local. It's a local workbench plus a central ledger.

Why the old default existed

For years, "where does the data live?" had one practical answer: a server, behind an API, in a shared Postgres. A lot of that wasn't architecture — it was the cheapest shape available.

SQLite was already everywhere, but it lacked the operational layer that makes a database viable as SaaS infrastructure: networking, replication, managed backups, and a way to run many small databases without drowning in tooling. So centralizing was the path of least resistance, and a tenant_id column in shared Postgres became the reflex.

What changed isn't SQLite. It's that the ecosystem grew the missing parts — and for a growing class of workloads, the thing doing the most frequent writing moved onto my own machine.

The constraint that's lifting

SQLite itself is, by design:

Embedded, not networked — a library, nothing listens on a port.
Single-file, not replicated — no built-in read replicas or failover.
Single-writer — WAL gives many readers + one writer; contend and you hit SQLITE_BUSY.

None of this got fixed by changing SQLite. It got fixed around it:

libSQL (Turso's SQLite-compatible fork) — managed server layer, remote access, embedded replicas, encryption, vector search. (The from-scratch Rust successor — "Limbo," now Turso Database — is a separate, less-mature track; don't conflate them.)
Embedded replicas — a full local SQLite copy synced into your process; reads local, writes forwarded to a primary.
Cloudflare D1 — managed serverless SQLite with global read replication and read-your-writes via a Sessions API.
Durable Objects — a SQLite database in the same thread as your code.
Litestream / LiteFS — stream the WAL to object storage for durability, without touching the write path.

The single-writer model hasn't disappeared, and I still design around it. But "SQLite can't be networked, replicated, or run as shared infrastructure" has stopped being quite as true in practice — so some of the reasons I used to centralize by reflex don't hold for me the way they once did.

State gravity

A loose model I use to keep the trade-off straight: state gets pulled toward whatever reads and writes it most. Put the writer far from the state and you pay the distance on every op — latency, egress, pools, consistency reconciliation. Put them close and most of that disappears.

For two decades the writer was a human clicking a web app: small, occasional, round-trip-tolerant. Weak pull, so central state was fine.

That writer changed. The useful agents run inside the work environment — file system, terminal, IDE, browser tab, an already-authenticated session. Codex CLI runs in a local terminal against a directory you choose; Claude Code reads the codebase, edits files, and runs commands on your machine. The strength is proximity as much as model quality.

While it works, an agent holds a lot of state: task plan, file index, staged/unstaged diffs, tool-call history, failures and retries, approval state, a local search index, an embeddings cache, sync cursors, idempotency keys, an undo/redo log.

It's high-churn, local, and useless to anyone else. Round-tripping all of it to central Postgres is expensive on three fronts:

Latency — local SQLite reads tend to be one to several orders of magnitude faster than a networked read (workload-dependent): an embedded replica answers from a local file; a remote read pays the network first.
Cost — ledger-grade infrastructure to store scratch work deleted in an hour.
Privacy — the moment an agent's index of your files leaves the machine, you've created a data-handling problem you didn't need.

Writer moves local → work state follows.

Local isn't just closer — it's bigger

Proximity is one reason. The one I find most underrated is raw hardware — but I want to be careful about which case it applies to, because it's easy to overreach here.

It applies to the resident agent running on the user's own machine — Claude Code, Codex, and the like, running as desktop/CLI apps, a distinctly desktop-shaped workload. Compare what each side gives that single user. A modern laptop, exclusively: several to a dozen-plus CPU cores, tens of GB of RAM, a fast NVMe SSD, the local file system, sometimes a GPU/NPU, and a session already authenticated as them. A cloud multi-tenant runtime would hand that same user a slice — capped CPU, memory, disk I/O, persistent storage — and to run tools safely server-side you'd also need sandboxes, VMs, network controls, permissioning, audit logging, queueing. So even before network latency enters the picture, the local machine often wins on resources per user; the network just widens the gap. Let the model think in the cloud — the reading, writing, diffing, indexing, searching, and caching are cheaper where the hardware actually is, and that's the work that generates the local state.

It does not automatically carry over to a server-side multi-tenant SaaS agent, where the agent runs in your own infrastructure rather than on the user's laptop — there's no laptop in the loop to be "bigger," so this particular argument simply doesn't apply. The case for SQLite there rests on something different: the per-tenant economics, isolation, and blast-radius properties in the next section — not on "the edge has more compute." Two separate arguments for two separate cases, and I don't want to smuggle one in to prop up the other.

database-per-tenant, reconsidered

The pattern I keep arriving at for SaaS: one SQLite database per tenant (or per user, per agent), instead of shared Postgres with tenant_id everywhere and RLS holding isolation together.

Because a database is a file, the economics flip:

Tenant #10,000 is just another file — no per-database process, no cold start.
Cost scales with usage, not database count. In Turso's model, database count isn't the scarce unit it would be with Postgres; D1's current limits allow up to 50,000 databases/account, with billing based on rows + storage rather than a per-database server.
Isolation is physical, not a WHERE clause you hope you never forget.
Backup, PITR, and export become per-file operations. "Delete this customer" gets close to a per-file action — not literally rm, since backups, logs, the warehouse, search indexes, and audit trails still matter, but the operational state isn't scattered across shared tables.
Blast radius is bounded — a bad migration hits one file, not the shared cluster.

The honest costs:

Cross-tenant queries get harder. Not solved by querying 10,000 files at runtime — solved by outbox per tenant → event stream → central warehouse. That's infra you now own.
Migrations fan out. N migrations with partial-failure states; you want tooling that treats "apply to all tenant DBs" as a first-class, resumable op.
Single-writer ceiling is per database. Usually fine. A genuinely write-saturating tenant needs a different home — and isolation means only that tenant does.
D1 shape limits — 10 GB per database, single-threaded query execution per database.

The trade: give up effortless cross-tenant analytics and single-migration simplicity; get physical isolation, flatter cost, simple per-tenant lifecycle ops, bounded blast radius. For a lot of the B2B SaaS I work on, that's felt like a good trade lately — though how it nets out depends heavily on the workload, and I wouldn't generalize it past that.

Two latency tiers

  PRIMARY (source of truth)
     │  WAL frames
     ▼
  EDGE REPLICAS  ──── regional, network read
     │
     ▼
  EMBEDDED REPLICA ── in your process, local file read
     │
     └── writes ─────────────▶ forwarded to PRIMARY

Regional read replicas (D1, Turso cloud) put data near the user. D1's read latency can be excellent near the Worker — but it's still a network read.
Embedded replicas (Turso/libSQL) sync a real SQLite file into the process, so reads never leave the box. This is the tier I want for agents, which read their own state constantly.

In both, writes route to a single primary — the single-writer rule reappearing as a write-latency floor. US-West primary + Singapore writer = a Pacific round trip, regardless. You design for read-locality and accept write-centralization, which conveniently matches "local work state, central facts."

Consistency isn't free: D1's Sessions API gives sequential consistency within a session and read-your-writes via bookmarks. Adopt replicas, adopt their staleness model on purpose.

The agent's database = workbench + memory

Colocated compute + data. A Durable Object is a named unit of compute with its own strongly-consistent, SQLite-backed storage: "this agent owns this workspace" becomes literal — one object, one database, one writer, on demand.
Vector search in the same DB. Turso ships native vector search alongside relational columns, so for agent memory and RAG, embeddings and records live together — no separate vector DB to sync.

Scratch state in local SQLite, an embedded replica for fast reads of shared state, vector search in-box for memory. Little of that wants to be a network call to central Postgres.

Objections I'd raise myself

"SQLite still has one writer." True. I'm not claiming high write concurrency — I'm claiming many workloads don't need it inside one database once you pick the right boundary. It's a reason to choose boundaries well, not to centralize everything.
"Postgres does multi-tenant cheaply too." It does — Neon, Aurora Serverless, Supabase, RLS. The point isn't "Postgres is bad" — it's that, for me, "shared Postgres + tenant_id" stopped being the automatic starting point and became one option I weigh among others.
"Local-first sync is hard." The load-bearing difficulty. Sync is a product surface, not a background job. If two actors edit the same object, you need a conflict model before a database opinion. Per-tenant is easiest when tenants don't share writable state.
"Cross-tenant analytics gets painful." Yes — you lose the free JOIN and buy it back with a warehouse. Analytics-first across all tenants? Shared Postgres may still win. Tenant-isolated with roll-ups? Per-tenant tends to win.

Where it's not all-SQLite

Three things keep a strict central store:

Collaboration — shared, concurrently-edited objects need sync, conflict resolution, permissions, a converged view. Local SQLite provides none of that.
Accountability — who instructed it, which model, what permissions, what changed. That trace can't live only on the laptop it happened on.
Global truth — money, inventory, billing, contracts. Spread across edges and the system can disagree with itself about how much money exists. The ledger stays central, strict, singular.

So the shape is a gradient — fast/disposable at the edge, slow/strict at the center:

  SYSTEM OF WORK — the workbench         (local · high churn · disposable)
  ┌──────────────────────────────────────────────┐
  │  Local SQLite          agent / device work     │
  │  Embedded replica      fast local reads         │
  │  Per-tenant SQLite     operational state        │
  └────────────────────────┬───────────────────────┘
                           │
                  ⟨ Event log — sync + audit spine ⟩
                           │
  ┌────────────────────────▼───────────────────────┐
  │  Central ledger (Postgres)  money · billing      │
  │                              inventory · contracts│
  │  Warehouse / search          cross-tenant analytics│
  └──────────────────────────────────────────────┘
  SYSTEM OF RECORD — the vault           (central · slow · strict)

Postgres doesn't go away. It stops being where I start, and its free cross-tenant analytics moves to the warehouse.

A test: trace one change

An agent on a laptop edits a customer-facing record. What did it touch? On whose authority? Against what state? Can the team see it without re-deriving it?

All-central — clean answers, paid for by routing every keystroke (mostly scratch) through the network. Ledger cost for workbench state.
All-local — what and against what are fast; authority and visibility have no home.
Gradient — scratch stays in local SQLite; the change that mattered flows through the event log into the ledger, where it's authorized, audited, shared.

What's still missing in 2026

Turso/libSQL — the most complete realization I've used: managed DBs, embedded replicas, vector search, per-tenant economics, open-source core (self-host exit). Build on the production C libSQL; treat the Rust successor as a separate track.
Cloudflare D1 — great if you live on Cloudflare: zero-ops, built-in read replication, per-tenant at scale, composes with Workers/DO/R2. What I miss is the embedded-replica model — D1 reads stay network reads. D1 reaching embedded-replica parity is the upgrade I'd most like to see.
Durable Objects — the per-entity colocated-SQLite primitive; storage billing for SQLite-backed DOs starting January 2026 reads as a real product line.
AWS has no first-class managed SQLite/libSQL tier — nothing comparable to RDS-for-Postgres or D1/Turso for SQLite workloads. You can assemble it (EFS/S3 + Litestream, SQLite on an ephemeral volume, rqlite on EC2), but there's no managed, replicated, embedded-replica-capable service with RDS-grade polish. For AWS-standardized teams, that's the biggest reason this is harder than it should be.

The pattern feels right to me, libSQL/Turso seem to show it working in production, Cloudflare shows a zero-ops version — and the major clouds, AWS most of all, haven't shipped the managed tier that would make adopting it boring.

Design for the gravity

It compounds. As the desktop gets stronger, the browser follows: WASM, OPFS, Web Workers, WebGPU turn the tab from a display surface into a local runtime — which is why a real SQLite file persisting inside a browser tab stopped being exotic. Stronger local execution pulls more state local, and local state pulls SQLite in.

Desktop agents, the browser becoming a runtime, database-per-tenant, the SQLite revival — to me these don't feel like separate trends so much as one shift seen from different angles: the writer moving back to the edge, the tooling finally giving the edge a real database, and state following. It all feels connected — though that's a hunch I hold loosely, not a thesis I'd defend to the death.

Postgres can be the vault again. SQLite, per tenant and per agent, becomes the workbench. An event log carries the difference.

That's the pull I keep feeling — designing for it a bit more, out of habit a bit less, and still figuring out the edges.

DEV Community: Takafumi Endo

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

Where this is going

Your Fuzzer Is Only as Smart as Its Oracle

"Semantic" needs pinning down

The oracle is the whole game

A worked example: schemas, extensions, a Docker loop

The flywheel is real, but it has a catch

What got cheap (and what didn't)

Where it breaks

Objections I'd raise myself

Where this is going

Every API Will Be Rebuilt for Agents

MCP standardizes the plug, not the operations

The wrapper ceiling is already visible

What "rebuilt for agents" looks like

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

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

Three layers now, one contract later

Objections I'd raise myself

Where this is going

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

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

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

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

Markdown should be a map, not the territory

Specs are scaffolding — give them an exit strategy

Naming is prompt engineering, run inside the repo

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

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

Where this is going

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

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

The global facts you want are mostly graphs

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