The problem

You've read the books. Probably more than one. Clean Architecture, DDD, Designing Data-Intensive Applications. You know what a hexagon is supposed to mean. You can spot a Repository pattern in the wild.

And yet here you are, six months into a project you started from scratch, and the architecture is already a mess. The boundaries you drew on day one are gone. The "service layer" became a 3000-line file that everything imports. Tests take forever. Adding a feature touches five modules that you swore would never depend on each other.

I've been there. More times than I'd like to admit. The frustrating part isn't the mess — every system gets messy. The frustrating part is that reading more books doesn't seem to fix it. You can have a whole shelf of architecture wisdom and still ship a system you'd be embarrassed to show a senior architect.

There's a recent post by matklad that pokes at this, and it nudged me to write down something I've been working out for a while. Let's actually debug it.

Root cause: the feedback loop is broken

Here's the thing nobody tells you in the books: software architecture isn't a body of knowledge. It's a skill. And skills are learned by feedback, not by reading.

The trouble is architecture feedback loops are long. Sometimes painfully long.

• A wrong for loop bites you in seconds.
• A wrong type bites you when you hit save.
• A slow SQL query bites you in hours.
• A wrong architecture decision bites you in months. Sometimes years.

By the time the pain shows up, the original context is gone. You've forgotten what tradeoff you were making. You don't remember the constraints that made the decision feel reasonable at the time. So you can't actually learn from it — you just inherit a mess and feel vaguely guilty about it.

That's the bug. Not "didn't read enough." The bug is that you don't capture decisions when you make them, so when reality slaps you, you can't connect cause to effect.

Step 1: write the decision down when you make it

This is unglamorous but it's the single most effective change I've made in how I work. Whenever I make an architecture decision — anything I'd struggle to explain to a new teammate two months later — I write it down in an ADR (Architecture Decision Record). The format was popularized by Michael Nygard over a decade ago and it has aged well.

You don't need fancy tooling. A folder of markdown files works:

# ADR 0007: use Postgres LISTEN/NOTIFY for the job queue

Date: 2026-04-22
Status: Accepted

## Context
We need a job queue for sending welcome emails after signup.
Volume is ~5k jobs/day, no real-time requirement.
We already run Postgres. We do not run Redis.

## Decision
Use LISTEN/NOTIFY in Postgres rather than introducing Redis + a queue lib.

## Consequences
- One fewer moving piece in prod, one fewer thing to monitor.
- LISTEN/NOTIFY does not persist after disconnect — need a fallback
  poll for missed notifications. 30s poll on a status column.
- If volume grows past ~50k jobs/day we should revisit.

The format isn't sacred. The point is: when this decision comes back to haunt me in eight months, I can read this file and learn something. Without it, I just have a mess and no idea whose idea it was (often: mine).

Step 2: keep a regret log

This one I borrowed from a former colleague and it's gold. Every couple of weeks, I take 20 minutes and walk through the things in the codebase that annoyed me that week. Bugs I had to chase, refactors I had to do, features that were harder than they should've been.

For each one I ask: what decision led to this? And: was the decision wrong, or was I just unlucky?

Most of the time it's the second one. Architecture is probabilistic — sometimes a reasonable call doesn't work out, and that's fine. But maybe one in five times, I trace it back to a decision and go "oh, that's what I should have noticed."

Those are the moments where you actually learn. Not when you read the chapter. When you connect the choice to the consequence.

I keep mine in a single file:

# regret-log.md

## 2026-04-08
The OrderProcessor is doing both validation and persistence.
Today I had to add a "dry run" mode and couldn't, because validation
is entangled with the DB write.

Root cause: I conflated "transaction boundary" with "function boundary."
Should have separated pure validation from effects from day one.

Lesson: when a function both checks invariants AND writes them,
that's a smell. Validate first, write second, two functions.

After a year of this, you have a personal patterns book. One you actually believe, because you wrote it from scars.

Step 3: shorten the feedback loop on purpose

If the natural cycle is months long, you have to engineer shorter ones. A few things that work for me:

• Pair on the design, not just the code. Walk a teammate through a design before you build it. Their confused face is free feedback.
• Build a thin slice end to end first. Don't design the whole thing on paper. Build the simplest possible version that touches every layer. The friction you hit there is the friction you'd hit later, but smaller and cheaper to fix.
• Re-read your own code three months later, deliberately. Not to fix it. Just to ask: "could I extend this comfortably?" If no, what would I do differently?

Here's a one-liner I run weekly to find the files that have been edited the most recently. Those are usually where the structural pain lives:

# files churned the most in the last 3 months
git log --since="3 months ago" --name-only --pretty=format: \
  | sort | uniq -c | sort -rn | head -20

If the same five files show up at the top every month, that's a structural problem. Not a "this file is buggy" problem — a "the boundaries are wrong" problem. Worth a 30-minute think.

Prevention: build the habit, not the heroics

The mistake I made for years was treating architecture as something you do up front and then are done with. Sit down, draw the boxes, start coding. Once the boxes were drawn I stopped thinking about architecture until something obviously broke.

That's not how it works. Architecture is something you maintain continuously, in tiny corrections, the same way you maintain a garden. The teams I've seen produce the cleanest systems aren't the ones with the smartest architect. They're the ones that:

• Write down decisions when they make them (not retroactively).
• Re-read those decisions when reality contradicts them.
• Refactor in small steps as their understanding improves.

None of that requires reading another book.

The books are still worth reading — they give you vocabulary, and vocabulary matters when you have to talk to other developers about tradeoffs. But the vocabulary alone won't make your systems better. The feedback loop will.

So: open a docs/adr folder in your current project this week. Write down the next three decisions you make, even the small ones. In six months, when something goes sideways, you'll have something to actually learn from.

That's the difference between knowing about architecture and getting better at it.