~/manifesto $ cat build-a-system.md

Build a system

How I want to build things with AI: code, workflows and agents.

// the idea

Complexity doesn't mean it's better. That's the big risk with AI.

A system needs to be well thought out, transparent and lean. What isn't used is taken away. And it has to scale.

Processes need to be defined to a T. What do we want? How do we want it? That's the real work in AI engineering. If you can specify what you want, you can have it. If you can't, you just create more and more complexity with, in the best case, little benefit and, in the worst case, none. Systems become bloated, and the output gets worse. That's slop.

If the prompts are right, the context is right, and input and output are clearly defined, systems can do incredibly efficient and intelligent work. A "make it better" prompt will rarely work. Instead of throwing everything at the wall to see what sticks, we make sure the system gets it right every single time. The intelligence is in the system, in the design.

// the car, not the soapbox

When you design a system, you can take parts out, upgrade others and build new structures on top of old ones, and the architecture holds. You don't remove one API key and suddenly the whole workflow stops. You can change models, vendors and providers as you see fit, and the system still works.

It's the difference between engineering a car and building a soapbox. In a car, there's a slot where everything fits. You can upgrade the engine, reinforce some parts, swap out others, add features or take them away, all on a stable platform that keeps running. A tyre gets punctured? Buy a new one and put it on. On a soapbox, you take out one screw and the whole thing collapses. A wheel breaks, and you can't find the same one anymore.

A well-engineered, well-maintained car can run for decades. That's a good system.

// a human in the loop is a design choice

Fully autonomous isn't the goal in itself. A human in the loop can be a deliberate part of the system: a clearly defined role with defined input and output, like any other part. That's how I want to build systems.

// in practice

  1. Specify before you build. Goal, input, output, and when it's done. Written down first.
  2. Lean. No part without a job. What isn't used gets removed. Fewer files, tools and rules beat more.
  3. Modular, with standard slots. Each part has a clear interface, so a model, vendor, key or tool can be swapped without breaking the rest.
  4. Transparent. State lives in files, every step can be traced, and results land where the next person or agent will look.
  5. Right every time. Check outputs against the spec, test, and fix a mistake once so it can't come back.
  6. Human gates by design. Sending, publishing, paying and deleting go to a person. Everything else inside a clear scope just gets done.