The Dirt Is On the Path: Building an Agent Wiki One Rung at a Time
The temptation when you build an agent system is to draw the final architecture first and then go implement it. I did the opposite. I built the agent wiki by climbing a complexity gradient: start with the dirtiest version that is on the path to the real one, and step up a rung only when a concrete pain forces you to. Two pains qualify. Trust dropped, or I became the bottleneck. Nothing else earns a rung. Not a more elegant design, not a best practice, not the part of me that wants the diagram to look impressive.
The cheapest version that is still on the path
The move is not "build the cheapest thing." The cheapest thing is usually a dead end you throw away. The move is to build the cheapest version that is on the path to the sophisticated one, so that climbing the next rung reuses what you already shipped instead of replacing it.
I say it to myself as "the dirt is on the path." The throwaway bash script that checks something by hand becomes the cron job, then becomes the CI action. Nothing is wasted, because each dirty rung is a stepping stone, not a detour. That is the whole difference between a prototype you delete and a foundation you build on. You are allowed to be sloppy. You are not allowed to be off the path.
Two pains earn a rung, and only two
A rung is expensive. It is more code to trust, more surface to break, more to carry. So the bar to climb has to be high and specific.
Trust drops: the system tells you something you cannot verify, or a less-trusted contributor enters the loop, or you stop being able to reason about whether the output is right. That earns structure, because structure is how trust survives more than one person.
You become the bottleneck: the dirty version cannot keep up with real volume, or every change has to route through you. That earns automation, because the constraint is now you, not the tool.
Everything else is feature-fanciness. It is the rung you climb because the next design is prettier, or because a blog post said you should, or because building the fancy thing is more fun than living with the plain one. The tell is simple. If you cannot name the concrete pain you are feeling today, you are not climbing for a reason. You are climbing because the ladder is there.
The storage gradient, in real life
The wiki's storage layer is the cleanest example, because the git history makes it impossible to lie about. It went: plain Markdown that an LLM reads and writes, then a couple of registries on top (an AST index and a claim registry) when lint and provenance needed real structure, then a vector index when semantic search became the thing I actually wanted and could not get from grep, then a graph mirror when traversal earned its keep, then a cloud system-of-record when a single laptop database became the constraint.
Markdown stayed canonical the entire way. Every layer above it is a derived mirror I can delete and rebuild from the text. That was the non-negotiable that kept each rung reversible: I was never one bad migration away from losing the knowledge base, because the database was never the truth.
There is one rung I climbed for the wrong reason, and I keep it around as the cautionary tale. I once built a branded, memory-specific extension with its own clever mechanisms. It was the elegant end of the gradient, and I jumped straight to it. I ripped it out a few weeks later. The durable lesson was not in the extension. It was that the wiki needed provenance and a rebuildable query layer far more than it needed a fancy memory layer with a name. I had climbed for fanciness, and the gradient made me pay it back.
Every rung is independently valuable and reversible
The reason this is not just "move slow" is that every phase has to ship value on its own and survive being rolled back. You are never holding your breath through a big-bang rewrite. When the wiki moved from the graph mirror to the cloud system-of-record, the old store and the new one ran side by side until a parity check passed. The dirty version keeps the lights on while the next rung proves itself next to it, in production, against real data.
If a proposed step cannot be shipped on its own and cannot be undone, that is a sign it is too big a rung. Cut it into two.
The one thing that does not get deferred
Gradient stepping is about complexity, not about safety. At the dirtiest rung, two things are still rung zero and never get postponed: secrets and sensitive data stay isolated, and a human stays in the loop before anything deploys to a surface that serves sensitive data. You can be casual about the database. You cannot be casual about those. The gradient gives you permission to be sloppy with the parts that are cheap to get wrong, precisely so you can be disciplined about the parts that are not.
Where it bites
The hard part is not the philosophy. It is the discipline of being honest about which pain you are actually feeling. Feature-lust is very good at dressing up as a bottleneck. "We will need it later" is the most common disguise, and later is doing a lot of work in that sentence. The cure is to make yourself point at the present pain, the one you can feel today, and if you cannot, you put the tool down.
The other cost is that gradient stepping looks unimpressive from the outside. You ship dirt and it works, and nobody applauds the bash script that quietly turned into the pipeline. The reward is not in the demo. It is that a year in, you are still standing on everything you built, because you never built anything you had to tear down to keep going.
Start one rung down
If you are building an agent system, resist the architecture diagram for one more day. Find the dirtiest version that is genuinely on the path to the thing you want, ship it, and write down the single concrete pain that would justify the next rung. Then refuse to build past it until that pain actually shows up. The elegant system is still the destination. You just get there by climbing, one earned rung at a time, instead of jumping and hoping the ladder was under you.