Why Athena/Iceberg Tends to Make Code the Spec

Every time this comes up, someone credits the same setup: Athena on Iceberg is where "the code is the spec" — where you open Git and read the whole system, catalog to transforms to schema, without logging into anything. In my experience they're not wrong. What I want to argue is that they're right for mostly the wrong reason. The reason people reach for is the engine — serverless, open format, nothing to provision. But the thing that actually keeps code as the spec, when it does, is something you could have applied to almost any engine. And the thing that breaks it, when it breaks, has nothing to do with Iceberg at all. So here's the split I've landed on, for now: whether "code is the spec" holds is about 90% discipline and 10% engine . Athena/Iceberg earns that 10% honestly — but 10% is all it earns, and I keep watching people mistake it for the whole thing. (Just where my own tinkering has led — not advice.) I should say up front that I'm still in the middle of this. What the best declarative setup for an agent actually looks like — how you turn a system into a spec it can read and act on without guessing — is something I'm actively testing, not something I've settled. Read what follows as a working idea at a particular moment, written down partly so I can find out where it's wrong. To see where the 10% actually lives, it helps to notice that a stateful system always keeps two copies of itself. The spec has two copies One copy is declared : the code you wrote, the schema you committed, the transforms in dbt, the catalog in Terraform. The other is realized : the state the engine accumulates while running — statistics, physical layout, caches, maintenance history, tuning knobs someone set at 2am. "Code is the spec" is really a claim about the distance between those two. When the declared copy explains almost everything about the realized one, you can reason about the system by reading Git. When it doesn't, you can't. Some of that state is declarable — you can pin a