Series
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.
17 parts · first published
- 01
Why Your Legacy React Codebase Confuses AI Coding Agents
AI agents stumble on mature codebases because they have accreted multiple valid answers to the same question — and an agent has no way to know which one is current.
·12 min read - 02
A 3-Week Plan to Make Your Legacy React Codebase Agent-Ready
Three weeks, one engineer, one opinionated order. Stop the drift, collapse the duplicates, and let the rules you already have actually start working.
·13 min read - 03
Rules That Agents Actually Follow: Enforcement Over Aspiration
A perfectly written CLAUDE.md cannot fix a contradictory codebase. The most effective rules file is short, opinionated, and backed by tooling.
·12 min read - 04
What to Put in design.md: A Complete Template
A good design.md is a decision document, not a style guide. If a senior designer left tomorrow, would the next person make the same calls?
·17 min read - 05
Writing Task-Specific Agent Prompts That Work First Try
If design.md is the agent's memory, task prompts are its muscle memory — the highest-leverage agentic asset you can build, and the most underused.
·12 min read - 06
Session-Start Hooks That Pay for Themselves
Zero ongoing cost. Measurable improvement on every interaction. The underused feature of modern coding agents — what to put in it, and what not to.
·12 min read - 07
design.md for an MUI Codebase: A Concrete Template
Part 4 was the meta-template. This is the full design.md for an MUI v6+ codebase — every token, variant, and rule, ready to copy.
·23 min read - 08
design.md for a Chakra UI v3 Codebase: Recipes, Tokens, Rules
Chakra v3 changed the game with recipes and semantic tokens. Here is the complete design.md that takes advantage of both — copy, swap your brand, ship.
·24 min read - 09
design.md for a Tailwind + shadcn/ui Codebase
Utility-first codebases need a design.md more, not less. Without one, agents reach for every utility class in the bundle. Here is the full file.
·21 min read - 10
MIGRATIONS.md Recipes: Six Concrete Stack-Pair Migrations
Part 2 said write a MIGRATIONS.md. This post is six concrete recipes — one per common stack pair — that any agent can execute end-to-end.
·26 min read - 11
The Agent-Ready Audit: A Runnable Checklist for Any React Codebase
One bash script, six numbers, an opinion about each. Run it on Monday morning and you have a prioritised list of what to fix before agents can help.
·12 min read - 12
How I Actually Wrote This Site's design.md
Parts 4–9 were the templates. This is the living artifact — a section-by-section tour of the design.md that powers this site, the calls I made, the rules that stuck, and the lines I would write differently if I started over.
·22 min read - 13
design.md, DESIGN.md, and Google Stitch: One File, Narrower Views
There's a popular framing that AGENTS.md is for coding agents and DESIGN.md is for design agents. That framing is a category error. Write one file; serve both.
·7 min read - 14
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.
·7 min read - 15
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.
·12 min read - 16
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.
·11 min read - 17
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.
·13 min read