~/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.
// 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.
The agent is just a loop
An agent is a loop around a model with tools. If you use Claude Code you are already inside one, and you can drive it with hooks and slash commands, no SDK required.
read →Your coding agent has no world model. You built it one.
Yann LeCun says the path to real intelligence runs through world models, not LLMs. He's probably right. And it explains exactly why your agent loop works.
The spec you didn't read
Using an agent to draft your spec is smart. Skimming what it produces and handing it to another agent to build from is how you end up with architecture you can't explain.
Working with an agent, properly
The complete workflow from first thought to merged commit: spec, context, enforcement, session hygiene, trust limits, and review. Everything that makes agents reliable.
They didn't push a new version. They moved yours.
On 22 May 2026 someone rewrote every git tag in four Laravel-Lang packages. Around 700 historical versions now resolve to malicious commits. Pinning a version is not the same as pinning a commit, and the difference just cost the PHP ecosystem its weekend.
Code churn is the lava you can still measure
AI-assisted teams ship more PRs than ever, but 40% of those lines are rewritten within two weeks. The lava layer is what hardens. Churn is what never gets the chance.
Stop asking your agent nicely
Your CLAUDE.md is a suggestion. Hooks are a wall. ADRs and custom lint rules are the missing layer between them, the difference between hoping your agent obeys and making it impossible to disobey.
You can't spot the bug if you didn't write the code
AI isn't making you a worse programmer. It's making you a worse reader. On debugging instincts, skill atrophy, and why the biggest gap isn't in writing code but in understanding it.
The brilliant parrot problem: what AI actually does when it 'thinks'
Transformers are extraordinary algorithms. But they are algorithms. On next-token prediction, the blindness of generation, and why a system that cannot see where it's going almost certainly cannot be conscious.
The prompt is not the spec
Developers are treating AI prompts like requirements documents. They're not. On vague intent, confident hallucinations, and why the wrong thing built fast is still the wrong thing.