~/blog/tag/craft
Craft
On code quality, deliberate building and the craft of software development.
What I write about here
Software craft is what you cannot outsource. Most posts under this tag are about that, written in the era where the temptation to outsource is the highest it has ever been.
Here is the trade I keep seeing teams make. They reach for an agent because it ships features faster. The features ship. The bugs ship with them.
The code review gets thinner because the diff looks plausible. Six months later, nobody on the team can explain why the auth flow does what it does, and the last person who could has left.
The craft I am defending here is the part that does not show up in commit velocity. It is taste, and the instinct that something is off before you can articulate why. It is the willingness to read code carefully, including code you did not write. And it is the discipline to refuse a fix you do not understand.
None of that gets easier when an agent is involved. If anything, it gets more important. A pull request you would have caught on instinct because it looked weird is the one an agent will produce in a tone of perfect confidence. The reader has to do more work, not less.
That is the through-line of these posts. The model is a tool. The judgment is yours, and you do not get to put it down.
The full argument, with all the posts in one connected arc, is in the Software craft in the AI era guide.
Best entry points
- The prompt is not the spec
The framing essay. A prompt carries intent, a spec carries constraints. Most craft failures are versions of this confusion.
- Stop asking your agent nicely
The shift in voice that changes results: not pleading, instructing. Practical and immediate.
- You can't spot the bug if you didn't write the code
The argument in its sharpest form. You only catch the bugs in code you understand. The craft is in the reading, not the writing.
How database indexes work: the B-tree under everything you shipped this week
A B-tree explained from the shape up, and why every index rule you memorised is that shape restated: leftmost prefix, sargable predicates, covering indexes, slow inserts.
read →Measuring AI code quality: the dashboard beyond coverage and mutation testing
Coverage proves a line ran, mutation testing proves a test would catch a bug, and neither tells you if the code is quietly getting harder to change. What complexity, clone detection and architecture fitness functions actually catch.
When not to use AI for coding: the tasks I still do by hand
Knowing when not to use AI for coding is already a skill you practise, unconsciously and badly. It is also what wrecked METR's follow-up study. Here is the dividing line I actually apply, and why difficulty is the wrong axis.
Who is responsible for AI-generated code? You are, and 2026 wrote it down
Accountability for AI-generated code stopped being a philosophical question this year. In January California barred "the AI did it" as a defence, Europe makes software a product in December, and no vendor indemnity covers your code being wrong.
Refactoring legacy code with a coding agent: start with characterization tests
A coding agent is at its best in the code nobody wants to touch, and most dangerous there too. How to refactor legacy code with AI safely: pin the behaviour first, then let the agent move it.
Learning to program in the age of AI: what I would learn first
Every junior skills list for 2026 says the same thing: learn the agent. That advice is worth about two weeks. Here are the four things I would actually learn first if I started developing today, and why the market is short on exactly those.
How to get better at reading code: a practice routine
Everyone diagnoses AI skill atrophy. Nobody trains the fix. Reading code is a muscle you can drill: a concrete practice routine with a merged PR a day, predict-before-you-run, and explaining code back without the AI.
Cleaning up AI code: the consolidation pass your codebase is waiting for
Churn, duplication and the lava layer are diagnoses. This is the treatment: how to clean up AI-generated technical debt with a scheduled consolidation pass, and which parts the agent can do itself.
Your codebase has twenty ways to format money
AI code duplication is quiet: an inherited codebase with twenty inconsistent money and date formatters. How near-clones form, how to spot them, and the CLAUDE.md rules that stop them.
How to review a pull request an AI wrote
Reviewing AI-generated pull requests is not the same job as reviewing a human one. The names are clean, the comments are confident, CI is green, and the boundary is wrong. A checklist ordered by where models actually slip.