Writing
Interesting finds and takes from whatever I'm working on. A post every other Tuesday, plus the odd extra depending on what's on my desk.
Posts
Spec-driven development: the OpenAPI file is the source of truth
Code structure & architectureOct 27, 20265 min
When I start a new service, I do not write the HTTP handlers by hand. I describe the API in an OpenAPI file first, and the handlers are generated from it. The compiler then will not let the spec and the code drift apart: you change the spec, run one command, and the build stays broken until the handlers match. I would not build a JSON API any other way now, and the reason is the mess it replaced.
Read the post
A REST error taxonomy: frozen codes and three shapes
Code structure & architectureOct 13, 20264 min
If your API can return an error in fifty different JSON shapes, your clients handle none of them and everyone ends up parsing a message string with a regex. So pick a small fixed set of shapes, give every error a stable code, and never let an endpoint invent its own. This is the taxonomy I put on every API, and it is the other half of the lathos post from last time.
Read the post
Behaviour-driven error handling: lathos and one global handler
Code structure & architectureSep 29, 20264 min
An error is a not-found because it says it is, not because of what type it happens to be. That one idea is what lets me delete the pile of errors.Is blocks out of every handler and put the whole HTTP-status decision in a single place. Here is how it hangs together, with the library I use for it, lathos.
Read the post
How I use sub-agents: separation of powers for writing Go
AI-driven development & guardrailsSep 17, 20266 min
One agent that writes the code, writes the tests, and reviews its own work has a problem you already know from humans: it grades its own homework. When a test it wrote fails against code it wrote, the cheapest way out is to edit the test, and a keen agent will take it. So I do not run one agent. I keep a handful of narrow ones, and I draw hard lines between what each of them is allowed to touch.
Read the post
How this blog is built and hosted for nothing
Code structure & architectureSep 14, 20264 min
This site has no server and costs nothing to run. Here is the whole stack, why every piece is the boring choice on purpose, and how fast I can stand one up for you.
Read the post
How I lay out a Go repo: three layers, one direction
Code structure & architectureSep 12, 20266 min
Domain imports nothing and internal owns the logic. Transports hold none of it, whether that is an HTTP handler or a queue consumer, and the data layer swaps under the service without a handler noticing.
Read the post
Three is a pattern: conventions that survive generated code
AI-driven development & guardrailsSep 10, 20264 min
An agent will happily write the same function four times in four files, each slightly different, each passing its own test. So will a tired human on a Friday. The volume just went up, so the habit that keeps a codebase coherent has to be written down where anyone, and anything, working in the repo will read it. Here is the one I lean on hardest.
Read the post