In the real world, this is a recipe for building a system that runs beautifully, passes its tests, and solves entirely the wrong problem.
Rich Hickey’s talks have long been a guide for developers trying to escape this trap. He is famous for advocating "hammock time"—the practice of stepping away from the keyboard, closing your eyes, and actually thinking about the problem before writing a single line of code.
Hickey’s talk, Design in Practice, is a masterclass in how to formalize this process. It is the practical companion to his philosophical talks, offering a concrete structure for recording design decisions without drowning in corporate bureaucracy. It also serves as a beautiful elaboration on Architecture Decision Records (ADRs), a concept first popularized by Mike Nygard's 2011 post, which I still reference regularly.
Here are my key takeaways and reflections on the talk.
If you ask the average developer why they don't write design documents, they'll tell you they don't have time. They need to ship features.
But design isn't about satisfying auditors or writing massive Word documents that no one reads. Design is a cognitive savings account. The goals of formalizing design are intensely practical:
Hickey emphasizes that design is essentially a Socratic dialogue with yourself. It requires detaching your ego from your ideas. The goal isn't to prove your favorite solution is right; it's to discover the objective truth of the system.
He suggests framing your progress around four fundamental questions:
By continuously asking these questions, you engage in reflective inquiry—being aware of your own cognitive state.
Part of this discipline is linguistic precision. If two developers use the same word to mean different things, design fails. Hickey recommends compiling a glossary early in the process. Force yourself to define your terms. If you can't explain what a term means in two sentences, you don't understand it yet.
To turn these philosophical ideas into practice, Hickey breaks the software design and development process into six distinct, sequential phases:
graph TD
A[1. Describe] --> B[2. Diagnose]
B --> C[3. Delimit]
C --> D[4. Direction]
D --> E[5. Design]
E --> F[6. Dev]
E -.->|Backtrack if needed| C
Write down the situation as you hear it. Focus entirely on describing symptoms, not solutions. How big is the problem? What is the business impact? If a database is slow, don't say "we need Redis." Say "queries on the user table are taking 800ms, delaying checkout."
Accumulate hypotheses. There is never just one reason for a bug or bottleneck. List them all and use the scientific method to test them one by one. Prove your hypotheses with data, not vibes.
If you do steps 1 and 2 correctly, you will discover that you are facing a Hydra of multiple, interconnected problems. You cannot solve them all. Delimiting means drawing a hard boundary around the single problem you are going to solve right now.
List high-level approaches and evaluate their trade-offs. Hickey suggests putting these in a decision matrix: columns are your approaches, and rows are your criteria (e.g., development time, operational cost, legal compliance). This is where bad ideas go to die, cheaply and quickly, before they cost a single line of code.
Once you have chosen a direction, map out the implementation path. Choose your libraries, database schemas, and API contracts. If you discover during this phase that your assumptions were wrong, backtrack. It is infinitely cheaper to rewrite a design document than to refactor a production database.
Actually write the code. If you did phases 1 through 5 correctly, this should be the easiest, most mechanical part of the entire process. You aren't guessing or exploring; you are simply executing a well-defined blueprint.
Writing code is fun. Thinking is hard.
But as software systems grow in complexity, the developers who succeed are not the ones who type the fastest. They are the ones who know how to sit in the hammock, ask the right questions, and write their decisions down.
For more details, check out the video of the talk or read the full transcript.
]]>And then, I didn't publish a single post for over two years.
There is a delicious, painful irony here. The very system I built to liberate myself from the bloated abstractions of modern web development ended up silencing me. I fell victim to the classic NIH (Not Invented Here) hangover.
So, what happened? In the real world, things got busy. I started a new job. My wife and I welcomed our second child. My personal programming time, once a vast ocean of late-night hacking, shrunk to a few precious puddles of semi-conscious hours.
But the real reason for the silence was friction.
Every time I wanted to write a quick note, I had to open up custom Lisp files, copy-paste DSL templates, configure Aero tags, and manually structure layout vectors. If I wanted to tweak the design, I had to do major surgery on my custom engine's compiler passes.
I had wanted to take my custom DSL in a brand-new direction, but the sheer mental overhead of building and maintaining that tool started to exceed the utility of the blog itself. A blog's primary job is to be a communication tool—a record of thoughts. If the tool makes writing feel like work, you stop writing.
The ultimate developer trap is optimizing the shovel instead of digging the hole.
As a mid-career engineer, much of my value comes from guiding teams away from rabbit holes and engineering pitfalls. Yet, I had guided myself straight into one.
I needed to apply my own professional judgement to my personal projects. I sat down and asked: What are my actual priorities? If the priority is writing, then the engine needs to be as invisible as possible. The benefits of maintaining my own custom engine had run their course. It was time to outsource the plumbing.
I wanted something lightweight, built on a stack I loved, that handles the boring details while letting me write in plain Markdown. Enter quickblog by Michiel Borkent (affectionately known in the Clojure community as @borkdude).
Quickblog is built on Babashka—a fast, native Clojure scripting engine—and standard markdown parsing. It is clean, minimalist, and doesn't require a master's degree in language design to add a bulleted list. Porting my old posts and custom styles over took an afternoon of work, but the return on investment was immediate: the friction was gone.
This shift in priorities has made me reflect on a lesson I've been learning in parenting.
Lately, whenever my family is running late and I start rushing, my five-year-old daughter likes to look up and say, "Daddy, remember the story of the tortoise and the hare? Slow and steady wins!"
She is wiser than she knows. In software, as in parenting, rushing is almost always a trap. Trying to move quickly on an ineffective path (like building a custom layout engine just to write a blog post) is magnitudes slower than choosing an effective path and moving steadily.
I am no longer in the blog generator business. I am back in the writing business. And hopefully, you'll be reading more from me because of it.
]]>You think: "I don't need a heavy grammar engine. I'll just write a quick regular expression and a split loop. It'll take ten minutes."
And it does. And it works beautifully. You feel like a wizard.
But then, the requirements change. You need to support nested brackets. You need to handle escaped quotes. Suddenly, that "quick regex" turns into a recursive, state-holding, back-tracking monster. You spend your weekends stepping through 300 lines of nested if/else statements, muttering dark oaths under your breath. You are trapped by the sunk-cost fallacy, unwilling to throw away the subsystem you’ve spent weeks debugging.
A hand-written parser is a financial loan shark: it offers incredibly easy terms upfront, followed by ruinous interest rates later.
If we want to build a better parser, we have to follow the classic Rich Hickey advice: let's decomplect it. We must untangle the three distinct duties that a parser implicitly performs:
f, u, n, c, t, i, o, n are recognized collectively as a single keyword token.Historically, computer scientists separated these concerns into specialized tools. In 1975, Mike Lesk and Eric Schmidt (who would later become the CEO of Google) wrote Lex, a lexical analyzer generator. It was typically paired with Yacc ("Yet Another Compiler-Compiler"), a parser generator.
For decades, CompSci students (including myself, fifteen years ago) were forced to learn these tools. It was dry, theoretical, and slightly painful. But the professors had a point: formal grammars are vastly superior to custom procedural parsing code.
Today, we don't have to use Lex and Yacc. We have tools like ANTLR 4 (Another Tool for Language Recognition), which combines lexer and parser definitions into a single, clean grammar file.
Here is a simple ANTLR 4 grammar for the ubiquitous CSV (comma-separated values) format:
csvFile: hdr row+ ;
hdr : row ;
row : field (',' field)* ' '? '\r'? '\n' ;
field : TEXT
| STRING
|
;
TEXT : ~[, "\r\n]+ ;
STRING : '"' ('""'|~'"')* '"' ;
In ANTLR, lexer rules (which define tokens) begin with an uppercase letter (TEXT, STRING), while parser rules (which define structure) begin with a lowercase letter (csvFile, hdr, row, field).
Look at how declarative this is. You don't write loops or search algorithms. You simply describe what a CSV file is. The generator takes this description and outputs highly optimized parsing code in Java, Clojure, Python, or JavaScript.
The trickiest part of designing your own language is ambiguity. An ambiguous language is one where a single string of characters can match more than one parser rule.
Consider this naive grammar for links:
link: '[[' STRING ']]' ;
alias: '[' STRING '](' STRING ')' ;
STRING: [a-zA-Z0-9 ]+ ;
What happens if the parser encounters [[alias](target)]?
Because both rules start with the open bracket [, the parser has to guess which path to follow. Without sufficient lookahead, it may commit to the link rule, proceed to look for ]], fail to find it, and throw a syntax error.
To avoid this, you should design your language syntax to be structurally unambiguous from the start. If that isn't possible, you can resort to lookahead markers or design your parser rules to explicitly allow optional characters to resolve the conflict. For example, using lookahead checks like ANTLR’s semantic predicates to check what characters follow.
If you want to escape the cycle of hand-written parser grief, I highly recommend:
Most modern static site generators are built on a premise I find fundamentally flawed: they exist to translate text-based markup languages (usually Markdown) into HTML and CSS. If you're a non-technical writer, this is a godsend. But if you already speak fluent HTML and CSS, Markdown is a leaky, restrictive abstraction.
I don't want to write Markdown. I want direct, programmatic access to the full expressiveness of the web's native formats. I need a tool that lets me manage the complexity of code re-use through simple composition, without burying me in a pile of YAML front-matter and nested templating engines.
To build this, I reached for Clojure. Clojure is uniquely suited for building domain-specific languages because of Lisp’s defining superpower: homoiconicity (the code is represented as data structures that the language itself can manipulate).
Instead of parsing string-based HTML templates, we can represent HTML elements and inline CSS directly as native Clojure vectors and maps. The Clojure ecosystem already has a brilliant library for this called Hiccup. Here is what Hiccup looks like in action:
user=> (html [:span {:class "foo"} "bar"])
"<span class=\"foo\">bar</span>"
Notice how clean that is. There are no trailing slash errors, no closing tag syntax, and no string interpolation bugs. It is just structured data.
Once your markup is represented as data, the problem of templating resolves into a problem of data composition.
To manage our site's assets and configuration, I pulled in Aero, a small Clojure library for parsing configuration files (written in EDN, Clojure's data format). Aero is excellent because it allows you to define custom tag literals. In Lisp terms, think of tag literals as compiler hooks that evaluate data structures at read-time.
By using Aero, we can write our entire website's layout and pages in static .edn files, version them with Git, and guarantee absolute idempotency. The compiler reads the data, evaluates our custom tags, renders the Hiccup to HTML/CSS, and writes it to the disk.
Let’s look at the asset configuration for this website's home page:
{
:type :html
:slug "/index.html"
:content #template ["pages/index.edn" [:content] {:path "/"}]
}
The heart of our composition engine is the custom #template tag literal. When Aero's reader encounters #template, it treats it like a function call. It takes three arguments:
"pages/index.edn": The path to the template definition.[:content]: A pull vector (similar to Clojure's get-in) to extract the exact portion of the evaluated data we want.{:path "/"}: A map of input variables passed into the template's rendering context.Here is a look inside pages/index.edn:
{
:color #include "../styles/color.edn"
:content
#template ["../components/layout.edn"
[:content]
{:title "home"
:body #ref [:body]}]
:body
[:div
{:style
#css {:display :flex
:flex-direction :column
:justify-content :flex-start
:align-items :flex-start}}
[:div
{:style
#css {:font-size "50px"
:font-weight 700
:color #ref [:color :yellow]}}
"Hi. I'm Adam Tait."]]
}
Notice how we compose the layout. The :content key calls the layout template, passing the :body of our home page as an input variable via the #ref literal. The #css tag translates Clojure maps into inline style strings. It is simple, explicit, and lacks any magical "black box" behavior.
In his famous talk, Are We There Yet?, Rich Hickey makes a crucial distinction between "simple" (unentangled) and "easy" (near at hand).
Most modern web frameworks are easy—you run npx create-next-app and you instantly have a working site. But they are not simple. They bring along a staggering amount of incidental complexity—Webpack configurations, Babel steps, node_modules folders the size of small planets—that you must eventually debug.
The mathematician Alfred North Whitehead once wrote:
Our custom EDN/Hiccup approach does not hide complexity; it lays it bare. There is no magic under the hood. You have direct access to the raw building blocks of the web, structured as immutable data."Seek simplicity, and distrust it."
Is this a poor abstraction? For many, yes. It requires you to write Lisp syntax to build a webpage. But by building a tool that builds the generator, I created a system I deeply understand. When a bug occurs, I don't file a GitHub issue; I just fix my code.
]]>Yet, I built this blog using a completely custom, handcrafted static site generator. Why? Because I am deeply, unapologetically biased toward building my own software systems.
In this post, I want to mount a defense of what the industry disparagingly calls Not Invented Here (NIH) syndrome. The next post will cover the actual technical details of what I built. For now, let’s talk about the why.
In software, dependencies are like renting an apartment. It looks great on paper—someone else handles the plumbing and maintains the roof. But eventually, you discover the landlord has some deeply eccentric house rules, the plumbing is made of papier-mâché, and they can raise the rent or evict you on a whim.
My architectural thinking has been heavily shaped by Rich Hickey's talks (for a quick digest of his philosophy, Daniel Higginbotham’s unofficial guide is fantastic). Hickey’s core lesson is that we should possess a healthy fear of systems we don't understand, written by people whose goals and biases we don't share.
Every time you pull in a heavy third-party framework or outsource a capability to a SaaS provider, you inherit their future roadmap, their bugs, and their licensing decisions. We’ve all been there: you invest weeks learning a complex new tool, only to hit a wall because its core abstraction makes your simple use-case incredibly difficult. Suddenly, instead of building your product, you're spelunking through the GitHub issues of a foreign repository, praying for a workaround.
With SaaS, the risks are even more immediate. You aren't just relying on their code; you're relying on their network stability, their database team, and their business model. When their server goes down, your system goes down with it, and you're left with no recourse but to refresh their status page.
There is a deeper, more insidious risk to depending on other people's abstractions: they capture your mind.
In his famous graduation speech, "This is Water", David Foster Wallace tells the story of two young fish swimming along who meet an older fish. The older fish nods and says, "Morning, boys. How's the water?" The two young fish swim on for a bit, and then eventually one looks at the other and goes, "What the hell is water?"
The longer and deeper you submerge your mind in a specific framework or tool, the more your thinking begins to resemble the limits of that environment. If you only write React, every problem looks like a component lifecycle issue. If you only use static site generators built around markdown, you begin to accept markdown's limitations as the natural laws of web publishing. You forget that other classes of design and entirely different paradigms of simplicity even exist.
At this stage in my career, I’ve stopped chasing the industry's flavor-of-the-month framework. Instead, I find myself returning to Ken Thompson's UNIX philosophy: build small, sharp, reliable tools that do one thing well and compose together.
Earlier in my career, I wasted countless hours learning broad but shallow frameworks, chasing the latest hypetrain only to watch it derail a year later. Mastery doesn't come from memorizing the APIs of ephemeral libraries. Mastery comes from deep, compounding knowledge of fundamental principles.
Building your own small tools is slow in the short term, but it carries a massive long-term dividend. The more small tools you construct, the larger your mental library of design patterns and clean code becomes. You can compose these simple components to solve massive, complex problems without inheriting the incidental complexity of a monolithic framework.
Software mastery isn't about writing perfect code; it's about practicing the art of composition. And to compose effectively, you must understand the notes you're playing.
If you want to dive deeper into the intellectual foundations of this approach, I highly recommend: