---
title: Working with AI coding agents
summary: The lessons that decided whether an AI agent's work could be trusted: verify with real flows, measure, don't invent, state costs, capture repeated work as skills
last_verified: 2026-09-26
---

# Working with AI coding agents

Each rule below came from a real mistake, and each says what went wrong. Put the ones
that apply into your project's `CLAUDE.md` and your agent's global instructions.

## 1. Verify by doing, not by looking

A read-only walk through a signed-in site **missed two bugs the owner then found
within minutes**. "Remove" on a completed item left it on screen, and a list/grid
toggle broke every card. Reading pages can't exercise actions, and it can't see "the
click worked but the screen didn't change".

- Drive a headless browser as a **test account**, at phone width.
- After every action: compare the DOM with the API, then **reload**, then compare again.
- Toggle every view switch and search on each list page.
- Write the flow from the user's **exact numbers** ("ticked 50, opened History, came
  back, sets said 45") and watch it **fail on the old code** before fixing.
  See `workflows/browser-flow-testing.md`.

## 2. Evidence before "done"

No "fixed", "passing" or "deployed" without the command output that shows it. A deploy
is done when the live site shows the change and the flow passed against production,
not when the script exited 0. If something was skipped, say so.

## 3. Measure, don't guess

- "Do we need a bigger server?" is answered with load, available RAM, swap, OOM kills,
  disk and per-app memory, plus the thresholds that would change the answer.
- "Did the email arrive?" is answered by the provider's **delivery events**, not the
  app's "sent" log line. That line counts attempts. A push service returning 201 does
  not mean the device saw it.
- Check the **user's own settings** before debugging delivery (notifications turned off
  explained a whole "nothing arrives" report).

## 4. Don't invent requirements

Build what the owner or client actually asked for. A feature built on an assumption
(a waiting list the club did not run) had to be removed. A pitch with invented
features reads as not having listened. When a client gives no requirements: list
the questions, don't answer them yourself. The same applies to design tools. Forbid
invented testimonials, user counts, features and data in every brief.

## 5. State recurring costs plainly

Say every recurring cost as **"$X per month, until you remove it"**. Server
snapshots, for example, bill monthly forever: take one only before a risky change, and
delete it right after. Before fanning out parallel agents or design generations, say
it will use a large share of the plan's usage limit.

## 6. Capture repeated work as a skill

The second time the same job is done (a password reset built for two apps), turn it
into a reusable skill. Keep what transfers: the **decisions, the infrastructure steps
and the traps**. Leave out what doesn't: the code (different hashing libraries, CSS
systems and test harnesses per app). This kit is that idea applied to everything.

## 7. Keep agents small and bounded

- One small, checkable change per ticket. Multi-hour, multi-phase work handed to an
  unattended agent died on usage limits and restarts.
- Write each repo's autonomy level into `CLAUDE.md` (PR-and-stop / branch / deploys).
- Parallel agents need their own worktree, test DB, ports and profile dirs
  (`workflows/parallel-agents.md`).
- After a deploy from `main`, switch back to your working branch. Committing on `main`
  by accident was caught only by a pre-push hook.

## 8. Once the owner hands you the terminal, drive it

When learning is the goal, go step by step. Once the owner says "take control", run
the commands yourself and explain what you ran and why. Handing them things to paste
after that is friction. Don't tell them to stop or rest; offer the next step.

## 9. Keep secrets out of transcripts

Never `cat` a `.env` or a config holding tokens. Print key names, or pipe values
straight into the next command. Run provider API calls from the server that holds the
key, so the key never travels. Never publish IPs, tokens or real users' data, including
in docs and screenshots.

## 10. Honest status everywhere

Status lines on a portfolio ("a pitch, not a commission", "in progress"), in
summaries, and in commit messages stay honest. Upgrading the wording to sound better
costs more trust than it earns.