The reading list
Essays, tech notes, and the in-between.
Reading paths
Read end to end.
Greenfield
Engineering, AI, and the businesses we build from scratch. Solo-narrated essay episodes on the rules, layers, and judgment calls behind working with coding agents in real codebases.
Start →Building an AI Podcast Index
An eight-part build-along: a locally-running tool that ingests a YouTube podcast channel, extracts guests and topics, lets you clip-search by intent, and generates questions for future episodes — using uv, FastAPI, Vite + React, and a provider-switchable LLM client.
Start →Agent-ready React
An ongoing series on making legacy React codebases ready for AI coding agents — from CLAUDE.md and rules to hooks, subagents, and skills.
Start →Choosing Your AI Stack
A six-part series on picking models, pricing models, and building workflows that aren't locked to any single provider.
Start →Browse all series →
See every reading path on the site.
- AI·3 min read
Workflow vs Agent Team: Two Ways to Run Many Claudes
Once you're spawning subagents, you hit a fork: let the lead agent decide who to spawn and when, or script the orchestration deterministically up front. They feel similar and fail differently. Here's how I pick.
- AI·3 min read
The Subagent I Deleted: A Field Note on Layer Discipline
I wrote a subagent that worked. I deleted it ten days later. The replacement was three lines of Prettier config. A short note on the wrong-layer trap, the four-questions test, and why a mature agent-ready repo isn't the one with the most artifacts in it.
- technical-notes·3 min read
The first real Alembic revision: a column, a backfill, and the parts autogenerate can't do
Last post set up Alembic in clipdex. This one cashes the bet: add a duration_ms column to processed_videos, backfill from the existing aggregation, and switch the /episodes endpoint to read it. Three commits. The parts autogenerate gets right, the parts it doesn't, and why the backfill is the line where raw SQL would have started to hurt.
- 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.
