The reading list
Essays, tech notes, and the in-between.
- technical-notes·3 min read
Adopting Alembic in clipdex without rewriting the query layer
The previous post named four cracks in clipdex's raw-SQL migration story. This one closes them. Declarative models that mirror the live schema, a no-op baseline revision, `alembic stamp head`, and a frozen `migrations/legacy/` directory. No query code changes. Ninety minutes.
- Technical Notes·3 min read
Lefthook for a Static Site: Four Hooks That Earn Their Keep
A static Astro site doesn't need Husky-grade ceremony. But it does have four failure modes worth catching before they reach `main`: a broken type, a leaked key, a post without a `directory:` field, and a build that silently breaks production. Here's the lefthook.yml I landed on, and why each hook is there.
- AI·3 min read
Installing Isn't Teaching: What I Learned From Auditing My Own Shell History
I asked Claude what new CLI tools I should install based on my last week of shell history. The honest answer wasn't a list of tools — it was that I'd already installed half the modern tools I needed and was still typing `cat` and `cd` like it was 2010. A short note on the gap between *having* a tool and *reaching* for one, and where that same gap shows up in your `CLAUDE.md`.
- technical-notes·3 min read
Raw SQL migrations: when they're enough, and the four cracks that force Alembic
Clipdex ships migrations as numbered `.sql` files applied by a Taskfile loop. That's been the right call for a teaching artifact. Here are the four specific cracks that will eventually force a move to Alembic — and the test for when 'eventually' becomes 'now'.
- AI·3 min read
Skills: The User-Facing Workflow Layer
Hooks enforce rules. Subagents review work. Commands and skills are how the team actually invokes them — thin wrappers route to detailed workflows, encoding multi-step knowledge in a single, memorable slash command. The architecture dissected.
- AI·3 min read
Subagents That Catch What Hooks Can't
Hooks block known-bad patterns. Subagents make the judgement calls hooks can't — type safety, architecture compliance, accessibility. One real subagent, dissected, plus a template for writing your own.
- AI·3 min read
The Identifier That Made My Podcast Sound Russian
I spent an evening shrinking ElevenLabs chunk size from 2500 characters down to 1000, convinced the model was choking on density. It wasn't. One camelCase identifier — appearing three times in a single paragraph — was making my voice clone drift into a Russian accent. A field note on debugging non-deterministic systems.
- AI·3 min read
From Audit to Hook: Turning Drift Into Enforcement
A tooling audit surfaces drift. CLAUDE.md tells the agent not to do it. Hooks make sure it actually doesn't. Eight real scripts from a production codebase, with the audit finding each one came from.
- AI·3 min read
The Claude Hooks Lifecycle: A Primer You Can Bookmark
Eight events, one JSON payload format, three exit codes that matter. The reference doc I wish I had open the first time I wrote a Claude Code hook.
- AI·3 min read
Tracking Tokens-Per-Session: The Number Claude Code Hides
Tokens-per-session is the single most useful signal for agentic coding sessions — and Claude Code doesn't show it. /usage gives you cost. /context gives you window percent. Neither sums to the number you actually want. Here's what to track, why, and how to put it on your statusline.
