My AI agents need onboarding too

My core is product definition, design and front end. Claude Code and Codex write most of the code in my own products now, including Blik, my home-services marketplace on the App Store. That doesn't mean I type a wish and ship whatever comes back. The work moved: less typing, more briefing and reviewing.

The best mental model I've found is that the agents are a very fast team that joined this morning. They're smart, they don't know anything about the project, and they will confidently fill every gap with a guess.

1. Spec before code

Every change starts as a small story with acceptance criteria. I loosely follow the BMAD method: a PRD for the what and why, an architecture note for the data model, APIs, Firestore rules and payments, then stories small enough to review in one sitting.

Small stories are the point. A 40-line change I can actually read. A 900-line change I can only skim, and skimming is how bugs ship.

2. A context file in every repo

Each repository has a CLAUDE.md (and an AGENTS.md for Codex) with the stack, the conventions and the rules. Both tools read the same source of truth before they touch anything.

The rules are the important part. "Never change payment logic without a test." "Firestore rules ship with every data change." "No deploy without approval." Each one exists because something went wrong once.

On top of that I write skills for repeated work: release steps, design-system rules, review checklists. For my game I have a skill that holds the whole art direction, so every session starts from the same standard instead of me re-explaining it.

3. Read the diff, not the summary

Agents write excellent summaries of what they did. The summary is not the code.

On Blik, a provider had 90 seconds to accept a job before the customer was asked to pick someone else. Real cleaners are mid-job, not watching their phone, so customers were giving up almost at once. I changed it to 10 minutes, plus a one-hour hold on the server. The important part of the review was noticing that the app and the server's cleanup job each had their own copy of that number, and making sure they changed together.

4. QA agents with one job each

For anything that can hurt users or money, I set up review agents with a single focus: payments, booking and dispatch, onboarding, data and Firestore rules, trust and safety. After a change, each one audits its area and reports problems with evidence. I decide what gets fixed.

They catch real things. They also report things that aren't problems, so their findings get checked like anyone else's.

5. Measure after launch

I test on my phone and, for payments, in Stripe test mode. After launch, Google Analytics 4 funnels show where people drop off and Microsoft Clarity recordings show why. What I see there becomes the next story.

The mistakes are still mine

The worst AI-assisted mistake I've made wasn't bad code. I deployed my portfolio from my laptop while another session had pushed newer work to GitHub, and for a few minutes two interactive features disappeared from the live site. The fix was a boring rule: fetch and merge before every deploy. It's in the context file now.

That's the whole job, really. The agents type. I decide what's right, check that it is, and write down what I learned so it doesn't happen twice.

More on the process, with the video: Designing with AI.