Building with AI agents

The shape that works

Driving the CLI from an agent is the command sequence, driving your AI with docs stops it guessing at flags, testing your backend is the gate it should run, and diagnosing a broken project is what to do when it stalls.

Let the agent run the CLI, and let the kit’s own gates catch it.

pithy init --name acme --worker api --json
pithy add auth --json
pithy migrate --json
pithy doctor --json

Every step reports what it did and what it could not finish. An agent that reads the result rather than assuming success needs very little supervision through this part.

Three gates a scaffold ships with

pithy init writes the checks CI needs, not only the two commands a developer runs:

The test split is the kit’s whole testing argument. Worker tests run inside workerd against a real D1 and a real KV through Miniflare; everything else runs in Node.

A test that mocks D1 proves the mock works — which is why the fiddly half is scaffolded rather than described.

The gap to hand the agent explicitly

Where an agent should stop

A supplied secret. Provisioning mints what is arbitrary and stops for anything that must agree with a third party.

A routing zone. Enabling Email Routing points a zone’s whole MX at Cloudflare, and the flags are explicit precisely so a command cannot do that on somebody’s behalf.

Production. A type-to-confirm phrase that --yes never replaces.

pithy remove. It rejects --json.

Reviewing what an agent wrote

Check the claims against code, not comments. Doc comments describe intentions, and an intention nobody implemented reads exactly like a feature — this repository has caught several.

Check the seams. A conditional around c.var.emit(...) means the agent thought the seam might be absent. It is present and inert.

Check the order. requireAuth() before requireEntitlement(), guards before validators. A validator ahead of a guard turns a 401 into a 400 and tells an unauthenticated caller which requests were well-formed.

Check the refs. Any ledger movement or workflow step built from a clock or a random source is a retry that pays twice.

Give it the constraints up front

Cloudflare-only. No filesystem. No code generation at runtime. No long-lived process. A bounded CPU budget per request. No interactive transactions in D1, and 100 bound parameters per query.

Most of the wrong code an agent writes for this kit comes from assuming a Node backend, and stating the constraints once is cheaper than correcting them ten times.

What the kit will tell it

pithy doctor reports what a deploy would fail on, and names the command that fixes each.

Every config block is validated at assembly, so a wrong algorithm, an immutable field changed, or a reserved plugin id fails on deploy rather than at 3am.